跳转至

知识库贡献指南

电控知识库旨在提供技术文档、技术规范,致力发展成为战队技术交流和传承平台,电控组成员人人可查看、编辑、添加文档。

编辑文档

若发现文档中出现纰漏,可以通知文档作者修订;若无争议内容,也可选择以下两种方式直接进行编辑:

在线编辑

  • 点击知识库文档界面主标题右侧的浅色 pencil 标记,直接进入文档所在 github 仓库对应 .md 文件的 Edit file 界面编辑内容;

  • 编辑完成后,可点击 Preview 预览文档,确认无误后,提交 commit.

本地编辑

  • 将仓库 clone 至本地,在 main 分支中 docs/ 目录找到对应的文档进行修改;
  • 在本地预览文档,确认无误后,提交 commit 并 push 至远程仓库.

添加文档

编写文档

  • 请编辑 .md 格式的文档;

  • 如需在文档内添加图片等资源,在文档根目录下创建 <文件名>.assets/ 目录来存放。

  • 请在标题下方添加版本和作者信息,可采用 https://shields.io 图标,如:

Text Only
![](https://img.shields.io/badge/version-1.0.0-green)
![](https://img.shields.io/badge/author-helloworld-lightgrey)

如何添加

  • 将仓库 Clone 至本地,在 main 分支中 docs/ 下找到新文档主题对应的目录,添加以下内容:
Bash
<文件名>.md          # 文档
<文件名>.assets/     # 内含 md 文档内链接的资料,如果没有则可不用创建
  • 如不需要预览网页效果,且确认文档无误,可以提交 commit 并 push 至远程仓库.

  • 稍等几分钟后,将完成自动构建和部署。访问 Wiki 页面 查看效果。

建议:最好在本地预览无误后再推送至远程仓库。

预览网页

本知识库站点基于 mkdocs-material 开发,因此最佳方案为在本地安装 mkdocs-material 及插件:

Bash
pip install mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-glightbox mkdocs-awesome-pages-plugin mkdocs-i18n

由于可能存在的安装包冲突等未知问题,推荐使用一个全新的 conda 或 pip 环境

然后在根目录下运行

Bash
mkdocs serve

即可在 localhost:8000 预览网页效果。更多相关信息,请访问官方Wiki.

注意事项

  1. 文档中不要出现敏感信息,如有,请联系作者删除;
  2. 文档中不要出现过时或不准确的内容,如有,请联系作者更新;
  3. 文档中不要出现错误或语法错误,如有,请联系作者修订;
  4. 文档中不要出现不必要的链接,如有,请联系作者删除;
  5. 文档中的行间公式($$ *** $$)需要在前后分别空一行,否则可能导致公式无法正常显示。

附录

版本说明

版本号 发布日期 说明
2022.11.16 首次发布