文档编写规范

🌱初步完成

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

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

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

项目结构

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

- crychicdoc
    - .github/    自动构建脚本
    - .vitepress/
        - config/ 本地化配置文件。
        - plugins/ mdit插件存放位置
        - theme/  自定义主题和组件
        - config.mts Vitepress的配置文件
        - index.ts 侧边栏的配置文件。
    - .vscode/ md-snippets
    - docs
        - public 存放静态文件
        - zh 简体中文内容
        - en 英文内容
    - README.md  本文件
    - .gitignore gitignore文件。
    - ExtractClassScript.js 请忽视
    - extracted_classes.md 请忽视
    - LICENSE CC BY-SA 4.0

侧边栏是该文档最重要的引导之一，并写有专门的，在本篇中将着重解释其在实际使用中的用法并让您知道编写文档时在侧边栏上需要进行的设置。

首先侧边栏有着两种运作逻辑。

第一种完全基于Index.md,利用children对侧边栏的生成进行详细地控制，这种方式的优点在于，你可以完全地自定义侧边栏的每个子栏目，确保其生成的内容符合你的预期，同时无需为每个文档都设置frontmatter，这有利于维护结构复杂的项目，例如KubeJS系列的文档。
第二种则为基于Index.md与各个文档单独的frontmatter设置，这种情况只需在index.md中进行最简单的root配置，并在需要生成的文章进行noguide: true与title的设置即可即可，详情可参。

由于文档的内容基本依靠侧边栏与导航栏来进行引导，因此当您编写文档内容时请务必保证侧边栏的同步，如有疑问请尝试询问负责成员。

请注意

为了保证Prev与Next的自动生成，请不要在index.md中书写内容而只把它当做侧边栏的生成器。

文章编撰规范

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

规范的目的是保证文档风格和引导的一致性，来保证读者能够更好地消化内容，规范的一部分内容有参考，规范并不约束第三方文档，但不允许过度偏离文章意图的表达。

标题

请注意

你必须遵守标题使用的规范，。

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

例如：

markdown

# 一级标题

## 二级标题
### 三级标题
#### 四级标题

## 二级标题
### 三级标题
#### 四级标题

自定义锚点

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

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

样式与插件

该部分内容非强制性。

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

样式

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

注

即便你不会使用复杂的样式，也请了解基本的与Vitepress的再进行文档的编写。

插件

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

文档配置

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

提示

本站同时支持Vitepress的原生frontmatter样式，详情请见

配置字段	用途	类型	省缺值
`title`	设置侧边栏中显示的标题（如未设置则使用文件名）	string	`N/A`
`noguide`	该文章是否显示在侧边栏	boolean	`true`
`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`

示例

yaml

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

frontmatter声明

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

yaml

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

类型补全

该部分实际算Plugin的范畴，但其过于特殊。

如果你看过了所提及的两个链接，那么你想必已经知道了Codeblock这个方便分享代码并显示代码高亮的功能。

文档在这个基础上内置了显示类型补全的插件，使得其可以提供更有利于相关教程的代码展示。

例如，同样的代码块：

Demo

const String = "No Twoslash"
console.log(String)
//              ^?

```js
const String = "No Twoslash"
console.log(String)
//              ^?        
```

但如果有了类型补全的话：

Demo

const String = "Twoslash"
console.log(String)
//              ^?

```js
const String = "Twoslash"
console.log(String)
//              ^?        
```

内容

该项目以内容的严谨性为首要标准，需确保自己正在编写正确的内容，为此可以多与社区与腾讯群中的众人进行交流与探讨。
无需担忧自己新著内容的严谨性，请先进行不完美的创作，并与合作者一起进行精改进与精进。
请一定要多与社群沟通，并且一定不要擅自删改他人的创作。

注意

请不要擅自删改他人的创作！！！

关于合作

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

第三方文档合作

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

文档编写规范 ​

项目结构 ​

侧边栏 ​

文章编撰规范 ​

标题 ​

自定义锚点 ​

样式与插件 ​

样式 ​

插件 ​

文档配置 ​

frontmatter声明 ​

类型补全 ​

内容 ​

关于合作 ​

第三方文档合作 ​