docs: website docs structure + first content pages

Phase D foundation. Configures the pragmatic four-section sidebar
(Getting started / Guides / Reference / Concepts) and replaces the
template example pages with grounded content built on the shared
"library" example database (authors/books/members/loans):

- Getting started: installation, first project, simple vs advanced,
  the example library.
- Reference: Types (all ten + serial/shortid + advanced aliases),
  Tables (create/drop, compound PK, advanced CREATE TABLE).
- Concepts: projects & storage (readable files, derived database,
  autosave, temp projects).
- Guides: Build the library (draft, to be refined for teaching).

Command syntax grounded in en-US.yaml usage/help, command.rs, and
types.rs (verified against tests). Records the settled doc decisions
in STYLE.md. Build green (10 pages, Pagefind); content clean of
"DSL"/engine-name.
This commit is contained in:
claude@clouddev1
2026-06-06 07:34:57 +00:00
parent cea99e8b70
commit 0fcb7b1105
13 changed files with 653 additions and 97 deletions
+36 -26
View File
@@ -1,40 +1,50 @@
---
title: Welcome to Starlight
description: Get started building your docs site with Starlight.
template: splash # Remove or comment out this line to display the site sidebar on this page.
title: RDBMS Playground
description: A terminal playground for learning relational databases — tables, keys, relationships, indexes, queries, and query plans, hands-on.
template: splash
hero:
tagline: Congrats on setting up a new Starlight project!
image:
file: ../../assets/houston.webp
tagline: Learn relational databases by doing — in your terminal.
actions:
- text: Example Guide
link: /guides/example/
- text: Get started
link: /getting-started/installation/
icon: right-arrow
- text: Read the Starlight docs
link: https://starlight.astro.build
icon: external
- text: Browse the reference
link: /reference/types/
variant: minimal
---
import { Card, CardGrid } from '@astrojs/starlight/components';
import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';
## Next steps
RDBMS Playground is a cross-platform terminal app that gives you a safe
sandbox for exploring relational database concepts: tables, columns,
primary and foreign keys, relationships, indexes, queries, and query
plans. It is built for learning — from your first table to writing raw
SQL.
<CardGrid stagger>
<Card title="Update content" icon="pencil">
Edit `src/content/docs/index.mdx` to see this page change.
<CardGrid>
<Card title="Two ways to work" icon="seti:db">
Start in **simple mode** — a friendly, keyword-based command language —
and switch to **advanced mode** for standard SQL whenever you are ready.
</Card>
<Card title="Change page layout" icon="document">
Delete `template: splash` in `src/content/docs/index.mdx` to display a
sidebar on this page.
<Card title="Learn the SQL underneath" icon="open-book">
Run a simple-mode command in advanced mode and the playground shows you
the equivalent SQL, so the bridge from concepts to SQL is always visible.
</Card>
<Card title="Add new content" icon="add-document">
Add Markdown or MDX files to `src/content/docs` to create new pages.
<Card title="Safe to experiment" icon="approve-check">
Every change can be undone, your work is saved as you go, and you can
rebuild the whole database from plain, readable files.
</Card>
<Card title="Configure your site" icon="setting">
Edit your `sidebar` and other config in `astro.config.mjs`.
</Card>
<Card title="Read the docs" icon="open-book">
Learn more in [the Starlight Docs](https://starlight.astro.build/).
<Card title="See how queries run" icon="rocket">
Ask the playground to explain any query and it renders the database's
plan as an annotated tree — so indexes and scans stop being a mystery.
</Card>
</CardGrid>
## Start here
<CardGrid>
<LinkCard title="Install" href="/getting-started/installation/" description="Get the playground running on your machine." />
<LinkCard title="Your first project" href="/getting-started/first-project/" description="Create a table, add a row, and see it." />
<LinkCard title="The example library" href="/getting-started/example-library/" description="The small database used throughout these docs." />
<LinkCard title="Reference" href="/reference/types/" description="Every command, type, and constraint in detail." />
</CardGrid>