docs(mkdocs): publish API docs site to GitHub Pages

[Abhishek Patil (abhishek-pattern)]

Set up a Material for MkDocs site over the existing docs/ markdown and wire it to GitHub Pages.

• mkdocs.yml: Material theme with light/dark palettes, nav covering the Metaflow API pages and admin/setup guides.
• scripts/mkdocs_hooks.py: generates index.md from README.md at build time so the landing page has a single source of truth, rebasing its docs/-prefixed links and pointing "edit this page" at the README.
• .github/workflows/docs.yaml: builds on PRs with --strict to catch dead internal links, deploys to Pages on main. Paths mirror the paths-ignore in the main CI workflow so the two do not overlap.
• pyproject.toml / uv.lock: docs dependency group (mkdocs pinned <2, which drops the plugin system this site depends on) plus docs-build and docs-serve poe tasks.

[Copilot]

Pull request overview

Sets up a MkDocs Material documentation site over the existing docs/ markdown and adds a GitHub Actions workflow to build (on PRs) and deploy (on main) the site to GitHub Pages.

Changes:

• Add mkdocs.yml configuring Material for MkDocs, navigation, and markdown extensions.
• Add an MkDocs build hook to generate index.md from README.md at build time.
• Add a Pages publish workflow plus a docs dependency group and poe tasks for building/serving docs.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
uv.lock	Adds locked dependencies required for MkDocs + Material and extensions.
scripts/mkdocs_hooks.py	Adds an MkDocs hook to generate index.md from README.md and adjust links/edit URI.
pyproject.toml	Adds a docs dependency group and poe tasks for building/serving the docs site.
mkdocs.yml	Defines the MkDocs Material site configuration (theme, nav, extensions, plugins, hooks).
.github/workflows/docs.yaml	Adds a workflow to build docs on PRs and deploy to GitHub Pages on main.

Suppressed comments (3)

.github/workflows/docs.yaml:35

• concurrency is defined at the workflow level with group: pages, so it serializes all runs (including pull_request builds) across branches/PRs. This can unnecessarily queue PR doc builds behind unrelated runs. Consider moving concurrency to the deploy job only, or keying the group by ref (e.g., pages-${{ github.ref }}) while keeping cancel-in-progress: false for main deploys.

# One Pages deploy at a time. Do not cancel a deploy that is already publishing --
# a half-finished deploy would leave the live site in an inconsistent state.
concurrency:
  group: pages
  cancel-in-progress: false

.github/workflows/docs.yaml:61

• The Pages workflow is missing the actions/configure-pages step that GitHub’s official Pages deployment examples include before uploading/deploying the artifact. Without it, deployments may be unreliable or unsupported. Add a uses: actions/configure-pages@v5 step (typically before upload-pages-artifact) and ensure the job has the permissions that step requires.

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Set up uv
        uses: astral-sh/setup-uv@v5
        with:
          enable-cache: true
          cache-dependency-glob: "${{ github.workspace }}/uv.lock"

      # --strict turns broken internal links into a build failure, so a PR that
      # renames a doc cannot silently ship a dead link. --frozen forbids uv from
      # resolving anything not already pinned in uv.lock.
      - name: Build Site
        run: uv run --frozen --group docs mkdocs build --strict

      - name: Upload Pages Artifact
        if: github.event_name != 'pull_request'
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./site

pyproject.toml:163

• docs-build/docs-serve use uv run --group docs ... without --frozen, while CI’s docs workflow uses uv run --frozen --group docs ... to enforce the lockfile. Consider adding --frozen to these poe tasks too so local builds match CI and don’t accidentally resolve outside uv.lock.

[tool.poe.tasks.docs-build]
shell = "uv run --group docs mkdocs build --strict"
help = "Build the documentation site into ./site (fails on broken links)"

[tool.poe.tasks.docs-serve]
shell = "uv run --group docs mkdocs serve"
help = "Serve the docs with live reload on http://localhost:8000"

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.