Back to Details

write-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Writing Prefect Documentation

编写Prefect文档

This guide covers everything needed to write, update, and test Prefect documentation pages. For structural context (directory layout, navigation, links, local dev commands), see 
docs/AGENTS.md
.
本指南涵盖了编写、更新和测试Prefect文档页面所需的全部内容。如果需要了解结构相关的背景（目录布局、导航、链接、本地开发命令），请参考 
docs/AGENTS.md
。

Page types

页面类型

Each section of the docs serves a distinct purpose. Place new content in the right section and match its tone and structure.
文档的每个部分都有明确的定位。请将新内容放在合适的板块，并匹配对应板块的语气和结构。

Get Started (
v3/get-started/
)

快速入门 (
v3/get-started/
)

Onboarding pages for new users. Content should be linear, opinionated, and get the reader to a working result as fast as possible. Use 
<Steps>
for sequential instructions and 
<Tabs>
to offer Cloud vs. self-hosted paths. Minimize explanation — link to Concepts for deeper understanding.
面向新用户的引导页面。内容应该是线性、有明确指引的，尽可能快地让读者得到可运行的结果。使用 
<Steps>
组件展示顺序操作步骤，用 
<Tabs>
组件提供Cloud版和自托管版的不同操作路径。尽量减少解释内容，深层原理可以链接到核心概念板块。

Concepts (
v3/concepts/
)

核心概念 (
v3/concepts/
)

Explain what something is and why it matters. Concepts pages define Prefect's mental model — flows, tasks, states, deployments, events, work pools, etc. Start with a short code example showing the concept in action, then explain the underlying model, lifecycle, and relationships to other concepts. Link to How-to Guides for step-by-step instructions. Do not provide exhaustive procedural walkthroughs here.
解释是什么以及为什么重要。概念页面定义了Prefect的心智模型：流、任务、状态、部署、事件、工作池等。开头先放一个展示概念实际用法的简短代码示例，然后解释底层模型、生命周期以及和其他概念的关联。可以链接到操作指南查看分步操作说明，不要在这里放置 exhaustive 的流程步骤演示。

How-to Guides (
v3/how-to-guides/
)

操作指南 (
v3/how-to-guides/
)

Task-oriented pages that show how to accomplish a specific goal. Each page should solve one problem (e.g., "How to write and run a workflow", "How to set up retries"). Structure as a series of actionable steps with code examples. Meet the reader where they are — do not assume familiarity with Prefect internals. Use the smallest amount of Prefect-specific jargon possible, and explain or link terms when they are unavoidable.
Guides are organized into the following categories:
  • workflows/
     — Writing, running, and customizing flows and tasks: retries, caching, concurrency, logging, testing, runtime info, state hooks, and artifacts.
  • deployments/
     — Creating, scheduling, running, and versioning deployments, including 
    prefect.yaml
    configuration and flow code storage.
  • deployment_infra/
     — Running workflows on specific infrastructure: Docker, Kubernetes, serverless platforms (AWS ECS, Azure ACI, GCP Cloud Run), Modal, Coiled, Prefect Managed, and local processes. Also covers work pool management.
  • automations/
     — Setting up event-driven automations: creating automations and triggers, chaining deployments via events, custom notifications, and accessing event payloads in flows.
  • cloud/
     — Prefect Cloud-specific operations: connecting to Cloud, managing workspaces and users, creating webhooks, and troubleshooting.
  • configuration/
     — Configuring the Prefect environment: managing settings, storing secrets, and using variables.
  • ai/
     — Using Prefect with AI tooling, such as the Prefect MCP server.
  • migrate/
     — Upgrading from older Prefect versions or migrating from other tools like Airflow.
  • self-hosted/
     — Running the Prefect server yourself via Docker Compose, the CLI, or on Windows.
