107

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

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

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

4

7 回答 7

127

有问题的标记巧合地称为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已发布降价标准和规范。

于 2012-04-20T04:10:30.237 回答
11

（重新发布此答案并进行一些编辑。）

游戏有点晚了，但我用 Python 写了一个小 CLI。它被称为Grip（Github 自述文件即时预览）。再加上帕特里克的回答，这将让您“在我的浏览器中本地查看我的文档”。

安装它：

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

希望这可以帮助。检查出来。

于 2014-07-21T04:04:15.383 回答
5

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

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

GitHub 上还有一个Preview按钮。

在下面的屏幕截图中可以看到，当我单击 Edit on 时会出现此按钮README.md。

在此处输入图像描述

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

更新

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

它有：

  • 语法高亮 => Markdown 语法的完全着色
  • 嵌入式语言智能感知 ( W00T ) => GitHub 的嵌入式语言功能完全支持 ``` 语言语法。

在此处输入图像描述

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

关于它的详细信息在这里。

于 2014-05-21T00:23:28.500 回答
4

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

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

https://f.cloud.github.com/assets/17715/1999080/7f0c15a2-853e-11e3-95dc-1d7737e1ec20.png

非文本更改以低调的虚线下划线显示。将鼠标悬停在文本上以查看发生了什么变化：

https://f.cloud.github.com/assets/17715/2005588/714cb5ea-86ef-11e3-9e92-a0d11ba6084f.png

于 2014-02-15T10:56:55.460 回答
1

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

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

于 2014-04-28T10:32:32.170 回答
1

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

在此处输入图像描述

于 2017-02-07T11:23:09.763 回答
0

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

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

于 2014-02-18T00:58:49.063 回答