打造高颜值产品文档的 10 个技巧

目录树与标题独立配置

要自定义目录树名称和文档标题，点击“目录树中显示的名称”即可进行修改。

引用项目资源与数据模型

插入当前项目的接口、文档资源：

代码

示例效果

Apifox Markdown 概述

插入数据模型：

代码

示例效果

Card

title

string

定义卡片标题

必需

href

string

定义卡片跳转地址

可选

icon

string

可选

定义图标。定义方法请查阅图标

class

string

可选

为HTML元素分配一个或多个类名，支持 Tailwind CSS

style

string

可选

内联样式属性，允许直接定义CSS样式

链接跳转行为与打开方式

Apifox 的 Markdown 支持多种链接格式。在“在线文档”中点击这些链接时，链接的打开方式取决于链接的类型：有的会在浏览器的新标签页中打开，有的会在当前页跳转，还有的可以通过锚点直接跳转到文档中的指定位置，选择不同的跳转方式可以帮助用户更高效地浏览与定位内容。

1. 在当前页打开的链接

代码

示例效果

Apifox Markdown 概述

点击我

这是一个卡片，点击后跳转到目标页面

2. 在新标签页打开的链接

代码

示例效果

Apifox Markdown 概述

3. 锚点链接（新标签页打开）

代码

示例效果

Apifox Markdown 概述

4. 锚点链接（当前页打开）

代码

示例效果

Apifox Markdown 概述

5. HTML 格式

代码

示例效果

在当前页打开的链接:
Apifox Markdown 概述

在新标签页打开的链接:
Apifox Markdown 概述

锚点链接（新标签页打开）:
Apifox Markdown 概述

锚点链接（当前页打开）：
Apifox Markdown 概述

容器+列表实现左右排版

当需要展示新旧版本差异、功能对比、并列信息等内容时，可以使用「容器」组件嵌套「列表」组件，创建视觉上醒目的左右分栏布局。

操作方法：在 Markdown 文档中先选择「容器」，再选择「多列 - 2 列」即可。

旧版本

新版本

这里是旧版本的内容

Card

title

string

定义卡片标题

必需

href

string

定义卡片跳转地址

可选

icon

string

可选

定义图标。定义方法请查阅图标

class

string

可选

为HTML元素分配一个或多个类名，支持 Tailwind CSS

style

string

可选

内联样式属性，允许直接定义CSS样式

这里是新版本的内容

CardGroup

cols

number

定义卡片组的列数量

必需

步骤组件实现视觉引导

对于实操性强的教程或功能指南，可以使用 Apifox Markdown 里的步骤组件，将复杂流程分解为清晰可见的步骤序列。

代码

示例效果

第一步

这里是第一步的内容

第二步

这里是第二步的内容

第三步

这里是第三步的内容

图片呈现与排版技巧

图片链接可以来自第三方 CDN，如：

代码

示例效果

支持使用 Markdown 或 HTML 两种语法插入图片，如：

代码

示例效果

采用 HTML 格式的图片可以添加 CSS 行内样式，比如给图片指定宽高并居中：

暗黑模式下移除白色背景：

为了让图片的呈现效果更加专业美观，你可以给图片添加背景：

给图片添加边框与说明：

外观偏好设置

用表格清晰展示结构信息

表格是展示结构化数据的最佳选择。Apifox Markdown 不仅支持标准 Markdown 表格语法，还允许使用 HTML 样式调整表格外观，使其更加专业美观。

基本表格：

功能模块	状态	备注说明
用户认证	✅ 已完成	支持多种登录方式
数据同步	⚠️ 进行中	预计下周完成
报表导出	❌ 未开始	计划Q3实施

调整列宽：使用 HTML 行内样式控制列宽，避免表格排版混乱

功能模块	状态	备注说明
用户认证	✅ 已完成	支持多种登录方式
数据同步	⚠️ 进行中	预计下周完成
报表导出	❌ 未开始	计划Q3实施

用折叠块收纳 FAQ

使用折叠块是组织常见问题（FAQ）或非必要细节的理想方式。这种结构可以让读者按需展开感兴趣的内容，避免页面被冗长的文字占满，保持文档的整洁性。

折叠块特别适合用于：常见问题解答、可选功能介绍、高级配置选项、故障排除指南等内容，让用户可以快速获取主要信息，同时又不失详尽性。

代码

示例效果

基本用法：

如何重置密码？

点击登录页的「忘记密码」链接

输入您注册时使用的邮箱地址

点击「发送重置邮件」按钮

在收到的邮件中点击重置链接，设置新密码

默认折叠：

高级配置选项（可选）

用告示突出重要提示信息

使用告示和高亮块可以有效突出重要信息，如注意事项、提示或警告，让用户不会错过关键内容。

告示： 请查看告示章节

折叠快： 请查看折叠块章节

为术语添加 Hover 和复制功能

代码

示例效果

Hover 这里有提示

点击这里可复制文字

打造高颜值产品文档的 10 个技巧

目录树与标题独立配置#

引用项目资源与数据模型#

链接跳转行为与打开方式#

1. 在当前页打开的链接#

2. 在新标签页打开的链接#

3. 锚点链接（新标签页打开）#

4. 锚点链接（当前页打开）#

5. HTML 格式#

容器+列表实现左右排版#

步骤组件实现视觉引导#

图片呈现与排版技巧#

用表格清晰展示结构信息#

用折叠块收纳 FAQ#

用告示突出重要提示信息#

为术语添加 Hover 和复制功能#

目录树与标题独立配置

引用项目资源与数据模型

链接跳转行为与打开方式

1. 在当前页打开的链接

2. 在新标签页打开的链接

3. 锚点链接（新标签页打开）

4. 锚点链接（当前页打开）

5. HTML 格式

容器+列表实现左右排版

步骤组件实现视觉引导

图片呈现与排版技巧

用表格清晰展示结构信息

用折叠块收纳 FAQ

用告示突出重要提示信息

为术语添加 Hover 和复制功能