使用 Github Pages 发布你的项目文档
创始人
2024-03-01 17:58:02
0

你可能比较熟悉如何用 Github Pages 来分享你的工作,又或许你看过一堂教你建立你的第一个 Github Pages 网站的教程。近期 Github Pages 的改进使得从不同的数据源来发布您的网站更加的方便,其中的来源之一就是你的仓库的 /docs 目录。

文档的质量是一个软件项目健康发展的标志。对于开源项目来说,维护一个可靠而不出错的知识库、详细说明所有的细节是至关重要的。精心策划的文档可以让增加项目的亲切感,提供一步步的指导并促进各种方式的合作可以推动开源软件开发的协作进程。

在 Web 上托管你的文档是一个消耗时间的挑战,而且对于它的发布和维护也没有省事的办法,然而这是并非不可避免的。面对多种不同的发布工具,又是 FTP 服务器,又是数据库,文件以各种不同的方式存放在不同的位置下,而这些都需要你手动来调整。需要说明的是,传统的 Web 发布方式提供了无与伦比的灵活性和性能,但是在许多情况下,这是以牺牲简单易用为代价的。

当作为文档使用时,麻烦更少的方式显然更容易去维护。

GitHub Pages 可以以指定的方式为你的项目创建网站,这使得它天然地适合发布和维护文档。因为 Github Pages 支持 Jekyll,所以你可以使用纯文本或 Markdown 来书写你的文档,从而降低你维护的成本、减少维护时的障碍。Jekyll 还支持许多有用的工具比如变量、模板、以及自动代码高亮等等,它会给你更多的灵活性而不会增加复杂性,这些你在一些笨重的平台是见不到的。

最重要的是,在 Github 上使用 GitHub Pages 意味着你的文档和代码可以使用诸如 Issues 和 Pull Requests 来确保它得到应有的高水平维护,而且因为 GitHub Pages 允许您发布代码库主分支上的 /docs 目录,这样您就可以在同一分支同时维护你的代码库及其文档。

现在开始!

发布你的第一个文档页面只需要短短几分钟。

  1. 在你的仓库的主分支里创建一个 /docs/index.md 文件。
  2. 把你的内容以 Jekyll 格式添加进去,并提交你的修改。

3. 查看你的仓库的设置分支然后选择主分支 /docs 目录,将其设置为 GitHub Pages 的源 ,点击保存,你就搞定了。

GitHub Pages 将会从你的 /docs 目录中读取内容,转换 index.md 为 HTML。然后把它发布到你的 GitHub Pages 的 URL 上。

这样将会创建并输出一个最基础的 HTML ,而且你可以使用 Jekyll 的自定义模板、CSS 和其他特性。如果想要看所有的可能,你可以看看 GitHub Pages Showcase


via: https://github.com/blog/2233-publish-your-project-documentation-with-github-pages

作者:loranallensmith 译者:Bestony 校对:wxy

本文由 LCTT 原创编译,Linux中国 荣誉推出

相关内容

邀请码炒到10万?Open...
新智元报道 编辑:编辑部 JHNZ 【新智元导读】离了个大谱,M...
2025-03-07 14:23:04
腾讯混元发布并开源图生视频...
每经AI快讯,3月6日,据腾讯混元消息,腾讯混元发布图生视频模型并...
2025-03-06 16:50:53
开源仅6天,阿里万相大模型...
3月3日消息,开源社区Hugging Face最新榜单显示,开源仅...
2025-03-03 20:19:33
EA 开源 4 款《命令与...
IT之家 2 月 28 日消息,EA 今日在 GitHub 开源了...
2025-02-28 12:48:47
DeepSeek开源第四弹...
DeepSeek开源周(OpenSourceWeek)第四弹来了,...
2025-02-27 23:19:27
DeepSeek开源第四弹...
2月27日消息,DeepSeek开源周(OpenSourceWee...
2025-02-27 21:49:45

热门资讯

使用 KRAWL 扫描 Kub... 用 KRAWL 脚本来识别 Kubernetes Pod 和容器中的错误。当你使用 Kubernet...
Helix:高级 Linux ... 说到 基于终端的文本编辑器,通常 Vim、Emacs 和 Nano 受到了关注。这并不意味着没有其他...
通过 SaltStack 管理... 我在搜索Puppet的替代品时,偶然间碰到了Salt。我喜欢puppet,但是我又爱上Salt了:)...
Epic 游戏商店现在可在 S... 现在可以在 Steam Deck 上运行 Epic 游戏商店了,几乎无懈可击! 但是,它是非官方的。...
如何在 Github 上创建一... 学习如何复刻一个仓库,进行更改,并要求维护人员审查并合并它。你知道如何使用 git 了,你有一个 G...
2024 开年,LLUG 和你... Hi,Linuxer,2024 新年伊始,不知道你是否已经准备好迎接新的一年~ 2024 年,Lin...
Bazzite:专为 Stea... 为 Linux 桌面或者 Steam Deck 做好游戏准备,听起来都很刺激!对于一个专为 Linu...
Motrix:一个漂亮的跨平台... 一个开源的下载管理器,提供了一个简洁的用户界面,同时提供了跨平台操作的所有基本功能。在这里了解关于它...
Bash 脚本中如何使用 he... here 文档 here document (LCTT 译注:here 文档又称作 heredoc ...
使用 dialog 和 jq ... 为何选择文字用户界面(TUI)?许多人每日都在使用终端,因此, 文字用户界面 Text User I...