在github.com上使用README.md

Question

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

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

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

Answer 1

有问题的标记巧合地称为Markdown,由Daring Fireball博客的作者John Gruber创建.Markdown的原始资料可以在Daring Fireball - Markdown找到.

有许多Markdown方言,Github的文档可以在Github Flavored Markdown页面上找到.

该页面的精彩提示:

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

您还可以使用Github Markdown实时预览页面来测试您的Markdown文档.

更新2012-11-08:正在努力标准化Markdown语法.看Markdown的未来 - Jeff Atwood,Coding Horror和W3C Markdown社区组织.

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

Answer 2

(通过一些编辑重新发布此答案.)

游戏有点晚了,但我用Python编写了一个小CLI.它叫做Grip(Github Readme Instant Preview).除了帕特里克的回答,这将让你"在我的浏览器中本地查看我的文档."

安装它:

$ 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
• 在链接文件之间导航
• 将呈现的文档导出到文件

希望这可以帮助.看看吧.

Answer 3

这里有一个不错的在线/实时编辑器：

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

PreviewGitHub上还有一个按钮。

在下面的屏幕截图中，单击“打开”时出现此按钮README.md。

恕我直言，实时编辑器比GitHub上的当前编辑器要好。

更新

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

它具有：

• 语法高亮=> Markdown语法全彩色
• 嵌入式语言的智能感知（W00T）=> GitHub的嵌入式语言功能完全受语言语法支持。

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

有关此的详细信息。