mkdocs.yml

site_name: GitHub Actions Gateway
site_description: >-
  An Actions Runner Controller (ARC) alternative for self-hosted GitHub Actions
  runners on multi-tenant Kubernetes — oversubscribe a shared quota, recover
  evicted jobs automatically, and isolate every tenant's GitHub egress.
site_url: https://actions-gateway.com/
repo_url: https://github.com/actions-gateway/github-actions-gateway
repo_name: actions-gateway/github-actions-gateway
edit_uri: edit/main/docs/
copyright: Licensed under the Apache License 2.0.

# The docs/ tree doubles as the in-repo documentation browsed on github.com and
# the source for this site. These paths are repo-internal (planning, contributor
# guides, the backlog); released versions of the site carry operator docs only.
# Anchored patterns (leading /) keep the per-section README.md indexes.
#
# The `dev` deploy overrides MKDOCS_EXCLUDE_DOCS with a shorter list so the
# unreleased version publishes them too (Q558) — a release is a frozen build, so
# a backlog in one would be a snapshot stale from tag day. Only the dev path in
# .github/workflows/pages.yml sets it, and it keeps /README.md excluded on every
# version: MkDocs drops it anyway as a conflict with the index.md landing page.
#
# /releases/ is excluded on EVERY version including dev, the one path here that is
# not repo-internal-vs-operator: those files are GitHub Release bodies, authored
# for github.com's renderer. Their GFM alerts (`> [!WARNING]`) have no MkDocs
# equivalent and would publish as literal text, and their links already point at
# the versioned site. The dev override in pages.yml carries this entry too.
# See website.md § Publication scope.
#
# /queue/ is the backlog (Q889), one file per item. It sits with /plan/ here:
# repo-internal, published on `dev` only. `/dev/queue/` is the store's README
# with the ordered backlog appended at build time by hooks/queue_page.py, so
# there is no generated page in the tree. It replaced /dev/STATUS/, which the
# retired table published.
exclude_docs: !ENV [MKDOCS_EXCLUDE_DOCS, "/README.md\n/plan/\n/queue/\n/development/\n/postmortems/\n/releases/\n/assets/README.md\n/assets/fonts/README.md\n"]

# Published but deliberately absent from the nav, which stays the operator-facing
# table of contents on every version: the repo-internal tree the `dev` version
# publishes (Q558, and `/postmortems/` joins it — an incident record is written
# for contributors, not operators), plus `/operations/examples/` — sample manifests reached from
# the page that explains them (admission-policies.md), not a TOC entry.
#
# Declaring every deliberate omission is what makes MkDocs' "not included in the
# nav" list mean something: what remains is a page a reader can reach only by
# search or URL, so `validation.nav.omitted_files` below fails the build on one
# (Q563) — at the INFO default, three operator pages sat there unnoticed under
# green builds (Q562). See website.md § What belongs in nav.
#
# /README.md is inert here: MkDocs drops docs/README.md as an index.md conflict
# before nav evaluation, so it reaches no scope's omitted list. Kept to mirror
# exclude_docs above rather than to suppress a report.
not_in_nav: |
  /README.md
  /plan/
  /queue/
  /development/
  /postmortems/
  /assets/README.md
  /assets/fonts/README.md
  /operations/examples/

theme:
  name: material
  custom_dir: overrides
  logo: assets/logo.svg
  favicon: assets/favicon.svg
  # Disable Material's built-in Google Fonts loader — it would fetch Roboto from
  # fonts.gstatic.com on every page view, the one Google request left in an
  # otherwise Google-free site. We self-host instead: @font-face declarations and
  # the --md-text-font / --md-code-font mapping live in stylesheets/extra.css, with
  # the woff2 files under assets/fonts/. See docs/development/website.md § Fonts.
  font: false
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - navigation.tracking
    - navigation.indexes
    - navigation.footer
    - toc.follow
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.code.annotate
    - content.tooltips
  icon:
    repo: fontawesome/brands/github
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: black
      toggle:
        icon: material/weather-night
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: black
      toggle:
        icon: material/weather-sunny
        name: Switch to light mode

