Languages: 简体中文 · English · 日本語 · 繁體中文

---

{{项目名}} Style Guide

Basic Information

Attribute	Value
Book Title	{{书名}}
Target Audience	{{读者画像}}
Source Project	{{项目名}} {{版本号}}
Programming Language	{{语言}}
Estimated Chapters	{{章节数}}
Words per Chapter	{{最低字数}}–{{最高字数}} words
Project Repository	{{仓库URL}}

Writing Style

• Point of view: First-person plural ("we")
• Tone: {{Style description}}
• Metaphor density: At least one metaphor per core concept
• Humor level: {{None / Occasional / Moderate / Frequent}}
• Reader address: {{e.g. "you" / "the reader" / "fellow developers"}}

Style Example

{{Sample paragraph}}

Prohibited Expressions

• ❌ {{Prohibited expression 1, e.g. "as everyone knows"}}
• ❌ {{Prohibited expression 2, e.g. "obviously"}}
• ❌ {{Prohibited expression 3, e.g. "simply put" followed by something very complex}}

Formatting Rules

Heading Levels

Level	Purpose	Count Limit	Example
H1 (#)	Chapter title	One per chapter	# Chapter 3: The Secret of Middleware
H2 (##)	Major section	3–6 per chapter	## The Life of a Request
H3 (###)	Subsection	As needed	### Route Matching Algorithm
H4 (####)	Avoid using	Refactor if too deep	—

Code Block Rules

• Language must be specified: ```
• Add comments on key lines: explain "why," not "what"
• Single code block must not exceed 30 lines
• Use ellipsis for long code: // ...omit code related to ... and explain what was omitted
• Annotate file path: above the code block, note the source file path

Paragraph Control

• No paragraph longer than 5 lines
• Avoid 3 or more consecutive paragraphs of pure text (intersperse code / diagrams / lists)
• Open each section with a story / question / hook
• End each H2 section with a transitional sentence connecting to what follows

Diagram Rules

Rule: Wherever a flowchart, architecture diagram, hierarchy diagram, or directory tree is needed, always use Mermaid. ANSI box-drawing characters (┌ ─ ┤ ├ └ │) are prohibited.

• Flowcharts for {{flow-type scenarios, e.g. request processing flow}}
• Class diagrams for {{structural scenarios, e.g. module dependency relationships}}
• Every diagram must have a title and a brief description

Common diagram types:

Scenario	Diagram Type	Directive
Vertical layered architecture (e.g., layered architecture diagram)	flowchart	flowchart TD
Horizontal processing flow	flowchart	flowchart LR
Reading roadmap / multi-step sequence	flowchart	flowchart TD + -->
File directory tree	graph	graph LR
Side-by-side category comparison	flowchart	flowchart LR + category nodes
Grouped / subsystem layout	flowchart + subgraph	subgraph name["…"]

Syntax notes:

• Labels containing spaces, non-ASCII characters, or parentheses must be quoted: node["Layer 6: Entry (CLI)"]
• Multi-line labels use <br/>: node["Line one<br/>Line two"] (\n is not supported in Mermaid)
• Node IDs use only ASCII letters/numbers — no non-ASCII characters
• **bold** Markdown syntax is not supported inside labels; use plain text

Special Callouts

• 💡 Tip: Supplementary knowledge that enriches understanding
• ⚠️ Caution: Common pitfalls
• 🔍 Deep Dive: An optional deeper exploration that can be skipped
• 📝 Exercise: Suggestions for hands-on practice

Terminology Rules

Terms Kept in English

{{List, e.g.: Promise, callback, middleware, event loop, closure}}

Translated Terms

English	Translation
{{英文术语1}}	{{中文翻译1}}
{{英文术语2}}	{{中文翻译2}}

Term Usage Rules

1. First appearance: Chinese translation (English Original)
2. Subsequent appearances: use only the Chinese translation or only the English form (per the convention above)
3. In headings: prefer the Chinese translation with English in parentheses
4. In code comments: follow the code's language

Sensitive Content Guidelines

• ❌ Do not evaluate commercial products against each other (e.g., "Framework X is better than Framework Y")
• ❌ Do not touch political / religious / gender topics
• ❌ Avoid absolute statements ("the best," "the only," "you must always")
• ✅ Keep technical comparisons objective — state only facts and data
• ✅ Cite sources when referencing others' opinions

Chapter Structure Template

# Chapter {{N}}: {{章标题}}

## Opening Hook (200–300 words)
<!-- Introduce with a story / question / cliffhanger. For example:
  "Imagine you're debugging a production issue. The logs show the request
   reached the server, but the response has mysteriously vanished. You checked
   the routes, you checked the middleware, everything looks fine. Until you
   opened the source code of {{模块}}..."
-->

## {{节标题1}}
<!-- First core knowledge point -->

## {{节标题2}}
<!-- Second core knowledge point -->

## {{节标题3}}
<!-- Third core knowledge point. Aim for 3–5 H2 sections per chapter -->

## Code Walkthrough
<!-- Annotated key code segments, explained step by step -->

## Design Thinking
<!-- Why did the author design it this way? What alternatives exist? What trade-offs were made? -->

## Summary
<!-- Under 200 words; recap chapter highlights in list form -->

## Discussion Questions (optional)
<!-- 2–3 thought-provoking questions — not exam questions, but prompts for deeper reflection -->
1. {{问题1}}
2. {{问题2}}

Cross-Reference Rules

• Forward reference: "We will discuss this topic in detail in Chapter {{N}}"
• Backward reference: "As described in Chapter {{N}}, ..."
• Avoid circular references (A references B, B references A)

Versioning and Updates

• When the source project releases a new version: {{handling strategy, e.g. "update only affected chapters"}}
• Erratum process: {{e.g. "record in audit-log.md; correct in the next review cycle"}}