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
@@ -0,0 +1,69 @@
---
title: Build the library
description: Build the example library database step by step — tables, a relationship, and some rows.
sidebar:
order: 1
---
:::note[Draft]
This guide is an early draft. The walkthrough is correct, but the wording
and pacing will be refined for teaching before the docs are published.
:::
This guide builds the [example library](/getting-started/example-library/)
from scratch in simple mode: two tables, a relationship between them, and a
few rows. By the end you will have used the create → add column → relate →
insert → query loop end to end.
## 1. Create the authors table
```text
create table authors with pk author_id(serial)
add column to authors: name (text)
add column to authors: birth_year (int)
```
## 2. Create the books table
```text
create table books with pk book_id(serial)
add column to books: title (text)
add column to books: author_id (int)
add column to books: published (int)
```
## 3. Relate books to authors
An author has many books, so `books.author_id` should point at
`authors.author_id`. Declare that one-to-many relationship:
```text
add 1:n relationship from authors.author_id to books.author_id
```
The relationship reads parent-to-child: **from** the `authors` side **to**
the `books` side.
## 4. Add some rows
`author_id` and `book_id` are `serial`, so they fill themselves in:
```text
insert into authors (name, birth_year) values ('Ada Lovelace', 1815)
insert into authors (name, birth_year) values ('Alan Turing', 1912)
insert into books (title, author_id, published) values ('Notes on the Analytical Engine', 1, 1843)
```
## 5. Look at your data
```text
show data authors
show data books
```
## Where to go next
- Add the `members` and `loans` tables the same way to model borrowing — a
many-to-many relationship through `loans`.
- Try the same steps in advanced mode to see the SQL form of each command.
- Look up any command in detail in the Reference section.