Manlink_Doc/Readme/markdown.md

好的，没问题。这是一份为您和您的同事准备的 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 级（最小）。

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

3.2. 强调 (Emphasis)

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

3.3. 列表 (Lists)

有序列表 (Ordered Lists)： 使用数字加点号

1. 第一项
2. 第二项
3. 第三项

无序列表 (Unordered Lists)： 使用 -, *, 或 +

- 列表项
- 另一个列表项
  - 嵌套列表项（缩进两个空格或一个制表符）

任务列表 (Task Lists - GFM 特性)： 非常适合记录待办事项

- [x] 已完成的任务
- [ ] 未完成的任务

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

链接：

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

图片：

![图片的替代文本(alt text)](images/logo.png "悬停提示文本（可选）")

最佳实践：使用 source\_images 文件夹来存放图片, source\_static来存放静态数据，并使用相对路径引用，这样在 Gitea 上也能正确显示。

3.5. 代码 (Code)

行内代码 (Inline Code)： 用反引号包裹

使用 `git commit` 命令来提交更改。

代码块 (Code Blocks)： 用三个反引号包裹，并可选指定语言以实现语法高亮

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

3.6. 引用 (Blockquotes)

使用 > 符号表示引用。

> 这是引用的文本。
> 这是引用的文本。
>
> > 这是嵌套的引用。

3.7. 表格 (Tables - GFM 特性)

使用连字符 - 来分隔表头，管道符 | 来分隔列。

| 左对齐 | 居中对齐 | 右对齐 |
| :----- | :------: | -----: |
| 单元格 |  单元格  | 单元格 |
| 单元格 |  单元格  | 单元格 |

---

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 高效、优雅地书写所有文档了！