面向任务的页面，展示如何完成特定目标。每个页面只解决一个问题（例如“如何编写并运行工作流”、“如何设置重试”）。结构为一系列可执行的步骤，附带代码示例。从读者的现有认知出发，不要默认读者熟悉Prefect内部原理。尽量减少Prefect特有的术语，如果不可避免要使用，需要解释或者给出术语链接。
指南分为以下类别：
  • workflows/
     — 编写、运行和自定义流与任务：重试、缓存、并发、日志、测试、运行时信息、状态钩子、制品。
  • deployments/
     — 创建、定时、运行和版本管理部署，包括 
    prefect.yaml
    配置和流代码存储。
  • deployment_infra/
     — 在特定基础设施上运行工作流：Docker、Kubernetes、无服务器平台（AWS ECS、Azure ACI、GCP Cloud Run）、Modal、Coiled、Prefect托管、本地进程。同时也包含工作池管理相关内容。
  • automations/
     — 设置事件驱动的自动化：创建自动化规则和触发器、通过事件串联部署、自定义通知、在流中访问事件负载。
  • cloud/
     — Prefect Cloud专属操作：连接到Cloud、管理工作空间和用户、创建Webhook、问题排查。
  • configuration/
     — 配置Prefect环境：管理设置、存储密钥、使用变量。
  • ai/
     — 将Prefect和AI工具结合使用，例如Prefect MCP服务器。
  • migrate/
     — 从旧版本Prefect升级，或者从Airflow等其他工具迁移。
  • self-hosted/
     — 通过Docker Compose、CLI或者在Windows上自行运行Prefect服务器。

Advanced (
v3/advanced/
)

进阶内容 (
v3/advanced/
)

In-depth pages for experienced users covering topics like transactions, interactive workflows, infrastructure-as-code, scaling self-hosted deployments, and custom API integrations. These assume familiarity with core concepts and how-to patterns. They can be longer and more detailed than how-to guides.
面向有经验用户的深度内容，涵盖事务、交互式工作流、基础设施即代码、自托管部署扩容、自定义API集成等主题。这些内容默认读者已经熟悉核心概念和常用操作模式，比操作指南更长、更详细。

Examples (
v3/examples/
)

示例 (
v3/examples/
)

Auto-generated — do not edit directly. Each page is generated from a standalone Python file in the repo's top-level 
examples/
directory by 
generate_example_pages.py
. To add an example, create a new 
.py
file in 
examples/
with YAML frontmatter in comments and run 
just generate-examples
. See 
contribute/docs-contribute.mdx
for the full process.
自动生成，请勿直接编辑。 每个页面都是由仓库顶层 
examples/
目录下的独立Python文件通过 
generate_example_pages.py
生成的。如果要添加示例，在 
examples/
目录下新建带有YAML头信息注释的 
.py
文件，然后运行 
just generate-examples
。完整流程请参考 
contribute/docs-contribute.mdx
。

Integrations (
integrations/
)

集成 (
integrations/
)

Each integration (e.g., 
prefect-aws
, 
prefect-gcp
) has its own subdirectory. The 
index.mdx
covers installation, credential setup (blocks), and key capabilities. Additional pages cover specific workers, tasks, or SDK reference. Integration metadata lives in 
integrations/catalog/
as YAML files. Follow the existing pattern: "Why use it" section, prerequisites, install instructions, blocks setup, then per-service usage sections.
每个集成（例如 
prefect-aws
、
prefect-gcp
）都有自己的子目录。
index.mdx
包含安装、凭证设置（块）、核心能力的说明。额外的页面会介绍特定的worker、任务或者SDK参考。集成的元数据以YAML文件的形式存放在 
integrations/catalog/
目录下。请遵循现有模式：先放“为什么使用它”板块，然后是前置要求、安装说明、块设置，最后是各个服务的使用章节。

API Reference (
v3/api-ref/
)

API参考 (
v3/api-ref/
)

Auto-generated — do not edit directly. Covers the Python SDK (
python/
), CLI commands (
cli/
), and REST API (
rest-api/
). CLI pages use 
<ResponseField>
and 
<Accordion>
components for arguments and options.
自动生成，请勿直接编辑。 涵盖Python SDK（
python/
）、CLI命令（
cli/
）和REST API（
rest-api/
）。CLI页面使用 
<ResponseField>
和 
<Accordion>
组件展示参数和选项。

