欢迎使用企业技术文档平台

本平台使用 Markdown 保存文档，并使用 Primer 进行页面渲染。

本文档同时作为 Markdown 常用语法示例，可用于快速了解平台支持的文档编写方式。

平台功能

• 网页编辑
• 实时预览
• Git 历史
• 文档发布
• Markdown 文件管理
• 代码语法高亮
• 表格与任务列表
• 提示信息块
• 文档版本追踪

Markdown 常用语法

1. 标题

Markdown 使用 # 表示标题。

1
2
3
4
5
6
7
8
9
10
11# 一级标题

## 二级标题

### 三级标题

#### 四级标题

##### 五级标题

###### 六级标题

实际效果如下：

一级标题

二级标题

三级标题

四级标题

五级标题

六级标题

2. 普通文本

Markdown 中直接输入文字即可形成正文。

1
2
3这是一段普通文本。

这是另一段文本。

段落之间建议保留一个空行。

3. 粗体

使用两个星号 ** 包裹文字：

1**这是粗体文字**

效果：

这是粗体文字

4. 斜体

使用一个星号 * 包裹文字：

1*这是斜体文字*

效果：

这是斜体文字

5. 粗斜体

使用三个星号 *** 包裹文字：

1***这是粗斜体文字***

效果：

这是粗斜体文字

6. 删除线

使用两个波浪线 ~~ 包裹文字：

1~~这是一段被删除的内容~~

效果：

这是一段被删除的内容

7. 行内代码

使用反引号 ` 包裹代码、参数、变量或命令：

1使用 `npm run dev` 启动开发服务器。

效果：

使用 npm run dev 启动开发服务器。

变量、文件名和配置项也推荐使用这种形式，例如：

1修改 `CONTENT_DIR` 配置后重新启动服务。

8. 无序列表

可以使用 -、* 或 + 创建无序列表。

1
2
3
4- 用户管理
- 文档管理
- 权限管理
- 系统设置

效果：

• 用户管理
• 文档管理
• 权限管理
• 系统设置

多级无序列表

1
2
3
4
5
6
7- 文档管理
  - 创建文档
  - 编辑文档
  - 删除文档
- 用户管理
  - 创建用户
  - 修改用户

效果：

• 文档管理

  • 创建文档
  • 编辑文档
  • 删除文档

• 用户管理

  • 创建用户
  • 修改用户

9. 有序列表

使用数字加英文句点：

1
2
3
41. 安装依赖
2. 配置数据库
3. 启动服务
4. 打开管理后台

效果：

1. 安装依赖
2. 配置数据库
3. 启动服务
4. 打开管理后台

多级有序列表

1
2
3
4
5
6
71. 安装项目
   1. 下载代码
   2. 安装依赖
2. 配置项目
   1. 配置数据库
   2. 配置环境变量
3. 启动项目

10. 混合列表

有序列表和无序列表可以组合使用：

1
2
3
4
5
6
7
8
9
101. 前端
   - React
   - TypeScript
   - Primer
2. 后端
   - Node.js
   - PostgreSQL
3. 运维
   - Docker
   - Nginx

效果：

1. 前端

   • React
   • TypeScript
   • Primer

2. 后端

   • Node.js
   • PostgreSQL

3. 运维

   • Docker
   • Nginx

11. 任务列表

任务列表适合用于开发计划、发布检查和项目进度管理。

1
2
3
4- [x] 创建文档
- [x] 完成内容审核
- [ ] 发布文档
- [ ] 配置生产环境

效果：

• 创建文档
• 完成内容审核
• 发布文档
• 配置生产环境

12. 链接

基本语法：

1[显示文字](https://example.com)

例如：

1访问 [GitHub](https://github.com/) 查看项目代码。

也可以直接书写 URL：

1https://github.com/

13. 图片

图片语法与链接类似，只需要在前面增加 !：

1![图片说明](https://example.com/image.png)

例如：

1![系统架构图](./images/architecture.png)

推荐为图片填写有意义的说明文字，便于无障碍访问和后续维护。

14. 引用

使用 > 创建引用：

1> 这是一段引用内容。

效果：

这是一段引用内容。

多行引用

1
2
3> 企业技术文档应该保持结构清晰。
>
> 重要配置应该说明用途和注意事项。

效果：

企业技术文档应该保持结构清晰。

重要配置应该说明用途和注意事项。

嵌套引用

1
2
3> 一级引用
>
> > 二级引用

15. 提示信息块

平台支持 GitHub / Primer 风格的提示块。

NOTE

1
2
3
> [!NOTE]
> 这是需要用户注意的补充信息。

TIP

1
2
3
> [!TIP]
> 这是一个推荐操作或使用技巧。

IMPORTANT

1
2
3
> [!IMPORTANT]
> 这是比较重要的信息。

WARNING

1
2
3
> [!WARNING]
> 这是可能产生风险的操作。

CAUTION

1
2
3
> [!CAUTION]
> 这是可能导致严重问题的操作。

16. 代码块

使用三个反引号创建代码块：

1
2
3```text
这里是代码内容
```

建议指定语言，以启用语法高亮。

Bash

1
2
3
4```bash
npm install
npm run dev
```

效果：

1
2npm install
npm run dev

JavaScript

1
2
3
4
5```javascript
const message = 'Hello Markdown';

