refactor: migrate from Astro Starlight to Docusaurus and refactor hosting system

.github/workflows/deploy.yml

@@ -0,0 +1,15 @@
+name: Deploy Docs Site
+
+on:
+    push:
+        branches: [main]
+    workflow_dispatch:
+
+jobs:
+    deploy:
+        name: Rebuild and deploy to server
+        runs-on: [self-hosted, docs]
+
+        steps:
+            - name: Rebuild and deploy docs site
+              run: bash /home/trickfire/trickfire-docs/scripts/build.sh

.github/workflows/sync-docs.yml

@@ -0,0 +1,38 @@
+name: Sync Docs (Reusable)
+
+on:
+    workflow_call:
+        inputs:
+            repo-name:
+                description: "URL path segment for this project (defaults to the calling repo's name)"
+                required: false
+                type: string
+                default: ""
+
+jobs:
+    sync:
+        name: Sync docs and rebuild site
+        runs-on: [self-hosted, docs]
+
+        steps:
+            - name: Checkout calling repo
+              uses: actions/checkout@v4
+
+            - name: Resolve repo name
+              id: name
+              run: |
+                  NAME="${{ inputs.repo-name }}"
+                  if [ -z "$NAME" ]; then
+                    NAME="${{ github.event.repository.name }}"
+                  fi
+                  echo "value=$NAME" >> "$GITHUB_OUTPUT"
+
+            - name: Sync docs content
+              run: |
+                  DEST="/home/trickfire/trickfire-docs/content/${{ steps.name.outputs.value }}"
+                  mkdir -p "$DEST"
+                  rsync -av --delete --checksum docs/ "$DEST/"
+                  cp docs.config.ts "$DEST/docs.config.ts"
+
+            - name: Rebuild and deploy docs site
+              run: bash /home/trickfire/trickfire-docs/scripts/build.sh

.gitignore

@@ -5,16 +5,15 @@
 # Node
 node_modules/
 
-# Astro
-dist/
-.astro/
+# Docusaurus
+build/
+.docusaurus/
 
 # Test coverage
 coverage/
 
 # CLI framework build/dev artifacts
 dist-cli/
-.astro-cache/
 *.tsbuildinfo
 **/*.tgz
 npm-debug.log*
@@ -23,6 +22,13 @@ npm-debug.log*
 .test-repo/
 .framework-test/
 
+# Local dev generated config (in member repos; also useful to ignore here during testing)
+.trickfire/
+
+# Synced member repo docs — populated by GitHub Actions runner on the server
+content/*
+!content/.gitkeep
+
 # Editor
 .vscode/*
 !.vscode/settings.json

.npmrc

@@ -1 +1,3 @@
 confirm-module-purge=false
+shamefully-hoist=true
+node-linker=hoisted

.prettierignore

@@ -1,5 +1,7 @@
 node_modules/
-dist/
-.astro/
+dist-cli/
+build/
+.docusaurus/
 coverage/
 pnpm-lock.yaml
+content/

.vscode/settings.json

@@ -1,10 +1,6 @@
 {
     "files.eol": "\n",
     "editor.rulers": [100],
-    "[astro]": {
-        "editor.defaultFormatter": "esbenp.prettier-vscode",
-        "editor.formatOnSave": true
-    },
     "[javascript]": {
         "editor.defaultFormatter": "esbenp.prettier-vscode",
         "editor.formatOnSave": true
@@ -34,13 +30,6 @@
     },
     "eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact"],
     "files.exclude": {
-        "**/.git": true,
-        "**/.DS_Store": true,
-        "**/node_modules": true,
-        "**/.astro": true,
-        "**/dist": true,
-        "**/dist-cli": true,
-        "**/.husky/_*": true,
-        "**/.pnpm-store": true
+        "**/node_modules": true
     }
 }

CONTRIBUTING.md

