From 670e5759f34a1afd6132728160f5f2ab1d26ed56 Mon Sep 17 00:00:00 2001 From: Joshua Temple Date: Wed, 10 Jun 2026 05:39:18 -0400 Subject: [PATCH] docs: stand up MkDocs Material Pages site Signed-off-by: Joshua Temple --- .github/workflows/pages.yml | 77 +++++++++++++++++++++++++++++++++++++ docs/requirements.txt | 1 + docs/versioning.md | 8 ++-- mkdocs.yml | 76 ++++++++++++++++++++++++++++++++++++ 4 files changed, 158 insertions(+), 4 deletions(-) create mode 100644 .github/workflows/pages.yml create mode 100644 docs/requirements.txt create mode 100644 mkdocs.yml diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 00000000..b56cd9f9 --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,77 @@ +# Builds and deploys the MkDocs documentation site to GitHub Pages on every +# push to main that touches docs source or this workflow. Pull requests trigger +# a build-only check to catch broken nav references or config errors early. +# +# Least-privilege: read the repo, mint an OIDC token for Pages, write the +# Pages deployment. No other scopes. +# +# Serialize Pages deployments. Do NOT cancel in progress: a half-applied Pages +# deploy can leave the live site in a broken state, so let each one finish. + +name: Deploy docs + +on: + push: + branches: [main] + paths: + - 'docs/**' + - 'mkdocs.yml' + - '.github/workflows/pages.yml' + pull_request: + branches: [main] + paths: + - 'docs/**' + - 'mkdocs.yml' + - '.github/workflows/pages.yml' + +permissions: + contents: read + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + name: Build + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 + + - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0 + with: + python-version: '3.x' + cache: pip + cache-dependency-path: docs/requirements.txt + + - name: Install dependencies + run: pip install -r docs/requirements.txt + + - name: Configure Pages base URL + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0 + + - name: Build site + run: mkdocs build --strict + + - name: Upload Pages artifact + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0 + with: + path: site/ + + deploy: + name: Deploy + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + needs: build + runs-on: ubuntu-latest + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0 diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..c8de0c5d --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +mkdocs-material==9.6.14 diff --git a/docs/versioning.md b/docs/versioning.md index 371b5fde..9c28c354 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -72,12 +72,12 @@ A CLI supports the current schema version and the immediately preceding one (N-1). When a new schema major lands, CLIs that ship with it continue to read the previous major with a warning. A subsequent major may drop support for the oldest major, at which point manifests at that version are rejected with a -pointer to the migration entry in [CHANGELOG.md](../CHANGELOG.md). +pointer to the migration entry in [CHANGELOG.md](https://github.com/stablekernel/cascade/blob/main/CHANGELOG.md). ## Migrations Each `schema_version` bump is recorded with a `Migration` section in -[CHANGELOG.md](../CHANGELOG.md) describing exactly what changed and the steps to +[CHANGELOG.md](https://github.com/stablekernel/cascade/blob/main/CHANGELOG.md) describing exactly what changed and the steps to update a manifest from the previous version. There are no migrations yet: the current schema version is the first. @@ -88,7 +88,7 @@ and new capabilities all land here. No stability guarantee is made for the CLI command surface or the manifest schema between 0.x releases; additive changes arrive without a `schema_version` bump, but breaking changes (field removals, type changes, behaviour changes) increment `schema_version` and carry a -`Migration` entry in [CHANGELOG.md](../CHANGELOG.md). +`Migration` entry in [CHANGELOG.md](https://github.com/stablekernel/cascade/blob/main/CHANGELOG.md). **1.0** — when cascade reaches v1.0 the following guarantees apply: @@ -101,7 +101,7 @@ type changes, behaviour changes) increment `schema_version` and carry a 1.x releases. Older tags outside the current release line do not receive backported fixes. -See [SECURITY.md](../SECURITY.md) for the security-patch policy. +See [SECURITY.md](https://github.com/stablekernel/cascade/blob/main/SECURITY.md) for the security-patch policy. ## Version bump reference diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..fda052ad --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,76 @@ +site_name: Cascade +site_description: >- + Manifest-driven release orchestration for GitHub Actions — coordinate + builds, promotions, and releases across any environment topology. +site_url: https://stablekernel.github.io/cascade/ +repo_url: https://github.com/stablekernel/cascade +repo_name: stablekernel/cascade +edit_uri: edit/main/docs/ + +theme: + name: material + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: indigo + accent: indigo + toggle: + icon: material/weather-night + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: indigo + accent: indigo + toggle: + icon: material/weather-sunny + name: Switch to light mode + features: + - navigation.tabs + - navigation.sections + - navigation.expand + - navigation.top + - search.suggest + - search.highlight + - content.code.copy + - content.code.annotate + - content.action.edit + icon: + repo: fontawesome/brands/github + +plugins: + - search + +markdown_extensions: + - admonition + - pymdownx.details + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.tabbed: + alternate_style: true + - tables + - toc: + permalink: true + +nav: + - Getting Started: getting-started.md + - Manifest Reference: configuration.md + - Callback Contract: callback-contract.md + - Workflows: + - Overview: workflows.md + - CLI Reference: cli-reference.md + - Architecture: architecture.md + - Versioning & Schema: versioning.md + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/stablekernel/cascade