作为一名开发人员，我真的不喜欢编写文档，但是当我不得不写文档时，我想让这个过程尽可能轻松。

Word 的问题在于它经常妨碍我。我更关心布局而不是实际内容……这就是我想摆脱 Word 的原因。

理想情况下，我想编写我的内容，然后将其“编译”成文档。

我听说过LaTeX，但我没有任何经验。这会是适合这项工作的技术吗？我应该使用什么编辑器（Windows）？从LyX开始是个好主意吗？

编辑：我不是在询问记录代码（我为此使用 Sandcastle）。

2014 年更新：

我们现在已经切换到GFM（GitHub Flavored Markdown）。

• 这真的很容易使用。
• 在同一个 IDE 中编写代码和文档！
• 一切都可以版本化！
• 以原始 txt、html或pdf形式获得出色的输出！

有没有办法从 Markdown 文件中创建 URL 锚链<a>接到同一存储库和分支中的另一个文件（也就是相对于当前分支的链接）？

例如，在主分支中，我有一个 README.md 文件，我想做类似的事情：

这将允许我在同一个分支中从一个 .md 链接到另一个，而不必担心我在哪个分支（避免必须执行包含 github.com 分支名称的绝对 URL）。

这是我的意思的一个工作示例：

1. 转到http://github.com/rynop/testRel，链接不起作用。
2. 转到http://github.com/rynop/testRel/blob/master/README.md，链接有效。

这是预期的，因为此时起始 URL 位于分支中。现在如何让它在存储库根目录的 README.md 中获取当前分支？

更新：我为此功能请求针对 GitHub打开了一个问题。

我想知道是否有用于获取GitHub 风格的 Markdown文件并将其呈现为 HTML 的命令行实用程序。

我正在使用 GitHub wiki 来创建网站内容。我已经在我的服务器上克隆了存储库，然后想将它处理成常规的 HTML。对我来说重要的是，出现在 GitHub 上的内容正是它应该如何查找我的网站。我也真的很想将围栏块与 一起使用~~~，所以我宁愿不只使用标准的 Markdown 语法。

我查看了一些 JavaScript 实时预览，认为我可以将它连接到 Node.js，但他们说它已被弃用。我查看了 redcarpet 存储库，但它看起来没有命令行界面。

但是，我推出了自己的解决方案，因为这里没有任何解决方案明显比其他解决方案更好，所以我将在没有选择答案的情况下留下问题。

我正在为我的 .md 格式的 github 项目编写自述文件。有没有办法在提交到 github 之前测试我的 readme.md 文件的外观？

在我们的网站（面向非技术人员）中，我们让他们在发送电子邮件时使用 Markdown 。那样的话，他们会得到一些不错的东西，比如粗体、斜体等。然而，作为非技术人员，他们永远无法超越“添加两行以使换行符真正起作用”的怪癖。

主要出于这个原因，我们使用了Github Flavored Markdown的变体。

我们主要借用了这部分：

这很好用，但在某些情况下它不会添加换行符，我想关键是该评论的“在非常清楚的情况下”部分。

如果我正确解释它，这只是为以单词字符或'<'开头的行添加换行符。

有谁知道这是为什么？特别是，为什么'<'？

将两个空格添加到基本上任何内容（以空格、连字符、任何内容开头的行）会有什么害处？

我有一个README.mdmarkdown 文件，用于描述托管在 GitHub 上的项目。在这个文件中，我有几个标题和子标题，每个标题都以一个或多个哈希开头，就像在降价中一样。

现在我想将一个标题的文本设置为C#，但 GitHub 不尊重文本的一部分哈希，而是将其解释为标题的（可选）结束哈希。

即使我通过在哈希前面加上反斜杠来转义它，它也不起作用。所以如果我输入

我得到：

如果我使用

我得到：

我如何以正确的方式写这个标题？

我在将带有图像的 javascript 小书签添加到我的 github 自述文件时遇到了麻烦。该图像应该使用户可以轻松地将书签添加到他的书签栏。

基本上，这（http://alaingilbert.github.com/Turntable-API/bookmarklet.html）是我想要实现的，而是在 github 自述文件上。

到目前为止，我有这个：

但是当我在 github 上查看我的自述文件的源代码时，我注意到 href 属性似乎已经消失了，所以小书签将不再起作用。

github会自动删除javascript href吗？有没有办法解决这个问题？

编辑：table、tbody、tr 和 td 标签的属性似乎也消失了。好像github不喜欢他们？

最近我加入了GitHub。我在那里主持了一些项目。

我需要在我的自述文件中包含一些图像。我不知道该怎么做。

我对此进行了搜索，但我得到的只是一些链接，这些链接告诉我“在网络上托管图像并在 README.md 文件中指定图像路径”。

有没有办法在不将图像托管在任何第三方网络托管服务上的情况下做到这一点？

是否可以在 github 的 markdown 中使用自定义字体？我目前正在将图像加载为徽标，但渲染字体会更快更好。

我使用Jekyll运行博客，并认为我会使用Redcarpet markdown 解释器，因为它是由 GitHub 开发和使用的。

好吧，我只是碰巧遇到了一个错误，去检查问题，发现了这个。

维护者说：“你可能已经注意到了 (har har har har) 我没有时间再维护 Redcarpet。这对我来说不是优先事项（我觉得 Markdown 非常无聊）也不是 GitHub 的优先事项，因为我们没有在生产中使用更长的时间。 ”

所以...

1. 是否有一个可以与 Jekyll (& pygments) 一起使用的好的 Ruby markdown 解释器（即积极开发，语法健全）？

2. 更好的是，语法类似于（或至少接近）GitHub Flavored Markdown 的 Markdown 解释器？