Skip to content

Commit dd98d87

Browse files
joshua-templejoshua-temple
authored
docs: stand up MkDocs Material Pages site (#88)
Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
1 parent c562bb7 commit dd98d87

4 files changed

Lines changed: 158 additions & 4 deletions

File tree

‎.github/workflows/pages.yml‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Builds and deploys the MkDocs documentation site to GitHub Pages on every
2+
# push to main that touches docs source or this workflow. Pull requests trigger
3+
# a build-only check to catch broken nav references or config errors early.
4+
#
5+
# Least-privilege: read the repo, mint an OIDC token for Pages, write the
6+
# Pages deployment. No other scopes.
7+
#
8+
# Serialize Pages deployments. Do NOT cancel in progress: a half-applied Pages
9+
# deploy can leave the live site in a broken state, so let each one finish.
10+
11+
name: Deploy docs
12+
13+
on:
14+
push:
15+
branches: [main]
16+
paths:
17+
- 'docs/**'
18+
- 'mkdocs.yml'
19+
- '.github/workflows/pages.yml'
20+
pull_request:
21+
branches: [main]
22+
paths:
23+
- 'docs/**'
24+
- 'mkdocs.yml'
25+
- '.github/workflows/pages.yml'
26+
27+
permissions:
28+
contents: read
29+
30+
concurrency:
31+
group: pages
32+
cancel-in-progress: false
33+
34+
jobs:
35+
build:
36+
name: Build
37+
runs-on: ubuntu-latest
38+
steps:
39+
- uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
40+
41+
- uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
42+
with:
43+
python-version: '3.x'
44+
cache: pip
45+
cache-dependency-path: docs/requirements.txt
46+
47+
- name: Install dependencies
48+
run: pip install -r docs/requirements.txt
49+
50+
- name: Configure Pages base URL
51+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
52+
uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
53+
54+
- name: Build site
55+
run: mkdocs build --strict
56+
57+
- name: Upload Pages artifact
58+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
59+
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
60+
with:
61+
path: site/
62+
63+
deploy:
64+
name: Deploy
65+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
66+
needs: build
67+
runs-on: ubuntu-latest
68+
permissions:
69+
pages: write
70+
id-token: write
71+
environment:
72+
name: github-pages
73+
url: ${{ steps.deployment.outputs.page_url }}
74+
steps:
75+
- name: Deploy to GitHub Pages
76+
id: deployment
77+
uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

‎docs/requirements.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
mkdocs-material==9.6.14

‎docs/versioning.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -72,12 +72,12 @@ A CLI supports the current schema version and the immediately preceding one
7272
(N-1). When a new schema major lands, CLIs that ship with it continue to read
7373
the previous major with a warning. A subsequent major may drop support for the
7474
oldest major, at which point manifests at that version are rejected with a
75-
pointer to the migration entry in [CHANGELOG.md](../CHANGELOG.md).
75+
pointer to the migration entry in [CHANGELOG.md](https://github.com/stablekernel/cascade/blob/main/CHANGELOG.md).
7676

7777
## Migrations
7878

7979
Each `schema_version` bump is recorded with a `Migration` section in
80-
[CHANGELOG.md](../CHANGELOG.md) describing exactly what changed and the steps to
80+
[CHANGELOG.md](https://github.com/stablekernel/cascade/blob/main/CHANGELOG.md) describing exactly what changed and the steps to
8181
update a manifest from the previous version. There are no migrations yet: the
8282
current schema version is the first.
8383

@@ -88,7 +88,7 @@ and new capabilities all land here. No stability guarantee is made for the CLI
8888
command surface or the manifest schema between 0.x releases; additive changes
8989
arrive without a `schema_version` bump, but breaking changes (field removals,
9090
type changes, behaviour changes) increment `schema_version` and carry a
91-
`Migration` entry in [CHANGELOG.md](../CHANGELOG.md).
91+
`Migration` entry in [CHANGELOG.md](https://github.com/stablekernel/cascade/blob/main/CHANGELOG.md).
9292

9393
**1.0** — when cascade reaches v1.0 the following guarantees apply:
9494

@@ -101,7 +101,7 @@ type changes, behaviour changes) increment `schema_version` and carry a
101101
1.x releases.
102102

103103
Older tags outside the current release line do not receive backported fixes.
104-
See [SECURITY.md](../SECURITY.md) for the security-patch policy.
104+
See [SECURITY.md](https://github.com/stablekernel/cascade/blob/main/SECURITY.md) for the security-patch policy.
105105

106106
## Version bump reference
107107

‎mkdocs.yml‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
site_name: Cascade
2+
site_description: >-
3+
Manifest-driven release orchestration for GitHub Actions — coordinate
4+
builds, promotions, and releases across any environment topology.
5+
site_url: https://stablekernel.github.io/cascade/
6+
repo_url: https://github.com/stablekernel/cascade
7+
repo_name: stablekernel/cascade
8+
edit_uri: edit/main/docs/
9+
10+
theme:
11+
name: material
12+
palette:
13+
- media: "(prefers-color-scheme: light)"
14+
scheme: default
15+
primary: indigo
16+
accent: indigo
17+
toggle:
18+
icon: material/weather-night
19+
name: Switch to dark mode
20+
- media: "(prefers-color-scheme: dark)"
21+
scheme: slate
22+
primary: indigo
23+
accent: indigo
24+
toggle:
25+
icon: material/weather-sunny
26+
name: Switch to light mode
27+
features:
28+
- navigation.tabs
29+
- navigation.sections
30+
- navigation.expand
31+
- navigation.top
32+
- search.suggest
33+
- search.highlight
34+
- content.code.copy
35+
- content.code.annotate
36+
- content.action.edit
37+
icon:
38+
repo: fontawesome/brands/github
39+
40+
plugins:
41+
- search
42+
43+
markdown_extensions:
44+
- admonition
45+
- pymdownx.details
46+
- pymdownx.superfences:
47+
custom_fences:
48+
- name: mermaid
49+
class: mermaid
50+
format: !!python/name:pymdownx.superfences.fence_code_format
51+
- pymdownx.highlight:
52+
anchor_linenums: true
53+
line_spans: __span
54+
pygments_lang_class: true
55+
- pymdownx.inlinehilite
56+
- pymdownx.snippets
57+
- pymdownx.tabbed:
58+
alternate_style: true
59+
- tables
60+
- toc:
61+
permalink: true
62+
63+
nav:
64+
- Getting Started: getting-started.md
65+
- Manifest Reference: configuration.md
66+
- Callback Contract: callback-contract.md
67+
- Workflows:
68+
- Overview: workflows.md
69+
- CLI Reference: cli-reference.md
70+
- Architecture: architecture.md
71+
- Versioning & Schema: versioning.md
72+
73+
extra:
74+
social:
75+
- icon: fontawesome/brands/github
76+
link: https://github.com/stablekernel/cascade

0 commit comments

Comments
 (0)