Release Notes (
v3/release-notes/
)

发布说明 (
v3/release-notes/
)

Changelogs organized by product surface: 
oss/
for open-source releases, 
cloud/
for Prefect Cloud, 
integrations/
for integration packages.
按产品模块组织的更新日志：
oss/
对应开源版本发布，
cloud/
对应Prefect Cloud更新，
integrations/
对应集成包更新。

Contribute (
contribute/
)

贡献指南 (
contribute/
)

Guides for contributors: how to set up the dev environment, write docs, develop integrations, and follow code style conventions.
面向贡献者的指南：如何搭建开发环境、编写文档、开发集成、遵循代码风格规范。

Adding vs. updating content

新增内容 vs 更新内容

When to update an existing page vs. create a new one

什么时候更新现有页面，什么时候新建页面

  • Update an existing page when the new content is a variation, option, or closely related technique for something the page already covers. For example, a new retry strategy belongs on the existing retries page, not a new page.
  • Create a new page when the content addresses a distinct goal that doesn't fit naturally into any existing page. A good test: if the page title would need to become vague or a compound sentence to accommodate the new content, it deserves its own page.
  • When in doubt, prefer extending an existing page. Fewer, more comprehensive pages are easier for readers to discover than many small, fragmented ones.
  • 更新现有页面：当新内容是当前页面已有内容的变体、选项或者密切相关的技术方案时。例如新的重试策略应该放在已有的重试页面，而不是新建页面。
  • 新建页面：当内容对应的目标和现有所有页面都不匹配时。一个很好的判断标准：如果为了容纳新内容，页面标题需要变得模糊或者变成复合句，那就值得新建单独的页面。
  • 不确定的时候优先扩展现有页面。少量的综合页面比很多碎片化的小页面更容易被读者找到。

When to add a new category or section

什么时候添加新的分类或者板块

  • Create a new subdirectory only when you have multiple pages (or a clear roadmap for multiple pages) that share a theme not covered by any existing category. A single page does not justify a new category — place it in the closest existing one.
  • Before creating a category, check whether the content fits in an existing one. For example, a guide about running flows on a new cloud platform belongs in 
    deployment_infra/
    , not a new category named after that platform.
  • New categories must also be added as a group in the 
    navigation.tabs
    section of 
    docs/docs.json
    , with an 
    index.mdx
    page for the group overview.
  • 新建子目录：只有当你有多个页面（或者明确的多个页面规划）属于同一个主题，且该主题没有被现有分类覆盖的时候。单个页面不足以支撑新分类，应该放在最接近的现有分类里。
  • 创建分类前先检查内容是否适合放在现有分类中。例如关于在新云平台上运行流的指南应该放在 
    deployment_infra/
    ，而不是新建一个以该平台命名的分类。
  • 新分类必须同时作为分组添加到 
    docs/docs.json
    的 
    navigation.tabs
    部分，并且要有对应的 
    index.mdx
    页面作为分组概览。

Page templates

页面模板

Starter templates live in this skill directory. Copy one as the basis for a new page and fill in the bracketed placeholders:
  • How-to guide — 
    template-howto.mdx
  • Concept page — 
    template-concept.mdx
Adjust headings and sections to fit the content — the templates show the expected shape, not a rigid format.
初始模板存放在当前skill目录下。复制一个模板作为新页面的基础，填充括号里的占位符即可：
  • 操作指南 — 
    template-howto.mdx
  • 概念页面 — 
    template-concept.mdx
根据内容调整标题和章节——模板只是展示了预期的结构，不是强制的格式。

Keywords for searchability

搜索关键词

Every page should include a 
keywords
array in its frontmatter. Keywords feed Mintlify's search index and help readers find pages using terms that don't appear in the title or description.
yaml
keywords: ["retry", "retries", "error handling", "fault tolerance"]
  • Include 3-5 lowercase terms a reader might search for.
  • Use synonyms and shorthand readers would actually type (e.g., "k8s" is wrong in prose but useful as a keyword alongside "Kubernetes").
  • Don't repeat words already in 
    title
    or 
    description
    — those are indexed automatically.
