# Markdown Writing Guide > Complete guide to writing high-quality technical documents in GEO Wiki Pro --- ## Overview GEO Wiki Pro uses Markdown as the document writing format. Each document starts with YAML Frontmatter, and the body supports standard Markdown syntax and extended syntax. This document covers writing standards, best practices, and common considerations. --- ## YAML Frontmatter Every document **must** start with YAML Frontmatter, surrounded by `---`: ```yaml --- title: CAN Bus Protocol slug: can-bus-protocol category: can-motion tags: [can-bus, protocol] author: admin sort: 1 description: Brief description for search results --- ``` ### Required Fields | Field | Description | Example | |-------|-------------|---------| | `title` | Document title | `CAN Bus Protocol` | | `slug` | URL identifier (letters, numbers, hyphens, underscores only) | `can-bus-protocol` | | `category` | Category slug (must exist) | `can-motion` | | `tags` | Tag array | `[can-bus, protocol]` | | `author` | Author name | `admin` | ### Optional Fields | Field | Description | Example | |-------|-------------|---------| | `sort` | Sort value (number, ascending, default 999) | `1` | | `description` | Search result summary | `CAN bus overview...` | | `notice` | Notification banner text | `This is a beta feature.` | | `published_at` | Publish time | `2026-05-20T10:30:00Z` | | `updated_at` | Update time | `2026-06-01T15:00:00Z` | ### Slug Rules - Must match `/^[\w-]+$/` (letters, numbers, hyphens, underscores only) - Maximum length: 200 characters - ASCII-only slugs recommended for URL compatibility - Cannot contain `..`, `/`, `\`, `\0` - System automatically checks slug uniqueness ::: warning Once created, slugs cannot be modified as they are used as filenames and URL paths. Choose a concise and meaningful slug. ::: --- ## Shared vs Independent Fields ### Shared Fields (Cross-language Sync) The following fields automatically sync across all language versions: - `category` - `tags` - `author` - `sort` When you update shared fields in one language, `syncSharedFields()` automatically broadcasts these values to other language versions. ### Independent Fields (Per-language) - `title` - `description` - `content` - `notice` - `updated_at` - `published_at` ::: note When writing multilingual documents, only set independent field content for each language. Shared fields only need to be set once. ::: --- ## Heading Hierarchy ```markdown # H1 Heading (Document title, only one per document) ## H2 Heading (Main sections) ### H3 Heading (Subsections) #### H4 Heading (More detailed breakdown) ``` **Best Practices:** - Use only one `#` heading per document - Use `##` and `###` to build document structure - Don't skip heading levels (e.g., from `##` directly to `####`) --- ## Text Formatting ### Emphasis ```markdown **Bold text** *Italic text* ~~Strikethrough text~~ ``` ### Lists **Unordered lists:** ```markdown - First item - Second item - Sub-item - Sub-item ``` **Ordered lists:** ```markdown 1. First step 2. Second step 3. Third step ``` ### Blockquotes ```markdown > This is a blockquote. > Can span multiple lines. ``` ### Horizontal Rule ```markdown --- ``` --- ## Links ### Internal Links Internal document links use the document slug as URL: ```markdown See [CAN Bus Protocol](/docs/can-bus-protocol) for details. ``` ### External Links ```markdown [Visit GitHub](https://github.com/example) ``` ### Anchor Links ```markdown [Jump to Installation Section](#installation-steps) ``` --- ## Images and Media ### Images Reference images in `public/media/` directory using relative paths: ```markdown  ``` Image features: - Automatic responsive scaling - Automatic rounded corners - Alt text automatically displayed as caption ### Video Embedding Use extended syntax to embed videos: ```markdown :::video[Video description](https://bilibili.com/video/BVxxx) ::: ``` Supported platforms: - Bilibili - YouTube - Other standard video URLs ### 3D Models ```markdown :::model[Model name](/media/model.step) ::: ``` ### File Downloads PDF, DOC, STEP, and other files automatically render as download cards: ```markdown [User Manual](/media/manual.pdf) ``` --- ## Code ### Inline Code ```markdown Use the `git clone` command to clone the repository. ``` ### Code Blocks ````markdown ```bash # Install dependencies npm install ``` ```python import os print("Hello, World!") ``` ```json { "name": "example", "version": "1.0.0" } ``` ```` Supported language identifiers: `bash`, `python`, `javascript`, `json`, `yaml`, `cpp`, `csharp`, `java`, `html`, `css`, etc. ### Wiring Diagram Alignment When drawing wiring diagrams in code blocks, left column needs equal-width alignment: **Correct (equal-width alignment):** ``` V+ ———— +16~48VDC V− ———— GND CAN_H ———— CAN 总线高 GND ———— 系统地 ``` **Alignment Rules:** - `————` (full-width em dashes, 2 cells each) must start at the same character column in every row - Each ASCII character = 1 cell, each CJK character = 2 cells - ASCII dashes (`-------`) recommended for simpler alignment --- ## Tables ```markdown | Column 1 | Column 2 | Column 3 | |----------|----------|----------| | Cell 1 | Cell 2 | Cell 3 | | Cell 4 | Cell 5 | Cell 6 | ``` --- ## Callout Blocks (Admonitions) GEO Wiki Pro supports multiple callout types: ```markdown ::: note Additional context information. ::: ::: tip Helpful hints and best practices. ::: ::: warning Important cautions. Renders with yellow border. ::: ::: danger Critical safety information. Renders with red border. ::: ``` --- ## FAQ Blocks ```markdown ::: faq **Q: How do I reset the device?** Press and hold the reset button for 5 seconds. **Q: What is the maximum cable length?** 30 meters for CAN bus at 250 kbps. ::: ``` --- ## Common Errors and Considerations ### 1. Don't Edit File System Directly All file writes must go through `saveDoc()` or `saveDb()`, don't use `fs.writeFileSync` directly. ### 2. Slugs Cannot Be Modified Once created, slugs are used as filenames and URLs. Modifying a slug equals creating a new document. ### 3. Shared Field Sync Updating `category`, `tags`, `author`, `sort` affects all language versions. ### 4. Image Paths Images must be placed in `public/media/` directory, referenced using `/media/filename.ext` paths. ### 5. Encoding Standards All user-visible text must go through `t()` function (i18n), don't hardcode strings. --- ## Writing Checklist - [ ] YAML Frontmatter contains all required fields - [ ] Slug follows naming conventions (ASCII, no special characters) - [ ] Heading hierarchy is correct (one `#`, multiple `##`/`###`) - [ ] Code blocks specify correct language identifiers - [ ] Internal links use `/docs/slug` format - [ ] Images use `/media/` relative paths - [ ] Table format is correct - [ ] Wiring diagrams are aligned - [ ] Callout blocks used for important information - [ ] Description field is concise and search-valuable --- *Last updated: 2026-06-06 | Version: v3.0.2*