知识库贡献指南¶
电控知识库旨在提供技术文档、技术规范,致力发展成为战队技术交流和传承平台,电控组成员人人可查看、编辑、添加文档。
编辑文档¶
若发现文档中出现纰漏,可以通知文档作者修订;若无争议内容,也可选择以下两种方式直接进行编辑:
在线编辑¶
-
点击知识库文档界面主标题右侧的浅色 pencil 标记,直接进入文档所在 github 仓库对应
.md
文件的Edit file
界面编辑内容; -
编辑完成后,可点击
Preview
预览文档,确认无误后,提交 commit.
本地编辑¶
- 将仓库 clone 至本地,在
main
分支中docs/
目录找到对应的文档进行修改; - 在本地预览文档,确认无误后,提交 commit 并 push 至远程仓库.
添加文档¶
编写文档¶
-
请编辑
.md
格式的文档; -
如需在文档内添加图片等资源,在文档根目录下创建
<文件名>.assets/
目录来存放。 -
请在标题下方添加版本和作者信息,可采用 https://shields.io 图标,如:
如何添加¶
- 将仓库 Clone 至本地,在
main
分支中docs/
下找到新文档主题对应的目录,添加以下内容:
-
如不需要预览网页效果,且确认文档无误,可以提交 commit 并 push 至远程仓库.
-
稍等几分钟后,将完成自动构建和部署。访问 Wiki 页面 查看效果。
建议:最好在本地预览无误后再推送至远程仓库。
预览网页¶
本知识库站点基于 mkdocs-material 开发,因此最佳方案为在本地安装 mkdocs-material 及插件:
Bash | |
---|---|
由于可能存在的安装包冲突等未知问题,推荐使用一个全新的 conda 或 pip 环境
然后在根目录下运行
Bash | |
---|---|
即可在 localhost:8000
预览网页效果。更多相关信息,请访问官方Wiki.
注意事项¶
- 文档中不要出现敏感信息,如有,请联系作者删除;
- 文档中不要出现过时或不准确的内容,如有,请联系作者更新;
- 文档中不要出现错误或语法错误,如有,请联系作者修订;
- 文档中不要出现不必要的链接,如有,请联系作者删除;
- 文档中的行间公式(
$$ *** $$
)需要在前后分别空一行,否则可能导致公式无法正常显示。
附录¶
版本说明¶
版本号 | 发布日期 | 说明 |
---|---|---|
2022.11.16 | 首次发布 |