每个页面的头信息里都应该包含 
keywords
数组。关键词会被录入Mintlify的搜索索引，帮助读者通过标题或描述里没有的术语找到页面。
yaml
keywords: ["retry", "retries", "error handling", "fault tolerance"]
  • 包含3-5个读者可能会搜索的小写术语。
  • 使用读者实际会输入的同义词和简写（例如“k8s”在正文里不合适，但作为关键词和“Kubernetes”一起使用很有用）。
  • 不要重复已经出现在 
    title
    或者 
    description
    里的词——这些内容会自动被索引。

Registering pages in navigation

在导航中注册页面

Every new page must be added to 
docs/docs.json
under 
navigation.tabs
or it won't appear in the sidebar. Add the page path (without 
.mdx
) to the appropriate group:
json
{
  "tab": "How-to Guides",
  "pages": [
    "v3/how-to-guides/index",
    {
      "group": "Workflows",
      "pages": [
        "v3/how-to-guides/workflows/write-and-run",
        "v3/how-to-guides/workflows/retries"
      ]
    }
  ]
}
  • Each tab has a 
    "tab"
    display name and either 
    "pages"
    or 
    "groups"
    .
  • Groups can nest: a group's 
    "pages"
    array can contain strings (page paths) or nested 
    {"group": ..., "pages": [...]}
    objects.
  • Place new pages at a logical position within the existing group — typically at the end, unless ordering matters for the reader.
每个新页面都必须添加到 
docs/docs.json
的 
navigation.tabs
下，否则不会在侧边栏展示。将页面路径（不带 
.mdx
）添加到对应的分组中：
json
{
  "tab": "How-to Guides",
  "pages": [
    "v3/how-to-guides/index",
    {
      "group": "Workflows",
      "pages": [
        "v3/how-to-guides/workflows/write-and-run",
        "v3/how-to-guides/workflows/retries"
      ]
    }
  ]
}
  • 每个标签页都有 
    "tab"
    显示名，以及 
    "pages"
    或者 
    "groups"
    字段。
  • 分组可以嵌套：分组的 
    "pages"
    数组可以包含字符串（页面路径）或者嵌套的 
    {"group": ..., "pages": [...]}
    对象。
  • 把新页面放在现有分组里的逻辑位置——通常放在末尾，除非对读者来说排序有特殊意义。

Mintlify components

Mintlify组件

Use these components (not standard Markdown admonition syntax):
mdx
<Note>Important information.</Note>
<Warning>Caution about potential issues.</Warning>
<Tip>Helpful suggestion.</Tip>
<Info>Additional context.</Info>

<Accordion title="Expandable section">
  Content hidden until clicked.
</Accordion>

<Tabs>
  <Tab title="Option A">Content for A</Tab>
  <Tab title="Option B">Content for B</Tab>
</Tabs>

<Steps>
  <Step title="First step">Instructions</Step>
  <Step title="Second step">Instructions</Step>
</Steps>

<CardGroup cols={3}>
  <Card title="Title" icon="icon" href="/v3/path">
    Description text.
  </Card>
</CardGroup>

<CodeGroup>
```bash pip
pip install prefect
bash
uv pip install prefect
</CodeGroup> ```
请使用以下组件（不要用标准Markdown提示语法）：
mdx
<Note>重要信息。</Note>
<Warning>关于潜在问题的注意事项。</Warning>
<Tip>有用的建议。</Tip>
<Info>额外背景信息。</Info>

<Accordion title="可展开区块">
  点击后才会显示的内容。
</Accordion>

<Tabs>
  <Tab title="选项A">选项A的内容</Tab>
  <Tab title="选项B">选项B的内容</Tab>
</Tabs>

<Steps>
  <Step title="第一步">操作说明</Step>
  <Step title="第二步">操作说明</Step>
</Steps>

