Write Docs

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.

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.

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.

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. Follow the existing pattern: "Why use it" section, prerequisites, install instructions, blocks setup, then per-service usage sections.

API Reference (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.

Release Notes (v3/release-notes/)

Changelogs organized by product surface: oss/ for open-source releases, cloud/ for Prefect Cloud, integrations/ for integration packages.

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

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.

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.

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.