1.8 Markdown

1. What Is Markdown

Markdown is a lightweight markup language: with a handful of symbols such as #, *, -, and [ ], you can add structure like headings, lists, links, and code blocks to plain text. The source file is still plain text (usually with a .md extension), and it renders into a well-formatted document.

It is precisely this "plain text, yet structured" property that makes it almost the default choice in technical writing:

• Notes: lighter than Word, more structured than TXT
• Documents: READMEs, API documentation, and technical proposals often use it
• Blogs: tools like GitHub Pages, Hexo, and Hugo can all use Markdown as the content source

2. Basic Syntax

2.1 Headings

Use # for headings; the count corresponds to the level:

# Level-1 Heading
## Level-2 Heading
### Level-3 Heading
#### Level-4 Heading

2.2 Paragraphs and Line Breaks

In Markdown, paragraphs need to be separated by a blank line. A single Enter press (without a blank line) is treated as a soft break inside the same paragraph and may be merged when rendered.

This is the first paragraph.

This is the second paragraph.

2.3 Emphasis

2.4 Lists

Use -, *, or + for unordered lists:

- First item
- Second item
    - Nested subitem (indented after the parent list content)
    - Another subitem
- Third item

Use numbers followed by a period for ordered lists:

1. First step
2. Second step
3. Third step

2.5 Links and Images

[Link text](https://example.com)
![Image description](image path or URL)

Image syntax is link syntax with one more !. The image description is used as alt text, and the path can be a relative path or a URL; when the path contains special characters such as spaces, escape or encode it according to the rules of the target renderer.

2.6 Blockquotes

Use > for blockquotes:

> This is a blockquote.
> It can span multiple lines.

Result:

This is a blockquote. It can span multiple lines.

2.7 Horizontal Rules

Use three or more - or *:

---

Technical documents often use code blocks and tables; both are explained below.

3. Code Blocks

3.1 Inline Code

Wrap with backticks: `code` renders as code.

3.2 Code Blocks

Wrap with three backticks and specify the language on the first line to enable syntax highlighting:

```python
def hello():
    print("Hello, World!")
```

Result:

def hello():
    print("Hello, World!")

3.3 Showing Backticks Inside a Code Block

When the code content itself contains triple backticks, wrap it with four backticks on the outside:

````markdown
```python
print("inner code block")
```
````

4. Tables

Common extensions such as GFM separate columns with | and use a separator row to distinguish the header from the content:

| Name | Age | Major |
| :--- | :---: | ---: |
| SSJ | 20 | Computer Science |
| SSSJ | 21 | Software Engineering |

Result:

Alignment:

5. Task Lists

- [x] Completed task
- [ ] Uncompleted task
- [ ] Another uncompleted task

They suit to-do lists and practice checklists.

6. Escape Characters

Markdown supports escaping some ASCII punctuation with a backslash. Whether a character can or needs to be escaped depends on the syntactic position; for example, | in a table usually needs escaping:

\*This is not italic\*    \# This is not a heading

Result: *This is not italic* # This is not a heading

Different platforms add extensions such as tables, task lists, and math formulas on top of the core syntax; compatibility depends on the target renderer.

7. Extended Syntax

Different Markdown renderers support different extended syntax; this section introduces a few common ones.

7.1 GitHub Flavored Markdown (GFM)

GitHub Flavored Markdown (GFM) adds a set of extensions on top of CommonMark; this project also enables the common GFM syntax, including:

• Task lists (see above)
• Tables (see above)
• Strikethrough (~~text~~)
• Autolinks (URLs become links automatically)

7.2 Alerts / Callouts

This project uses GitHub-style alerts; different types map to different styles:

> [!NOTE]
> This is a note.

> [!TIP]
> This is a tip.

> [!WARNING]
> This is a warning.

> [!IMPORTANT]
> This is important information.

7.3 Collapsible Details Blocks

This project also provides collapsible blocks suitable for answers, supplementary explanations, and longer examples:

> [!DETAILS-HINT] View the hint
> Put supplementary information that does not affect the main reading flow here.

> [!DETAILS-ANSWER] View the answer
> Put the exercise answer or reference implementation here.

7.4 Math Formulas

Some platforms (including this project) support math formulas written in LaTeX syntax, wrapped with $:

Inline formula: $E = mc^2$

Block formula:
$$
\int_0^1 x^2 dx = \frac{1}{3}
$$

Besides correct syntax, technical documents also need a clear structure and verifiable examples.

8. Writing Conventions

8.1 Clear Structure

• Use only one H1 per article (this project does not use H1; it starts from H2)
• Do not skip levels (going straight from H2 to H4 is a bad habit)
• Each section focuses on one topic; do not cram too much

8.2 Chinese-English Typography

Add a half-width space between Chinese and English or digits to improve readability:

# Good
Write programs with Python 3.12

# Bad
Write programs with Python3.12

This is also this project's convention; see Contributing Guide for details.

8.3 Examples and Explanations Working Together

Commands, configurations, and API behavior are best shown with runnable examples, while keeping the necessary prerequisites, risks, and expected results. With only descriptions and no examples, readers often find it hard to verify whether an operation is correct.

Good approach — write a lead-in sentence, followed by a code block:

Use git status to check the status:

git status

Bad approach — describe in words what could have been shown with code:

We can check the status of the current repository by typing git followed by the status subcommand in the terminal.

8.4 Use Descriptive Link Text, Not "Here"

# Good
See the [Contributing Guide](/en/docs/about/contributing)

# Bad
See the contributing guide, [click here](/en/docs/about/contributing)

9. Recommended Tools

10. Further Reading

For more syntax examples, see this project's Markdown Syntax Examples. To learn the project's specific conventions, see the Contributing Guide.

When you need to write complex math formulas or fully typeset documents, continue with 1.9 LaTeX; for complex diagrams, use 1.10 Mermaid to draw flowcharts and sequence diagrams directly in Markdown.

11. TODO Checklist

• Can organize a short article with headings, lists, links, images, tables, and code blocks
• All code blocks are tagged with the correct language
• Remember that heading levels must be consecutive, and link text describes the target content
• Can choose between a regular callout and a collapsible details block based on content importance
• Try previewing and checking the final result in the target renderer

12. Questions Worth Thinking About