@@ -8,21 +8,17 @@ pnpm install
 
 Node 22 (see `.nvmrc`) and pnpm are required.
 
-This repo produces two things - the `docs.trickfirerobotics.com` portal site and the `trickfire-docs` npm package - sharing one `package.json`, lockfile, and toolchain. See the [README](README.md#repo-layout) for how the two are laid out and which commands belong to which.
-
 ## Before you commit
 
 ```sh
 pnpm check   # lint + format check + typecheck everything
 pnpm test    # framework tests
 ```
 
-Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `chore:`, `docs:`, etc.) - this is enforced by commitlint via a git hook, and it's what drives the framework's automated npm releases (see the README's [Releasing section](README.md#releasing-trickfire-docs-to-npm)). A pre-commit hook also runs lint-staged automatically, so most formatting/lint issues get fixed for you on commit.
+Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `chore:`, `docs:`, etc.) - this is enforced by commitlint via a git hook, and it drives the framework's automated npm releases. A pre-commit hook also runs lint-staged automatically, so most formatting/lint issues get fixed for you on commit.
 
 ## Opening a PR
 
 - Keep PRs focused on one concern - don't mix portal and framework changes unless they're genuinely related.
 - Make sure `pnpm check` and `pnpm test` pass.
 - Note in the PR description whether the change touches the portal, the framework, or both.
-
-That's it - nothing else is required. Ask in an issue or PR if anything here is unclear.

README.md

