mkdocs使用说明¶

介绍篇（非必读）-------------------¶

什么是mkdocs?¶

mkdocs是一个静态网站生成器，它使用Markdown语法编写文档，然后使用mkdocs生成静态网站。

为什么要用这个文档？¶

有哪些基本的功能？¶

• markdown 语法支持（包括数学公式，代码、表格等，详情见Material for MkDocs | Reference）
• 搜索
• 评论区互动
• 用户反馈统计以及Google Analytics访问量统计
• 更多功能描述请见文档框架设计文档

如何最快地上手？¶

最简单的方法就是多尝试。（本文章使用了大部分常用的功能，可以作为参考）

使用篇（必读）-------------------¶

如何本地部署文档？（初次使用）¶

本教程提供三种部署方式，对比如下：

（所有方法都只需部署一次，以后一直用就行）

1. 基础软件安装和配置

   安装git：https://git-scm.com/downloads 下载。如果你用Windows，下载Standalone Installer: 64-bit Git for Windows Setup.

   github ssh登录配置：必应搜索：github ssh免密登录配置，打开任意一篇教程，按照教程操作即可。

   那个黑色窗口（终端）是怎么打开的

   安装完成git后，右键点击桌面，选择Git Bash Here即可打开终端。

2. 克隆仓库（执行以下命令，如果让你输入[yes/no]，输入yes即可）

   git clone git@github.com:Peiyang-Aeromodelling-Association/documentation.git
   

3. 配置部署软件

   docker原生pythonanaconda

   下载并安装docker：https://www.docker.com/products/docker-desktop

   更多详细内容参考菜鸟教程：https://www.runoob.com/docker/windows-docker-install.html

   下载并安装python：https://www.python.org/downloads/

   1. 下载并安装anaconda：https://www.anaconda.com/products/individual

   2. 配置环境变量：

      

   3. 如果你是windows环境：用管理员权限打开powershell，输入set-executionpolicy remotesigned

   4. 创建一个虚拟环境：conda create -n docs_env
   5. 激活虚拟环境：conda activate docs_env
   6. 安装pip：conda install pip

4. 进入到文档文件夹下，进一步配置

   docker原生pythonanaconda

   1. 将学长/学姐给你的密钥mkdocs_deploykey放在当前目录下（project root）。
   2. 运行以下命令：

      docker-compose up
      

   1. pip install -r requirements.txt
   2. mkdocs serve

   1. conda activate docs_env
   2. pip install -r requirements.txt
   3. mkdocs serve

5. 过一会，等文档构建完打开浏览器，输入http://127.0.0.1:8030/，即可看到文档。

如何新建文档？¶

1. 在docs/目录下新建.md文件
2. 然后在mkdocs.yml的nav中添加新的文档路径和标题

以下是一个例子：

如何修改文档和提交（基础）¶

以下是一个从创建有限状态机介绍.md到提交的完整例子：

1.新建分支

git checkout -b lcf_update  # 新建分支lcf_update，-b表示新建。不一定要叫lcf_update，可以自己取名

2.新建文档并编辑

3.配置文件中新增一个栏目

4.提交并推送

git add .  # 添加所有修改
git commit -am "新建了FSM介绍文档"  # 提交到本地仓库
git push origin lcf_update  # 推送到远程仓库的lcf_update分支

5.在github上发起Pull Request，合并PR

然后基本上就可以了。

6.合并PR后，更新本地文档，并删除本地分支和远程分支

git checkout main  # 切换到main分支
git pull  # 更新本地文档，使其与远程文档main分支同步
git branch -d lcf_update  # 删除本地分支（因为main分支已经更新到最新，而lcf_update分支作用是个人临时编写文档使用的，所以编辑完成了就可以删除）
git push origin --delete lcf_update  # 删除对应的远程分支

如何解决冲突？（进阶）¶

以下是一个完整的例子：

比如我和杨昕明在同一时间段先后从main分支上新建了各自的分支，打算同时修改mkdocs使用说明.md文件。过程如下：

我先提交了PR并成功合并进了main分支。

杨昕明在我提交PR之后，修改好了mkdocs使用说明.md文件，推送了自己的分支yxm_update后，发起了PR。

然后发现了冲突。根本原因是：git并不知道到底应该选择我的版本还是杨昕明的版本，所以就会提示冲突。 接下来我们使用GitHub自带的编辑器手动选择保留谁的哪一部分内容。解决流程如下图所示：

