在github.com上处理README.md文件

Question

在github.com上处理README.md文件

githubmarkdownmarkup

107

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

有哪些资源可以让我学习如何编写适用于我的开源库的 README/wiki 文件的合适标记语法呢？

还有没有工具可以让我在将更新后的 README 推送到 GitHub 仓库之前在本地浏览器中“查看我的文档”呢？

- Calvin Cheng

7个回答

11

(在一些编辑后重新发布这个答案.)

虽然有点晚了，但我用 Python 写了一个小型命令行界面。它被称为 Grip (Github 读我文档即时预览)。在 Patrick 的答案上进行扩展，它可以让你“在本地浏览器中审查我的文档”。

请使用以下命令进行安装：

$ pip install grip

要使用它，只需：

$ grip

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

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

$ grip CHANGES.md

同时更改端口：

$ grip 8080

或者将前两者结合起来：

$ grip CHANGES.md 8080

你甚至可以呈现 GitHub-Flavored Markdown（即评论和问题的呈现方式），可选择使用仓库上下文自动超链接到其他问题的引用：

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

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

$ grip -h

主要特点：

以与 GitHub 一致的方式呈现页面
围栏代码块
Python API
在链接文件之间导航
将渲染后的文档导出到文件

希望这可以帮助你。查看它。

- Joe

5

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

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

Github上也有一个预览按钮。

在下面的截图中，当我点击README.md上的“编辑”时，可以看到此按钮。

enter image description here

在我个人看来，在线编辑器比Github当前提供的编辑器更好。

更新

刚才我搜索了一下Markdown和Visual Studio, 发现如果您使用VS，可以安装Web Essentials，并从Visual Studio中直接支持Markdown。太酷了！

它包括：

语法突出显示 => 对Markdown语法进行全彩色标示
嵌入式语言的智能感知（W00T） => 完全支持GitHub的嵌入式语言特性。

enter image description here

预览窗口 => 查看渲染后HTML内容的并排预览窗口
编译为HTML => 右键单击任何Markdown文件，然后选择“编译Markdown到HTML”。这将在Markdown文件下生成一个.html文件，并会随着Markdown文件的更改而保持同步。
自定义样式表 => 您可以添加特定于解决方案的样式表以控制预览窗口的样式。

有关详细信息，请点击此处。

- Leniel Maccaferri

4

请注意，自2014年2月以来，使用“ Rendered Prose Diffs”，您还可以在Markdown文件的差异中看到呈现版本：

引用：提交和拉取请求包括散文文件，现在具有源和呈现视图。

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

- VonC

1

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

- Ruby Nanthagopal

1

另一个选择是Github的新文本编辑器Atom，它将在您编辑时呈现Github风格的Markdown。请参见https://atom.io/

我不确定它是否会长期免费。

- user2428107

0

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

离线编辑的能力
不仅仅是普通的Markdown，而是实际的Github风格的Markdown

这就是我最终选择的：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，以避免任何意外情况。

- schimmy

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Patrick Klingemann · Accepted Answer

涉及的标记恰好被称为Markdown，由John Gruber创建，他是Daring Fireball博客的作者。Markdown的原始来源可以在Daring Fireball - Markdown找到。

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

该页面还提供了一个不错的提示：

在任何具有Markdown编辑器的Github页面上按M键即可查看Cheat Sheet。

您还可以使用Github Markdown实时预览页面来测试Markdown文档。 更新2012-11-08：正在进行努力以标准化Markdown语法。请参见Jeff Atwood的The Future of Markdown - Coding Horror和W3C Markdown Community Group。 更新2014-09-09：发布了CommonMark，一种Markdown标准和规范。