Markdown 文档
概览
掌握 Markdown 语法和最佳实践，用于创建格式良好、易读的文档，使用标准 Markdown 和 GitHub Flavored Markdown (GFM)。
何时使用
- README 文件
- 文档页面
- GitHub/GitLab 维基
- 博客文章
- 技术写作
- 项目文档
- 注释格式化
Markdown 语法参考
标题
# H1 标题
## H2 标题
### H3 标题
#### H4 标题
##### H5 标题
###### H6 标题
替代 H1
==============
替代 H2
--------------
文本格式化
**粗体文本**
__也是粗体__
*斜体文本*
_也是斜体_
***粗斜体***
___也是粗斜体___
~~删除线~~
`行内代码`
> 引用
> 多行
> 在引用中
---
水平分隔线（也可以是 ___ 或 ***）
列表
无序列表：
- 项目 1
- 项目 2
- 嵌套项目 2.1
- 嵌套项目 2.2
- 项目 3
使用星号：
* 项目 1
* 项目 2
使用加号：
+ 项目 1
+ 项目 2
有序列表：
1. 第一项
2. 第二项
1. 嵌套项目 2.1
2. 嵌套项目 2.2
3. 第三项
任务列表（GitHub Flavored Markdown）：
- [x] 完成的任务
- [ ] 未完成的任务
- [ ] 另一项任务
链接和图片
[链接文本](https://example.com)
[带标题的链接](https://example.com "链接标题")
参考风格链接：
[链接文本][reference]
[reference]: https://example.com
自动链接：
<https://example.com>
<email@example.com>
参考风格图片：
![Alt 文本][image-ref]
[image-ref]: image.png
代码块
行内代码：`const x = 5;`
带语言的代码块：
```javascript
function hello(name) {
console.log(`Hello, ${name}!`);
}
def hello(name):
print(f"Hello, {name}!")
npm install
npm start
缩进代码块（4 个空格）： const x = 5; console.log(x);
### 表格
```markdown
简单表格：
| 列 1 | 列 2 | 列 3 |
|----------|----------|----------|
| 行 1 | 数据 | 数据 |
| 行 2 | 数据 | 数据 |
对齐列：
| 左 | 中心 | 右 |
|:-----|:------:|------:|
| 左 | 中心 | 右 |
| 文本 | 文本 | 文本 |
最小表格：
列 1 | 列 2
---------|----------
数据 | 数据
数据 | 数据
扩展语法（GitHub Flavored Markdown）
脚注：
这里有一句带脚注的话[^1]。
[^1]: 这是脚注。
定义列表：
术语
: 定义
表情符号：
:smile: :rocket: :heart:
:+1: :-1: :eyes:
自动 URL 链接：
https://github.com
问题中的任务列表：
- [x] #739
- [ ] https://github.com/octo-org/repo/issues/1
- [ ] 添加测试
提及用户和团队：
@username
@org/team-name
引用问题和 PR：
#123
GH-123
username/repo#123
README 模板
# 项目名称
这个项目是做什么的以及它面向的用户简短描述。
[](https://github.com/user/repo/actions)
[](LICENSE)
[](https://www.npmjs.com/package/package-name)
## 目录
- [特性](#features)
- [演示](#demo)
- [安装](#installation)
- [使用](#usage)
- [API 参考](#api-reference)
- [贡献](#contributing)
- [许可证](#license)
- [联系](#contact)
## 特性
- 特性 1
- 特性 2
- 特性 3
## 演示
在线试用：[https://demo.example.com](https://demo.example.com)
## 安装
### 先决条件
- Node.js 18+
- npm 或 yarn
### 通过 npm 安装
```bash
npm install package-name
通过 yarn 安装
yarn add package-name
从源代码安装
git clone https://github.com/user/repo.git
cd repo
npm install
npm run build
使用
基本使用示例：
import { Package } from 'package-name';
const instance = new Package({
option1: 'value1',
option2: 'value2'
});
instance.doSomething();
高级使用
更复杂的示例：
const result = await instance.advancedMethod({
param1: 'value',
param2: 123
});
console.log(result);
API 参考
Class.method(param1, param2)
描述这个方法的作用。
参数：
param1(string): param1 的描述param2(number): param2 的描述
返回： 返回值的描述
示例：
const result = instance.method('value', 42);
配置
创建一个 .configrc 文件：
{
"setting1": "value1",
"setting2": true,
"setting3": {
"nested": "value"
}
}
贡献
欢迎贡献！请按照以下步骤操作：
- Fork 仓库
- 创建一个功能分支 (
git checkout -b feature/AmazingFeature) - 提交你的更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启一个 Pull Request
请阅读 CONTRIBUTING.md 了解我们的代码行为准则和开发流程的详细信息。
测试
# 运行所有测试
npm test
# 运行并生成覆盖率报告
npm run test:coverage
# 运行监视模式
npm run test:watch
部署
# 为生产构建
npm run build
# 部署
npm run deploy
构建工具
版本控制
我们使用 SemVer 进行版本控制。可用版本请查看这个仓库的 标签。
作者
- 你的名字 - 初始工作 - 你的用户名
同时查看参与这个项目的 贡献者 列表。
许可证
这个项目使用 MIT 许可证 - 详情请参阅 LICENSE 文件。
致谢
- 向任何使用过的代码的人致敬
- 灵感
- 参考资料
支持
- 文档：https://docs.example.com
- 问题：GitHub 问题
- 讨论：GitHub 讨论
- 邮箱：support@example.com
路线图
- [x] 特性 1
- [x] 特性 2
- [ ] 特性 3
- [ ] 特性 4
查看 开放问题 获取完整的功能列表。
FAQ
问题 1？
问题 1 的答案。
问题 2？
问题 2 的答案。
更新日志
查看 CHANGELOG.md 获取更改列表。