<CardGroup cols={3}>
  <Card title="标题" icon="icon" href="/v3/path">
    描述文本。
  </Card>
</CardGroup>

<CodeGroup>
```bash pip
pip install prefect
bash
uv pip install prefect
</CodeGroup> ```

Reusable snippets

可复用片段

Snippets live in 
snippets/
and are imported with JSX:
mdx
import ComponentName from '/snippets/path.mdx'

<ComponentName />
Always check for an existing snippet before writing duplicate content. Key snippets to know about:
  • snippets/installation.mdx
    — Standard Prefect install instructions (used in 
    v3/get-started/install.mdx
    ). Use this instead of writing ad-hoc install blocks.
  • snippets/resource-management/
    — Consistent "manage this resource via CLI / API / Terraform / Helm" callouts. Import the relevant variant when documenting a Prefect resource.
片段存放在 
snippets/
目录下，通过JSX导入：
mdx
import ComponentName from '/snippets/path.mdx'

<ComponentName />
编写重复内容之前请先检查是否已有对应片段。需要了解的核心片段：
  • snippets/installation.mdx
    — 标准的Prefect安装说明（在 
    v3/get-started/install.mdx
    中使用）。使用这个片段，不要编写临时的安装代码块。
  • snippets/resource-management/
    — 统一的“通过CLI / API / Terraform / Helm管理该资源”提示。记录Prefect资源的时候导入对应的变体即可。

Code blocks

代码块

Code blocks support language hints, filenames, line highlighting, and expandable sections:
mdx
```python my_flow.py
from prefect import flow

@flow
def hello():
    print("Hello!")
```

```bash {3} [expandable]
prefect deploy --all
prefect work-pool create my-pool --type process
prefect worker start --pool my-pool
```
Mark code blocks that should not be tested with the comment 
{/* pmd-metadata: notest */}
on the line before the code block.
Prefer minimal, runnable snippets that produce a visible result (printed output, a return value, or a logged message). Avoid placeholder names like 
foo
/
bar
in user-facing examples — use realistic names that reflect the domain (e.g., 
process_order
, 
customer_id
).
代码块支持语言提示、文件名、行高亮和可展开区域：
mdx
```python my_flow.py
from prefect import flow

@flow
def hello():
    print("Hello!")
```

```bash {3} [expandable]
prefect deploy --all
prefect work-pool create my-pool --type process
prefect worker start --pool my-pool
```
如果代码块不需要测试，在代码块的上一行添加注释 
{/* pmd-metadata: notest */}
进行标记。
优先使用精简、可运行、能产生可见结果（打印输出、返回值或者日志信息）的片段。在面向用户的示例中避免使用 
foo
/
bar
这类占位符名称，使用能反映业务领域的真实名称（例如 
process_order
、
customer_id
）。

Code example testing

代码示例测试

Python code blocks in 
.mdx
files are automatically extracted and executed as tests using pytest-markdown-docs. Tests run in CI against a live Prefect server and are parallelized with pytest-xdist (up to 6 workers). All test configuration — fixtures, skip lists, and injected globals — lives in 
docs/conftest.py
.
.mdx
文件中的Python代码块会被自动提取，并通过 pytest-markdown-docs 作为测试执行。测试会在CI中针对运行中的Prefect服务器执行，通过pytest-xdist并行运行（最多6个worker）。所有测试配置——fixture、跳过列表、注入的全局变量——都存放在 
docs/conftest.py
中。

How it works

工作原理

By default, every fenced Python code block in an 
.mdx
file is treated as an independent test. The plugin extracts the block, executes it, and fails if it raises an exception. Each block runs in its own namespace unless 
continuation
is used (see below).
默认情况下，
.mdx
文件中的每个围栏Python代码块都会被视为独立测试。插件会提取代码块并执行，如果抛出异常则测试失败。每个代码块在自己的命名空间中运行，除非使用了 
continuation
（见下文）。

Running tests locally

本地运行测试

