github - 在 Github 上发布编程教程的最佳方式是什么？

Question

关闭。这个问题是opinion-based .它目前不接受答案。












想改善这个问题吗？更新问题，以便可以通过 editing this post 用事实和引文回答问题.

4年前关闭。



Improve this question




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

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

将普通的 Markdown 文件和代码一起放入存储库

使用 github wiki 获取教程并链接到代码

使用 github 页面(例如使用 jekyll)获取教程并链接到代码

我对 github 页面和 github wiki 都不是很熟悉，因此在此上下文中有关(dis)优势的任何提示都是有帮助的!

Answer 1

您已经提到了三种不同的方法来执行此操作，我将详细说明它们中的每一种...

存储库中的 Markdown 文件

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

Github 维基

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

Github 页面生成器

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

我的个人推荐

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