| name | formatting |
| description | MDX formatting standards for marvinzhang.dev blog articles. Covers frontmatter, comments, truncate markers, admonitions, bold formatting (critical for Chinese), Mermaid diagram styling with semantic colors, tables, code blocks, and section structure. Load this skill for any content creation or formatting fixes. |
| metadata | {"author":"marvinzhang","version":"2.0","tier":"foundation","platform":"Docusaurus 3.8.1"} |
Formatting Standards
MDX syntax, visual elements, and structure guidelines for marvinzhang.dev.
MDX Syntax
Frontmatter
---
slug: article-slug
title: "Article Title"
authors: ["marvin"]
tags: ["tag1", "tag2"]
date: YYYY-MM-DD
unlisted: true
---
Comments & Markers
{/* JSX comments, not HTML comments */}
{/* truncate */} {/* Add after introduction */}
Admonitions
:::note Title
Content here
:::
:::tip
Helpful tip content
:::
:::warning
Warning content
:::
Bold Formatting (Critical for Chinese)
Multiple bold sections on same line — add space before second **:
✅ 这与 **语法属性（Syntactic Properties）** 形成对比
❌ 这与**语法属性（Syntactic Properties）**形成对比
Bold with quotes — add spaces inside bold markers:
✅ ** "所有程序行为" ** 是一个语义属性
❌ **"所有程序行为"** 是一个语义属性
Validation: pnpm run validate:zh-bold-source before committing.
Visual-First Approach
- Mermaid diagrams: For processes, flows, architectures
- Tables: For all comparisons and feature lists
- Minimal code: ≤10 lines only when syntax is the learning point
Mermaid Theme-Aware Styling
Always style nodes explicitly for light/dark mode:
flowchart TD
A[Start] --> B[Process]
style A fill:#e1f5fe,stroke:#01579b,color:#01579b
style B fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32
Color semantics:
| Purpose | Fill | Stroke | Use For |
|---|
| Info | #e1f5fe | #01579b | Starting points, inputs |
| Success | #e8f5e9 | #2e7d32 | Completion, positive outcomes |
| Warning | #fff3e0 | #e65100 | Caution, processing |
| Error | #ffebee | #c62828 | Failures, negative states |
| Highlight | #f3e5f5 | #7b1fa2 | Key concepts, emphasis |
Section Structure
| Section Type | Words | Purpose |
|---|
| Introduction | 300-500 | Hook + context + roadmap |
| Main Section | 600-1000 | One concept with depth |
| Conclusion | 250-400 | Summary + takeaways |
Each main section: clear H2, opening hook, core concept (bolded), visual element, transition.
File Locations
| Content | Path |
|---|
| English | blog/YYYY-MM-DD-slug.mdx |
| Chinese | i18n/zh/docusaurus-plugin-content-blog/YYYY-MM-DD-slug.mdx |
References
