记录一次部署Hugo主题lotusdocs到Github Pages实践

引言

• 随着开源项目的越来越复杂，项目文档的重要性日渐突出。一个好的项目要有一个清晰明了的文档来帮助大家使用。
• 最近一直有在找寻一个简洁明了的文档主题来放置项目的各种相关文档。最终找到这次的主角：Lotus Docs 基于Hugo的主题。Lotus Docs的样子，可以移步这里查看。
• 下面着重讲解如何使用这个主题部署自己项目的文档。目前已经部署好的主题：LabelConvert 和 Knowledge-QA-LLM

分支说明

最终仓库下会有三个分支：

• main: 项目源码
• hugo_source: 放置主题和文档内容
• gh-pages: 部署Github Pages的静态页面。Github Actions自动生成。

部署方法

以部署LabelConvert项目文档界面为例。

1. 克隆项目main分支到本地

   git clone git@github.com:RapidAI/LabelConvert.git
   1

2. 新建hugo_source空白分支

   cd LabelConvert
   git checkout --orphan hugo_source
   git rm -rf .
   1
   2
   3

3. 克隆LabelConvert hugo_source分支到当前目录下

    git clone -b hugo_source git@github.com:RapidAI/LabelConvert.git
   
   # 将LabelConvert hugo_source中内容移到最外层目录，并删除LabelConvert
    mv LabelConvert/* .
    rm -r LabelConvert
   1
   2
   3
   4
   5

4. 更改content下内容为自己内容。这一步骤可以照猫画虎，更改对应内容即可。如果不会之处，可以参考主题说明文档
5. 更改hugo.toml的相关内容为自己项目相关的内容
6. 将项目的Github Actions功能打开。（ Github → Actions → Enable）
7. 提交hugo_source分支到Github

   # 先将remote改为自己的哈
   git remote remove origin
   git remote add origin your_git_address
   git push --set-upstream origin hugo_source
   1
   2
   3
   4

8. 设置Github Pages部署的分支
   
9. 最终效果，可访问这里查看