There is no 
just
command for markdown tests. Run them manually:
bash
undefined
没有专门的 
just
命令运行Markdown测试，可以手动运行：
bash
undefined

Start a Prefect server in the background

后台启动Prefect服务器

PREFECT_HOME=$(pwd) uv run prefect server start &
PREFECT_HOME=$(pwd) uv run prefect server start &

Run the markdown doc tests

运行Markdown文档测试

PREFECT_API_URL="http://127.0.0.1:4200/api" uv run --group markdown-docs pytest docs/ -m markdown-docs
undefined
PREFECT_API_URL="http://127.0.0.1:4200/api" uv run --group markdown-docs pytest docs/ -m markdown-docs
undefined

pmd-metadata directives

pmd-metadata指令

Control test behavior with 
{/* pmd-metadata: <directive> */}
comments placed on the line immediately before a code fence.
notest
 — Skip this code block entirely. Use when code is illustrative, incomplete, or requires setup that cannot be provided in the test environment.
mdx
{/* pmd-metadata: notest */}
```python
在代码围栏的上一行添加 
{/* pmd-metadata: <directive> */}
注释可以控制测试行为。
notest
 — 完全跳过该代码块。当代码只是示例、不完整，或者需要测试环境无法提供的前置条件时使用。
mdx
{/* pmd-metadata: notest */}
```python

This block will not be tested

该代码块不会被测试

prefect deploy --some-hypothetical-flag
undefined
continuation
 — Share state (imports, variables, function definitions) from preceding code blocks on the same page. Without this, each block starts with a clean namespace. Use when a multi-step example is split across blocks for readability.
mdx
```python
from prefect import flow

@flow
def my_workflow() -> str:
    return "Hello, world!"
{/* pmd-metadata: continuation */}
python
my_workflow()  # Can reference the function defined above

**`fixture:<name>`** — Inject a pytest fixture defined in `conftest.py` as a global in the code block. Use when a block needs mocking (e.g., HTTP calls).

```mdx
{/* pmd-metadata: fixture:mock_post_200 */}
```python
import requests
response = requests.post(endpoint, headers=headers, json=data)
assert response.status_code == 200
undefined
prefect deploy --some-hypothetical-flag
undefined
continuation
 — 和同一页面上前面的代码块共享状态（导入、变量、函数定义）。不使用该指令的话，每个代码块都会从干净的命名空间开始。当多步骤示例为了可读性被拆分成多个代码块时使用。
mdx
```python
from prefect import flow

@flow
def my_workflow() -> str:
    return "Hello, world!"
{/* pmd-metadata: continuation */}
python
my_workflow()  # 可以引用上面定义的函数

**`fixture:<name>`** — 将 `conftest.py` 中定义的pytest fixture作为全局变量注入到代码块中。当代码块需要mock（例如HTTP调用）时使用。

```mdx
{/* pmd-metadata: fixture:mock_post_200 */}
```python
import requests
response = requests.post(endpoint, headers=headers, json=data)
assert response.status_code == 200
undefined

Global imports

全局导入

The 
pytest_markdown_docs_globals
hook in 
conftest.py
injects a small set of globals into every code block automatically: 
Mapped
, 
Run
, 
Union
, 
mapped_column
, 
sa
. You do not need to import these in doc examples.
conftest.py
中的 
pytest_markdown_docs_globals
钩子会自动向每个代码块注入少量全局变量：
Mapped
、
Run
、
Union
、
mapped_column
、
sa
。你不需要在文档示例中导入这些。

Autouse fixtures

自动应用的fixture

Two fixtures are applied to every test automatically (defined in 
conftest.py
):
  • mock_runner_start
    — Mocks 
    prefect.cli.flow.Runner.start
    so flow-serving examples don't actually start a long-running process.
  • mock_base_worker_submit
    — Mocks 
    BaseWorker.submit
    and 
    KubernetesWorker.submit
    so worker examples don't attempt real infrastructure calls.
