编写须知

文档目录结构

1. 文档采用分层目录结构组织，每个主要功能模块对应一个目录：

   docs/zh/
   ├── index.md                          # 首页
   ├── quick_start/                      # 快速开始
   │   └── index.md
   ├── account/                          # 用户账号管理
   │   ├── accountapplication/
   │   │   └── README.md
   │   └── password/
   │       └── README.md
   ├── connect/                          # 登录集群
   │   ├── SSH_connection/
   │   │   └── README.md
   │   └── InteractiveConnection/
   │       └── README.md
   └── ...                              # 其他目录
   

2. 文件创建规则

   新增章节：在对应目录下新建 .md文件 中文文档：使用 README.md或描述性文件名（如 ssh-configuration.md） 英文文档：在相同目录下创建对应的 .en.md文件（如 README.en.md）

3. 导航栏配置

   导航结构在 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级，保持导航简洁

文档编写流程

1. 编写环境配置

Markdown 编辑器

下面列出了一些各平台上比较常用的 Markdown 编辑器。

全平台

• VS Code: 微软开发的开源编辑器，安装 markdown 插件使用
• Typora: Windows 平台上非常好用的编辑器
• Sublime Text: 商业软件，可免费试用
• Atom: Github 出品的编辑器，功能强大
• Yu Writer: 漂亮好用的 Markdown 写作工具
• Inkdrop: 商业软件， 支持丰富插件
• 作业部落: 作业部落出的客户端
• Laverna： 支持 Dropbox 同步, 具有加密功能

Windows

• MarkdownPad: 全功能编辑器，非常好用的 Markdown 编辑器
• Remarkable

Linux

• GNU Emacs
• ReText
• Remarkable
• Haroopad
• Vim Instant-Markdown Plugin：需要 nodejs

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 中设置文档服务器的别名，这一步很重要，没有这个文件则创建一个。

Host code
    Hostname code.ihep.ac.cn
    User git
    Port 22
    Identityfile ~/.ssh/id_rsa

此处的 ~/.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 = Bob
    email = bob@mail

[alias]
    a = add .
    br = branch
    ci = commit -m
    co = checkout
    df = diff
    dump = cat-file -p
    last = log -1 HEAD
    pl = pull
    ps = push
    st = status
    type = cat-file -t

1. 内容编写步骤

   标准工作流

   拉取最新代码：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请求合并

2. 多语言支持

   对于需要中英文双语的内容，采用并行文件结构：

   shell/
   ├── configuration/
   │   ├── README.md          # 中文文档
   │   └── README.en.md       # 英文文档
   └── software/
       ├── README.md          # 中文文档  
       └── README.en.md       # 英文文档
   

3. 自动化部署

   自动化部署已配置

   仓库位置：https://github.com/xxxxxx/user-manual

   部署分支：main

   触发条件：Pull Request合并到main分支后自动触发

   部署地址：https://storage-docs.com/test/

   查看部署结果

   PR合并后约2-5分钟，即可在部署地址查看变更效果。如部署失败，会通过邮件通知相关人员。

内容维护指南

1. 已有内容更新

   对于已迁移的老版本内容： 在对应目录下直接编辑现有的 .md文件 保持文件路径不变，避免链接失效 更新后记得同步修改对应的英文文档

2. 新增内容创建

   对于全新的功能文档：

   # 1. 创建文档目录和文件
   mkdir -p docs/新功能模块/子模块
   touch docs/新功能模块/子模块/README.md
   
   # 2. 编写内容后，更新导航配置
   # 编辑 mkdocs.yml，在nav部分添加新项
   

   3. 内容质量检查

   在提交前请检查： - 文档结构清晰，标题层级正确

   • 所有链接地址有效

   • 代码示例可正常运行

   • 图片资源已上传并引用正确

   • 中英文文档内容同步更新`

文档引用

1. 内部章节引用

   使用相对路径进行章节间引用：

   交叉引用

   关于SSH连接的详细说明，请参考第四章 登录集群 作业提交的具体操作见 第七章 作业提交

2. 外部资源引用

   规范外部链接的引用格式：

   ## 参考资源
   - [HTCondor官方文档](https://htcondor.org/documentation/){:target="_blank"}
   - [Slurm快速指南](https://slurm.schedmd.com/quickstart.html){:target="_blank"}
   

3. 图片资源引用

   图片统一存放在对应文档一级目录下：

   ![INK申请应用](./ink/fig/application.png)
   *图：申请INK应用*
   

   图：申请INK应用

4. 代码文件引用

   如果引用外部代码文件：

   示例配置文件：`configs/example.conf`
   

5. 表格使用规范

   表格应包含表头和对齐方式：

   | 参数 | 类型 | 默认值 | 说明 |
   |------|------|--------|------|
   | `-J` | 字符串 | 无 | 作业名称 |
   | `-N` | 整数 | 1 | 节点数量 |
   | `-t` | 时间 | 01:00:00 | 运行时间 |
   

平台新功能

1. 标注功能

• 实现效果

Note

标注功能

• 实现方法 在markdown中编辑文本格式为

  !!! note
      重要但非关键的信息提示
  

• 支持类型

  • Note

  Note

  !!! note
      重要但非关键的信息提示
  

  • Abstract

    Abstract

    !!! abstract 标注内容

  • Info

    Info

        !!! info
            标注内容
    

  • Tip

    Tip

        !!! tip
            提高效率的小技巧
    

  • Success

    Success

        !!! success
            标注内容
    

  • Question

    Question

        !!! question
            标注内容
    

  • Warning

    Warning

        !!! warning
            可能导致问题的操作提醒
    

  • Failure

    Failure

        !!! failure
            标注内容
    

  • Danger

    Danger

        !!! danger
            会导致数据丢失或系统故障的操作
    

2. 代码块

• 基础代码展示

支持多种代码语言，如：python、shell等，直接在```后指定语言即可，如：

    ```bash
    echo "Hello World!"
    ``` 

    echo "Hello World!"

    ```py
    def main():
    print("hello world!")
    return
    ``` 

   def main():
    print("hello world!")
    return

• 代码折叠

    === "Linux"

        ```bash
        ssh -l [用户名]@lxlogin.ihep.ac.cn #直接在命令行输入该命令，并输入密码

        ```

    === "Mac"
        ```bash
        ssh -l [用户名]@lxlogin.ihep.ac.cn #用法与linux相同
        ```

    === "Windows"
        ```bash
        #在SSH客户端输入以下命令
        ssh -l [用户名]@lxlogin.ihep.ac.cn
        ```

效果如下：

LinuxMacWindows

ssh -l [用户名]@lxlogin.ihep.ac.cn #直接在命令行输入该命令，并输入密码

ssh -l [用户名]@lxlogin.ihep.ac.cn #用法与linux相同

#在SSH客户端输入以下命令
ssh -l [用户名]@lxlogin.ihep.ac.cn

🤖 AI 助手

💬 快速提问 ×

有问题？输入后跳转到对话页继续交流

发送 →