博文编写指南¶

第一部分：Markdown 基本语法速查¶

Markdown 是一种轻量级标记语言，广泛用于编写博客、技术文档、README 等。本节简要介绍常用语法，方便快速参考。

1. 标题（Headers）¶

使用 # 表示标题等级（1~6 级）。

# 一级标题
## 二级标题
### 三级标题
#### 四级标题

2. 段落与换行¶

段落之间使用空行分隔。若需强制换行，行末加两个空格：

MkDocs改善

已经通过MkDocs插件改善不需要行末加两个空格

这是第一行。  
这是第二行。

3. 强调（Emphasis）¶

*斜体* 或 _斜体_  → *斜体*  
**加粗** 或 __加粗__  → **加粗**  
***斜体加粗*** → ***斜体加粗***

4. 列表（Lists）¶

无序列表使用 -、+ 或 *

有序列表使用 1. 2. 3.

- 项目 A
- 项目 B
  - 子项 B1

1. 步骤一
2. 步骤二

5. 链接与图片（Links & Images）¶

[链接文本](https://example.com)
![图片说明](./images/sample.png)

6. 引用（Blockquote）¶

> 这是引用内容
>> 可以嵌套引用

7. 代码块（Code）¶

行内代码：使用反引号 `code`

多行代码块：使用三个反引号（可指定语言）

`console.log("Hello")`

```python
print("Hello Markdown")

### 8. 分隔线（Horizontal Rule）
```markdown
---

9. 表格（Tables）¶

| 姓名 | 年龄 |
|------|------|
| 张三 | 25   |
| 李四 | 30   |

10. 任务列表（Task Lists）¶

- [x] 已完成项
- [ ] 待完成项

第二部分：Material for MkDocs 渲染增强语法¶

Material for MkDocs 在标准 Markdown 的基础上，提供了丰富的扩展语法，用于创建结构清晰、美观且功能丰富的文档内容。

1. 提示块（Admonitions）¶

通过 !!! 和 ??? 语法创建边框内容块，用于提示、说明、错误、提示等。

!!! note "重点提示"
    这是一个提示内容

??? info "这是一个问题提示"
    这是问题内容

???+ note "笔记是蓝色"
    内容支持展开收起

!!! bug "bug 是红色"
        用于标记问题说明

!!! example "举例"
        举例展示内容块样式

!!! tip "这是一个提示"
        用于高亮提示技巧、方法等

2. 内容切换（Tabs）¶

用于展示不同平台或语言的代码/说明：

=== "Unix, Powershell"

    ```bash
    docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
    ```

=== "Windows"

    ```powershell
    docker run --rm -it -p "%cd%":/docs squidfunk/mkdocs-material
    ```

还可以嵌入列表、代码块、说明等复合内容：

=== "Unordered list"

    * Item A
    * Item B

=== "Ordered list"

    1. Step 1
    2. Step 2

3. 代码块增强¶

支持带标题、行号、高亮等代码块功能。

```py title="add_numbers.py" linenums="1"
# Function to add two numbers
def add(num1, num2):
    return num1 + num2

result = add(5, 3)
print('The sum is:', result)

```markdown
```js title="concatenate_strings.js" linenums="1" hl_lines="2-4"
// Function to concatenate two strings
function concatenateStrings(str1, str2) {
    return str1 + str2;
}
const result = concatenateStrings("Hello, ", "World!");
console.log("The concatenated string is:", result);

---

### 4. Mermaid 图表支持

Material for MkDocs 支持通过 `mermaid` 绘制流程图、状态图、类图等。

- 横向流程图：

```markdown
```mermaid
graph LR
  A[Start] --> B{Error?}
  B -->|Yes| C[Hmm...]
  C --> D[Debug]
  D --> B
  B ---->|No| E[End]

- 序列图：

```markdown
```mermaid
sequenceDiagram
  autonumber
  Alice->>John: Hello John
  John-->>Alice: Hi Alice

- 状态图：

```markdown
```mermaid
stateDiagram-v2
  state fork_state <<fork>>
  [*] --> fork_state
  fork_state --> State2
  fork_state --> State3
  state join_state <<join>>
  State2 --> join_state
  State3 --> join_state
  join_state --> State4
  State4 --> [*]

- 类图：

```markdown
```mermaid
classDiagram
  Person <|-- Student
  Person <|-- Professor
  class Person {
    +String name
    +String phoneNumber
  }

- ER 图：

```markdown
```mermaid
erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE-ITEM : contains
  LINE-ITEM {
    string name
    int pricePerUnit
  }
  CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

这些增强语法极大提升了 Markdown 文档的表达力，是 Material for MkDocs 的核心优势之一。

第三部分：VS Code 插件配置与使用技巧¶

使用 Visual Studio Code 编写 Markdown 配合 Material for MkDocs，可借助插件大幅提升效率和写作体验。

1. 推荐插件清单¶

插件名称	功能简介
Markdown All in One	支持自动编号、目录生成、列表格式化等常用语法
Markdown Table Prettifier	表格美化对齐、从文本快速转换为表格格式
Paste Image	粘贴截图自动保存图片并生成 Markdown 链接
Markdown Preview Enhanced	高级渲染支持（如公式、Mermaid 图）
Path Intellisense	自动补全本地文件路径（图片、链接等）
YAML	提供 mkdocs.yml 的语法高亮和校验支持
GitLens	Git 历史可视化，便于版本控制和回滚

2. 插件功能与使用方法¶

1. Markdown All in One¶

自动编号：输入 1. 多行后运行命令或快捷键可自动编号
目录生成：插入 [TOC]，保存或运行命令自动更新

快捷键建议：

{
  "key": "ctrl+alt+l",
  "command": "markdown.extension.editing.toggleList",
  "when": "editorLangId == 'markdown'"
}

2. Markdown Table Prettifier¶

功能：对选中表格进行格式化、对齐列宽
转换制表符分隔文本为 Markdown 表格
命令：Markdown Table: Convert Text to Table

3. Paste Image¶

粘贴截图时自动保存到指定目录，并插入相对路径

建议配置：

"pasteImage.path": "${currentFileDir}/assets/images",
"pasteImage.basePath": "${projectRoot}"

4. Markdown Preview Enhanced¶

支持数学公式（KaTeX）、流程图（Mermaid）、图表等
使用方式：代码块中输入特定标记如 mermaid, math

5. YAML¶

对 mkdocs.yml 文件提供格式校验、缩进提示等
避免 mkdocs 配置语法错误造成构建失败

3. 编写习惯建议¶

使用标题结构组织内容，便于目录生成
表格推荐使用 Prettifier 插件统一格式
图片使用 Paste Image，避免手动保存路径
任务列表可追踪待办进度，提升条理性

第四部分：MkDocs 项目结构与部署发布指南¶

本节将展示如何构建一个典型的 MkDocs 项目结构，并介绍如何通过本地或 GitHub Pages 发布博客内容。

1. 推荐项目目录结构¶

my-blog/
├── docs/                      # Markdown 内容目录
│   ├── index.md               # 主页
│   ├── about.md               # 关于页面
│   ├── blog/                  # 博文子目录
│   └── assets/images/         # 图片资源
├── overrides/                 # 自定义模板和样式
│   └── partials/              # MkDocs 模板部件
├── site/                      # 构建输出目录（自动生成）
├── mkdocs.yml                 # 配置文件

2. mkdocs.yml 最小配置示例¶

site_name: 我的博客
theme:
  name: material
nav:
  - 首页: index.md
  - 关于: about.md
  - 博客:
    - 第一篇文章: blog/first-post.md

3. 本地启动预览¶

在项目目录中执行以下命令，即可开启实时预览：

mkdocs serve

浏览器访问：http://localhost:8000

4. 发布到 GitHub Pages¶

方法一：使用命令部署（适合个人博客）¶

mkdocs gh-deploy --force

自动将构建内容发布到 gh-pages 分支
仓库设置中启用 GitHub Pages：来源为 gh-pages 分支

方法二：使用 GitHub Actions 自动部署（推荐）¶

在 .github/workflows/ci.yml 中添加以下内容：

name: Deploy MkDocs

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.x'
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

5. 自定义域名部署（可选）¶

在项目根目录创建 CNAME 文件，内容为你的域名：
```
blog.example.com
```
在 GitHub 仓库设置中绑定该域名，并将 DNS 指向 GitHub Pages

The End