extra_css:
  - stylesheets/extra.css

extra_javascript:
  - javascripts/extra.js

extra:
  # Versioned docs (Q238) — Material renders a version selector from mike's
  # versions.json when the provider is `mike`. `default: stable` marks the
  # `stable` alias (the latest release) as canonical, so a visitor viewing an
  # older release or `dev` (the unreleased main branch) gets Material's
  # "you're looking at a different version" banner. The deploy that populates
  # these versions lives in .github/workflows/pages.yml; see
  # docs/development/website.md § Versioned deploy.
  version:
    provider: mike
    default: stable
  # Privacy-respecting analytics (Plausible) — opt-in, no cookies, no Google.
  # Wired in overrides/main.html. Leave plausible_domain empty to keep analytics
  # OFF (the default). To enable, a maintainer sets it to the public site domain
  # (e.g. actions-gateway.com — this is not a secret); point plausible_src at a
  # self-hosted instance to avoid the hosted plausible.io. See
  # docs/development/website.md § Analytics.
  analytics:
    plausible_domain: ""
    plausible_src: https://plausible.io/js/script.js
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/actions-gateway/github-actions-gateway
      name: GAG on GitHub
    - icon: material/message-question-outline
      link: https://github.com/actions-gateway/github-actions-gateway/issues
      name: Questions & issues

# The docs-site announce bar advertises the newest stable release. Deriving that
# version from the git tags (Q393) keeps it out of overrides/main.html, where it
# was a hand-edited release step every stable tag missed. See
# docs/development/website.md § The announce bar.
#
# A relative link this build does not publish resolves on github.com and 404s on
# the site — a target escaping docs/ (Q558), or a page the version's own scope
# drops, like design/ citing plan/ on a release (Q561). source_links.py
# absolutizes those against repo_url, deciding per build from its own file set,
# so one markdown link works everywhere. See website.md § Links into the source
# tree.
#
# backlog_link.py derives whether this build carries the backlog store, so the
# version banner links it only where the page exists (Q558).
#
# queue_page.py renders the backlog into /dev/queue/ and MUST precede
# source_links.py: hooks run in this order, both use on_page_markdown, and an
# item's `target` routinely points outside docs/ (a Go file, a workflow), which
# is precisely what source_links absolutizes. Appended after it, those links
# reach the build unrewritten and fail --strict.
hooks:
  - hooks/release_version.py
  - hooks/release_gates.py
  - hooks/queue_page.py
  - hooks/source_links.py
  - hooks/backlog_link.py

# Site-side link gate (Q560). scripts/docs/check-doc-links.sh resolves links the way
# github.com does; MkDocs resolves them differently, so a link can pass that gate
# and 404 here — heading-slug dedup suffixes (`_1` here, `-1` on GitHub), a bare
# `dir/` target that GitHub renders as the directory's README, an `<angled>`
# placeholder that Python-Markdown strips as a tag. These ship as INFO by
# default, invisible under a green build; raised to warnings they fail
# `mkdocs build --strict` in pages.yml. `nav.omitted_files` is the same move for
# a published page in no nav section and no `not_in_nav` entry (Q563).
# `absolute_links` keeps its default, and so does `nav.not_found` — already warn.
# A link to a page the built scope excludes is NOT covered here — MkDocs clamps
# that below warning level whatever this block says, so
# source_links.py absolutizes it instead (Q561). See
# docs/development/website.md § The two link gates.
validation:
  nav:
    omitted_files: warn
  links:
    not_found: warn
    anchors: warn
    unrecognized_links: warn

plugins:
  - search

