编写须知¶
文档目录结构¶
文档采用分层目录结构组织,每个主要功能模块对应一个目录:
文件创建规则
新增章节:在对应目录下新建 .md文件 中文文档:使用 README.md或描述性文件名(如 ssh-configuration.md) 英文文档:在相同目录下创建对应的 .en.md文件(如 README.en.md)
导航栏配置
导航结构在 mkdocs.yml文件的 nav部分配置:
nav:- 1. 简介: index.md- 2. 快速开始: quick_start/index.md- 3. 用户账号管理:- 3.1 账号申请: account/accountapplication/README.md- 3.2 密码管理: account/password/README.md#... 其他导航项导航配置提示
新增文档后需要在 mkdocs.yml中添加对应的导航项
导航标题支持中文,便于用户理解
层级结构最多支持3级,保持导航简洁
文档编写流程¶
- 编写环境配置
Markdown 编辑器¶
下面列出了一些各平台上比较常用的 Markdown 编辑器。
全平台¶
- VS Code: 微软开发的开源编辑器,安装 markdown 插件使用
- Typora: Windows 平台上非常好用的编辑器
- Sublime Text: 商业软件,可免费试用
- Atom: Github 出品的编辑器,功能强大
- Yu Writer: 漂亮好用的 Markdown 写作工具
- Inkdrop: 商业软件, 支持丰富插件
- 作业部落: 作业部落出的客户端
- Laverna: 支持 Dropbox 同步, 具有加密功能
Windows¶
- MarkdownPad: 全功能编辑器,非常好用的 Markdown 编辑器
- Remarkable
Linux¶
macOS¶
- Ulysses:收费软件,支持 macOS, iPhone, iPad
- MWeb:收费软件
- Bear:收费软件
- Mou: 现已收费
- MacDown:开源免费
- Paper:有内购功能,免费版支持 markdown
macOS 下的很多是收费软件。
git 使用环境¶
Windows¶
- Git for Windows
- WSL for Windows 10
- cmder- 完整版
- Github Desktop
ssh 环境配置¶
在~/.ssh/config中设置文档服务器的别名,这一步很重要,没有这个文件则创建一个。
~/.ssh/id_rsa为
个人的密钥,并且个人公钥
~/.ssh/id_rsa.pub已经添加到
Code 平台的个人
SSH Keys(
点击) 中,注意
~/.ssh/config权限要设为
600,
~/.ssh/id_rsa设置为
400。
git 配置文件¶
git 在配置文件为~/.gitconfig, 没有这个文件则可以创建一个,可以在里面加入一些alias,重要的是name和email这两项,将这两个变量改成自己的,没有这两项极可能会报错。 不设置git alias也没问题。
[user]name=Bobemail=bob@mail[alias]a=add.br=branchci=commit-mco=checkoutdf=diffdump=cat-file-plast=log-1HEADpl=pullps=pushst=statustype=cat-file-t
内容编写步骤
标准工作流
拉取最新代码:git pull origin main
创建功能分支:git checkout -b feature/add-new-chapter
编写文档内容:在对应目录创建或编辑 .md文件
更新导航配置:在 mkdocs.yml中添加导航项(如需要)
提交更改:git add . && git commit -m "描述变更内容"
推送分支:git push origin feature/add-new-chapter
创建Pull Request:在Git仓库界面创建PR请求合并
多语言支持
对于需要中英文双语的内容,采用并行文件结构:
自动化部署
查看部署结果
PR合并后约2-5分钟,即可在部署地址查看变更效果。如部署失败,会通过邮件通知相关人员。
内容维护指南¶
已有内容更新
对于已迁移的老版本内容: 在对应目录下直接编辑现有的 .md文件 保持文件路径不变,避免链接失效 更新后记得同步修改对应的英文文档
新增内容创建
对于全新的功能文档:
3. 内容质量检查# 1. 创建文档目录和文件mkdir -p docs/新功能模块/子模块touch docs/新功能模块/子模块/README.md# 2. 编写内容后,更新导航配置# 编辑 mkdocs.yml,在nav部分添加新项在提交前请检查: - 文档结构清晰,标题层级正确
所有链接地址有效
代码示例可正常运行
图片资源已上传并引用正确
中英文文档内容同步更新`
文档引用¶
内部章节引用
使用相对路径进行章节间引用:
外部资源引用
规范外部链接的引用格式:
图片资源引用
图片统一存放在对应文档一级目录下:
图:申请INK应用代码文件引用
如果引用外部代码文件:
表格使用规范
表格应包含表头和对齐方式:
平台新功能¶
1. 标注功能¶
- 实现效果
Note
标注功能
实现方法 在markdown中编辑文本格式为
支持类型
- Note
Abstract
Abstract
!!! abstract 标注内容Info
Tip
Success
Question
Warning
Failure
Danger
2. 代码块¶
- 基础代码展示
支持多种代码语言,如:python、shell等,直接在```后指定语言即可,如:
- 代码折叠
=== "Linux"```bashssh -l [用户名]@lxlogin.ihep.ac.cn #直接在命令行输入该命令,并输入密码```=== "Mac"```bashssh -l [用户名]@lxlogin.ihep.ac.cn #用法与linux相同```=== "Windows"```bash#在SSH客户端输入以下命令ssh -l [用户名]@lxlogin.ihep.ac.cn```
效果如下:
有问题?输入后跳转到对话页继续交流
图:申请INK应用