每个测试会自动应用两个fixture（定义在 
conftest.py
中）：
  • mock_runner_start
    — mock 
    prefect.cli.flow.Runner.start
    方法，这样流服务示例不会真的启动长时间运行的进程。
  • mock_base_worker_submit
    — mock 
    BaseWorker.submit
    和 
    KubernetesWorker.submit
    方法，这样worker示例不会尝试发起真实的基础设施调用。

Skipped files

跳过的文件

Some files are skipped entirely via the 
SKIP_FILES
dict in 
conftest.py
. Common reasons include needing database fixtures, block cleanup, live network calls, or async contexts. Additionally:
  • All files under 
    v3/api-ref/python/
    are auto-skipped (generated reference docs).
  • All files under 
    v3/examples/
    are auto-skipped (tested separately in their source repo).
When adding a new page that genuinely cannot be tested, add it to 
SKIP_FILES
with a reason rather than marking every block with 
notest
.
有些文件会通过 
conftest.py
中的 
SKIP_FILES
字典被完全跳过。常见原因包括需要数据库fixture、块清理、真实网络调用或者异步上下文。除此之外：
  • v3/api-ref/python/
    下的所有文件都会被自动跳过（自动生成的参考文档）。
  • v3/examples/
    下的所有文件都会被自动跳过（在它们的源仓库中单独测试）。
如果新增的页面确实无法测试，将它添加到 
SKIP_FILES
并说明原因，不要给每个代码块都标记 
notest
。

Images

图片

Place images in 
v3/img/
organized by section (e.g., 
v3/img/ui/
, 
v3/img/concepts/
). Reference them with absolute paths:
mdx
![Description](/v3/img/ui/screenshot.png)
  • Always include meaningful alt text that describes what the image shows.
  • Use compressed PNG or WebP format to keep page load times fast.
  • Avoid committing unnecessarily large screenshots; crop to the relevant area.
将图片按板块存放在 
v3/img/
目录下（例如 
v3/img/ui/
、
v3/img/concepts/
）。使用绝对路径引用：
mdx
![描述信息](/v3/img/ui/screenshot.png)
  • 始终添加有意义的替代文本，描述图片展示的内容。
  • 使用压缩后的PNG或者WebP格式，保证页面加载速度。
  • 避免提交不必要的大截图，裁剪到相关区域即可。

Linting

lint检查

Docs are linted with Vale using Google style, Vale defaults, and custom Prefect rules. Run locally:
bash
just lint
Or manually: 
vale --glob='**/*.{md,mdx}' .
文档使用 Vale 进行lint检查，遵循Google风格、Vale默认规则和Prefect自定义规则。本地运行命令：
bash
just lint
或者手动运行：
vale --glob='**/*.{md,mdx}' .

Tone and style

语气和风格

  • Use second person ("you") and active voice in present tense.
  • Avoid first person ("I", "we") and marketing language ("powerful", "seamless", "best-in-class").
  • Be direct and concise. Shorter sentences are easier to scan.
  • Follow the Google developer documentation style guide as the baseline.
Examples of preferred phrasing:
Instead ofWrite
"We recommend configuring...""Configure..."
"You'll want to make sure to...""Make sure to..." or just state the instruction
"This powerful feature allows you to...""Use [feature] to..."
"I'll show you how to set up...""To set up..., do the following:"
"It should be noted that..."State the fact directly
"In order to""To"
When introducing a concept, lead with what the reader can do, not what the feature is:
  • Before: "The retry mechanism is a configurable system that allows flows to recover from transient failures."
  • After: "Add retries to your flow to recover automatically from transient failures."
  • 使用第二人称（“你”）和一般现在时的主动语态。
  • 避免第一人称（“我”、“我们”）和营销话术（“强大的”、“无缝的”、“业界领先的”）。
  • 直接、简洁。短句更易浏览。
  • 基础规范遵循 Google开发者文档风格指南。
