Documentation Writing Standards

This document explains the standards for sidebar, file structure, and collaboration in this documentation project, helping you understand how to efficiently collaborate on writing documentation and minimize conflicts caused by non-standard cooperation.

First, you need to understand how to start collaborating through .

Project Structure

The documentation currently maintains Chinese/English bilingual content, with Chinese as the primary language.

• CrychicDoc Main Project
  • .github CI/CD Scripts
    • workflows Automated build scripts //+
  • .vitepress VitePress Configuration
    • config Localization configs
      • index.ts Main config file //v
    • plugins Custom plugins
      • custom-alert.ts Alert plugin //+
      • dialog.ts Dialog plugin //+
    • theme Custom theme
      • components Vue components //v
      • styles CSS styles //v
    • config.mts VitePress config
    • index.ts Sidebar config
  • .vscode VS Code settings
    • snippets Markdown snippets //v
  • docs Content Directory
    • public Static assets //v
    • zh Chinese content
      • various files Documentation files //+
    • en English content
      • various files Documentation files //+
  • README.md Project description
  • ExtractClassScript.js Legacy script
  • extracted_classes.md Legacy file
  • LICENSE CC BY-SA 4.0
  • .gitignore Git ignore rules

Sidebar

The sidebar operates with two different logics:

Sidebar Operation Modes

• Sidebar Configuration Methods
  • Method 1: Index.md Based Control Full Control
    • Configure children in Index.md Complete sidebar customization
    • No individual frontmatter needed Maintenance-friendly
    • Perfect for complex projects Like KubeJS series
    • Predictable structure generation Full control over sub-categories
  • +Method 2: Frontmatter Based Simple Setup
    • Basic root config in Index.md Minimal setup required
    • Set noguide: true in articles Individual article control
    • Configure title in frontmatter Article-specific titles
    • Simple maintenance Easy for individual articles
    • Flexible article management Per-document control

Article Writing Standards

This section explains necessary standards. Although the standards will generally clarify the details to pay attention to, please still focus on Pull Request feedback.

Headings

Heading hierarchy should be progressive, and H1 level headings should appear at the top and only once.

Example Structure:

• Document Structure
  • # Primary Heading Only one per document //!
    • ## Secondary Heading Multiple allowed //v
      • ### Tertiary Heading Nested under H2 //v
        • #### Quaternary Heading Nested under H3 //v
    • ## Another Secondary Heading Same level as above //v
      • ### Another Tertiary Heading Nested structure //v
        • #### Another Quaternary Proper nesting //v

Custom Anchors

Anchors {#custom-anchor} are a VitePress supported Markdown extension. Using them prevents links from becoming lengthy characters due to Chinese titles when copied. For example, is a link without custom anchors, while is optimized with anchors.

We generally encourage using anchors for easier sharing.

Styles and Plugins

This documentation has built-in beautification styles and similar plugins that help writers design more vivid documentation content, avoid plain text wearing down reader patience, and help authors guide readers to truly important sections.

Styles

The documentation has organized current supported styles in a separate . If you have needs in this area, you can check this content before writing.

Plugins

The documentation has some built-in plugins/components, generally added to serve specific scenarios. You can view them .

Documentation Configuration

All documentation files have the following configuration fields:

Configuration Field	Purpose	Type	Default Value
title	Set title displayed in sidebar (uses filename if not set)	string	N/A
noguide	Whether this article appears in sidebar (false = show, true = hide)	boolean	false
backPath	Set destination when clicking BackButton	string	N/A
authors	Set additional authors for this article, displayed in contributors section	string[]	N/A
showComment	Whether to show comment section	boolean	true
gitChangelog	Whether to show contributors and page history	boolean	true
progress	Set article writing progress	int	N/A
description	Set article preview content	string	N/A

Configuration Example

---
title: Example
backPath: ../
authors: ['M1hono', 'skyraah'] # You must submit at least one contribution to properly display your avatar and link
showComment: false
gitChangelog: false
progress: 100
description: This article provides documentation writing standards for this site!
---

frontmatter Declaration

At the beginning of each Markdown file, use --- to create frontmatter configuration:

---
# Add your frontmatter here
---

Alternative Solutions:

• Use standard code block syntax highlighting
• Add type explanations in comments manually
• Utilize JSDoc-style type annotations

Content

• Content Guidelines
  • Content Accuracy Primary standard
    • Ensure correct content Verify information accuracy
    • Discuss with community and QQ groups Collaborate for verification
  • +Content Creation Process Collaborative approach
    • Create imperfect initial content Don't worry about perfection
    • Collaborate for refinement and improvement Work together for quality
  • Community Communication Essential practice
    • Communicate frequently with community Stay connected
    • /modify others' work Respect others' contributions

About Collaboration

This documentation has no complicated collaboration standards, only one: ask the original author's opinion first before making modifications!! For the third time!!

Third-party Documentation Collaboration

If you are the owner of third-party documentation and want your name to appear in the author column, you need to submit at least one content modification to be properly recognized by the program, otherwise links and avatars cannot be generated normally.