​

Markdown syntax

​

Basic Syntax

​

Headings

# 一级title
## 二级title
### 三级title
#### 四级title
##### 五级title
###### 六级title

​

Emphasis

*斜体* 或 _斜体_
**粗体** 或 __粗体__
***粗斜体*** 或 ___粗斜体___
~~Removed线~~

​

list

​

Unordered lists

- 项目1
- 项目2
  - 子项目2.1
  - 子项目2.2
- 项目3

* 也可以用星号
+ 或者加号

​

Ordered lists

1. 第一项
2. 第二项
3. 第三项
   1. 子项3.1
   2. 子项3.2

​

Link

[Link文本](https://example.com)
[带title's Link](https://example.com "鼠标悬停显示")

# 自动Link
<https://example.com>
<email@example.com>

# Reference式Link
[Link文本][ref]
[ref]: https://example.com

​

Images

![替代文本](image.jpg)
![带title's 图片](image.jpg "图片title")

# 图片Link
[![图片](image.jpg)](https://example.com)

​

Blockquotes

> 这is一段Reference
> 可以有多行

> 多级Reference
>> 第二级
>>> 第三级

​

Code

​

Inline code

使用 `反引号` Package裹代码

​

Code blocks

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

```javascript
console.log("Hello World");
```

​

Horizontal rules

---
***
___

​

Tables

| Left aligned | Centered | Right aligned |
|:-------|:----:|-------:|
| Content 1 | Content 2 | Content 3 |
| 内容4  | 内容5 | 内容6 |

​

Task lists

- [x] FinishedTask
- [ ] Unfinished task
- [ ] 另aTask

• FinishedTask
• Unfinished task

​

Footnotes

这is一段文字[^1]

[^1]: 这is脚注内容

​

Github Flavored Markdown (GFM)

​

Syntax highlighting

```python
def hello():
    print("Hello")
```

​

Emoji

:smile: :heart: :+1: :rocket:

​

@mentions and issue references

@username
#123

​

Automatic links

https://github.com

​

Diff code blocks

```diff
- Removed line
+ Added line
```

​

Collapsible content

<details>
<summary>点击展开</summary>

This is hidden content

</details>

​

Alert boxes (newer GitHub feature)

> [!NOTE]
> Useful information users should know.

> [!TIP]
> Suggestions that help users succeed.

> [!IMPORTANT]
> Critical information for successful use.

> [!WARNING]
> Urgent information that needs immediate attention.

> [!CAUTION]
> Potential negative consequences of an action.

​

Mathematical formulas

行内公式：$E = mc^2$

块级公式：
$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

​

Mermaid diagrams

```mermaid
graph TD
    A[开始] --> B{判断}
    B -->|is| C[执行]
    B -->|否| D[结束]
    C --> D
```

​

Advanced tips

​

HTML embedding

<div align="center">
  <img src="image.jpg" width="300">
</div>

<kbd>Ctrl</kbd> + <kbd>C</kbd>

<mark>高亮文本</mark>

​

Escaping characters

\* 不is斜体
\# 不istitle
\[ 不isLink

​

Anchor links

[跳转到title](#titlename)

# Chinese title会被转为拼音或其他形式

​

Badges

![GitHub stars](https://img.shields.io/github/stars/user/repo)
![License](https://img.shields.io/badge/license-MIT-blue)

​

Table of contents

[TOC]

# 某些Editor Supportautomatically generates目录

​

Common tools

• Editors: Typora, VS Code, Obsidian
• Online editors: StackEdit, Dillinger
• Formatting: Prettier, markdownlint
• Conversion: Pandoc (Markdown to PDF/Word/HTML)

​

Best Practices

1. Keep it simple: Markdown works best when it stays lightweight.
2. Use headings well: keep the hierarchy clear.
3. Use code highlighting: specify languages for better readability.
4. Optimize images: keep image sizes under control.
5. Preview often: check the rendered result after writing.
6. Version control: Markdown works very well with Git.
7. Check links: make sure all links work.
8. Consider HTML for rich Agent output: When AI agents generate long documents with tables, diagrams, and interactive elements, HTML may be more expressive than Markdown (see below).

​

HTML vs Markdown for Agent Output

​

When Markdown is still the right choice

• Short documents (under ~100 lines) — Markdown remains the simplest format
• Config files, READMEs, changelogs — Git-friendly, easy to diff
• Knowledge base pages (like this site) — Mintlify/Jekyll render Markdown beautifully
• Team wikis — Where version control and collaborative editing are important

​

When HTML has advantages

​

Five practical use cases for HTML

1. Planning & exploration — Generate an “HTML file network”: 6 directions side-by-side, then mockups, then an implementation plan
2. Code review — Render diff, inline annotations, and flow charts in one page
3. Design prototyping — HTML as design intermediate language, then translate to React/Swift
4. Reports & learning — Cross-source synthesis with interactive explanations or slides
5. Disposable editors — A throwaway UI for one task (reorder 30 tickets, toggle feature flags, adjust system prompt) with an “Export as JSON/prompt” button

​

Tradeoffs

• Generation time — HTML takes 2–4× longer to generate than Markdown
• Token cost — Higher, but less relevant with 1M+ context windows
• Version control — HTML diff is noisy and hard to review — this is Markdown’s biggest remaining advantage
• Style consistency — Requires a “design system HTML file” as reference to constrain aesthetics

​

References

• Markdown Guide
• GitHub Markdown documentation
• CommonMark Specification
• Markdown Cheatsheet