# 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) 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.
- [Requires](#requires)
- [Usage](#usage)
- [Install](#install)
- [Configure index.php](#configure-indexphp)
- [Setup URL rewrite rules](#setup-url-rewrite-rules)
- [Test](#test)
- [CSS style issues](#css-style-issues)
## Requires
- PHP 5.4+
- [PHP cURL extension](http://php.net/manual/en/book.curl.php) - more than likely already part of your PHP install/compile.
- Nginx or Apache URL rewrite support.
## Usage
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.
## Install
### Configure index.php
Generate a new [GitHub OAuth](https://developer.github.com/v3/oauth/) personal access token using either:
- The [generatetoken.sh](generatetoken.sh) bash script.
- Directly from the [Personal access tokens](https://github.com/settings/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`](index.php#L11-L12) 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](http://developer.github.com/v3/#rate-limiting), 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.
### Setup URL rewrite rules
- Configure a 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.nginx.conf) & [`rewrite.apache.conf`](rewrite.apache.conf) for examples.
**Note:**
- You may wish to have requested raw Markdown files 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` within your Nginx installation and modify to suit.
- Haven't tested `rewrite.apache.conf` - it should do the trick, would appreciate a pull-request if it needs fixing.
### Test
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.
## CSS style issues
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`](test.md)) to help make things complete.
没有合适的资源?快使用搜索试试~ 我知道了~
github-markdown-render:使用GitHub的Markdown渲染API和CSS在本地Web服务器上显示Mar...
共7个文件
conf:2个
md:2个
license:1个
需积分: 18 2 下载量 86 浏览量
2021-02-04
13:44:03
上传
评论
收藏 10KB ZIP 举报
温馨提示
GitHub Markdown渲染 使用GitHub的和CSS在本地开发Web服务器上显示格式的文档,以模仿GitHub本身的可视显示。 方便在项目存储库中创作/预览README.md文件(或与此有关的任何Markdown),希望避免由于过多的错别字/错误而在提交日志中产生嘈杂的git push操作。 注意:这仅用于本地开发,由于每个用户的GitHub API速率限制,这可能不是用于生产的好主意。 需要 PHP 5.4以上 -很可能已经是您PHP安装/编译的一部分。 Nginx或Apache URL重写支持。 用法 可从本地Web服务器访问Markdown文件,并以纯文本形式返回,例如:
资源详情
资源评论
资源推荐
收起资源包目录
github-markdown-render-main.zip (7个子文件)
github-markdown-render-main
test.md 4KB
generatetoken.sh 903B
LICENSE 1KB
README.md 4KB
index.php 12KB
rewrite.nginx.conf 162B
rewrite.apache.conf 225B
共 7 条
- 1
鑨鑨
- 粉丝: 30
- 资源: 4653
上传资源 快速赚钱
- 我的内容管理 展开
- 我的资源 快来上传第一个资源
- 我的收益 登录查看自己的收益
- 我的积分 登录查看自己的积分
- 我的C币 登录后查看C币余额
- 我的收藏
- 我的下载
- 下载帮助
安全验证
文档复制为VIP权益,开通VIP直接复制
信息提交成功
评论0