Atlas Books

A book is a documentation library served through Atlas. It lives in a directory under books/ and is served at /book/{slug}/.

Two Types

Standalone book -- static HTML files. No template, no depot. Atlas serves them directly. The book and its content are the same thing.

Templated book -- a template defines the structure, a depot (called a larder) provides the data. Atlas renders a landing page with links to the template definition and the data browser.

Directory Structure

Standalone Book

books/
└── feature-flow/
    ├── index-en.html       # English version
    ├── index-es.html       # Spanish version
    └── CLAUDE.md           # Dev notes

Routes:

/book/feature-flow/ -- language picker
/book/feature-flow/en -- English
/book/feature-flow/es -- Spanish

A standalone book is just HTML. Put it in the directory, register it in books.json, add a route in main.py.

Templated Book

books/
└── feature-form-samples/
    ├── template/                   # Template definition
    │   └── plantilla-flujo.md
    ├── feature-form/               # Larder (data)
    │   ├── .larder                 # Marker file
    │   ├── pet-owner/
    │   ├── veterinarian/
    │   └── backoffice/
    ├── index.html                  # Larder browser
    └── detail.html                 # Detail renderer

Routes:

/book/feature-form-samples/ -- landing page (links to template + larder)
/book/feature-form-samples/template/ -- template definition
/book/feature-form-samples/larder/ -- data browser
/book/feature-form-samples/larder/{user_type}/{file} -- specific entry

The .larder marker identifies which subdirectory holds the data.

The Feature Flow Example

Feature Flow is the standalone reference. It documents the BDD standardization pipeline -- how features go from idea to Gherkin to test. Two languages, no template, pure HTML.

Registration

Books are registered in books.json:

{
  "items": [
    {
      "name": "feature-flow",
      "slug": "feature-flow",
      "title": "Feature Flow Pipeline",
      "status": "ready",
      "system": "atlas"
    }
  ]
}

Adding a Room-Specific Book

Create the book directory in cfg/<room>/atlas/books/{slug}/
Add the HTML files
Register it in the room's books.json (in cfg/<room>/data/)
Add routes in main.py if it needs custom handling
Build: python build.py --cfg <room>

The build merges room books into the output alongside core books. Room books can also override core books by using the same slug.

2.6 KiB Raw Blame History