页面和维基

您有许多选项可以以协作的方式分享内容。除了问题和讨论，您还可以使用 GitHub Pages 和 Wiki。

GitHub Pages

GitHub Pages 是一个静态网站托管服务，可以直接从 GitHub 上的仓库提供您的文件。您可以托管普通的超文本标记语言（HTML）、层叠样式表（CSS）和 JavaScript 文件，并自行构建一个网站。但您也可以利用内置的预处理器 Jekyll（请参阅 https://jekyllrb.com/ ），它允许您使用 Markdown 构建漂亮的网站。

GitHub Pages 网站默认托管在 github.io 域名下（例如 https://wulfland.github.io/AccelerateDevOps/ ），但您也可以使用自定义域名。

GitHub Pages 对于公共仓库是免费的。对于内部使用（私有仓库），需要 GitHub Enterprise。

GitHub Pages 是一个免费的服务，但它并不适用于运行商业网站！禁止用于运行网店或任何其他商业网站。它的配额为 1GB，并且每月有 100GB 的带宽限制。有关更多信息，请访问 https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages。

学习 GitHub Pages 的最佳方法是亲自体验。以下是操作步骤：

如果您已经在前几章的实践中 fork 了 https://github.com/wulfland/AccelerateDevOps 仓库，您可以直接访问您的 fork。如果没有，可以通过点击仓库右上角的 Fork 按钮来创建一个 fork。这将在 https://github.com/<USER>/AccelerateDevOps 下创建一个 fork。
在 fork 的仓库中，导航到 Settings | Pages。选择您想要从中运行网站的分支——在这种情况下是 main，并选择 /docs 文件夹作为网站的根目录。您只能选择仓库的根目录或 /docs 文件夹！无法使用其他文件夹。点击 Save 来初始化网站（如图 4.10 所示）：

Figure 1. 图 4.10 – 启用 GitHub Pages 的设置
网站创建完成可能需要几分钟的时间。点击链接，如图 4.11 所示，并刷新页面，如果网站尚未显示：

Figure 2. 图 4.11 – 导航到网页
检查网站，并注意它有一个包含静态页面的菜单和一个显示带摘录的帖子菜单（如图 4.12 所示）：

Figure 3. 图 4.12 – 使用 Jekyll 的网站
返回到您的代码。首先，检查 /docs/_config.yaml 配置文件。在这里，您可以放置网站的全局配置，例如标题和描述，如下所示的代码片段所示：
title: Accelerate DevOps with GitHub description: >- This is a sample Jekyll website that is hosted in GitHub Pages. ...
有许多主题可以用来渲染您的网站。每个主题都有自己的特性，因此请务必查看文档。我使用的是默认的 Jekyll 主题 minima。为了渲染 Markdown，您可以使用 Kramdown 或 GitHub Flavored Markdown (GFM)。Jekyll 还支持不同的插件。minima 主题支持 jekyll-feed 插件，并且通过 show_excerpts 选项，您可以设置是否在主页上显示文章的摘要，如以下代码片段所示：
theme: minima Markdown: kramdown plugins: - jekyll-feed show_excerpts: true
许多主题还支持额外的设置。例如，您可以设置在网站上显示的社交媒体账号，如下所示：
twitter_username: mike_kaufmann github_username: wulfland
通常，静态页面会按字母顺序显示在顶部导航栏中。要筛选和排序页面，您可以在配置文件中添加一个部分。例如，我们想要添加一个新页面，可以在 About.md 前面添加一个 my-page.md 条目，如下所示：
header_pages: - get-started.md - about-Markdown.md - my-page.md - About.md
直接将更改提交到 main 分支。
在 /docs 文件夹中，点击右上角的 Add file | Create new file。输入 my-page.md 作为文件名，并在文件中添加以下头部信息：
layout: page title: "My Page" permalink: /my-page/
如果需要，您可以添加更多的 Markdown 内容。然后直接将更改提交到主分支。
现在，前往 /docs/_posts/ 文件夹。在右上角选择 Add file | Create new file。输入 YYYY-MM-DD-my-post.md 作为文件名，其中 YYYY 为当前年份，MM 为两位数月份，DD 为两位数日期。添加以下头部信息，并将日期替换为当前日期：
layout: post title: "My Post" permalink: /2021-08-14_writing-with-Markdown/
添加一些更多的 Markdown 内容，并直接将其提交到主分支。
给后台的处理器一些时间，然后刷新页面。你应该能够看到页面和文章出现在首页，并且可以浏览它们（见图4.13）：

Figure 4. 图4.13 – 在 Jekyll 中查看新页面和文章

你已经看到在 GitHub Pages 上发布内容是多么容易。Jekyll 是一个非常强大的工具，你几乎可以自定义所有内容，包括主题。你也可以安装 Ruby 和 Jekyll 来离线运行你的网站进行测试（更多细节请参考 GitHub Pages 设置文档）。然而，这是一个非常复杂的话题，超出了本书的范围。

