Frytea's Blog
·
GitLab Pipline 使用 mkdocs 及 docs-material 自动编译生成静态页面并自动提交 GitLab Pages
内容提要
MkDocs 是一个简单的静态网站生成工具，使用 Markdown 编写文档。用户只需一个 YAML 配置文件即可创建项目。本文介绍了如何安装 MkDocs、撰写文档、提交至 GitLab，以及配置 GitLab Pipeline 实现自动生成和提交到 GitLab Pages。
关键要点
-
MkDocs 是一个简单的静态网站生成工具，使用 Markdown 编写文档。
-
用户只需一个 YAML 配置文件即可创建项目。
-
安装 MkDocs 的步骤包括使用 pip 安装和新建项目。
-
MkDocs 项目文件夹下包含 docs 文件夹和 mkdocs.yaml 配置文件，用户可以根据需要撰写文档。
-
提交至 GitLab 的步骤包括初始化 git 仓库、添加远程地址、提交和推送代码。
-
配置 GitLab Pipeline 需要创建 .gitlab-ci.yml 文件，并配置 Docker 镜像和安装命令。
-
使用 mkdocs build 命令生成静态网站，并将其转移到 public 文件夹下以提交到 GitLab Pages。
延伸解读
MkDocs 的优势与比较
MkDocs 是一个轻量级的静态网站生成工具，特别适合快速创建文档。与其他工具如 Hexo 和 Docsify 相比，MkDocs 的配置更为简洁，用户只需一个 YAML 文件即可开始项目。这使得它在文档编写和管理上更具效率，适合需要快速上线文档的网站。
GitLab Pipeline 的配置注意事项
在配置 GitLab Pipeline 时，确保 Docker Runner 已正确设置，并且 GitLab Pages 功能已启用。配置 .gitlab-ci.yml 文件时，注意 Docker 镜像的选择和依赖包的安装顺序，以避免构建失败。此外，确保在 master 分支上进行提交，以触发自动构建。
文档结构的设计
在撰写 MkDocs 文档时，合理设计文档结构至关重要。使用树形导航可以帮助用户更好地理解内容层次。注意最后一级导航必须指向具体的 Markdown 文件，并确保上一级菜单后留空，以避免导航错误。
延伸问答
MkDocs 是什么？
MkDocs 是一个简单的静态网站生成工具，使用 Markdown 编写文档，用户只需一个 YAML 配置文件即可创建项目。
如何安装 MkDocs？
安装 MkDocs 的步骤包括使用 pip 安装命令 'pip install mkdocs'，然后新建项目 'mkdocs new my-project'。
如何将文档提交到 GitLab？
提交至 GitLab 的步骤包括初始化 git 仓库、添加远程地址、提交和推送代码，具体命令为 'git init', 'git remote add origin', 'git add .', 'git commit -m "Initial commit"', 'git push -u origin master'。
如何配置 GitLab Pipeline？
配置 GitLab Pipeline 需要在项目根目录下新建一个 .gitlab-ci.yml 文件，并配置 Docker 镜像和安装命令。
使用 mkdocs build 命令有什么作用？
使用 mkdocs build 命令可以生成静态网站，并将其转移到 public 文件夹下以提交到 GitLab Pages。
MkDocs 项目文件夹包含哪些内容？
MkDocs 项目文件夹下包含 docs 文件夹和 mkdocs.yaml 配置文件，用户可以在 docs 文件夹中撰写文档。
