Skip to content

Contributing to the Docs

These docs are built with MkDocs and the Material for MkDocs theme. Anyone can fix a typo, improve a page, or add new content with a pull request.

Prerequisites

  • Python 3.10+
  • uv (recommended) or pip
  • Git

Run the docs locally

git clone https://github.com/potpie-ai/potpie-docs-test.git
cd potpie-docs-test
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
mkdocs serve

git clone https://github.com/potpie-ai/potpie-docs-test.git
cd potpie-docs-test
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
mkdocs serve

Then open http://127.0.0.1:8000. The site live-reloads as you edit files under docs/.

Tip

When this docs site is merged into the main potpie repository, the same commands apply — clone that repo and run mkdocs serve from its root.

Project layout

mkdocs.yml          # site config: theme, nav, plugins, extensions
requirements.txt    # docs build dependencies (pinned)
docs/
  index.md          # landing page
  introduction.md   # what Potpie is + end-to-end scenario
  quickstart.md
  concepts/         # context graph, knowledge graph
  cli/              # installation, commands, troubleshooting
  agents/           # prebuilt + custom agents
  tutorials/        # hands-on walkthroughs
  api-reference/    # REST API + authentication
  internals/        # auto-generated Python API (mkdocstrings)
  stylesheets/      # custom CSS (brand colors)
src/potpie/         # sample module for mkdocstrings autodoc demo

Adding a new page

  1. Create the Markdown file under the appropriate folder in docs/.
  2. Add it to the nav: section of mkdocs.yml — pages not listed in nav won't appear in the sidebar.
  3. Run mkdocs serve and confirm it renders.

Style conventions

  • Use admonitions for callouts: !!! note, !!! tip, !!! warning
  • Use tabbed blocks for alternatives (e.g. uv vs pip)
  • Link between pages with relative .md paths so links are checked at build time
  • Show real commands and their expected output, not just prose
  • Do not invent product features — if something is unclear in source material, leave a <!-- TODO: verify --> comment rather than guessing

Before you open a PR

Always run a strict build — this is the same check CI runs, and it fails on broken links, missing nav entries, or invalid references:

mkdocs build --strict

Fix every warning until it passes clean, then open your pull request.

Deployment model

This site uses a source-on-main, published HTML-on-gh-pages split managed by Mike:

Branch Contents
main Markdown source (docs/), mkdocs.yml, requirements.txt
gh-pages Versioned built site only (index.html, versions.json, v1.0/, latest/, etc.)

Generated artifacts do not belong on main:

  • site/ is local build output only and is git-ignored
  • gh-pages/ is an optional local Mike worktree and is git-ignored
  • only Mike should write published files to the gh-pages branch

CI/CD workflows

Two GitHub Actions workflows are expected:

  1. Docs CI: on every push or PR to main, run mkdocs build --strict to validate the source docs.
  2. Docs Release: on every push to main, run Mike to publish the current docs version into gh-pages and move latest to it.

This keeps main clean while preserving every published documentation version.

Release workflow

Local Mike command

To prepare a new stable version locally and move latest to it in your local Mike state:

./scripts/docs-release.sh v1.0

To publish a version without moving latest:

./scripts/docs-release.sh v1.1 v1.1 false

Key behavior:

  • ./scripts/docs-release.sh v1.0 runs a strict build, creates or updates the v1.0/ version, points latest/ at it, and keeps the root default on latest
  • add a fourth argument of true only when you intentionally want Mike to push the gh-pages branch from your local machine
  • older versions such as v1.0/ and v1.1/ remain intact unless you explicitly delete them with Mike

GitHub Actions release behavior

The repository release workflow publishes automatically on every push to main:

  1. A PR is merged into main
  2. Docs Release reads project.version from pyproject.toml
  3. It publishes that version as v<project.version> using Mike
  4. It moves the latest alias to that published version
  5. Mike writes the generated static site to gh-pages
  6. Cloudflare Pages redeploys from gh-pages

Recommended stable release pattern:

  • v1.0, v1.1, v2.0 are immutable version directories once you move on to a newer version number
  • latest always points to the version published from the latest merge to main
  • bump project.version in pyproject.toml before the first merge for a new docs release line
  • if you merge multiple PRs without changing project.version, Mike updates that same version directory instead of creating a new one

Cloudflare Pages

Cloudflare Pages should serve the published branch, not rebuild from source:

  • Production branch: gh-pages
  • Build command: none
  • Build output directory: /

That setup makes Cloudflare serve the exact Mike-generated output, including version folders and versions.json.

If Cloudflare is still building from main, switch it to gh-pages after the release workflow is in use.

Note

The .scratch/ folder (if present) holds read-only clones of source repos used while drafting content. It is git-ignored and never committed.