feat(website): migrate to a full Starlight documentation site

Merged
TH
3mo ago
+988-730

User description

Summary

Replaces the minimal 3-page landing site with a full Astro Starlight documentation site that renders the existing engdocs/ and specs/ trees, adds search, navigation, diagrams, and a polished theme.

What changed

  • Switched website/ to @astrojs/starlight and removed the standalone src/pages/* Astro pages.
  • Added website/scripts/sync-docs.ts which copies engdocs/user/, engdocs/architecture/, engdocs/adr/, engdocs/contributing/, and specs/ into src/content/docs/, renames index files (README.md, spec.md → index.md), injects Starlight frontmatter, and rewrites internal .md links to directory-style URLs.
  • New src/content/docs/index.mdx landing page uses Starlights splash template with hero actions and feature cards.
  • astro.config.mjs now configures Starlight (title, social, editLink, lastUpdated, custom CSS), keeps SITE_URL/BASE_PATH env support for GitHub Pages (https://sverka-dev.github.io/sverka/), and injects a small Mermaid script so ```mermaid blocks render as diagrams.
  • Added brand accent colors in src/styles/custom.css.
  • Updated website/.gitignore so generated docs and public/mermaid.min.js are not committed.
  • Updated public/robots.txt sitemap URL to /sverka/sitemap-index.xml.

Validation

  • bun run lint passed
  • bun run typecheck passed
  • bun run test passed
  • bun run build passed
  • bun --cwd=website run check passed
  • bun --cwd=website run build passed with SITE_URL=https://sverka-dev.github.io BASE_PATH=/sverka

Merging this PR will deploy the expanded docs site to GitHub Pages via the existing deploy-website.yml workflow.

CodeAnt-AI Description

Replace the minimal website with a searchable, navigable Sverka documentation portal

What Changed

  • The landing page now guides users to installation, workflow API, CLI reference, engineering documentation, specs, and GitHub.
  • Documentation from engdocs/ and specs/ is published as browsable pages with navigation, search, edit links, and last-updated information.
  • Internal documentation links are converted to working website routes, while titles and descriptions are generated for imported pages.
  • Mermaid architecture diagrams render directly in documentation pages.
  • The site uses a Starlight theme with Sverka accent colors and supports GitHub Pages paths and sitemap generation.

Impact

✅ One searchable home for user, engineering, and specification docs
✅ Working links between published documentation pages
✅ Rendered architecture diagrams

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.

Summary by cubic

Migrates the website to a full Astro Starlight docs site that builds from engdocs/ and specs/, adding search, sidebar navigation, Mermaid diagrams, and a branded theme. Adds a sync-docs build step, per-page editUrl, and correct SITE_URL/BASE_PATH handling for clean GitHub Pages deploys.

  • New Features

    • Switched website/ to @astrojs/starlight; removed custom Astro pages/layouts.
    • Added website/scripts/sync-docs.ts to copy docs (incl. engdocs/runbooks), rename indexes, inject frontmatter with per-page editUrl, and rewrite links; dev|build|check run it automatically.
    • Enabled Mermaid diagrams with mermaid and a lightweight loader.
    • Configured Starlight (title, social, edit link, last updated, custom CSS) and base path for GitHub Pages; sitemap/robots handled by @astrojs/sitemap.
    • Updated deploy workflow to rebuild on engdocs/** and specs/** changes.

  • Bug Fixes

    • Refactored sync-docs.ts for reliability and path handling. Added tests, warn on unresolved links, fixed Mermaid selector, asset URLs under BASE_PATH, and excluded tests from astro check.
    • Updated splash page to use relative links so BASE_PATH is respected.