在github.com上使用README.md [关闭]

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

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

在将更新的自述文件推送到github存储库之前，有没有可以“在浏览器中本地查看文档”的工具？

该标记被巧合地称为Markdown，由Daring Fireball博客的作者John Gruber创建。Markdown的原始资料可在Daring Fireball-Markdown找到。

Markdown的方言很多，有关Github的文档可在Github Flavored Markdown页面上找到。

该页面上的一个不错的提示：

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

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

2012-11-08更新：正在努力标准化Markdown语法。请参阅Markdown的未来-Jeff Atwood，Coding Horror和W3C Markdown社区小组。

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

（通过一些编辑重新发布此答案。）

游戏有点晚了，但是我用Python编写了一个小的CLI。它称为Grip（Github自述文件即时预览）。加上Patrick的答案，这将使您“在浏览器中本地查看我的文档”。

通过以下方式安装：

$ pip install grip

要使用它，只需：

$ grip

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

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

$ grip CHANGES.md

并更改端口：

$ grip 8080

或合并前两个：

$ grip CHANGES.md 8080

您甚至可以呈现GitHub风格的Markdown（即，如何呈现评论和问题），还可以选择使用repo上下文来自动超链接引用其他问题：

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

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

$ grip -h

显着特点：

• 渲染页面看起来与GitHub上的完全一样
• 围栏
• Python API
• 在链接的文件之间导航
• 将渲染的文档导出到文件

希望这可以帮助。检查一下。

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

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文件，然后选择将Markdown编译为HTML。这将生成一个嵌套在Markdown文件下的.html文件，并将在Markdown文件更改时保持同步。
• 自定义样式表=>您可以添加解决方案特定的样式表来控制预览窗口的样式。

有关此的详细信息。

请注意，自2014年2月起，通过“ Rendered Prose Diffs ”，您还可以在markdown文件中看到diff的渲染版本：

包括散文文件在内的提交和拉取请求现在具有源视图和渲染视图。

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

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

我不确定它是否会长期免费（如啤酒）。

从今天开始，您可以在编辑文件时进行预览。

我发现其他工具不够好-我想要：

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，因此不会有任何意外。