冲突至此就成功化解。后续的操作和之前一样，合并PR，更新本地文档，删除本地分支和远程分支即可。

总结一下，冲突是如何产生的可以这样理解：

（DEPRECATED）如何更新对外开放的stable分支？（进阶）¶

for root, dirs, files in os.walk("./docs"):
for file in files:
    path = os.path.join(root, file)
    # replace backslashes with forward slashes
    path = path.replace("\\", "/")
    # remove the ./ prefix if it exists
    path = path[2:] if path.startswith("./") else path
    if not is_public(path):  # if the file is not public, delete it
        print(f"rm:{path}")
        os.remove(path)  # delete the file
        with open(path, 'w', encoding='utf-8') as f:  # replace original file with redirection template
            f.write(redirection_template(get_suffix(path)))

操作步骤：

1. 首先和每个组商量好哪些内容是对外开放的，将这些内容写入main分支的public.yml中。

2. 将main分支的内容合并到stable分支上。

   a. 更新stable分支。如果stable分支曾经删除过某些文件（使用过剪枝脚本prune.py），则需要先将stable分支的内容恢复到main分支的状态，再进行下一步操作。

   git checkout stable # 切换到stable分支
   git reset --hard $(git merge-base main stable)  # 将stable分支更新到与main分支的最新公共祖先
   

   b. 将main分支的内容合并到stable分支上。

   git merge --ff-only main # 将main分支合并到stable分支，--ff-only参数表示只允许fast-forward合并（即不允许产生新的commit）
   

3. 运行剪枝脚本，删除不对外开放的内容。

   python prune.py -c public.yml
   

4. (可选) 修改mkdocs.yml的nav标签，使网站的导航栏目能按需求显示文章标签。具体方法见上文。
5. 提交并推送到远程仓库。

   git commit -am "Pruned"
   git push -u origin stable --force
   

番外篇（选修）-------------------¶

如何开启评论区？¶

在文档开头的fontmatter中添加comments: false即可。

一些常用功能¶

公式¶

$a^2+b^2=c^2$

内联公式：\(a^2+b^2=c^2\)

$$
    \int_0^1 f(x)dx
$$

代码¶

print("hello world")

表格¶

| 语法  | 说明     |
|:------|:-------|
| `#`   | 一级标题 |
| `##`  | 二级标题 |
| `###` | 三级标题 |

Admonitions¶

具体使用请参考这里

!!! note "注意"
    标记出需要读者即使在略读时也要注意的信息。

!!! warning "警告"
    标记出关键信息，读者需要特别注意。

!!! danger "危险"
    标记出可能会导致严重后果的信息。

!!! tip "提示"
    一些常用的小技巧可以在这里提示。

!!! example "示例"
    一些示例可以帮助读者更好地理解。

!!! question "问题"
    适当添加引导性问题并给出答案，可以帮助读者更好地理解。

参考文献¶

既可以直接指定参考文献，也可以使用bibtex格式的参考文献。

使用bibtex格式的参考文献可以方便地管理参考文献，只需要在bibliography中添加参考文献的bib文件，然后在文档中引用即可。

像LaTeX²一样写Markdown参考文献。

@article{gpt3,
    title={Language Models are Few-Shot Learners},
    author={Brown, Tom B and Mann, Benjamin and Ryder, Nick and Subbiah, Melanie and Kaplan, Jared and Dhariwal, Prafulla and Neelakantan, Arvind and Shyam, Pranav and Sastry, Girish and Askell, Amanda and others},
    journal={arXiv preprint arXiv:2005.14165},
    year={2020}
}

GPT[@gpt3]是一个非常厉害的模型。

[^git merge原理]:[git merge原理（递归三路合并算法）](https://www.jianshu.com/p/e8932999fe1f)

参考文献[^git merge原理]是关于git merge原理的。

思维导图¶

详情参考：https://github.com/markmap/mkdocs-markmap

Draw.io支持¶

详情见：https://github.com/onixpro/mkdocs-drawio-file/

mkdocs material的详细使用说明（非必读）¶

参考mkdocs-material。

一些Feature请参考这里。

开发者幕后（非必读）¶

最后的话¶

如果还想进一步深入了解幕后的原理，可以参考文档框架设计文档.

希望大家积极参与到文档的编写中来，共同维护好这个文档。文档中留下的是你的足迹，也是你的贡献。

References¶