跳转至

技术库贡献指南

欢迎跃鹿战队各届电控组成员参与本技术指南的编写！

环境安装

本网站基于 Mkdocs-Material 开发，开发者可专注于文档编写而无需掌握 HTML 相关知识，需本地安装 Mkdocs-Material 及相关插件：

Bash
1
pip install mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-glightbox

编辑文档

  • 将本仓库 clone 至本地，在master分支docs/下修改或新建文件夹。
  • 在文件夹下修改或新建 markdown 文档和 assets 文件夹，保证文件目录如下：
    Text Only
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
    docs/
├─ 文件夹一/
|    ├─ 文件夹1/
|    |   ├─ assets/         # 内含 md 文档内链接的资料，如果没有则可不用创建
|    |   ├─ <文件名1>.md    # md 文档
|    |   ├─ <文件名2>.md
|    |   ├─ ...
|    ├─ 文件夹2/
|    |    ├─ ...
|    ├─ ...
├─ 文件夹二/
|    ├─ ...
├─ ...
  • 注意：当需要在 md 文档内插入链接时，请使用/而不要使用\，例如assets/allrobot.jpg，否则即使本地网页预览显示正常，也有可能导致远端无法显示！

修改导航

在mkdocs.yml中nav下修改网站导航，基本保证网站导航与文件目录一致。

网页预览

在根目录下运行：

Bash
1
mkdocs serve
即可在localhost:8000预览网页效果

远程推送

  • 在网页预览效果和格式无误后，可以提交 commit 并 push 至远程仓库。
  • 当新提交推送到 master 或 main 分支时，将自动构建和部署静态站点。
  • 同样可使用手动部署：
    Bash
    1
    mkdocs gh-deploy --force
    这将构建您的文档并将其部署到存储库中的分支 gh-pages 。

更多信息

想了解 Mkdocs-Material 更多信息，请访问官方文档。