# Markdown Writing Guide # Markdown Writing Guide > A complete guide to writing high-quality technical documentation | v1.0.4 --- ## YAML Frontmatter (Required) Every document must begin with YAML frontmatter: ```yaml --- title: Document Title slug: url-friendly-slug category: category-slug tags: [tag1, tag2] author: admin sort: 1 description: Short summary (important for SEO) language: en notice: "Optional notice banner" --- ``` ### Field Reference | Field | Required | Description | |------|----------|-------------| | `title` | Yes | Document title | | `slug` | Yes | URL identifier (letters, numbers, hyphens, underscores only; max 200 characters) | | `category` | Yes | Category slug (must already exist) | | `tags` | Yes | Array of tags `[tag1, tag2]` | | `author` | Yes | Author name | | `sort` | No | Sort order (integer, ascending, default 999) | | `description` | No | Summary for search results | | `notice` | No | Notice banner text | | `language` | No | Language code (zh/en/jp) | ::: warning Once created, a slug cannot be changed because it is used as the filename and URL path. ::: --- ## Basic Markdown Syntax ### Headings ```markdown # Heading 1 (one per document) ## Heading 2 ### Heading 3 #### Heading 4 ``` ### Text Formatting ```markdown **Bold** | *Italic* | ~~Strikethrough~~ | ==Highlight== ``` ### Lists ```markdown - Unordered list - Sub-item 1. Ordered list 2. Second item - [x] Completed task - [ ] Pending task ``` ### Blockquotes and Horizontal Rules ```markdown > Quoted text --- ``` ### Links ```markdown [Internal link](/docs/slug) [External link](https://example.com) [Anchor link](#section-id) ``` ### Tables ```markdown | Column 1 | Column 2 | Column 3 | |----------|----------|----------| | Data | Data | Data | ``` ### Footnotes ```markdown This is a sentence with a footnote[^1]. [^1]: This is the footnote content, displayed at the bottom of the page. ``` Footnotes are automatically rendered at the bottom of the document with a separator and numbering. --- ## Code Blocks ### Basic Code Blocks ````markdown ```bash npm install ``` ```javascript console.log("Hello"); ``` ```json { "key": "value" } ``` ```` ### Supported Languages `bash`, `javascript`, `python`, `json`, `yaml`, `css`, `html`, `sql`, `go`, `java`, `rust`, `cpp`, `shell`, `dockerfile`, `nginx` ### Tabbed Code Blocks Combine consecutive code blocks into a tabbed view by adding `// [TabName]` after the language identifier: ````markdown ```bash // [Bash] npm install geowiki-cli ``` ```python // [Python] import requests response = requests.get("https://api.example.com") ``` ```javascript // [JavaScript] fetch("https://api.example.com") .then(res => res.json()) ``` ```` Rendered result: tab buttons appear at the top of the code blocks, allowing you to switch between different language implementations. ::: tip Tabbed code blocks are ideal for showing the same functionality implemented in multiple languages. ::: --- ## Mermaid Diagrams Use the `mermaid` language identifier to create flowcharts, sequence diagrams, Gantt charts, and more: ### Flowchart ````markdown ```mermaid graph TD A[Start] --> B{Decision} B -->|Condition 1| C[Process 1] B -->|Condition 2| D[Process 2] C --> E[End] D --> E ``` ```` ### Sequence Diagram ````markdown ```mermaid sequenceDiagram participant A as User participant B as Server A->>B: Send request B->>A: Return response ``` ```` ### Gantt Chart ````markdown ```mermaid gantt title Project Plan section Phase 1 Requirements: 2026-01-01, 7d Design: 2026-01-08, 5d section Phase 2 Development: 2026-01-13, 14d Testing: 2026-01-27, 7d ``` ```` ### Class Diagram ````markdown ```mermaid classDiagram class User { +String name +String email +login() } class Post { +String title +String content +publish() } User --> Post : writes ``` ```` ::: note Mermaid diagrams automatically adapt to dark mode without any extra configuration. ::: --- ## ECharts Charts Use the `echarts` language identifier to create interactive charts: ### Bar Chart ````markdown ```echarts { "title": { "text": "Monthly Visits" }, "tooltip": {}, "xAxis": { "data": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"] }, "yAxis": {}, "series": [{ "name": "Visits", "type": "bar", "data": [120, 200, 150, 80, 70, 110] }] } ``` ```` ### Line Chart ````markdown ```echarts { "title": { "text": "Trend Analysis" }, "tooltip": { "trigger": "axis" }, "xAxis": { "type": "category", "data": ["Mon", "Tue", "Wed", "Thu", "Fri"] }, "yAxis": { "type": "value" }, "series": [{ "name": "Data", "type": "line", "data": [100, 150, 130, 180, 160] }] } ``` ```` ### Pie Chart ````markdown ```echarts { "title": { "text": "Traffic Sources" }, "tooltip": { "trigger": "item" }, "series": [{ "name": "Source", "type": "pie", "radius": "50%", "data": [ { "value": 335, "name": "Direct" }, { "value": 310, "name": "Search Engine" }, { "value": 234, "name": "Social Media" } ] }] } ``` ```` ::: tip ECharts charts support interactive operations — hover to see detailed data. Charts automatically adapt to dark mode. ::: --- ## Grid Layout Use `:::grid` to create responsive grid layouts, ideal for displaying images or content blocks side by side: ### Basic Grid ```markdown :::grid{cols=2} Content block 1 Content block 2 ::: ``` ### Card-Style Grid ```markdown :::grid{cols=3 style=card} Card content 1 Card content 2 Card content 3 ::: ``` | Parameter | Description | Default | |-----------|-------------|---------| | `cols` | Number of columns (1-6) | 2 | | `style` | Style (default / card) | default | ::: note Each content block separated by a blank line becomes a grid cell. Supports 1 to 6 columns. ::: --- ## Extended Syntax ### Callouts ```markdown ::: note Additional context that supplements the main text. ::: ::: tip Helpful hints or best practices. ::: ::: warning Important cautions or things to watch out for. ::: ::: danger Critical safety information. ::: ``` ### FAQ Blocks ```markdown ::: faq **Q: First question?** Answer to the first question. **Q: Second question?** Answer to the second question. ::: ``` ### Math Formulas Inline formula: `$E=mc^2$` Block-level formula: ```markdown $$ \int_{a}^{b} f(x) dx = F(b) - F(a) $$ ``` ### Video Embedding ```markdown :::video[Video description](https://bilibili.com/video/BVxxx) ::: ``` ### 3D Models ```markdown :::model[Model name](/media/model.step) ::: ``` ### File Downloads PDF, DOC, and other files are automatically rendered as download cards: ```markdown [User Manual](/media/manual.pdf) ``` ### Images Images are automatically responsive, and alt text is displayed as a caption: ```markdown  ``` --- ## Callout Types | Type | Usage | Border Color | |------|-------|--------------| | `::: note` | Supplementary information | Blue | | `::: tip` | Tips and suggestions | Green | | `::: warning` | Important cautions | Yellow | | `::: danger` | Safety warnings | Red | --- ## Frequently Asked Questions **Q: Can a slug be changed after creation?** A: No. A slug is used as the filename and URL path, so changing it would create a new document. **Q: How do I edit a document in a different language?** A: Use the CLI with the language flag: `geo doc update --slug xxx --lang en` **Q: Where should I put images?** A: Place them in the `public/media/` directory and reference them as `/media/filename.ext`. **Q: How do I add line numbers to code blocks?** A: Line numbers are added automatically — no manual configuration needed. **Q: How many tabs are supported in tabbed code blocks?** A: It is recommended to use no more than 5 tabs; too many can affect the display. **Q: What chart types does ECharts support?** A: All ECharts 5 chart types are supported: bar, line, pie, scatter, radar, heatmap, and more. --- *Last updated: 2026-06-22 | Version: v1.0.4*