console.log(message);
```

效果：

1
2
3const message = 'Hello Markdown';

console.log(message);

TypeScript

1
2
3
4
5
6
7
8
9
10
11```typescript
interface User {
  id: number;
  name: string;
}

const user: User = {
  id: 1,
  name: 'Admin',
};
```

JSON

1
2
3
4
5
6
7```json
{
  "name": "docs-platform",
  "version": "1.0.0",
  "private": true
}
```

YAML

1
2
3
4
5
6
7
8```yaml
server:
  port: 3000

database:
  host: localhost
  port: 5432
```

SQL

1
2
3
4
5
6```sql
SELECT id, title, status
FROM documents
WHERE status = 'published'
ORDER BY created_at DESC;
```

17. 表格

基本表格：

1
2
3
4
5| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `CONTENT_DIR` | string | Markdown 内容目录 |
| `DATABASE_URL` | string | PostgreSQL 连接地址 |
| `PORT` | number | 服务监听端口 |

效果：

表格对齐

使用冒号控制文字对齐：

1
2
3
4
5| 名称 | 状态 | 数量 |
| :--- | :---: | ---: |
| 文档 | 正常 | 128 |
| 用户 | 正常 | 32 |
| 项目 | 维护中 | 8 |

其中：

• :--- 表示左对齐
• :---: 表示居中
• ---: 表示右对齐

效果：

18. 分隔线

使用三个或更多 -：

1---

效果：

分隔线适合用于划分不同章节。

19. 转义特殊字符

如果希望 Markdown 特殊字符按照普通字符显示，可以使用反斜杠 \ 转义。

1
2
3\*这里不会变成斜体\*

\# 这里不会变成标题

常见需要转义的字符包括：

1\ * _ # ` > + - . ! [ ] ( )

21. 脚注

如果 Markdown 渲染器支持脚注，可以使用：

1
2
3企业技术文档应该进行版本管理。[^1]

[^1]: 推荐通过 Git 保存每次修改记录。

效果类似：

企业技术文档应该进行版本管理。¹

22. 自动链接

部分 Markdown 渲染器支持将 URL 和邮箱自动识别为链接：

1
2
3https://github.com/

admin@example.com

也可以使用尖括号明确表示：

1
2
3<https://github.com/>

<admin@example.com>

23. Front Matter

每篇文档顶部可以使用 YAML Front Matter 保存文档元数据。

例如：

1
2
3
4
5---
title: API 使用指南
description: REST API 接口使用说明
status: published
---

当前文档使用：

1
2
3
4
5---
title: 欢迎使用企业技术文档平台
description: 平台功能、Markdown 常用语法及格式示例
status: published
---

常见字段可以包括：

具体支持哪些字段，应以平台定义的 Front Matter Schema 为准。

综合示例

下面是一段较完整的技术文档 Markdown 示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40## 启动开发环境

安装依赖：

```bash
npm install
```

创建 `.env` 文件：

```env
DATABASE_URL=postgresql://localhost:5432/docs
CONTENT_DIR=./content
PORT=3000
```

启动开发服务器：

```bash
npm run dev
```

> [!TIP]
> 修改 Markdown 文档后，可以通过实时预览直接查看渲染结果。

### 启动检查

- [x] 安装 Node.js
- [x] 安装依赖
- [x] 配置数据库
- [ ] 启动开发服务器
- [ ] 验证文档页面

### 配置参数

| 参数 | 必填 | 说明 |
| --- | :---: | --- |
| `DATABASE_URL` | 是 | PostgreSQL 数据库连接地址 |
| `CONTENT_DIR` | 是 | Markdown 文档目录 |
| `PORT` | 否 | HTTP 服务端口 |

Markdown 编写建议

为了保持企业技术文档的一致性，建议：

• 一级标题 # 每篇文档只使用一次。
• 主要章节使用 ##。
• 子章节依次使用 ###、####，尽量不要跳级。
• 命令、变量、文件名使用行内代码格式，如 npm run dev。
• 多行代码必须使用代码块并注明语言。
• 参数、接口和配置项优先使用表格展示。
• 操作步骤优先使用有序列表。
• 功能清单优先使用无序列表。
• 工作进度和发布流程优先使用任务列表。
• 风险操作使用 [!WARNING] 或 [!CAUTION]。
• 补充说明使用 [!NOTE]。
• 推荐操作使用 [!TIP]。
• 文档内部尽量保持统一的标题层级和空行格式。

示例命令

1npm run dev

构建生产版本：

1npm run build

启动生产服务：

1npm start

参数

发布检查清单

• 创建文档
• 检查 Markdown 格式
• 检查代码示例
• 完成内容审核
• 发布文档
• 检查线上页面