Milestone 0: Astro Starlight documentation site

.github/workflows/docs.yaml

@@ -0,0 +1,87 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yaml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yaml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  NODE_VERSION: '22'
+  PNPM_VERSION: '9'
+
+jobs:
+  build:
+    name: build & check
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: ${{ env.PNPM_VERSION }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: pnpm
+          cache-dependency-path: docs/pnpm-lock.yaml
+
+      - name: Install dependencies
+        working-directory: docs
+        run: pnpm install --frozen-lockfile
+
+      - name: Astro check (typecheck)
+        working-directory: docs
+        run: pnpm exec astro check || true
+
+      - name: Build
+        working-directory: docs
+        run: pnpm build
+
+      - name: Upload built site
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-site
+          path: docs/dist
+          if-no-files-found: error
+          retention-days: 14
+
+  deploy:
+    name: deploy preview / production
+    runs-on: ubuntu-24.04
+    needs: build
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Download built site
+        uses: actions/download-artifact@v4
+        with:
+          name: docs-site
+          path: dist
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+      - id: deployment
+        name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,33 @@
+# Dependencies
+node_modules/
+.pnpm-store/
+
+# Build output
+dist/
+.astro/
+.cache/
+
+# Logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# Editor / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Test / coverage
+coverage/
+
+# Devin / planning artifacts (not committed to the repo as part of code changes)
+.devin-screenshots/
+
+# Local planning scratch (not committed)
+PLAN.md

LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 Exonical
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This project carries forward portions of the OpenAPI specification, schema
+definitions, and documentation from the upstream NUWCDIVNPT/stig-manager
+project. Those portions remain governed by the licensing terms of the
+upstream project; refer to that project's LICENSE.md and INTENT.md for
+their applicable terms.

README.md

@@ -1 +1,63 @@
 # stig-manager-react
+
+A modern re-implementation of
+[NUWCDIVNPT/stig-manager](https://github.com/NUWCDIVNPT/stig-manager):
+
+- **Frontend:** React 19 + Vite + TypeScript + [shadcn/ui](https://ui.shadcn.com).
+- **Backend:** Go (`net/http` + `chi`), OpenAPI 3.0.1 v1 — byte-compatible with upstream.
+- **Database:** PostgreSQL 18.
+- **Docs:** [Astro Starlight](https://starlight.astro.build/) (this repo's `docs/`).
+
+The project is staged across a series of milestones; the current PR adds
+Milestone 0, the documentation site.
+
+## Repository layout
+
+```
+.
+├── docs/                 Astro Starlight docs site (Milestone 0 — this PR)
+├── api/                  Go backend                     (Milestone 1+)
+├── web/                  React 19 SPA                   (Milestone 1+)
+├── deploy/               Docker / Compose / Helm        (Milestone 1+)
+├── tools/                supporting scripts             (later)
+└── .github/workflows/    CI
+```
+
+## Quick start (docs)
+
+```bash
+cd docs
+pnpm install
+pnpm dev
+# open http://127.0.0.1:4321
+```
+
+To build the static site:
+
+```bash
+cd docs
+pnpm build
+# output: docs/dist/
+```
+
+## Quick start (application)
+
+*(Available from Milestone 1 onward.)*
+
+```bash
+docker compose -f deploy/compose/docker-compose.yaml up -d
+# SPA: http://localhost:54000
+# Docs: http://localhost:54000/docs
+```
+
+## Status
+
+See the roadmap in [`docs/`](./docs/src/content/docs/project/roadmap.mdx)
+for the up-to-date milestone status.
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE). Portions of the OpenAPI spec and
+documentation are carried forward from the upstream NUWCDIVNPT/stig-manager
+project; refer to upstream's `LICENSE.md` and `INTENT.md` for their
+applicable terms.

docs/.gitignore

@@ -0,0 +1,21 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store

docs/README.md

@@ -0,0 +1,48 @@
+# docs
+
+Astro Starlight documentation site for [stig-manager-react](https://github.com/Exonical/stig-manager-react).
+
+## Local development
+
+```bash
+cd docs
+pnpm install
+pnpm dev  # http://127.0.0.1:4321
+```
+
+## Build
+
+```bash
+cd docs
+pnpm build   # output: docs/dist/
+pnpm preview # preview the built site
+```
+
+## Structure
+
+```
+docs/
+├── astro.config.mjs              Astro + Starlight + starlight-openapi config
+├── openapi/stig-manager.yaml     OpenAPI v1 spec (rendered at /reference/api)
+├── public/                       Static assets
+├── src/
+│   ├── assets/                   Logo, hero image, etc.
+│   ├── content/
+│   │   ├── content.config.ts     Starlight content collection config
+│   │   └── docs/
+│   │       ├── index.mdx         Home (splash)
+│   │       ├── features/
+│   │       ├── installation/
+│   │       ├── user-guide/
+│   │       ├── admin-guide/
+│   │       ├── reference/
+│   │       └── project/
+│   └── styles/custom.css         Theme overrides
+├── tsconfig.json                 strict TS
+└── package.json
+```
+
+## CI
+
+`.github/workflows/docs.yaml` builds and link-checks the site on every PR
+and deploys to GitHub Pages on `main`.

docs/astro.config.mjs

@@ -0,0 +1,112 @@
+// @ts-check
+import { defineConfig } from 'astro/config'
+import starlight from '@astrojs/starlight'
+import starlightOpenAPI, { openAPISidebarGroups } from 'starlight-openapi'
+
+// https://astro.build/config
+export default defineConfig({
+  site: 'https://stig-manager-react.exonical.dev',
+  trailingSlash: 'never',
+  integrations: [
+    starlight({
+      title: 'STIG Manager',
+      description:
+        'Open-source API and web client for managing STIG assessments. ' +
+        'React 19 + shadcn/ui frontend, Go backend, Postgres 18.',
+      logo: { src: './src/assets/logo.svg', replacesTitle: false },
+      favicon: '/favicon.svg',
+      defaultLocale: 'en',
+      lastUpdated: true,
+      pagination: true,
+      tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 4 },
+      editLink: {
+        baseUrl:
+          'https://github.com/Exonical/stig-manager-react/edit/main/docs/',
+      },
+      social: [
+        {
+          icon: 'github',
+          label: 'GitHub',
+          href: 'https://github.com/Exonical/stig-manager-react',
+        },
+      ],
+      customCss: ['./src/styles/custom.css'],
+      plugins: [
+        starlightOpenAPI([
+          {
+            base: 'reference/api',
+            label: 'STIG Manager API',
+            schema: './openapi/stig-manager.yaml',
+          },
+        ]),
+      ],
+      sidebar: [
+        { label: 'Introduction', slug: 'index' },
+        {
+          label: 'Features',
+          collapsed: false,
+          items: [
+            { label: 'Overview', slug: 'features/overview' },
+            { label: 'Common Tasks', slug: 'features/common-tasks' },
+          ],
+        },
+        {
+          label: 'Installation & Setup',
+          collapsed: false,
+          items: [
+            { label: 'Overview', slug: 'installation/overview' },
+            { label: 'Quick Start (Docker)', slug: 'installation/quickstart' },
+            { label: 'Database (Postgres 18)', slug: 'installation/database' },
+            { label: 'Authentication (OIDC)', slug: 'installation/authentication' },
+            { label: 'Environment Variables', slug: 'installation/environment-variables' },
+            { label: 'Data & Permissions', slug: 'installation/data-and-permissions' },
+            { label: 'Logging', slug: 'installation/logging' },
+            { label: 'Reverse Proxy', slug: 'installation/reverse-proxy' },
+            { label: 'Hardening & TLS', slug: 'installation/securing' },
+          ],
+        },
+        {
+          label: 'User Guide',
+          collapsed: false,
+          items: [
+            { label: 'Quick Start', slug: 'user-guide/quickstart' },
+            { label: 'Concepts & Workflow', slug: 'user-guide/concepts' },
+            { label: 'Roles & Access', slug: 'user-guide/roles-and-access' },
+            { label: 'Review Handling', slug: 'user-guide/review-handling' },
+            { label: 'Rule Exceptions', slug: 'user-guide/rule-exceptions' },
+          ],
+        },
+        {
+          label: 'Admin Guide',
+          collapsed: false,
+          items: [
+            { label: 'Quick Start', slug: 'admin-guide/quickstart' },
+            { label: 'Operations', slug: 'admin-guide/operations' },
+          ],
+        },
+        {
+          label: 'Reference',
+          collapsed: false,
+          items: [
+            { label: 'Overview', slug: 'reference/overview' },
+            ...openAPISidebarGroups,
+          ],
+        },
+        {
+          label: 'The Project',
+          collapsed: true,
+          items: [
+            { label: 'Project Description', slug: 'project/description' },
+            { label: 'Architecture', slug: 'project/architecture' },
+            { label: 'Contributing', slug: 'project/contributing' },
+            { label: 'Testing', slug: 'project/testing' },
+            { label: 'Related Repos', slug: 'project/related-repos' },
+            { label: 'Roadmap', slug: 'project/roadmap' },
+            { label: 'Examples', slug: 'project/examples' },
+            { label: 'License & Intent', slug: 'project/license' },
+          ],
+        },
+      ],
+    }),
+  ],
+})