yuysh
66285a56cf
Build Sphinx Documentation / Build Documentation from PR Branch (pull_request) Successful in 2m0s
184 lines
6.8 KiB
Markdown
184 lines
6.8 KiB
Markdown
|
||
好的，没问题。这是一份为您和您的同事准备的 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
|
||
|
||
```
|
||
> **最佳实践**：使用 `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 高效、优雅地书写所有文档了！ |