2

我想在 github 上发布一系列编程教程以及一些代码。教程将使用 Markdown 编写。会有几个互相引用的markdown文档。

现在我想知道什么是最好的选择：

  1. 将纯 Markdown 文件连同代码一起放入存储库
  2. 使用 github wiki 获取教程并链接到代码
  3. 使用 github 页面（例如使用 jekyll）获取教程并链接到代码

我对 github 页面和 github wiki 都不是很熟悉，所以在这种情况下任何关于（不利）优势的提示都是有帮助的！

4

1 回答 1

3

您已经提到了三种不同的方法可以做到这一点，我将详细说明它们......

仓库中的 Markdown 文件

这种方法实际上并不算太糟糕，因为人们只要知道 Markdown 就可以为它做出贡献（而且 Markdown 无论如何都很容易学习），因为他们只需要在分叉你的存储库后发送一个拉取请求。此外，由于 Github 使用了一种叫做Github Flavored Markdown的东西，你可以将代码直接嵌入到每个文件中，并有一些漂亮的语法高亮显示。

Github 维基

使用 Github wiki 是一个可行的选择，因为它可以让其他人轻松地为它做出贡献。但是，您可能更希望其他人在批准类型系统上进行更改，这是由于拉取请求功能而使用第一个选项的时候。我个人不建议您纯粹使用 wiki，因为它破坏了 Github 存储库本身（在 wiki 中有一个带有堆的空存储库）。不过这只是我个人的看法。

Github 页面生成器

您可以使用 Github Pages 生成器并使用它创建一个网站。但是我想指出，它使用 Jekyll 来生成站点，并且生成器只会自动创建一个页面，其余页面将由您使用 Markdown 和一些 HTML 来制作。它看起来会更好，但会更耗时。

我的个人推荐

我建议您将教程本身托管在用 Markdown 编写的 Github 存储库中，然后您可以使用页面生成器创建一个页面，该页面将链接到教程的所有部分（充当登录页面）

于 2013-04-08T14:22:41.117 回答