好的，没问题。这是一份为您和您的同事准备的 Markdown 使用指南，风格和受众与之前的 Git 文档保持一致。

---

# Markdown 协作书写指南

## 文档说明

本文档面向公司内部所有需要使用 Markdown 语言书写文档的同事。Markdown 是一种轻量级标记语言，允许人们使用易读易写的纯文本格式编写文档，并可转换为有效的 HTML 文档。我们将在 **VSCode** 中编写，并托管在 **Gitea** 上进行版本管理与协作。

## 1. 术语表 (Glossary)

| 术语 | 解释 |
| :--- | :--- |
| **Markdown (.md)** | 一种轻量级标记语言，使用纯文本格式的语法，使其易读、易写，并可转换为结构化的 XHTML/HTML。 |
| **语法 (Syntax)** | 一套规则体系，定义了如何通过简单的符号（如 `#`, `*`, `-` 等）来格式化文本。 |
| **渲染 (Rendering)** | 将 Markdown 源代码解析并转换为可视化的、格式优美的文档（如 HTML、PDF）的过程。 |
| **预览 (Preview)** | 在编写 Markdown 时实时查看其渲染后效果的功能。 |
| **GFM (GitHub Flavored Markdown)** | GitHub（及 Gitea）对标准 Markdown 的扩展，提供了表格、任务列表等实用功能。 |
| **扩展语法 (Extended Syntax)** | 并非所有 Markdown 处理器都支持的额外语法，如表格、脚注、定义列表等。 |

---

## 2. 为什么使用 Markdown？

*   **通用性强**：广泛用于 `README` 文件、论坛帖子、文档、博客、代码注释等。
*   **专注于内容**：无需关心字体、颜色等样式，只需用简单的符号定义结构。
*   **纯文本特性**：意味着：
    *   兼容所有文本编辑器。
    *   非常适合用 **Git** 进行版本控制，差异对比清晰明了。
    *   永远不会因为软件换代而过时。
*   **可转换**：轻松转换为 HTML、PDF、Word 等多种格式。

---

## 3. 核心语法速查表

这是你最常用到的 90% 的语法。

### 3.1. 标题 (Headers)

使用 `#` 的数量来表示标题的级别，从 1 级（最大）到 6 级（最小）。

```markdown
# 一级标题 (H1)
## 二级标题 (H2)
### 三级标题 (H3)
#### 四级标题 (H4)
##### 五级标题 (H5)
###### 六级标题 (H6)
```

### 3.2. 强调 (Emphasis)

```markdown
*这是斜体文本* 或 _这也是斜体文本_
**这是粗体文本** 或 __这也是粗体文本__
***这是粗体加斜体*** 或 ___这也是粗体加斜体___
```

### 3.3. 列表 (Lists)

**有序列表 (Ordered Lists)：** 使用数字加点号
```markdown
1. 第一项
2. 第二项
3. 第三项
```

**无序列表 (Unordered Lists)：** 使用 `-`, `*`, 或 `+`
```markdown
- 列表项
- 另一个列表项
  - 嵌套列表项（缩进两个空格或一个制表符）
```

**任务列表 (Task Lists - GFM 特性)：** 非常适合记录待办事项
```markdown
- [x] 已完成的任务
- [ ] 未完成的任务
```

### 3.4. 链接与图片 (Links & Images)

**链接：**
```markdown
[显示的链接文本](https://www.example.com "悬停提示文本（可选）")
```

**图片：**
```markdown
![图片的替代文本(alt text)](images/logo.png "悬停提示文本（可选）")
```
> **最佳实践**：使用 `source\_images`  文件夹来存放图片, `source\_static`来存放静态数据，并使用**相对路径**引用，这样在 Gitea 上也能正确显示。

### 3.5. 代码 (Code)

**行内代码 (Inline Code)：** 用反引号包裹
```markdown
使用 `git commit` 命令来提交更改。
```

**代码块 (Code Blocks)：** 用三个反引号包裹，并可选指定语言以实现语法高亮
````markdown
```python
def hello_world():
    print("Hello, World!")
```
````

### 3.6. 引用 (Blockquotes)

使用 `>` 符号表示引用。
```markdown
> 这是引用的文本。
> 这是引用的文本。
>
> > 这是嵌套的引用。
```

### 3.7. 表格 (Tables - GFM 特性)

使用连字符 `-` 来分隔表头，管道符 `|` 来分隔列。
```markdown
| 左对齐 | 居中对齐 | 右对齐 |
| :----- | :------: | -----: |
| 单元格 |  单元格  | 单元格 |
| 单元格 |  单元格  | 单元格 |
```

---

## 4. VSCode 中的高效书写

VSCode 对 Markdown 提供了强大的原生支持。

1.  **实时预览 (Preview)**：
    *   打开一个 `.md` 文件。
    *   点击编辑器右上角的 **拆分编辑器** 图标，或按 `Ctrl+K V`（按住 `Ctrl+K`，松开再按 `V`）。
    *   右侧将打开一个实时渲染的预览窗口，与你左侧的编辑同步滚动。

2.  **快捷键与自动补全**：
    *   **加粗**：选中文本，按 `Ctrl+B`。
    *   **斜体**：选中文本，按 `Ctrl+I`。
    *   **代码块**：输入三个反引号 ```` ``` ```` 后按回车，VSCode 会自动补全并让你输入语言类型。
    *   **列表**：输入 `- ` 或 `1. ` 后，按回车会自动创建下一项。

3.  **目录生成 (TOC)**：
    *   有许多扩展可以自动根据标题生成目录（如 `Markdown All in One`）。
    *   在 Gitea 中，仓库的 `README.md` 文件会自动根据标题生成目录。

4.  **代码格式化**：
    *   安装 `Markdownlint` 等扩展，它可以帮你自动格式化 Markdown 文档并标记出不符合规范的写法。

---

## 5. 与 Gitea/Git 的协作

1.  **版本控制**：`.md` 文件是纯文本文件，非常适合用 Git 管理。每次对文档的修改（修正错别字、增加章节）都可以清晰地通过 `git diff` 看到。

2.  **Gitea 渲染**：Gitea 完全支持 GFM。你推送至 Gitea 的任何 `.md` 文件都会在网页上被自动渲染成美观的文档。

3.  **使用 Issues 和 PR 协作修改文档**：
    *   发现文档错误或想贡献内容？和代码一样：
        1.  **Fork** 或 **Clone** 仓库。
        2.  基于 `main` 分支创建一个新分支（如 `docs/fix-typo`）。
        3.  修改 `.md` 文件。
        4.  提交更改，写清提交信息（如 `[Docs] 修复用户手册中的拼写错误`）。
        5.  推送分支并发起 **Pull Request (PR)**。
    *   其他同事可以在 PR 中对文档修改进行**评审（Review）**，提出建议。

---

## 6. 最佳实践与规范

1.  **保持简洁**：Markdown 的哲学是易读易写。不要滥用复杂格式。
2.  **标题层级**：从 `H1` 开始，按顺序使用，不要跳级。
3.  **中英文混排**：中英文之间加一个空格，例如：“学习 Markdown 语言” 而不是 “学习Markdown语言”。
4.  **统一的图片管理**：在项目根目录建立 `assets` 或 `images` 文件夹，所有图片统一放入。
5.  **行尾不要留空格**：这可能会在某些渲染器中导致意外的换行。
6.  **善用代码块**：对于命令行操作、配置代码等，务必使用代码块，提高可读性。

现在，你可以开始使用 Markdown 高效、优雅地书写所有文档了！