Prefect 官方文档工程指南基于 Mintlify 与 MDX 的内容架构、写作规范与 CI 质量保障【免费下载链接】prefectPrefect is a workflow orchestration framework for building resilient data pipelines in Python.项目地址: https://gitcode.com/GitHub_Trending/pr/prefect导读本文基于 Prefect 开源仓库中的 docs/AGENTS.md系统拆解 Prefect 官方文档站点的工程化组织方式从目录结构、自动生成与手工维护的内容边界、MDX 文件格式与导航注册到术语校验、代码示例的 CI 测试机制以及 Cloud-only 特性的标注约定。读完本文你将完整掌握在 Prefect 文档体系中新增一页、注册导航、通过链接与代码测试、符合术语规范的全流程操作也能理解 Prefect 如何借助 docs/docs.json、docs/justfile 与 docs/conftest.py 把一套大型开源文档变成可自动化校验、可持续维护的工程资产。文档平台与站点配置Prefect 的官方文档构建在 Mintlify 平台上对外发布在 docs.prefect.io。所有文档文件一律使用.mdxMarkdown JSX扩展名站点级配置集中在仓库根目录下的 docs/docs.json 中。该文件承担多重职责站点外观colors、logo、favicon、footer.socials等全局配置导航结构navigation.tabs定义全部顶层 Tab 与分组页面错误处理errors[404][redirect]控制页面重定向页面跳转redirects数组用于维护页面改名/迁移后的旧链接。从源码佐证看docs/justfile 中封装了三条与文档相关的核心命令可直接用于本地开发与质量检查just docs # 启动本地文档开发服务器npx mintlatest dev默认 localhost:3000 just links # 检查死链npx mintlatest broken-links just lint # 运行 Vale 文档风格检查器其中 lint 命令的具体形式为vale --glob**/*.{md,mdx} .即对仓库中全部 Markdown/MDX 文件执行 Vale 校验。目录结构一份文档仓库的地图Prefect 文档目录被精心分区每个子目录有明确职责docs/ v3/ # Prefect 3.x 主文档 get-started/ # 安装与快速入门 concepts/ # 核心概念flows、tasks、states、deployments 等 how-to-guides/ # 按类别组织的实战指南 advanced/ # 高级主题 examples/ # 由 examples/ 下的 Python 文件自动生成——禁止手工编辑 api-ref/ # API 参考自动生成与手工编写混合 python/ # SDK 参考自动生成——禁止手工编辑 cli/ # CLI 命令参考自动生成——禁止手工编辑 rest-api/ # REST API 文档endpoint 页自动生成index.mdx 概览页手工维护 events/ # 事件参考目录——手工编写、可编辑 release-notes/ # 版本发布说明 img/ # 按板块组织的图片 integrations/ # 各集成专属文档prefect-aws、prefect-gcp 等 contribute/ # 贡献者指南 snippets/ # 可跨页面复用的 MDX 片段 images/ # 遗留图片 logos/ # 品牌素材 styles/ # Vale 校验风格规则 resources/ # 未列入导航的页面hidden: true位于 v3/ 版本树之外这一结构的核心设计意图是**版本树内统一管理 非版本树灵活放置**所有面向当前 Prefect 3.x 的新内容都必须进入v3/目录唯一例外是hidden: true的未列出页面它们可以放在docs/resources/下。自动生成内容与手工维护的边界Prefect 文档的一个重要工程决策是机器能生成的绝不手写。文档中明确划定了以下几类自动生成内容禁止直接编辑目录生成来源维护方式v3/examples/顶层 examples/ 下的 Python 文件由 scripts/generate_example_pages.py 生成v3/api-ref/python/、v3/api-ref/cli/Python SDK、CLI自动生成的 API 参考v3/api-ref/rest-api/server/ 与 cloud/ 的 REST 端点endpoint 页面自动生成rest-api/index.mdx与rest-api/server/index.mdx为手工编写、可编辑integrations/name/api-ref/各集成包通过mdxify生成如integrations/prefect-kubernetes/api-ref/每个集成发版时重新生成例外v3/api-ref/events/是手工编写的内容当事件 schema 发生变化时应直接编辑它。以示例页生成为例scripts/generate_example_pages.py 的流程可以完整还原自动生成的机制脚本扫描examples/目录下的.py文件提取其中的 YAML frontmattertitle、description、icon、keywords、order将 Python 代码按#注释标题拆分为 Markdown 章节与代码块写入docs/v3/examples/下的.mdx文件并自动更新docs.json中 Examples Tab 的页面列表。生成页顶部会插入一段 JSX 注释标记本页由generate_example_pages.py自动生成任何修改都将被覆盖——docs/v3/examples/hello-world.mdx 就是这类自动生成页的典型样本因此贡献者绝不应手工修改这些文件。MDX 文件格式YAML frontmatter 规范每个.mdx文件都以 YAML frontmatter 开头。frontmatter 的键必须全小写可用的键如下--- title: Page Title # 必填渲染为页面 H1 description: Brief description for SEO and navigation # 必填用于 SEO 与导航 sidebarTitle: Optional shorter sidebar label # 可选侧边栏短标签 icon: icon-name # 可选Mintlify 图标 mode: wide # 可选传 custom 时使用原始 JSX/HTML 布局 hidden: true # 可选未列出页面无需注册导航 keywords: [keyword1, keyword2] # 可选用于搜索 ---仓库中的真实页面可以作为格式参照例如 docs/v3/concepts/flows.mdx 的 frontmatter--- title: Flows description: Flows compose work into a workflow. keywords: [flow, workflow, decorator, flow, orchestration, subflow] ---由于title会作为页面的 H1 渲染正文内容必须从##二级标题开始不得再添加一个 H1。导航注册、链接与重定向规范导航注册所有页面都必须在 docs/docs.json 的navigation.tabs下注册。新增页面时将该页路径不带.mdx扩展名加入对应分组即可。未注册的页面不会出现在导航中例外是hidden: true的未列出页面它们不需要导航注册。链接规范文档内链接必须使用从文档根目录开始的绝对路径且不携带.mdx扩展名See the flows documentation for details.禁止使用相对路径也禁止在链接中写.mdx扩展名。对照到本仓库这条链接对应的实际文件是 docs/v3/concepts/flows.mdx。重定向当页面被重命名或移动时需要在docs/docs.json的redirects数组中添加重定向记录保证旧链接继续可用。除非能确认旧 URL 已无任何入站流量否则不要删除已有重定向。路径同样不应包含.mdx扩展名。术语与大小写由 Vale 强制执行的文风Prefect 文档的术语偏好由 Vale 通过 docs/styles/CustomStyles/WordList.yml 强制约束。该文件基于 Google 的 word list 修改而来其中针对 Prefect 定制的关键条目包括Prefect Cloud而不是 Prefect cloudPrefect server而不是 Prefect Serverinfrastructure而不是 infraKubernetes而不是 k8sopen source而不是 open-source从 docs/styles/CustomStyles/WordList.yml 的实现可以看到Vale 规则以substitution类型运行每条规则带有message: Use %s instead of %s.的提示语与level: warning的告警级别并且ignorecase: false——这意味着大小写不匹配也会被捕获。此外还包括一批通用工程术语约束例如 regex 应写为 regular expression、url 应写为 URL、open-source 应写为 open source 等。本地开发工作流按 docs/AGENTS.md 与 docs/justfile 的说明编写文档后的标准本地工作流为just docs # 启动开发服务器在 localhost:3000 预览 just links # 检查链接是否失效 just lint # 运行 Vale 检查文风与术语在提交前还应当确认代码示例可以通过 CI 中的文档测试见下一节。代码示例的 CI 测试机制让文档中的代码真正可运行Prefect 文档工程化的亮点在于文档里的代码示例是在 CI 中真实执行的。实现依赖pytest-markdown-docs插件它被声明在 pyproject.toml 的markdown-docsextra 中markdown-docs [ pytest-markdown-docs0.6.0, prefect[aws], prefect[azure], # ... 其余集成 extras ]由于示例可能涉及各种集成包该 extra 同时安装了全部 Prefect 集成的依赖保证测试环境可以覆盖各类代码片段。对于少数无法在隔离环境中运行的示例文档提供两级跳过机制按代码块跳过在需要跳过的围栏代码块上方添加注释{/* pmd-metadata: notest */}用于单个示例无法独立运行的场景按文件跳过将整个页面路径加入 docs/conftest.py 中的SKIP_FILES集合用于整页依赖真实外部基础设施如真实数据库、dbt 项目与 profiles、真实 API 凭据的场景——集成类页面几乎都属于这一类。docs/conftest.py 的实现给出了这套机制的具体运作方式pytest_collection_modifyitems钩子会为三类文件自动添加 skip 标记——api-ref/python/目录、integrations/下api-ref/目录的生成文件以及SKIP_FILES中硬编码的页面每个条目都附有跳转原因例如docs/AGENTS.md本身因为不是文档页面、含有供 Agent 参考的原始代码示例而被跳过。此外pytest_markdown_docs_globals()还为文档测试注入了Mapped、Run、sa等 SQLAlchemy 全局对象并提供了两个 autouse fixturemock_runner_start与mock_base_worker_submit来 mock 掉 Runner 启动与 Worker 提交等重操作确保文档示例测试在 CI 中轻量可控。对于开发者而言这意味着编写文档示例时必须保证代码开箱即跑或者在必要时合理地使用上述两种跳过机制并说明原因。Cloud-only 特性的标注约定Prefect 文档还承担着向用户与下游消费者如 Terraform provider、各语言 SDK传递该功能仅适用于 Prefect Cloud信息的重要职责。这类特性SSO、audit logs、incidents、SLAs、send-email-notification自动化动作等源于nebula仓库由 Prefect 官方人员与 Agent 维护文档。相关约定有三条Cloud-only 指南的位置账户、工作区、用户管理类指南统一放在v3/how-to-guides/cloud/下新写的 Cloud-only how-to 内容应优先放于此。使用 Cloud 徽标标记整节/整页当页面同时覆盖开源行为时在被标记内容的正上方独立一行放置span classbadge cloud/span。该 span 故意保持为空——文案由样式提供其后需要空一行使标记作用于整个段落而非单个句子。样式定义可见 docs/styles.css 中的.badge.cloud类仓库页面如 docs/v3/concepts/slas.mdx、docs/v3/concepts/webhooks.mdx均有实际使用。使用 Note 提示内联标注对于单行场景如某个表格行或变量使用NoteThis action is only available in Prefect Cloud./Note这类提示组件。可复用片段与组件的使用为避免内容重复文档体系提供了两类复用机制snippets在编写新页面之前先检查 docs/snippets 中是否已有可复用的 MDX 片段。例如 docs/snippets/installation.mdx 使用 Mintlify 的CodeGroup组件同时展示pip与uv两种安装方式各页面可直接 import 引用而非重复撰写。Mintlify 组件文档规范要求优先使用 Mintlify 组件Note、Tabs、Steps等而不是 Markdown 原生的 admonition 语法以保证渲染一致性与交互能力。关键规则速查最后将 docs/AGENTS.md 的核心规则汇总如下供文档贡献者对照自检不编辑自动生成文件v3/examples/、v3/api-ref/python/、v3/api-ref/cli/、v3/api-ref/rest-api/端点页、integrations/name/api-ref/均由源码生成唯一例外是手工编写的v3/api-ref/events/。新页面必须在docs/docs.json注册未注册页面不会出现在导航中hidden: true页面除外。所有新文档文件使用.mdx扩展名。使用 Mintlify 组件Note、Tabs、Steps等而非 Markdown 原生 admonition。保持代码示例可运行CI 通过pytest-markdown-docs执行文档代码必要时用{/* pmd-metadata: notest */}按块跳过或将整页加入docs/conftest.py的SKIP_FILES。使用绝对链接路径且不带文件扩展名如/v3/concepts/flows。先检查snippets/再动手避免内容重复。正文从##开始frontmatter 的title即 H1正文不要再加 H1。标注 Cloud-only 特性用span classbadge cloud/span标记整节或用Note内联提示并优先把 Cloud-only 指南放入v3/how-to-guides/cloud/。遵循以上规范即可让新增文档与 Prefect 的官方文档体系保持一致结构可预期、链接不失效、术语被校验、代码经过 CI 验证最终形成一套高质量、可持续演进的开源项目文档资产。【免费下载链接】prefectPrefect is a workflow orchestration framework for building resilient data pipelines in Python.项目地址: https://gitcode.com/GitHub_Trending/pr/prefect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
