Please sign in to comment.
- Loading branch information...
Showing with 509 additions and 0 deletions.
|@@ -0,0 +1,62 @@|
|+# GitHub Markdown render|
|+Display [Markdown](http://github.github.com/github-flavored-markdown/) formatted documents on your local development web server using GitHub's [Markdown Rendering API](http://developer.github.com/v3/markdown/) and CSS to mimic the visual display on GitHub itself.|
|+Handy for authoring & previewing **README.md** files (or any Markdown for that matter) for project repositories, avoiding additional noisy `git push` actions in your commit logs due to Markdown typos/errors.|
|+**Note:** this is intended for local development use only, probably not a good idea for production usage due to GitHub API rate limits per user.|
|+- PHP 5.4+ (developed against PHP 5.4.10)|
|+- [PHP cURL extension](http://php.net/manual/en/book.curl.php) (more than likely part of your PHP install)|
|+- Nginx or Apache URL rewrite support|
|+Your project(s) Markdown files are accessible on your local web server in plain text, for example:|
|+To view using the same parsing and styling as GitHub project pages, request using a querystring switch:|
|+Rendered HTML is cached in a PHP session based on **\*.md** modification time to reduce repeated GitHub API calls for the same Markdown file content.|
|+### Configure index.php|
|+The following constants need to be configured at the top of `index.php` in the `GitHubMarkdownRender` class:|
|+ <td>Your GitHub username. <a href="http://developer.github.com/v3/#rate-limiting">Anonymous GitHub API calls are limited to 60 per hour</a>, providing your credentials ramps this up to a much more suitable 5000 requests per hour.</td>|
|+ <td>See above.</td>|
|+ <td>Your local web server document root. (Assuming you are serving up all your project(s) directories over your default virtual host.)</td>|
|+### Setup URL rewrite rules|
|+Next, setup URL rewrite for your default virtual host so all requests to **/local/path/*.md?ghmd** are rewritten to `/path/to/ghmarkdownrender/index.php`. Refer to the supplied `rewrite.nginx.conf` & `rewrite.apache.conf` for examples.|
|+- You may want to have requested raw Markdown files (e.g. `http://localhost/projects/ghmarkdownrender/README.md`) served up with a MIME type such as `text/plain` for convenience.|
|+ - Nginx by default serves up unknown file types based on extension as `application/octet-stream`, forcing a browser download - see `/etc/nginx/mime.types` and modify to suit.|
|+- I haven't had a chance to test `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 cached based on file modification time.|
|+## CSS style issues|
|+Markdown display CSS has been lifted (deliberately) from GitHub.com. It's quite possible there are some CSS styles missing, if so would appreciate examples and/or pull requests to fix.|
Oops, something went wrong.