Display Markdown formatted documents on your local development web server using GitHub's Markdown Rendering API and CSS to mimic the visual display on GitHub itself.
Handy for authoring/previewing README.md files (or any Markdown for that matter) in project repositories, hopefully avoiding noisy git push actions in commit logs due to excessive typos/errors.
Note: this is intended for local development only, probably not a good idea for production use due to GitHub API rate limits per user.
- PHP 5.4+
- PHP cURL extension - more than likely already part of your PHP install/compile.
- Nginx or Apache URL rewrite support.
Markdown files are accessible from a local web server and returned in plain text, for example:
http://localhost/projects/ghmarkdownrender/README.md
http://localhost/projects/thummer/README.md
http://localhost/projects/unrarallthefiles/README.md
http://localhost/projects/webserverinstall.ubuntu12.04/install.md
To view rendered Markdown, request same URIs with a querystring switch:
http://localhost/projects/ghmarkdownrender/README.md?ghmd
http://localhost/projects/thummer/README.md?ghmd
http://localhost/projects/unrarallthefiles/README.md?ghmd
http://localhost/projects/webserverinstall.ubuntu12.04/install.md?ghmd
Rendered result is cached against the last modification time of each Markdown document to reduce repeated GitHub API calls for identical source content.
Generate a new GitHub OAuth personal access token using either:
- The generatetoken.sh bash script.
- Directly from the Personal access tokens page within your GitHub account:
- Click Generate new token.
- No scope permissions are required.
Note down the token generated.
Update the following constants within index.php in the GitHubMarkdownRender class:
| Setting | Description |
|---|---|
GITHUB_PERSONAL_ACCESS_TOKEN |
Your generated GitHub personal access token. Anonymous GitHub API calls are limited to 60 per hour, providing user credentials ramps this up to a more usable 5000 requests per hour. |
DOCUMENT_ROOT |
Web server document root location on the file system. Assumes you are serving up all your project(s) directories under a default virtual host. |
- Configure a URL rewrite for your default virtual host so all requests to
/local/path/*.md?ghmdare rewritten to/path/to/ghmarkdownrender/index.php. - Refer to the supplied
rewrite.nginx.conf&rewrite.apache.conffor examples.
Note:
- You may wish to have requested raw Markdown files served up with a MIME type such as
text/plainfor convenience.- Nginx by default serves up unknown file types based on extension as
application/octet-stream, forcing a browser download - see/etc/nginx/mime.typeswithin your Nginx installation and modify to suit.
- Nginx by default serves up unknown file types based on extension as
- Haven't tested
rewrite.apache.conf- it should do the trick, would appreciate a pull-request if it needs fixing.
You should now be able to call a Markdown document with a querystring of ?ghmd to receive a familiar GitHub style Markdown display. The page footer will also display the total/available API rate limits, or if rendering was returned from cache.
Markdown display CSS has been lifted (deliberately) from GitHub.com. It's quite possible/likely there are some CSS styles missing to make this complete.
If anything missing is noted with your own markdown documents, it would be great to get any source examples or pull requests (add your example(s) to test.md) to help make things complete.