在撰写产品或者技术文档的时候，让内容的排布具有清晰的结构，以及让内容具有直观的视觉呈现是相当重要的。这样就能让看这份文档的读者快速 get 到内容中想要表达的意图，减少阅读理解的成本。
Apifox 作为一款 API 管理工具，不仅能高效管理 API 文档，还能通过灵活的 Markdown 语法，帮助团队打造专业级产品文档。现在你看到的 Apifox 帮助文档，就是用 Apifox 自身的 Markdown 能力打造而成的。
以下是在 Apifox 中使用 Markdown 撰写产品文档的 10 个实用技巧。文中涉及的 Markdown 示例，均已整理至 Apifox 的《Markdown 文档最佳实践》模块中，可前往查看示例效果。
目录树与标题独立配置
在 Apifox 中新建 Markdown 文档并将其命名时，“文档标题”会默认作为目录树中的显示名称，如下图所示：
如果你希望目录树名称和文档标题不一样，也可以分别自定义它们。
比如，你可以用“概述”作为目录名称，而将文档标题命名为更具体的“设计 API”。
操作方法
在 Markdown 文档内，点击“目录树中显示的名称”即可进行修改。
将目录名称和文档标题分开命名，可以让目录保持简洁，而文档标题则更具体。第三方平台解析文档链接时，会以“文档标题”作为预览显示，具体的文档标题会让显示效果更加友好。例如，这是在企业微信中的解析预览：
引用项目资源与数据模型
Apifox 支持在 Markdown 文档中直接插入当前项目的接口、文档和数据模型资源。
点击 Markdown 文档内的「插入项目内接口/文档」按钮，然后选择目标资源（接口或文档）即可。被嵌入的内容会自动以链接形式指向项目中的目标资源，在渲染界面点击后可直接跳转到相应的详情页。
依次选择「插入 -> 数据结构」即可将“数据模型”嵌入到 Markdown 文档中。当项目成员修改接口数据模型的字段时，文档中已嵌入的数据模型会自动同步更新，无需手动维护，文档始终反映最新的 API 结构，这可以避免因文档滞后导致的沟通障碍。
示例代码：
<DataSchema id="121374616" />
链接跳转行为与打开方式
Apifox 的 Markdown 支持多种链接格式。在“在线文档”中点击这些链接时，链接的打开方式取决于链接的类型：有的会在浏览器的新标签页中打开，有的会在当前页跳转，还有的可以通过锚点直接跳转到文档中的指定位置，选择不同的跳转方式可以帮助用户更高效地浏览与定位内容。
下文将详细说明各类链接在“在线文档”中的打开行为及配置方式。
在当前页打开的链接
通过 Markdown 编辑器右上角的「插入项目内接口/文档」按钮插入的链接资源，会生成以apifox://link/pages/...开头的地址，这类链接点击后会在浏览器当前页中打开。例如：
[Apifox Markdown 概述](apifox://link/pages/4275322)
链接插入方式：点击「插入项目内接口/文档」按钮，选择接口或文档即可。
形如apifox://link/pages/...这样的链接，在 Apifox 的 Markdown 中可按普通链接使用。文档发布或分享后，它会被自动转换为实际的在线访问地址（如 https://xxx.apifox.cn/...），并支持跳转。例如在「卡片」组件中的用法：
<Card title="点击我" href="apifox://link/pages/4275322">
这是一个卡片，点击后跳转到目标页面
</Card>
在新标签页打开的链接
只要不是通过「插入项目内接口/文档」方式添加的链接，点击后都会默认在浏览器的新标签页中打开。例如：
[Apifox Markdown 概述](https://markdown.apifox.cn/4275322m0)
锚点链接（新标签页打开）
如果希望点击链接后跳转到某个目录下的具体位置，可以在链接后加锚点#xxx。例如：
[Apifox Markdown 概述](https://markdown.apifox.cn/4275322m0#如何使用-apifox-markdown)
锚点链接（当前页打开）
你也可以在项目内的链接中使用锚点，实现在当前页里跳转到文档中的某个位置。例如：
[Apifox Markdown 概述](apifox://link/pages/4275322#如何使用-apifox-markdown)
类似apifox://link/pages/4275322#如何使用-apifox-markdown这样的锚点链接需要将文档分享或者发布出去后，在浏览器中点击才能生效。在 Apifox 端内点击时会提示“引用资源未找到”，因为链接还未渲染为实际可访问的路径。
上文的链接除了是 Markdown 格式的，还可以是 HTML 格式的，例如：
在当前页打开的链接:
<a href="apifox://link/pages/4275322">Apifox Markdown 概述</a>
在新标签页打开的链接:
<a href="https://markdown.apifox.cn/4275322m0">Apifox Markdown 概述</a>
锚点链接（新标签页打开）:
<a href="https://markdown.apifox.cn/4275322m0#如何使用-apifox-markdown">Apifox Markdown 概述</a>
锚点链接（当前页打开）：
<a href="apifox://link/pages/4275322#如何使用-apifox-markdown">Apifox Markdown 概述</a>
容器+列表实现左右排版
当需要展示新旧版本差异、功能对比、并列信息等内容时，可以使用「容器」组件嵌套「列表」组件，创建视觉上醒目的左右分栏布局。
这样的排版方式能让读者直观地比较不同内容，提升信息传递效率。
示例：
操作方法
在 Markdown 文档中先选择「容器」，再选择「多列 - 2 列」即可。你可以在每一列中填入对应内容，比如“旧版本”与“新版本”说明。
示例 Markdown 语法参考：
<Container>
<Columns>
<Column>
**旧版本**
</Column>
<Column>
**新版本**
</Column>
</Columns>
---
<Columns>
<Column>
这里是旧版本的内容
<DataSchema id="151301629" />
</Column>
<Column>
这里是新版本的内容
<DataSchema id="151301749" />
</Column>
</Columns>
</Container
💡 上述 Markdown 中的<DataSchema id="xxxxxx" />引用的是项目中的数据模型。
步骤组件实现视觉引导
对于实操性强的教程或功能指南，可以使用 Apifox Markdown 里的「步骤」组件，将复杂流程分解为清晰可见的步骤序列。
引导式设计能降低用户理解难度，提升操作成功率，尤其适合新手用户或复杂功能介绍。
「步骤」组件会自动为每个步骤添加序号，并以醒目的视觉样式引导用户按顺序完成操作。
示例：
操作方法
在 Markdown 文档中选择「步骤」组件即可，你可以为每一步输入详细内容。
示例 Markdown 语法参考：
<Steps>
<Step title="第一步">
这里是第一步的内容
<Background>
</Background>
</Step>
<Step title="第二步">
这里是第二步的内容
</Step>
<Step title="第三步">
这里是第三步的内容
</Step>
</Steps>
图片呈现与排版技巧
在 Apifox Markdown 中插入图片很简单，你可以将图片从本地上传或者直接复制粘贴到编辑界面。
图片链接可以来自第三方 CDN，如：
支持使用 Markdown 或 HTML 两种语法插入图片，如：
<img src="https://api.apifox.com/api/v1/projects/4997831/resources/511936/image-preview" alt="Apifox"/>
采用 HTML 格式的图片可以添加 CSS 行内样式，比如给图片指定宽高并居中：
<img src="https://api.apifox.com/api/v1/projects/4997831/resources/511936/image-preview" alt="Apifox" style="width: 400px;display: block; margin: 0 auto"/>
// 或
<div style="text-align: center;">
<img src="https://api.apifox.com/api/v1/projects/4997831/resources/511936/image-preview" alt="Apifox" style="width: 400px;" />
</div>
在暗黑模式下，如果图片有透明度，那么会默认将图片背景置为白色。
要移除白色背景，也可以通过 CSS 的行内样式来设置，例如：
<img src="https://api.apifox.com/api/v1/projects/4997831/resources/511936/image-preview" alt="Apifox" style="background-color: transparent;"/>
为了让图片的呈现效果更加专业美观，你可以给图片添加背景：
<Background>
</Background>
或者给图片添加边框与说明：
<Frame caption="外观偏好设置">
</Frame>
用表格清晰展示结构信息
表格是展示结构化数据的最佳选择。Apifox Markdown 不仅支持标准 Markdown 表格语法，还允许使用 HTML 样式调整表格外观，使其更加专业美观。
基本表格：
| 功能模块 | 状态 | 备注说明 |
| --- | --- | --- |
| 用户认证 | ✅ 已完成 | 支持多种登录方式 |
| 数据同步 | ⚠️ 进行中 | 预计下周完成 |
| 报表导出 | ❌ 未开始 | 计划Q3实施 |
调整列宽：使用 HTML 行内样式控制列宽，避免表格排版混乱。
| <div style="width: 100px;">功能模块</div> | <div style="width: 100px;">状态</div> | <div style="width: 200px;">备注说明</div> |
| --- | --- | --- |
| 用户认证 | ✅ 已完成 | 支持多种登录方式 |
| 数据同步 | ⚠️ 进行中 | 预计下周完成 | | 报表导出 | ❌ 未开始 | 计划Q3实施 |
用折叠块收纳 FAQ
使用折叠块是组织常见问题（FAQ）或非必要细节的理想方式。这种结构可以让读者按需展开感兴趣的内容，避免页面被冗长的文字占满，保持文档的整洁性。
折叠块特别适合用于：常见问题解答、可选功能介绍、高级配置选项、故障排除指南等内容，让用户可以快速获取主要信息，同时又不失详尽性。
基本用法：
<Accordion title="如何重置密码？" >
1. 点击登录页的「忘记密码」链接
2. 输入您注册时使用的邮箱地址
3. 点击「发送重置邮件」按钮
4. 在收到的邮件中点击重置链接，设置新密码
</Accordion>
设置默认状态（默认折叠）：
<Accordion title="高级配置选项（可选）" defaultOpen={false}>
本节介绍一些高级但非必要的配置项，适合有特殊需求的用户。
- 自定义请求头设置
- 代理服务器配置
- 性能优化选项
</Accordion>
用告示突出重要提示信息
使用告示和高亮块可以有效突出重要信息，如注意事项、提示或警告，让用户不会错过关键内容。
告示：
:::tip
这是一个提示类告示
:::
:::warning
这是一个警告类告示
:::
:::caution
这是一个注意类告示
:::
:::danger
这是一个危险类告示
:::
:::check
这是一个检查类告示
:::
:::info
这是一个信息类告示
:::
:::note
这是一个备注类告示
:::
高亮块：
:::highlight purple 💡
这里是高亮内容
:::
:::highlight yellow 👋
这里是高亮内容
:::
:::highlight orange 🚀
这里是高亮内容
:::
:::highlight red 🌟
这里是高亮内容
:::
:::highlight gray 🚀
这里是高亮内容
:::
:::highlight blue 📌
这里是高亮内容
:::
:::highlight green 🔑
这里是高亮内容
:::
为术语添加 Hover 和复制功能
通过Tooltip组件，可以实现鼠标悬停在文本上时显示定义的效果。
<Tooltip tip="这是一个提示！"> Hover 这里有提示</Tooltip>
通过CopyToClipboard组件，实现点击组件复制文字的效果。
<CopyToClipboard >点击这里可复制文字</CopyToClipboard>
Tooltip组件与CopyToClipboard组件结合，可以实现“悬停提示+复制文字”的效果。
<Tooltip tip="这是一个提示，可以复制！"><CopyToClipboard >点击这里可复制文字</CopyToClipboard></Tooltip>
通过灵活运用 Apifox Markdown 的这些功能，你可以构建既专业又美观的文档。好的文档不仅能减少沟通成本，提高开发效率，还能展现团队的专业素养和产品品质。优秀的文档是产品体验的重要组成部分，值得投入时间和精力去打磨。想要学习更多技巧可以查看 Apifox Markdown 文档。
扫一扫
1万+
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
