在github.com上使用README.md

Question

我不太熟悉github在更新README文件时使用的轻量级标记语言。

关于如何为我的开源库的README / wiki文件编写适当的标记语法，我可以阅读哪些资源？

是否有一个工具可以在将更新后的README推送到我的github存储库之前“在浏览器中本地查看我的文档”？

Answer 1

有问题的标记巧合地称为 Markdown ，由Daring Fireball blog的作者John Gruber创建。可以在Daring Fireball - Markdown找到Markdown的原始来源。

有许多Markdown方言，Github的文档可以在Github Flavored Markdown页面找到。

该页面的精彩提示：

使用Markdown编辑器在任何Github页面上按 M 以显示备忘单。

您还可以使用Github Markdown Live Preview页面测试您的Markdown文档。

更新2012-11-08 ：正在努力标准化Markdown语法。请参阅The Future of Markdown - Jeff Atwood, Coding Horror和W3C Markdown Community Group。

更新2014-09-09 ：CommonMark降价标准和规范已经发布。

Answer 2

（Re-posting this answer进行了一些修改。）

游戏稍晚，但我在Python中编写了一个小CLI。它被称为Grip (Github Readme Instant Preview)。除了Patrick的回答，这将让您在我的浏览器中本地查看我的文档。＆＃34;

使用以下命令安装：

$ pip install grip

使用它，只需：

$ grip

然后访问localhost:5000以查看该位置的readme.md文件。

您也可以指定自己的文件：

$ grip CHANGES.md

并更改端口：

$ grip 8080

或者结合前两个：

$ grip CHANGES.md 8080

你甚至可以渲染GitHub-Flavored Markdown（即如何呈现评论和问题），可选择使用repo context来自动超链接对其他问题的引用：

$ grip --gfm --context=username/repo issue.md

为简洁起见，请使用CLI帮助查看其余选项及其详细信息：

$ grip -h

显着特征：

• 呈现的页面与GitHub上的内容完全相同
• 围栏块
• Python API
• 在链接文件之间导航
• 将呈现的文档导出到文件

希望这会有所帮助。 Check it out

Answer 3

这里有一个不错的在线/现场编辑器：

http://jbt.github.io/markdown-editor/

GitHub上还有一个Preview按钮。

请参阅以下屏幕截图，当我点击README.md上的修改时，会显示此按钮。

恕我直言，实时editor比GitHub上现有的更好。

<强>更新

刚才我在搜索Markdown和Visual Studio后发现，如果您使用的是VS，则可以在Visual Studio中安装Web Essentials并获得Markdown支持。那很酷！

它有：

• 语法highlighting =＆gt; Markdown语法的完全着色
• 嵌入式语言的智能感知（ W00T ）=＆gt; GitHub的嵌入式语言功能完全支持“语言语法。

• 预览窗口=＆gt; 查看呈现的HTML的并排预览窗口
• 编译为HTML =＆gt; 右键单击任何Markdown文件，然后选择“将Markdown编译为HTML”。这将生成一个嵌套在Markdown文件下的.html文件，它将在Markdown文件更改时保持同步。
• 自定义样式表=＆gt; 您可以添加特定于解决方案的样式表来控制预览窗口的样式。

有关它的详细信息here。

Answer 4

请注意，自2014年2月起，使用“Rendered Prose Diffs”，您还可以在降价文件中看到差异的渲染版本：

  

提交和提取请求（包括散文文件）现在包含来源和呈现的视图。

  

非文字更改以低调虚线下划线显示。将鼠标悬停在文本上可查看更改内容：

Answer 5

另一个选项--Github的新文本编辑器Atom将在您编辑时呈现github风格的markdown。见https://atom.io/

我不确定从长远来看它是否会免费（如啤酒）。

Answer 6

截至今天，您可以在编辑文件时进行预览。

Answer 7

我没有发现其他工具足够好 - 我想：

1. 离线编辑
2. 不只是定期降价，而是实际的 Github风味降价

这是我最终解决的问题：https://github.com/ypocat/gfms

> gfms

Github Flavored Markdown Server.
Run in your project's root directory.
Usage: gfms

Options:
  -p, --port              Port number to listen at.        [required]
  -h, --host              Host address to bind to.         [default: "localhost"]
  --proxy                 if behind a proxy, proxy url.
  -a, --api               Render using Github API.
  -n, --no-api-on-reload  Disable usage of Github API when the doc is manually reloaded.

所以我有别名：

alias gm='gfms -a -p 8070'

使用-p选项命中Github API并使用实际的当前Github CSS，因此没有任何意外。