文档编写规范

🌱初步完成

本文中内容已经初步完成，能够正常提供参考，但存在可能的错漏/亟待改进部分。

本文将对该文档项目的侧边栏、文件结构与合作的规范进行一定的说明，帮助您理解该如何高效地进行合作编写文档，并尽可能减少不规范合作引发的冲突。

首先您需要通过知晓如何开始合作。

项目结构

文章当前维护中/英两种语言，主要语言为中文。

• CrychicDoc 主项目
  • .github CI/CD脚本
    • workflows 自动构建脚本 //+
  • .vitepress VitePress配置
    • config 本地化配置
      • index.ts 主配置文件 //v
    • plugins 自定义插件
      • custom-alert.ts 警告插件 //+
      • dialog.ts 对话框插件 //+
    • theme 自定义主题
      • components Vue组件 //v
      • styles CSS样式 //v
    • config.mts VitePress配置
    • index.ts 侧边栏配置
  • .vscode VS Code设置
    • snippets Markdown代码片段 //v
  • docs 内容目录
    • public 静态资源 //v
    • zh 中文内容
      • 各种文件 文档文件 //+
    • en 英文内容
      • 各种文件 文档文件 //+
  • README.md 项目说明
  • ExtractClassScript.js 旧版脚本
  • extracted_classes.md 旧版文件
  • LICENSE CC BY-SA 4.0
  • .gitignore Git忽略规则

侧边栏

侧边栏有着两种不同的运作逻辑：

侧边栏操作模式

• 侧边栏配置方法
  • 方法一：基于Index.md控制 完全控制
    • 在Index.md中配置children 完全自定义侧边栏
    • 无需单独的frontmatter设置 维护友好
    • 适合复杂项目 如KubeJS系列
    • 可预测的结构生成 完全控制子类别
  • +方法二：基于Frontmatter 简单设置
    • Index.md中基本root配置 最小化设置要求
    • 文章中设置noguide: true 单独文章控制
    • 在frontmatter中配置title 文章特定标题
    • 简单维护 单个文章易管理
    • 灵活的文章管理 每个文档控制

文章编撰规范

该部分将将要讲述必要规范，即便规范会大致讲清需要注意的细则但还是请以Pull Request的反馈为主。

标题

标题的层级应当采用渐进式，且H1级别的标题应当在最上方出现且只出现一次。

结构示例：

• 文档结构
  • # 一级标题 每个文档只有一个 //!
    • ## 二级标题 允许多个 //v
      • ### 三级标题 嵌套在H2下 //v
        • #### 四级标题 嵌套在H3下 //v
    • ## 另一个二级标题 与上面同级 //v
      • ### 另一个三级标题 嵌套结构 //v
        • #### 另一个四级标题 正确嵌套 //v

自定义锚点

锚点{#custom-anchor}是Vitepress默认支持的Markdown扩展，使用它能够让链接不因为中文的标题而在复制后变为冗长的字符，例如就是没有自定义锚点的链接，而则是被锚点优化过后的。

一般我们鼓励使用锚点来便于分享。

样式与插件

该文档内置了不少美化样式与类似功能的插件，它们有利于帮助撰写者设计更加生动的文档内容，避免平淡的文字消磨读者的耐性，也有利于作者引导读者阅读真正重要的部分。

样式

文档对当前支持的样式有整理一个单独的，如果你有这方面的需求，可以在撰写前先查看该部分内容。

插件

文档有一些内置的插件/组件，一般是为服务某种特殊场景而添加，可在查看。

文档配置

该文档文件都有以下配置字段：

配置字段	用途	类型	省缺值
title	设置侧边栏中显示的标题（如未设置则使用文件名）	string	N/A
noguide	该文章是否显示在侧边栏 (false=显示, true=隐藏)	boolean	false
backPath	设置该界面点击BackButton后前往的位置	string	N/A
authors	设置该文章额外的作者，显示在贡献者栏	string[]	N/A
showComment	是否显示评论区	boolean	true
gitChangelog	是否显示贡献者和页面历史	boolean	true
progress	设置该文章的编撰进度	int	N/A
description	设置该文章的预览内容	string	N/A
state	设置该文章的编写状态	string	N/A

示例

---
title: 示例
backPath: ../
authors: ['M1hono', 'skyraah'] # 你必须提交过一次贡献才能正常地显示自己的头像与链接。
showComment: false
gitChangelog: false
progress: 100
description: 该文章提供了本站文档编写规范！
state: preliminary #仅允许preliminary unfinished outdated renovating四种输入
---

frontmatter声明

在每个 Markdown 文件的开头，使用 --- 来创建frontmatter配置

---
# 在这里添加您的frontmatter
---

内容

• 内容指导原则
  • 内容准确性 首要标准
    • 确保编写正确的内容 验证信息准确性
    • 与社区和QQ群众人交流探讨 协作验证
  • +内容创作流程 协作方式
    • 进行不完美的初始创作 不要担心完美
    • 与合作者一起精改进与精进 团队合作提升质量
  • 社区沟通 重要实践
    • 多与社群沟通 保持连接
    • 绝不擅自删改他人的创作 尊重他人贡献

关于合作

该文档在合作上并没有繁琐的规范，有且仅有一个：在进行修改前请先询问原作者的意见！！第三遍了！！

第三方文档合作

如果你是第三方文档的拥有者，要在作者一栏显示你的名字，你需要至少提交一次内容修改，才能被程序正确地识别，否则无法正常生成链接与头像。