@@ -1,136 +1,13 @@
-> [!NOTE]
-> Looking for the TrickFire website? The main TrickFire Robotics website [trickfirerobotics.com](https://trickfirerobotics.com/) lives at [github.com/TrickfireRobotics/TrickFire-Website](https://github.com/TrickfireRobotics/TrickFire-Website).
+# TrickFire Docs Framework
 
-# TrickFire Docs
+A shared documentation system for TrickFire Robotics member repositories. Member repos add `trickfire-docs` as a dev dependency, run `trickfire-docs init` to get scaffolding, and write docs in their own `docs/` folder. A self-hosted server pulls from each repo and builds them into a single Docusaurus site at [docs.trickfirerobotics.com](https://docs.trickfirerobotics.com).
 
-`trickfire-docs` is TrickFire Robotics' documentation framework - an Astro/Starlight-based tool other TrickFire repos install to generate and publish their own docs at `docs.trickfirerobotics.com/<repo-name>`. This repo is where it's built and published from.
+## Docs
 
-This repo also servers `docs.trickfirerobotics.com` itself - more on that [below](#also-in-this-repo-the-docstrickfireroboticscom-portal).
+Full documentation: **[docs.trickfirerobotics.com/trickfire-docs](https://docs.trickfirerobotics.com/trickfire-docs/)**
 
-## Using `trickfire-docs` in a project
-
-### Set up
-
-Run this in your project root (the repo must already exist and have `git remote origin` set):
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/TrickfireRobotics/TrickfireRobotics.github.io/refs/heads/main/init.sh | bash
-```
-
-This script:
-
-- Creates `package.json` (if absent or name matches the repo) with the correct `name`, scripts, and `trickfire-docs` dependency
-- Creates `pnpm-workspace.yaml`
-- Creates `.github/workflows/pages.yml` for automated Pages deployment
-- Appends `node_modules/`, `dist/`, and `.pnpm-store/` to `.gitignore`
-- Runs `pnpm install`
-- Scaffolds `docs/` and `docs.config.ts` via `trickfire-docs init`
-
-Edit `docs.config.ts` to set your project's name, description, landing page cards, and sidebar.
-
-The site's URL and base path (`docs.trickfirerobotics.com/<repo-name>`) are derived automatically from `package.json`'s `"name"` field - there's nothing to configure for that.
-
-### Develop
-
-```bash
-pnpm docs:dev
-```
-
-Starts a local dev server with live reload. Edits under `docs/` hot-reload; changes to `docs.config.ts` require restarting the dev server.
-
-### Build
-
-```bash
-pnpm docs:build
-```
-
-Outputs the static site to `dist/`.
-
-## Publishing to docs.trickfirerobotics.com
-
-`docs.trickfirerobotics.com` is the TrickFire Robotics organization's GitHub Pages site. Any other repo in the org that enables GitHub Pages (without setting its own custom domain) is automatically served at `docs.trickfirerobotics.com/<repo-name>/` - which is exactly the base path `trickfire-docs` already builds for.
-
-The init script creates `.github/workflows/pages.yml` which handles builds and deploys automatically. The one manual step: in the repo's **Settings → Pages**, set **Source** to **GitHub Actions** and leave the custom domain field empty.
-
-Every push to `main` that touches `docs/` or `docs.config.ts` will then rebuild and redeploy the site.
-
-## Migrating from a legacy docs setup
-
-If the repo already has a self-contained `docs/` folder with its own `astro.config.mjs` and `package.json`, run this from the repo root to convert it to `trickfire-docs`:
-
-```bash
-cd path/to/repo
-curl -fsSL https://raw.githubusercontent.com/TrickfireRobotics/TrickfireRobotics.github.io/refs/heads/main/migrate-docs.py | python3
-```
-
-The script moves `docs/content/docs/**` into `docs/`, generates `docs.config.ts`, adds `trickfire-docs` to `package.json` (creating one if the repo has none), and runs `pnpm install`. Fill in the `description` TODOs in `docs.config.ts` when done.
-
-## Developing `trickfire-docs` itself
-
-Because this package generates and drives a real Astro project from inside its own install location (`node_modules/trickfire-docs/.astro-cache/`), changes don't show up correctly under `pnpm link` - a symlink doesn't reproduce how a real consumer's package manager lays out `node_modules`. Test changes against a real, packed install instead:
-
-```bash
-pnpm check            # lint/format/typecheck everything (framework + portal)
-pnpm test             # run the framework's tests
-pnpm framework:build  # compile the framework to dist-cli/
-npm pack              # produces trickfire-docs-<version>.tgz
-```
-
-Then in a throwaway project (not inside this repo):
-
-```bash
-mkdir /tmp/test-consumer && cd /tmp/test-consumer
-echo '{"name": "test-project", "private": true}' > package.json
-npm install /path/to/trickfire-docs/trickfire-docs-<version>.tgz
-# or: pnpm add /path/to/trickfire-docs/trickfire-docs-<version>.tgz
-
-npx trickfire-docs init
-npx trickfire-docs dev      # check hot reload works
-npx trickfire-docs build    # check dist/ output
-```
-
-Test with **both `npm` and `pnpm`** when changing anything that touches dependency resolution or the cache layout (`framework/astro/`). `npm`'s default hoisting is more forgiving and can hide bugs that only show up under `pnpm`'s strict, non-hoisted isolation - that's exactly how the `outDir`/dev-watch issues during initial development were found.
-
-Delete the throwaway project and the `.tgz` when done; `.astro-cache/` inside this repo (if you ever run the CLI directly from source) is gitignored and safe to delete at any time.
-
-## Releasing `trickfire-docs` to npm
-
-Releases are fully automated via [semantic-release](https://semantic-release.gitbook.io/) (`.github/workflows/release.yml`, config in `release.config.cjs`) - there's no manual version bump or `npm publish` step. The release workflow only runs on pushes to `main` that touch the framework's own paths (`framework/`, `internal/`, `scaffold/`, `tsup.config.ts`, `vitest.config.ts`, `tsconfig.cli.json`, `release.config.cjs`) - a portal-only change won't trigger it. Once triggered, semantic-release:
-
-1. Reads commit messages since the last release (relies on the [Conventional Commits](https://www.conventionalcommits.org/) enforced by commitlint) to decide whether a release is needed and what the next version is - `fix:` → patch, `feat:` → minor, a `BREAKING CHANGE:` footer → major. `chore:`/`docs:`/`style:`/etc. don't trigger a release on their own.
-2. Publishes the new version to the public npm registry.
-3. Tags the commit, creates a GitHub Release with generated notes, and commits the bumped `package.json`/`CHANGELOG.md` back to `main`.
-
-If a push to `main` only contains non-releasing commit types, the workflow runs but semantic-release no-ops - nothing gets published.
-
-**One-time setup required:** add an npm [automation token](https://docs.npmjs.com/creating-and-viewing-access-tokens) as the `NPM_TOKEN` repository secret (Settings → Secrets and variables → Actions). The workflow's `GITHUB_TOKEN` is automatic and just needs `contents: write` (already set) to push the version-bump commit and create releases.
-
-To preview what the next release would look like without actually publishing:
-
-```bash
-pnpm release:dry-run
-```
-
-This README is also what gets published to npm alongside `trickfire-docs` and shown on its registry page, portal section included.
-
-## Also in this repo: the docs.trickfirerobotics.com portal
-
-GitHub serves an organization's `<org>.github.io` repository at the root of its GitHub Pages domain. By naming this repo `TrickfireRobotics.github.io` and pointing the custom domain at it, we own `docs.trickfirerobotics.com/` - which is also the base path every other repo's own docs (built with `trickfire-docs`, above) get served under. Rather than leave that root domain pointing at nothing, this repo also builds and deploys a small Astro site as the `docs.trickfirerobotics.com` landing page itself.
-
-That site lives in `website/`, `public/`, and `astro.config.ts`, and is deployed by `.github/workflows/pages.yml` - unrelated to the `trickfire-docs` framework beyond sharing this repo and its toolchain.
-
-```sh
-pnpm install
-pnpm website:dev      # start the portal's dev server at http://localhost:4321
-pnpm website:build    # production build of the portal → dist/
-pnpm website:preview  # preview the portal's production build locally
-```
-
-## Repo layout
-
-One repo, one `package.json`, two things it produces:
-
-- **`trickfire-docs`** (the main point of this repo) - `framework/`, `internal/`, `scaffold/`, `tsup.config.ts`, `vitest.config.ts`, `tsconfig.cli.json`, `release.config.cjs` - published to npm independently via `.github/workflows/release.yml` (only runs on changes to the paths listed above).
-- **The portal site** (a side project living in this repo) - `website/`, `public/`, `astro.config.ts` - deployed by `.github/workflows/pages.yml`.
-
-Both share the same `pnpm-lock.yaml`, ESLint/Prettier/commitlint config, and git hooks - there's nothing to separately install or configure. `tsconfig.cli.json` (framework, Node) and `tsconfig.json` (portal, Astro) stay separate since they target genuinely different runtimes; same for `tsup.config.ts`/`vitest.config.ts` vs `astro.config.ts`.
+- [**Member guide**](docs/member-guide.md) — install, init, write content, and preview locally with `trickfire-docs dev`
+- [**Architecture**](docs/architecture.md) — how the framework, CI, and hosted site fit together
+- [**Configuration reference**](docs/configuration.md) — all `docs.config.ts` fields
+- [**Writing content**](docs/writing-content.md) — frontmatter, links, code blocks, admonitions, tabs
+- [**Deployment**](docs/deployment/index.md) — server setup, Cloudflare tunnel, GitHub Actions runner (admin)

docs-sidebars.js

@@ -0,0 +1,17 @@
+/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+export default {
+    docs: [
+        "index",
+        "architecture",
+        "member-guide",
+        "writing-content",
+        "sidebar-config",
+        "configuration",
+        {
+            type: "category",
+            label: "Deployment",
+            collapsed: false,
+            items: ["deployment/index", "deployment/server-setup", "deployment/cloudflare-tunnel"],
+        },
+    ],
+};