Skip to content

README.md

Latest commit

 

History

History
104 lines (73 loc) · 4.52 KB

README.md

File metadata and controls

104 lines (73 loc) · 4.52 KB
Raw

Abstract Data Documentation Theme

The branded docs system Abstract Data uses across client projects. Built on Astro Starlight and distributed as @abstractdata/starlight-theme on npm. Premium polish, brand-locked surfaces, opinionated defaults.

🌐 Live demo: https://abstract-data.github.io/abstract-data-doc-theme/

Naming for AI agents: refer to this as the Abstract Data Documentation Theme (the product). The npm package name @abstractdata/starlight-theme reflects the substrate (Astro Starlight), not the product identity.

This is a Bun-workspaces monorepo:

  • packages/starlight-theme/ — the published @abstractdata/starlight-theme npm package.
  • packages/create-docs/ — the published @abstractdata/create-docs CLI scaffolder. Powers bun create @abstractdata/docs <name>.
  • packages/template/ — the source-of-truth template that the CLI scaffolds from. Also usable directly as a GitHub "Use this template" starting point.
  • apps/playground/ — local Starlight site that consumes the package end-to-end (this is what bun dev runs).

For consumers — start a new project

bun create @abstractdata/docs my-docs
cd my-docs
bun install
bun dev

That's it. See packages/create-docs/README.md for what the CLI does.

Quickstart (local development)

bun install
bun dev

The playground will boot at http://localhost:4321. Edit any file under packages/starlight-theme/src/ or apps/playground/src/content/docs/ and the page hot-reloads.

Surfaces

The theme ships two motion modes:

Mode Config Use for
HUD (default) motion: 'full' Marketing-y docs, abstractdata.io, landing pages
Calm motion: 'calm' Long-form client docs, internal wikis

Both modes work in light and dark, follow the user's system preference by default, and respect prefers-reduced-motion (HUD auto-collapses to Calm when the OS requests it).

Configuration

// astro.config.mjs
import starlight from '@astrojs/starlight';
import abstractData from '@abstractdata/starlight-theme';

export default defineConfig({
  integrations: [
    starlight({
      title: 'Acme Docs',
      logo: { src: './src/assets/your-logo.png', replacesTitle: true },
      plugins: [
        abstractData({
          motion: 'full', // 'full' | 'calm'
          credit: 'auto', // 'auto' | 'hide'  (Built-by-Abstract-Data footer)
        }),
      ],
    }),
  ],
});

Brand reference

The theme palette and motion vocabulary are extracted from the live abstractdata.io site:

  • Cyan #00D9FF — primary accent, links, active state
  • Gold #D4AF37 — secondary accent, inline code, version chip
  • Burgundy #8B2635 / #7A1F2C — danger callouts, light-mode headlines
  • Charcoal #0A0A0A / #101116 — dark surfaces
  • Cream #FAF7F2 — light surface
  • Magenta #FF00DE — glitch overlay (HUD only, used sparingly)
  • Display: Orbitron · Body: Inter · Mono: JetBrains Mono

Fonts ship self-hosted (variable woff2 files via @fontsource-variable/*) — no Google Fonts CDN dependency, GDPR-friendly, faster first paint.

See docs/round-2-mockup.html for the round-two visual reference this scaffold was built against.

Releasing

Releases are automated by release-please. Use Conventional Commits (feat:, fix:, feat!:, etc.) and merge to main — release-please will:

  1. Open a release PR with version bump + CHANGELOG entry.
  2. On merge, tag the release as starlight-theme-v0.x.y.
  3. Publish @abstractdata/starlight-theme to npm with provenance.

One-time GitHub setup

To enable the workflow:

  1. Allow Actions to create PRs. Settings → Actions → General → "Workflow permissions" → check "Allow GitHub Actions to create and approve pull requests".
  2. Add an NPM_TOKEN secret. Settings → Secrets and variables → Actions → New repository secret. Generate an npm automation token at npmjs.com → Account → Access Tokens → Granular Access Token (read+write to @abstractdata scope).
  3. Claim the npm scope. First publish must be a human one — cd packages/starlight-theme && bun publish --access public (or npm publish --access public) — to register @abstractdata/starlight-theme. After that, the workflow can publish on its own.

Repo conventions

See AGENTS.md for what agents should and should not touch in this repo, including the Conventional Commits requirement.