文档结构  
翻译进度:已翻译     翻译赏金:0 元 (?)    ¥ 我要打赏

你可能很熟悉怎样利用Github页面帮助你向世界分享你的工作内容,或者你已经加入了一个帮你建立你自己的Github页面的小组。最近Github的更新已经让你的网站通过各种源进行分享变得更加容易。其中的一个来源是你的库的文档文件夹。

质量文件是所有良好软件项目的一个标志。然而,对于开源项目,保持一个强大的知识概要,详细说明所有的插件是最重要的。精心策划的文档可以增加你的项目的可接受性,提供异步指导,培养协调合作推动开源软件发展的类型。

第 1 段(可获 1.36 积分)

将文档托管在网络上存在时间消耗上的难题,文档的发布以及维护有着糟糕的体验——这往往很容易避免。面对多个不同的出版工具比如 FTP 服务和数据库,这意味着文件经常存在于不同的状态和多个位置,他们都需要手动同步。要明确的是,传统的 web 发布方式提供了无与伦比的灵活性和力量;但这是以牺牲易用性为代价的,在许多情况下,甚至牺牲了实用性。

当涉及到文档时,阻力较小的一条路径往往是更好的方法。

第 2 段(可获 1.16 积分)

GitHub 页面提供了直接的路径用来创建你的项目,这使得其成为发布项目以及维护文档的自然而然的选择。由于GitHub页面支持Jekyll,你可以用纯文本或Markdown编辑器编辑文档,有助于维持发布的低门槛。Jekyll还包括许多有用的工具,比如变量、模板和自动化代码高亮,它提供了许多灵活性,这种灵活性会在不复杂的大平台上被发现。

最重要的是,使用GitHub页面意味着你的文档和你在GitHub上的代码存放在一起,你可以使用类似“问题”或者“提交请求”的GitHub功能确保页面得到高度关注。因为GitHub页面允许在主分支的 /docs目录进行发布,你可以维护代码并且维护在同一分之上发布的文档。

第 3 段(可获 1.76 积分)

现在开始

发布你的第一个文档页面只需要花费几分钟的时间。

  1. 在你资源的主分支上创建/docs/index.md文件

  2. 添加内容以及任何必要的Jekyll front matter(文件头部),然后提交你的改动。

create-an-index-file

  1. 访问资源的设置选项卡,选择aster branch /docs文件夹作为GitHub页面的资源。点击save,然后就好了

set-the-publishing-source

GitHub页面将读取/docs 目录下的内容,将index.md转化为HTML,并且在你的GitHub页面URL上进行发布。

这将输出最基本的HTML页面,今后你可以用模板、CSS以及其他Jekylld的可用功能进行个性化设置。想要看各种例子,请参看 GitHub页面展示 。

第 4 段(可获 1.41 积分)

文章评论