mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
2138f0804d
Generated-By: mintlify-agent Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
287 lines
7.1 KiB
Plaintext
287 lines
7.1 KiB
Plaintext
---
|
||
title: "操作指南、教程、参考和说明的文档模板"
|
||
sidebarTitle: "内容模板"
|
||
description: "复制并修改即用型 MDX 模板，用于在文档中撰写操作指南、教程、概念解释和 API 参考页面。"
|
||
keywords: ["文档模板", "操作指南模板", "教程模板", "参考模板", "MDX 模板"]
|
||
---
|
||
|
||
使用这些模板作为创建文档的起点。根据你的文档和受众对模板进行自定义。
|
||
|
||
1. 复制与你的内容类型匹配的模板。
|
||
2. 将占位符和示例内容替换为你的实际内容。
|
||
3. 按需调整各个部分。
|
||
4. 删除任何不适用的部分。
|
||
|
||
<Tip>
|
||
不确定该使用哪个模板？阅读 [内容类型](/zh/guides/content-types) 以了解每种模板适用的场景。
|
||
</Tip>
|
||
|
||
<div id="how-to-guide-template">
|
||
## 操作指南模板
|
||
</div>
|
||
|
||
当用户需要完成某项特定任务且已经对你的产品有一定了解时，应使用操作指南。操作指南以目标为导向，直奔解决方案。
|
||
|
||
````mdx How-to guide template
|
||
---
|
||
title: "[标题应以动词开头]"
|
||
description: "[执行特定任务]以[达成结果]。"
|
||
---
|
||
|
||
以简短的陈述开始，说明本指南帮助用户完成什么任务。
|
||
|
||
## 前置条件（可选）
|
||
|
||
仅列出必要的内容：
|
||
|
||
- 必需的设置或配置
|
||
- 所需的权限
|
||
- 应首先配置的相关功能
|
||
|
||
## [描述任务的行动导向标题]
|
||
|
||
提供专注于实现目标的直接说明。
|
||
|
||
1. 打开[位置]并导航到[特定位置]
|
||
2. 点击[按钮或选项]
|
||
3. 输入[必填信息]
|
||
4. 点击[确认按钮]
|
||
|
||
```language
|
||
// Include code examples that users can copy and modify
|
||
```
|
||
|
||
<Tip>
|
||
Include practical tips that help users avoid common mistakes or work more efficiently.
|
||
</Tip>
|
||
|
||
## Verify the result (optional)
|
||
|
||
If success is ambiguous, explain how users can confirm they completed the task successfully.
|
||
|
||
## Troubleshooting (optional)
|
||
|
||
Address common issues users might encounter:
|
||
|
||
- **Problem description**: Solution or workaround
|
||
- **Another common issue**: How to resolve it
|
||
|
||
## Related tasks
|
||
|
||
Link to related how-to guides or next steps.
|
||
````
|
||
|
||
<div id="tutorial-template">
|
||
## 教程模板
|
||
</div>
|
||
|
||
当你希望通过实践操作来帮助新用户学习时，请使用教程。教程会一步步引导用户，完成一个具有清晰结果的完整学习过程。
|
||
|
||
````mdx Tutorial template
|
||
---
|
||
title: "[动作动词] [具体结果]"
|
||
description: "了解如何通过[方法或途径]实现[具体结果]。"
|
||
---
|
||
|
||
使用介绍段落说明用户可以期望学到什么，以及完成本教程后他们能做什么。
|
||
|
||
## 前提条件
|
||
|
||
列出用户在开始之前需要具备的条件：
|
||
|
||
- 所需知识或技能
|
||
- 工具、账户或权限
|
||
- 时间投入（可选）
|
||
|
||
## 步骤 1：[第一个操作]
|
||
|
||
为第一步提供清晰、具体的说明。
|
||
|
||
```language
|
||
// Include code examples where helpful
|
||
```
|
||
|
||
解释此步骤完成了什么以及为什么重要。
|
||
|
||
## 步骤 2：[第二个操作]
|
||
|
||
继续按顺序执行基于前面工作的步骤。
|
||
|
||
指出里程碑和进度标记，让用户知道他们在正确的轨道上。
|
||
|
||
## 步骤 3：[第三个操作]
|
||
|
||
保持步骤专注于具体操作而非理论。
|
||
|
||
尽量减少用户需要做出的选择。
|
||
|
||
## 后续步骤
|
||
|
||
总结用户所学内容并建议合理的后续步骤：
|
||
|
||
- 可尝试的相关教程
|
||
- 常见任务的操作指南
|
||
- 用于深入学习的额外资源
|
||
````
|
||
|
||
<div id="explanation-template">
|
||
## 说明模板
|
||
</div>
|
||
|
||
当用户需要理解概念、设计决策或复杂功能的工作机制时，使用说明类内容。说明类内容用于提供上下文并加深理解，而不是给出一步一步的操作指引。
|
||
|
||
```mdx Explanation template
|
||
---
|
||
title: "关于 [概念或功能]"
|
||
description: "了解 [概念] 及其在 [产品或上下文] 中的工作原理。"
|
||
---
|
||
|
||
首先明确说明本文档涵盖的内容以及理解它的重要性。
|
||
|
||
用通俗易懂的语言定义概念。解释它是什么、有什么作用以及为什么存在。
|
||
|
||
必要时使用类比或与熟悉概念的对比来帮助理解。
|
||
|
||
## [概念] 的工作原理
|
||
|
||
解释底层机制、架构或流程。
|
||
|
||
<Frame>
|
||
<img src="/path/to/diagram.png" alt="显示 [概念] 工作原理的图表" />
|
||
</Frame>
|
||
|
||
将复杂的概念分解为易于理解的部分。
|
||
|
||
## 为什么采用 [设计决策或方法]
|
||
|
||
提供关于事物为何以这种方式工作的背景信息。
|
||
|
||
讨论权衡取舍、考虑过的替代方案或影响设计的约束条件。
|
||
|
||
## 何时使用 [概念]
|
||
|
||
帮助用户了解何时最适合使用此概念或方法。
|
||
|
||
- **用例 1**:适合使用此方法的场景
|
||
- **用例 2**:另一个适合选择此方法的场景
|
||
- **不推荐用于**:替代方案更优的情况
|
||
|
||
## 与其他功能的关系
|
||
|
||
建立与产品中相关概念或功能的联系。
|
||
|
||
解释此概念如何融入更广泛的系统或工作流程。
|
||
|
||
## 常见误解
|
||
|
||
澄清误解或阐明细微差别。
|
||
|
||
## 延伸阅读
|
||
|
||
链接到相关说明、教程或参考文档。
|
||
```
|
||
|
||
<div id="reference-template">
|
||
## 参考模板
|
||
</div>
|
||
|
||
当用户需要查找产品功能的具体细节时，请使用参考文档。编写参考文档时，应优先考虑其准确性、一致性和便于快速浏览。
|
||
|
||
````mdx Reference template
|
||
---
|
||
title: "[Feature or API name] reference"
|
||
description: "Complete reference for [feature or API] properties, parameters, and options."
|
||
---
|
||
|
||
Provide a one-sentence description of what this feature or API does.
|
||
|
||
## Properties
|
||
|
||
<ParamField body="property1" type="string" required>
|
||
Brief description of the property.
|
||
</ParamField>
|
||
|
||
<ParamField body="property2" type="number">
|
||
Brief description with default value if applicable.
|
||
</ParamField>
|
||
|
||
<ParamField body="property3" type="boolean" default="false">
|
||
Brief description.
|
||
</ParamField>
|
||
|
||
## Parameters
|
||
|
||
<ParamField body="parameterName" type="string">
|
||
Description of what this parameter does and when to use it.
|
||
|
||
```language
|
||
// Example showing typical usage
|
||
```
|
||
</ParamField>
|
||
|
||
<ParamField body="anotherParameter" type="object">
|
||
参数的说明。
|
||
|
||
可用选项:
|
||
|
||
- `option1`: 此选项的说明。
|
||
- `option2`: 此选项的说明。
|
||
</ParamField>
|
||
|
||
## Examples
|
||
|
||
### Basic example
|
||
|
||
```language title="Basic usage"
|
||
// Minimal example showing common use case
|
||
```
|
||
|
||
### Advanced example
|
||
|
||
```language title="Advanced configuration"
|
||
// Example with multiple options configured
|
||
```
|
||
|
||
## Response
|
||
|
||
If documenting an API, describe the response structure.
|
||
|
||
<ResponseField name="field1" type="string" required>
|
||
Description of the response field.
|
||
</ResponseField>
|
||
|
||
<ResponseField name="field2" type="number">
|
||
Description of another response field.
|
||
</ResponseField>
|
||
|
||
Example response:
|
||
|
||
```json
|
||
{
|
||
"field1": "value",
|
||
"field2": 123
|
||
}
|
||
```
|
||
|
||
## Related references
|
||
|
||
Link to related reference documentation.
|
||
````
|
||
|
||
<div id="related-pages">
|
||
## 相关页面
|
||
</div>
|
||
|
||
<CardGroup cols={2}>
|
||
<Card title="内容类型" icon="shapes" href="/zh/guides/content-types">
|
||
根据文档目标选择合适的内容类型。
|
||
</Card>
|
||
|
||
<Card title="风格和语气" icon="pen" href="/zh/guides/style-and-tone">
|
||
以一致的风格撰写高效的文档。
|
||
</Card>
|
||
|
||
<Card title="格式化文本" icon="text" href="/zh/create/text">
|
||
了解如何格式化文本并设置内容样式。
|
||
</Card>
|
||
</CardGroup> |