---
title: 欢迎使用企业技术文档平台
description: 平台功能、Markdown 常用语法及格式示例
status: published
---
# 欢迎使用企业技术文档平台
本平台使用 **Markdown** 保存文档，并使用 **Primer** 进行页面渲染。
本文档同时作为 Markdown 常用语法示例，可用于快速了解平台支持的文档编写方式。
---
## 平台功能
* 网页编辑
* 实时预览
* Git 历史
* 文档发布
* Markdown 文件管理
* 代码语法高亮
* 表格与任务列表
* 提示信息块
* 文档版本追踪
---
# Markdown 常用语法
## 1. 标题
Markdown 使用 `#` 表示标题。
```markdown
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题
```
实际效果如下：
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题
---
## 2. 普通文本
Markdown 中直接输入文字即可形成正文。
```markdown
这是一段普通文本。
这是另一段文本。
```
段落之间建议保留一个空行。
---
## 3. 粗体
使用两个星号 `**` 包裹文字：
```markdown
**这是粗体文字**
```
效果：
**这是粗体文字**
---
## 4. 斜体
使用一个星号 `*` 包裹文字：
```markdown
*这是斜体文字*
```
效果：
*这是斜体文字*
---
## 5. 粗斜体
使用三个星号 `***` 包裹文字：
```markdown
***这是粗斜体文字***
```
效果：
***这是粗斜体文字***
---
## 6. 删除线
使用两个波浪线 `~~` 包裹文字：
```markdown
~~这是一段被删除的内容~~
```
效果：
~~这是一段被删除的内容~~
---
## 7. 行内代码
使用反引号 `` ` `` 包裹代码、参数、变量或命令：
```markdown
使用 `npm run dev` 启动开发服务器。
```
效果：
使用 `npm run dev` 启动开发服务器。
变量、文件名和配置项也推荐使用这种形式，例如：
```markdown
修改 `CONTENT_DIR` 配置后重新启动服务。
```
---
## 8. 无序列表
可以使用 `-`、`*` 或 `+` 创建无序列表。
```markdown
- 用户管理
- 文档管理
- 权限管理
- 系统设置
```
效果：
* 用户管理
* 文档管理
* 权限管理
* 系统设置
### 多级无序列表
```markdown
- 文档管理
- 创建文档
- 编辑文档
- 删除文档
- 用户管理
- 创建用户
- 修改用户
```
效果：
* 文档管理
* 创建文档
* 编辑文档
* 删除文档
* 用户管理
* 创建用户
* 修改用户
---
## 9. 有序列表
使用数字加英文句点：
```markdown
1. 安装依赖
2. 配置数据库
3. 启动服务
4. 打开管理后台
```
效果：
1. 安装依赖
2. 配置数据库
3. 启动服务
4. 打开管理后台
### 多级有序列表
```markdown
1. 安装项目
1. 下载代码
2. 安装依赖
2. 配置项目
1. 配置数据库
2. 配置环境变量
3. 启动项目
```
---
## 10. 混合列表
有序列表和无序列表可以组合使用：
```markdown
1. 前端
- React
- TypeScript
- Primer
2. 后端
- Node.js
- PostgreSQL
3. 运维
- Docker
- Nginx
```
效果：
1. 前端
* React
* TypeScript
* Primer
2. 后端
* Node.js
* PostgreSQL
3. 运维
* Docker
* Nginx
---
## 11. 任务列表
任务列表适合用于开发计划、发布检查和项目进度管理。
```markdown
- [x] 创建文档
- [x] 完成内容审核
- [ ] 发布文档
- [ ] 配置生产环境
```
效果：
* [x] 创建文档
* [x] 完成内容审核
* [ ] 发布文档
* [ ] 配置生产环境
---
## 12. 链接
基本语法：
```markdown
[显示文字](https://example.com)
```
例如：
```markdown
访问 [GitHub](https://github.com/) 查看项目代码。
```
也可以直接书写 URL：
```markdown
https://github.com/
```
---
## 13. 图片
图片语法与链接类似，只需要在前面增加 `!`：
```markdown
```
例如：
```markdown
```
推荐为图片填写有意义的说明文字，便于无障碍访问和后续维护。
---
## 14. 引用
使用 `>` 创建引用：
```markdown
> 这是一段引用内容。
```
效果：
> 这是一段引用内容。
### 多行引用
```markdown
> 企业技术文档应该保持结构清晰。
>
> 重要配置应该说明用途和注意事项。
```
效果：
> 企业技术文档应该保持结构清晰。
>
> 重要配置应该说明用途和注意事项。
### 嵌套引用
```markdown
> 一级引用
>
> > 二级引用
```
---
## 15. 提示信息块
平台支持 GitHub / Primer 风格的提示块。
### NOTE
```markdown
> [!NOTE]
> 这是需要用户注意的补充信息。
```
> [!NOTE]
> 文档正文会保存为真实的 `.md` 文件。
### TIP
```markdown
> [!TIP]
> 这是一个推荐操作或使用技巧。
```
> [!TIP]
> 推荐在提交文档前使用实时预览检查 Markdown 渲染效果。
### IMPORTANT
```markdown
> [!IMPORTANT]
> 这是比较重要的信息。
```
> [!IMPORTANT]
> 修改生产环境配置前，请确认相关配置已经备份。
### WARNING
```markdown
> [!WARNING]
> 这是可能产生风险的操作。
```
> [!WARNING]
> 生产环境不要启用本地开发登录。
### CAUTION
```markdown
> [!CAUTION]
> 这是可能导致严重问题的操作。
```
> [!CAUTION]
> 不要直接删除生产环境数据库。
---
## 16. 代码块
使用三个反引号创建代码块：
````markdown
```text
这里是代码内容
```
````
建议指定语言，以启用语法高亮。
### Bash
````markdown
```bash
npm install
npm run dev
```
````
效果：
```bash
npm install
npm run dev
```
### JavaScript
````markdown
```javascript
const message = 'Hello Markdown';
console.log(message);
```
````
效果：
```javascript
const message = 'Hello Markdown';
console.log(message);
```
### TypeScript
````markdown
```typescript
interface User {
id: number;
name: string;
}
const user: User = {
id: 1,
name: 'Admin',
};
```
````
### JSON
````markdown
```json
{
"name": "docs-platform",
"version": "1.0.0",
"private": true
}
```
````
### YAML
````markdown
```yaml
server:
port: 3000
database:
host: localhost
port: 5432
```
````
### SQL
````markdown
```sql
SELECT id, title, status
FROM documents
WHERE status = 'published'
ORDER BY created_at DESC;
```
````
---
## 17. 表格
基本表格：
```markdown
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `CONTENT_DIR` | string | Markdown 内容目录 |
| `DATABASE_URL` | string | PostgreSQL 连接地址 |
| `PORT` | number | 服务监听端口 |
```
效果：
| 参数 | 类型 | 说明 |
| -------------- | ------ | --------------- |
| `CONTENT_DIR` | string | Markdown 内容目录 |
| `DATABASE_URL` | string | PostgreSQL 连接地址 |
| `PORT` | number | 服务监听端口 |
### 表格对齐
使用冒号控制文字对齐：
```markdown
| 名称 | 状态 | 数量 |
| :--- | :---: | ---: |
| 文档 | 正常 | 128 |
| 用户 | 正常 | 32 |
| 项目 | 维护中 | 8 |
```
其中：
* `:---` 表示左对齐
* `:---:` 表示居中
* `---:` 表示右对齐
效果：
| 名称 | 状态 | 数量 |
| :- | :-: | --: |
| 文档 | 正常 | 128 |
| 用户 | 正常 | 32 |
| 项目 | 维护中 | 8 |
---
## 18. 分隔线
使用三个或更多 `-`：
```markdown
---
```
效果：
---
分隔线适合用于划分不同章节。
---
## 19. 转义特殊字符
如果希望 Markdown 特殊字符按照普通字符显示，可以使用反斜杠 `\` 转义。
```markdown
\*这里不会变成斜体\*
\# 这里不会变成标题
```
常见需要转义的字符包括：
```text
\ * _ # ` > + - . ! [ ] ( )
```
---
## 21. 脚注
如果 Markdown 渲染器支持脚注，可以使用：
```markdown
企业技术文档应该进行版本管理。[^1]
[^1]: 推荐通过 Git 保存每次修改记录。
```
效果类似：
企业技术文档应该进行版本管理。[^1]
[^1]: 推荐通过 Git 保存每次修改记录。
---
## 22. 自动链接
部分 Markdown 渲染器支持将 URL 和邮箱自动识别为链接：
```markdown
https://github.com/
admin@example.com
```
也可以使用尖括号明确表示：
```markdown
```
---
## 23. Front Matter
每篇文档顶部可以使用 YAML Front Matter 保存文档元数据。
例如：
```yaml
---
title: API 使用指南
description: REST API 接口使用说明
status: published
---
```
当前文档使用：
```yaml
---
title: 欢迎使用企业技术文档平台
description: 平台功能、Markdown 常用语法及格式示例
status: published
---
```
常见字段可以包括：
| 字段 | 示例 | 说明 |
| ------------- | ---------------- | ---- |
| `title` | `API 使用指南` | 文档标题 |
| `description` | `API 接口说明` | 文档简介 |
| `status` | `published` | 文档状态 |
| `author` | `Platform Team` | 作者 |
| `tags` | `[api, backend]` | 文档标签 |
| `created` | `2026-08-30` | 创建日期 |
| `updated` | `2026-08-30` | 更新日期 |
具体支持哪些字段，应以平台定义的 Front Matter Schema 为准。
---
# 综合示例
下面是一段较完整的技术文档 Markdown 示例：
````markdown
## 启动开发环境
安装依赖：
```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]`。
* 文档内部尽量保持统一的标题层级和空行格式。
---
# 示例命令
```bash
npm run dev
```
构建生产版本：
```bash
npm run build
```
启动生产服务：
```bash
npm start
```
---
# 参数
| 参数 | 类型 | 必填 | 说明 |
| -------------- | ------ | :-: | --------------- |
| `CONTENT_DIR` | string | 是 | Markdown 内容目录 |
| `DATABASE_URL` | string | 是 | PostgreSQL 连接地址 |
| `PORT` | number | 否 | Web 服务监听端口 |
| `NODE_ENV` | string | 否 | 当前运行环境 |
---
# 发布检查清单
* [x] 创建文档
* [x] 检查 Markdown 格式
* [x] 检查代码示例
* [ ] 完成内容审核
* [ ] 发布文档
* [ ] 检查线上页面