Skip to content

Commit 1a9ec04

Browse files
zircotezircote
committed
feat: add Astro + Starlight documentation site
- Scaffold Astro 5 site with Starlight and astro-mermaid - Add generators that build MDX from agents, commands, skills, and references - Generate 33 pages: 3 agents, 7 commands, 12 skills, 10 references, 1 changelog - Hand-authored splash page with CardGrid overview - Freshness checker ensures generated content stays in sync - GitHub Pages deploy workflow on push to main - Static assets: logos, OG image, llms.txt
1 parent f267994 commit 1a9ec04

50 files changed

Lines changed: 16866 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/docs-deploy.yml‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
name: Deploy Documentation
3+
4+
"on":
5+
push:
6+
branches: [main]
7+
paths:
8+
- 'agents/**'
9+
- 'commands/**'
10+
- 'site/**'
11+
- 'skills/**'
12+
- 'templates/**'
13+
- 'CHANGELOG.md'
14+
- 'README.md'
15+
workflow_dispatch:
16+
17+
permissions:
18+
contents: read
19+
pages: write
20+
id-token: write
21+
22+
concurrency:
23+
group: "pages"
24+
cancel-in-progress: false
25+
26+
jobs:
27+
build-docs:
28+
name: Build Documentation
29+
runs-on: ubuntu-latest
30+
31+
steps:
32+
- name: Checkout code
33+
# yamllint disable-line rule:line-length
34+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
35+
36+
- name: Setup Node.js
37+
# yamllint disable-line rule:line-length
38+
uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
39+
with:
40+
node-version: '22'
41+
42+
- name: Install site dependencies
43+
working-directory: site
44+
run: npm ci || npm install
45+
46+
- name: Generate content
47+
working-directory: site
48+
run: npm run generate
49+
50+
- name: Check freshness
51+
working-directory: site
52+
run: npm run check:freshness
53+
54+
- name: Build Astro site
55+
working-directory: site
56+
run: npx astro build
57+
58+
- name: Setup Pages
59+
# yamllint disable-line rule:line-length
60+
uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
61+
62+
- name: Upload artifact
63+
# yamllint disable-line rule:line-length
64+
uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
65+
with:
66+
path: site/dist
67+
68+
deploy:
69+
name: Deploy to GitHub Pages
70+
environment:
71+
name: github-pages
72+
url: ${{ steps.deployment.outputs.page_url }}
73+
runs-on: ubuntu-latest
74+
needs: build-docs
75+
76+
steps:
77+
- name: Deploy to GitHub Pages
78+
id: deployment
79+
# yamllint disable-line rule:line-length
80+
uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

‎site/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
node_modules/
2+
dist/
3+
.astro/

‎site/astro.config.mjs‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
import { defineConfig } from "astro/config";
2+
import starlight from "@astrojs/starlight";
3+
import astroMermaid from "astro-mermaid";
4+
5+
export default defineConfig({
6+
site: "https://zircote.com",
7+
base: "/adr",
8+
integrations: [
9+
astroMermaid(),
10+
starlight({
11+
title: "ADR Plugin",
12+
head: [
13+
{
14+
tag: "meta",
15+
attrs: {
16+
property: "og:image",
17+
content: "https://zircote.com/adr/og-image.svg",
18+
},
19+
},
20+
{
21+
tag: "meta",
22+
attrs: { property: "og:image:width", content: "1280" },
23+
},
24+
{
25+
tag: "meta",
26+
attrs: { property: "og:image:height", content: "640" },
27+
},
28+
{
29+
tag: "meta",
30+
attrs: { name: "twitter:card", content: "summary_large_image" },
31+
},
32+
{
33+
tag: "meta",
34+
attrs: {
35+
name: "twitter:image",
36+
content: "https://zircote.com/adr/og-image.svg",
37+
},
38+
},
39+
],
40+
logo: {
41+
light: "./src/assets/logo-light.svg",
42+
dark: "./src/assets/logo-dark.svg",
43+
replacesTitle: true,
44+
},
45+
social: [
46+
{
47+
icon: "github",
48+
label: "GitHub",
49+
href: "https://github.com/zircote/adr",
50+
},
51+
],
52+
sidebar: [
53+
{
54+
label: "Overview",
55+
items: [
56+
{ label: "Introduction", slug: "index" },
57+
{ label: "Changelog", slug: "changelog" },
58+
],
59+
},
60+
{
61+
label: "Commands",
62+
items: [
63+
{ label: "/adr:setup", slug: "commands/adr-setup" },
64+
{ label: "/adr:new", slug: "commands/adr-new" },
65+
{ label: "/adr:list", slug: "commands/adr-list" },
66+
{ label: "/adr:update", slug: "commands/adr-update" },
67+
{ label: "/adr:supersede", slug: "commands/adr-supersede" },
68+
{ label: "/adr:search", slug: "commands/adr-search" },
69+
{ label: "/adr:export", slug: "commands/adr-export" },
70+
],
71+
},
72+
{
73+
label: "Agents",
74+
items: [
75+
{ label: "ADR Author", slug: "agents/adr-author" },
76+
{ label: "ADR Compliance", slug: "agents/adr-compliance" },
77+
{ label: "ADR Researcher", slug: "agents/adr-researcher" },
78+
],
79+
},
80+
{
81+
label: "Skills — Core",
82+
items: [
83+
{ label: "ADR Fundamentals", slug: "skills/adr-fundamentals" },
84+
{ label: "Decision Drivers", slug: "skills/adr-decision-drivers" },
85+
{ label: "ADR Quality", slug: "skills/adr-quality" },
86+
],
87+
},
88+
{
89+
label: "Skills — Formats",
90+
items: [
91+
{ label: "MADR", slug: "skills/adr-format-madr" },
92+
{
93+
label: "Structured MADR",
94+
slug: "skills/adr-format-structured-madr",
95+
},
96+
{ label: "Nygard", slug: "skills/adr-format-nygard" },
97+
{ label: "Y-Statement", slug: "skills/adr-format-y-statement" },
98+
{ label: "Alexandrian", slug: "skills/adr-format-alexandrian" },
99+
{ label: "Business Case", slug: "skills/adr-format-business-case" },
100+
{ label: "Tyree-Akerman", slug: "skills/adr-format-tyree-akerman" },
101+
],
102+
},
103+
{
104+
label: "Skills — Specialized",
105+
items: [
106+
{ label: "ADR Compliance", slug: "skills/adr-compliance" },
107+
{ label: "ADR Integration", slug: "skills/adr-integration" },
108+
],
109+
},
110+
{
111+
label: "Reference Materials",
112+
items: [
113+
{
114+
label: "Decision Criteria",
115+
slug: "references/decision-criteria",
116+
},
117+
{ label: "Review Checklist", slug: "references/review-checklist" },
118+
{
119+
label: "Quality Attributes",
120+
slug: "references/quality-attributes",
121+
},
122+
{
123+
label: "Trade-off Patterns",
124+
slug: "references/trade-off-patterns",
125+
},
126+
{ label: "MADR Examples", slug: "references/madr-examples" },
127+
{
128+
label: "Structured MADR Examples",
129+
slug: "references/structured-madr-examples",
130+
},
131+
{
132+
label: "Compliance Patterns",
133+
slug: "references/compliance-patterns",
134+
},
135+
{
136+
label: "Compliance Automation",
137+
slug: "references/compliance-automation",
138+
},
139+
{ label: "CI Templates", slug: "references/ci-templates" },
140+
{ label: "Export Templates", slug: "references/export-templates" },
141+
],
142+
},
143+
],
144+
}),
145+
],
146+
});

0 commit comments

Comments
 (0)