使用 Jekyll 的 GitHub Pages 是以漂亮的方式展示内容并进行协作的一个好方法，你可以像处理代码一样，通过拉取请求（pull requests）来协作。你可以将它用作技术博客或者用户文档。在一个分布式团队中，你可以用它来发布每个 Sprint 的结果，可能还包含小视频。这有助于即使团队成员无法参加 Sprint 回顾会议时，也能传达你的成功。

Wikis

GitHub 在每个仓库中都有一个简单的 wiki，但你也可以选择在代码旁边创建自己的基于 Markdown 的 wiki。

GitHub wiki

每个仓库都有一个非常简单的 wiki。你可以选择以不同的格式编辑页面：Markdown、AsciiDoc、Creole、MediaWiki、Org-mode、Prod、RDoc、Textile 或 reStructuredText。由于 GitHub 中的其他内容都是 Markdown，因此我认为这是最好的选择，但如果你已经有了其他格式的 wiki 内容，它也可以帮助你将内容迁移过来。

像 AsciiDoc 或 MediaWiki 这样的其他编辑格式具有更高级的功能，如自动生成目录（ToC）。如果你的团队已经熟悉这些语法，使用这些格式可能更适合你。但如果同时学习 Markdown 和另一种 Markdown 语言，可能会适得其反，影响学习效果。

Wikis 非常简单。它有一个主页可以编辑，你还可以添加自定义的侧边栏和页脚。其他页面的链接通过双括号指定，格式为 [[Page Name]]。如果你想要使用自定义链接文本，可以使用 [[Link Text|Page Name]] 格式。如果你创建了一个指向尚不存在页面的链接，该链接将以红色显示，你可以通过点击该链接来创建页面。

Wiki 是一个与仓库同名并带有 .wiki 扩展名的 Git 仓库（<name_of_repository>.wiki）。你可以克隆该仓库，并在本地的分支中工作，但遗憾的是，目前没有办法通过拉取请求（pull requests）来协作处理更改！这是 GitHub wiki 的最大缺点！

另外，wikis 不支持嵌套页面。所有页面都在仓库的根目录下。你可以使用侧边栏通过 Markdown 嵌套列表来创建一个具有层级结构的菜单，如下所示：

[[Home]]
*   [[Page 1]]
    * [[Page 1.1]]
    * [[Page 1.2]]

如果你希望菜单的部分内容是可折叠的，可以使用 GitHub Markdown 功能中的 <details></details>。这会在 Markdown 中创建一个可折叠的部分，使用 <summary></summary> 可以自定义标题，示例如下：

* [[Page 2]]
    * <details>
    <summary>[[Page 2.1]] (Click to open)</summary>
        * [[Page 2.1.1]]
        * [[Page 2.1.2]]
    </details>

请注意，为了使其正常工作，空行是必要的！结果如下图 4.14 所示：

Figure 5. 图 4.14 – GitHub Wiki 的结构

GitHub Wiki 是一个非常简单的 Wiki 解决方案，缺乏许多其他 Wiki 解决方案的功能，特别是无法使用拉取请求，这限制了它在异步工作流中的优势。但幸运的是，你可以将 Markdown 托管在自己的仓库中，并自己构建一个自定义的 Wiki。

自定义 Wiki

如果你不想使用 GitHub Pages 的复杂性，但仍然希望在 Wiki 中使用拉取请求，你可以将 Markdown 文件直接放入你的仓库中。GitHub 会自动为所有的 Markdown 文件生成目录（如图 4.15 所示）。你可能已经在 GitHub 仓库中的 README 文件中注意到了这一点：

Figure 6. 图 4.15 – GitHub Markdown 文件的目录

使用自定义 Wiki 的问题是导航。你可以很容易地使用 Markdown 嵌套列表和相对链接来构建导航系统。如果需要，你还可以使用 details 来使导航部分可折叠，如下面的代码片段所示：

<details>
<summary>Menu</summary>
* [Home](#Header-1)
* [Page1](Page1.md)
    * [Page 1.1](Page1-1.md)
    * [Page 1.2](Page1-2.md)
* [Page2](Page2.md)
</details>

但是，如果你需要它出现在每一页上，当你修改导航时，你必须将其复制并粘贴到所有页面。虽然你可以自动化这个过程，但它仍然会混乱你的历史记录。更好的方法是在每个页面上使用类似面包屑的导航，让用户可以返回主页并从那里使用菜单。你可以在这个链接中查看一个自定义导航的例子： GitHub 示例。

从社区论坛、简单的 Markdown Wiki 到使用 Jekyll 构建的完全可定制的网页，GitHub 上有很多选项可以托管你的工作内容。选择适合当前任务的方式并不容易。有时候，你需要尝试找出最适合你团队的方式。