We use Mintlify to host and build the Prefect documentation.

The main branch of the prefecthq/prefect GitHub repository is used to build the Prefect 3.0 docs at docs-3.prefect.io.

The 2.x docs are hosted at docs-2.prefect.io and built from the 2.x branch of the repository.

Fork the repository

All contributions to Prefect need to start on a fork of the repository. Once you have successfully forked the Prefect repo, clone a local version to your machine:

git clone https://github.com/GITHUB-USERNAME/prefect.git
cd prefect

Create a branch with an informative name:

git checkout -b fix-for-issue-NUM

After committing your changes to this branch, you can then open a pull request from your fork that we will review with you.

Set up your local environment

We provide a justfile with common commands to simplify development. We recommend using just to run these commands.

Installing just

To install just:

  • macOS: brew install just or cargo install just
  • Linux: cargo install just or check your package manager
  • Windows: scoop install just or cargo install just

For more installation options, see the just documentation.

  1. Clone this repository.
  2. Run just docs to start the documentation server.

Your docs should now be available at http://localhost:3000.

Manual setup

If you prefer not to use just, you can set up manually:

  1. Clone this repository.
  2. Make sure you have a recent version of Node.js installed. We recommend using nvm to manage Node.js versions.
  3. Run cd docs to navigate to the docs directory.
  4. Run nvm use node to use the correct Node.js version.
  5. Run npm i -g mintlify to install Mintlify.
  6. Run mintlify dev to start the development server.

Your docs should now be available at http://localhost:3000.

See the Mintlify documentation for more information on how to install Mintlify, build previews, and use Mintlify’s features while writing docs.

All documentation is written in .mdx files, which are Markdown files that can contain JavaScript and React components.

Considerations

Keep in mind the following when writing documentation.

External references

Prefect resources can be managed in several ways, including through the CLI, UI, Terraform, Helm, and API.

When documenting a resource, consider including external references that describe how to manage the resource in other ways. Snippets are available to provide these references in a consistent format.

For example, the Deployment documentation includes a snippet for the Terraform provider:

import { TF } from "/snippets/resource-management/terraform.mdx"
import { deployments } from "/snippets/resource-management/vars.mdx"

<TF name="deployments" href={deployments.tf} />

For more information on how to use snippets, see the Mintlify documentation.