markdown_extensions:
  - admonition
  - attr_list
  - md_in_html
  - tables
  - toc:
      permalink: true
      # Match GitHub's heading-slug algorithm so the in-repo docs' GitHub-style
      # anchor links (e.g. #21-tier-1--gmc) resolve on the site too.
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  - pymdownx.details
  # Enables :material-*:/:fontawesome-*: icon shortcodes (used in the landing-page grid cards).
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.inlinehilite
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

nav:
  - Home: index.md
  - Why GAG: why-gag.md
  - Alternatives: alternatives.md
  - Features: features.md
  - Demo: demo.md
  - Get started: getting-started.md
  - Roadmap: roadmap.md
  - Design:
      - Overview: design/README.md
      - Executive summary: design/01-executive-summary.md
      - Architecture: design/02-architecture.md
      - Network architecture: design/network-architecture.md
      - API & data contracts: design/03-api-contracts.md
      - Operational flows: design/04-operational-flows.md
      - Security: design/05-security.md
      - Implementation phases: design/06-implementation-phases.md
      - Test plan: design/07-test-plan.md
      - Glossary: design/08-glossary.md
      - "Appendix A — Capacity & SLOs": design/appendix-a-capacity-slos.md
      - "Appendix B — Worker isolation": design/appendix-b-worker-isolation.md
      - "Appendix C — AI-assisted implementation": design/appendix-c-ai-implementation.md
      - "Appendix D — Alternatives considered": design/appendix-d-alternatives-considered.md
      - "Appendix E — Capacity planning": design/appendix-e-capacity-planning.md
      - "Appendix F — Cost model": design/appendix-f-cost-model.md
      - "Appendix G — Future enhancements": design/appendix-g-future-enhancements.md
      - "Appendix H — v2 API decomposition": design/appendix-h-v2-api-decomposition.md
      - "GitHub protocol dependencies": design/github-protocol-dependencies.md
  - Operations:
      - Overview: operations/README.md
      - "Personas: who owns what": operations/personas.md
      - Install: operations/install.md
      - "Air-gapped install": operations/air-gapped-install.md
      - "GitOps install (Argo CD / Flux)": operations/gitops.md
      - Upgrade: operations/upgrade.md
      - "Migrate from ARC": operations/migration-from-arc.md
      - "Migrate v1 → v2": operations/migration-v1-to-v2.md
      - "Deprecations & the v2.0.0 removal": operations/v1alpha1-deprecation.md
      - Tenant onboarding: operations/tenant-onboarding.md
      - "ResourceQuota sizing": operations/resourcequota-sizing.md
      - Runner template library: operations/runner-template-library.md
      - "Shared worker storage (RWX)": operations/worker-shared-storage.md
      - In-runner image builds: operations/in-runner-image-builds.md
      - "Kata DinD / image-build workloads": operations/kata-dind-workloads.md
      - "P2P image distribution": operations/p2p-image-distribution.md
      - Service mesh coexistence: operations/service-mesh-coexistence.md
      - Observability:
          - Overview: operations/observability.md
          - "Metrics reference": operations/observability-metrics.md
          - "Accessing metrics (scraping)": operations/observability-metrics-access.md
          - "Alerting & SLOs": operations/observability-alerting.md
          - "Grafana dashboards": operations/observability-dashboards.md
          - "Logging & tracing": operations/observability-logging.md
      - "Cost attribution": operations/cost-attribution.md
      - "Worker right-sizing": operations/worker-rightsizing.md
      - "Node shutdown budgets": operations/node-shutdown-budgets.md
      - Runbook: operations/runbook.md
      - Backup & restore: operations/backup-restore.md
      - Velero backup & restore: operations/velero-backup-restore.md
      - Troubleshooting: operations/troubleshooting.md
      - Security operations: operations/security-operations.md
      - "Admission policies (Kyverno / Gatekeeper)": operations/admission-policies.md
      - Release: operations/release.md
      - "Kata-on-GKE spike runbook": operations/kata-ci-spike-runbook.md
  - Reference:
      - Overview: reference/README.md
      - "API reference (v2beta1)": reference/api.md