Skip to content

Commit ddd01cf

Browse files
marcusrbrownmarcusrbrown
authored
docs: scaffold Starlight documentation site (#56)
* docs: scaffold Starlight documentation site with content - Initialize Starlight project in docs/ with Astro + brand colors - Configure /systematic base path for GitHub Pages deployment - Add 6 hand-crafted content pages (installation, config, architecture, guides) - Create build-time transform script for generating reference docs from source - Update root config: gitignore, package.json workspace, README docs badge - Add GitHub Actions workflow for cross-repo deployment to fro-bot/systematic Verification: - 35 pages build successfully (6 hand-crafted + 28 generated + 404) - Root project unaffected (build, tests, lint all pass) - Generated reference files gitignored (build artifacts only) - Package excludes docs/ directory * ci(docs): fix actions versions in docs workflow * fix(docs): resolve typecheck failure and apply review fixes - Add @opencode-ai/sdk as explicit devDependency to fix workspace hoisting - Update tsconfig types from bun-types to bun (@types/bun) - Fix Starlight social config to array format (required >=0.33.0) - Add error handling and input validation to transform-content.ts - Improve docs workflow deploy safety (verify output, conditional push) - Add .astro and .sisyphus to biome ignore list - Update bun.lock for Starlight 0.37.6 and new dependencies * fix(docs): resolve build and navigation issues Fix sidebar paths, add stale file cleanup, improve workflow reliability, and correct internal links to use base path. * docs: harden reference generation cleanup * docs: add reference landing pages * docs: order guide sidebar * ci(docs): guard docs deploy in forks * ci: add docs build check * docs: add docs next steps plan
1 parent 75f73d3 commit ddd01cf

27 files changed

Lines changed: 2438 additions & 18 deletions

‎.github/settings.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ branches:
1111
protection:
1212
required_status_checks:
1313
strict: true
14-
contexts: [Build, Typecheck, Lint, Test, Release, Analyze (typescript), CodeQL, Renovate / Renovate]
14+
contexts: [Build, Docs Build, Typecheck, Lint, Test, Release, Analyze (typescript), CodeQL, Renovate / Renovate]
1515
enforce_admins: true
1616
required_pull_request_reviews: null
1717
restrictions: null

‎.github/workflows/docs.yaml‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
name: Docs
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'docs/**'
8+
- 'skills/**'
9+
- 'agents/**'
10+
- 'commands/**'
11+
- 'README.md'
12+
workflow_dispatch:
13+
14+
concurrency:
15+
group: docs-deploy
16+
cancel-in-progress: true
17+
18+
permissions:
19+
contents: read
20+
21+
jobs:
22+
build-and-deploy:
23+
name: Build and Deploy Docs
24+
runs-on: ubuntu-latest
25+
steps:
26+
- name: Checkout
27+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
28+
29+
- name: Setup Bun
30+
uses: oven-sh/setup-bun@3d267786b128fe76c2f16a390aa2448b815359f3 # v2.1.2
31+
32+
- name: Install dependencies
33+
run: bun install --frozen-lockfile
34+
35+
- name: Generate reference content
36+
run: bun run docs:generate
37+
38+
- name: Build docs
39+
run: bun run --cwd docs build
40+
41+
- name: Create GitHub App token
42+
if: github.repository == 'marcusrbrown/systematic'
43+
uses: actions/create-github-app-token@29824e69f54612133e76f7eaac726eef6c875baf # v2.2.1
44+
id: app-token
45+
with:
46+
app-id: ${{ secrets.FRO_BOT_APPLICATION_ID }}
47+
private-key: ${{ secrets.FRO_BOT_APPLICATION_PRIVATE_KEY }}
48+
owner: fro-bot
49+
50+
- name: Deploy to fro-bot/systematic
51+
if: github.repository == 'marcusrbrown/systematic'
52+
env:
53+
GH_TOKEN: ${{ steps.app-token.outputs.token }}
54+
APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
55+
run: |
56+
name="${APP_SLUG}[bot]"
57+
user_id=$(gh api "/users/${name}" --jq .id)
58+
email="${user_id}+${name}@users.noreply.github.com"
59+
git config --global user.email "${email}"
60+
git config --global user.name "${name}"
61+
62+
# Verify docs build output exists
63+
if [ ! -d "docs/dist" ]; then
64+
echo "✗ Docs build output not found"
65+
exit 1
66+
fi
67+
68+
# Clone deployment repository
69+
git clone "https://x-access-token:${GH_TOKEN}@github.com/fro-bot/systematic.git" deploy-repo
70+
cd deploy-repo
71+
72+
# Clean and copy new docs (preserve .git directory)
73+
find . -mindepth 1 -not -path './.git' -not -path './.git/*' -delete
74+
cp -r ../docs/dist/* .
75+
76+
# Commit and push if there are changes
77+
git add -A
78+
if ! git diff-index --quiet HEAD --; then
79+
git commit -m "Deploy docs from marcusrbrown/systematic@${{ github.sha }}"
80+
git push
81+
else
82+
echo "No changes to commit"
83+
fi

‎.github/workflows/main.yaml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,21 @@ jobs:
8383
- name: Run tests
8484
run: bun test tests/unit
8585

86+
docs:
87+
name: Docs Build
88+
runs-on: ubuntu-latest
89+
steps:
90+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
91+
92+
- name: Setup Bun
93+
uses: oven-sh/setup-bun@3d267786b128fe76c2f16a390aa2448b815359f3 # v2.1.2
94+
95+
- name: Install dependencies
96+
run: bun install --frozen-lockfile
97+
98+
- name: Build docs
99+
run: bun run docs:build
100+
86101
release:
87102
env:
88103
DRY_RUN: ${{ github.event_name == 'pull_request' || github.event.inputs.dry-run && 'true' || 'false' }}

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,3 +29,10 @@ tests/tmp/
2929

3030
# Sisyphus (OMO)
3131
.sisyphus/
32+
33+
# Docs build artifacts
34+
docs/dist/
35+
docs/.astro/
36+
docs/src/content/docs/reference/**
37+
!docs/src/content/docs/reference/**/
38+
!docs/src/content/docs/reference/**/index.mdx

‎README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010

1111
[![Build Status](https://img.shields.io/github/actions/workflow/status/marcusrbrown/systematic/main.yaml?style=flat-square&label=build&labelColor=1a1a2e&color=4FD1C5)](https://github.com/marcusrbrown/systematic/actions)
1212
[![npm version](https://img.shields.io/npm/v/@fro.bot/systematic?style=flat-square&label=npm&labelColor=1a1a2e&color=E91E8C)](https://www.npmjs.com/package/@fro.bot/systematic)
13+
[![Docs](https://img.shields.io/badge/docs-fro.bot/systematic-4FD1C5?style=flat-square&labelColor=1a1a2e)](https://fro.bot/systematic)
1314
[![License](https://img.shields.io/badge/license-MIT-F5A623?style=flat-square&labelColor=1a1a2e)](LICENSE)
1415

1516
<br>
@@ -324,7 +325,7 @@ See [`AGENTS.md`](./AGENTS.md) for detailed development guidelines, code style c
324325

325326
## Converting from Claude Code
326327

327-
Migrating skills, agents, or commands from Claude Code (CEP) to Systematic? See the [Conversion Guide](./docs/CONVERSION-GUIDE.md) for field mappings and examples.
328+
Migrating skills, agents, or commands from Claude Code (CEP) to Systematic? See the [Conversion Guide](https://fro.bot/systematic/guides/conversion-guide) for field mappings and examples. (Also available as [local Markdown](./docs/CONVERSION-GUIDE.md).)
328329

329330
## References
330331

‎biome.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,9 @@
3030
"!**/dist",
3131
"!**/.opencode",
3232
"!**/node_modules",
33-
"!**/*.md"
33+
"!**/*.md",
34+
"!**/.astro",
35+
"!.sisyphus"
3436
]
3537
}
3638
}

0 commit comments

Comments
 (0)