推荐表述示例：
避免使用推荐使用
"我们建议配置...""配置..."
"你需要确保...""请确保..." 或者直接给出指令
"这个强大的特性可以让你...""使用[特性]来..."
"我会教你如何设置...""要设置...，请执行以下操作："
"需要注意的是..."直接陈述事实
"为了""要"
介绍概念的时候，先讲读者可以用它做什么，而不是这个特性是什么：
  • 反面示例：“重试机制是一个可配置的系统，可以让流从瞬时故障中恢复。”
  • 正面示例：“为你的流添加重试能力，可以自动从瞬时故障中恢复。”

Quality checklist

质量检查清单

Before considering a page complete, verify:
  1. The page opens with appropriate context: for how-to guides, a single-sentence scope line (or jump straight into steps if the title already establishes the goal); for concepts and advanced pages, an opening paragraph that defines the topic and why it matters.
  2. Prerequisites (tools, access, prior knowledge) are called out up front.
  3. The page includes at least one cross-link to a related Concept or How-to page.
  4. All code blocks are runnable and tested, or explicitly marked with 
    {/* pmd-metadata: notest */}
    with a reason.
  5. Frontmatter includes 
    keywords
    with 3-5 search terms not already in the title or description.
  6. The page is registered in 
    docs/docs.json
    navigation.
认为页面完成之前，请确认：
  1. 页面开头有合适的上下文介绍：操作指南可以用一句话说明范围（如果标题已经明确了目标，也可以直接进入步骤）；概念和进阶页面的开头段落要定义主题以及它的重要性。
  2. 前置要求（工具、权限、前置知识）在开头就明确说明。
  3. 页面至少包含一个指向相关概念或者操作指南页面的交叉链接。
  4. 所有代码块都是可运行、可测试的，或者明确标记了 
    {/* pmd-metadata: notest */}
    并说明原因。
  5. 头信息包含 
    keywords
    字段，其中有3-5个没有出现在标题或描述中的搜索词。
  6. 页面已经在 
    docs/docs.json
    的导航中注册。

Common mistakes

常见错误

  • Using 
    #
    (H1) in the body — the frontmatter 
    title
    already renders as H1.
  • Using relative links or including 
    .mdx
    in link paths.
  • Using Markdown admonitions (
    > **Note:**
    ) instead of Mintlify components (
    <Note>
    ).
  • Inconsistent heading hierarchy (jumping from H2 to H4).
  • Missing 
    description
    or 
    keywords
    in frontmatter — both improve search discoverability.
  • First-person pronouns ("I", "we") — use "you" or imperative voice.
  • Wrong terminology casing: "Prefect cloud" (should be "Prefect Cloud"), "Prefect Server" (should be "Prefect server"), "k8s" (should be "Kubernetes"), "infra" (should be "infrastructure").
  • Forgetting to register a new page in 
    docs/docs.json
    — the page won't appear in nav.
  • Forgetting to add a redirect in 
    docs/docs.json
    when moving or renaming a page.
  • Overusing 
    <Note>
    /
    <Tip>
    /
    <Warning>
    — reserve for genuinely important callouts, not every paragraph.
  • 在正文中使用 
    #
    （一级标题）——头信息中的 
    title
    已经会渲染为一级标题。
  • 使用相对链接，或者链接路径中包含 
    .mdx
    。
  • 使用Markdown提示（
    > **Note:**
    ）而不是Mintlify组件（
    <Note>
    ）。
  • 标题层级不连贯（从二级标题直接跳到四级标题）。
  • 头信息中缺少 
    description
    或者 
    keywords
    ——这两个字段都会提升搜索可发现性。
  • 使用第一人称代词（“我”、“我们”）——使用“你”或者祈使语气。
  • 术语大小写错误：“Prefect cloud”（应该是“Prefect Cloud”）、“Prefect Server”（应该是“Prefect server”）、“k8s”（应该是“Kubernetes”）、“infra”（应该是“infrastructure”）。
  • 忘记在 
    docs/docs.json
    中注册新页面——页面不会出现在导航中。
  • 移动或者重命名页面的时候忘记在 
    docs/docs.json
    中添加重定向规则。
  • 过度使用 
    <Note>
    /
    <Tip>
    /
    <Warning>
    ——只保留真正重要的提示，不要每段都加。