76 lines
3.0 KiB
Markdown
76 lines
3.0 KiB
Markdown
# Atlas Templates
|
|
|
|
A template is a documentation pattern. It defines the structure that content must follow. Templates turn unstructured knowledge into consistent, browsable documentation.
|
|
|
|
---
|
|
|
|
## How Templates Work
|
|
|
|
A template defines fields, layout, and validation rules. Content that follows the template gets rendered through Atlas with consistent formatting and navigation.
|
|
|
|
Templates live in `soleprint/atlas/templates/` (core) or inside a book's `template/` subdirectory.
|
|
|
|
Data templates -- the schema files that define structure -- live in `cfg/<room>/data/template/`.
|
|
|
|
## The Feature Form Example
|
|
|
|
The feature form template captures user flows in a structured format:
|
|
|
|
| Field | Purpose |
|
|
|-------|---------|
|
|
| User Type | Who performs this flow |
|
|
| Entry Point | Where the flow starts |
|
|
| User Goal | One-sentence objective |
|
|
| Steps | Numbered sequence of actions |
|
|
| Expected Result | What success looks like |
|
|
| Common Problems | Known failure modes |
|
|
| Special Cases | Edge cases and exceptions |
|
|
| Related Flows | Connected user flows |
|
|
| Technical Notes | Developer-facing details |
|
|
|
|
This template is served at `/book/feature-form-samples/template/` as a styled HTML form with placeholder fields. Non-technical team members can understand the structure without reading code.
|
|
|
|
## Depots and Larders
|
|
|
|
A **depot** is data storage connected to a template. In Atlas, the depot pattern is called a **larder** -- a directory that holds content conforming to a template.
|
|
|
|
The connection works like this:
|
|
|
|
```
|
|
Template (structure) + Larder (data) = Templated Book
|
|
```
|
|
|
|
A larder directory contains a `.larder` marker file and organizes content in subdirectories. For feature forms, the larder groups entries by user type:
|
|
|
|
```
|
|
feature-form/
|
|
├── .larder
|
|
├── pet-owner/
|
|
│ ├── register-pet.html
|
|
│ └── book-appointment.html
|
|
├── veterinarian/
|
|
│ └── review-history.html
|
|
└── backoffice/
|
|
└── manage-users.html
|
|
```
|
|
|
|
Each file in the larder follows the template's field structure. Atlas renders them through a detail view that reads the content and applies consistent styling.
|
|
|
|
## The Larder Pattern
|
|
|
|
Larders enforce a constraint: all content in a larder must match the connected template. This keeps documentation consistent even when multiple people contribute.
|
|
|
|
The landing page of a templated book links to both:
|
|
- The **template** -- so you can see the pattern
|
|
- The **larder** -- so you can browse the actual content
|
|
|
|
This separation means the template can evolve independently from the data. Update the template, and all larder entries get the new rendering.
|
|
|
|
## Adding a Template
|
|
|
|
1. Define the template structure (HTML or markdown) in `soleprint/atlas/templates/` or inside a book's `template/` directory
|
|
2. Create a larder directory with a `.larder` marker
|
|
3. Add content files that follow the template structure
|
|
4. Register the book in `books.json` with `template` metadata
|
|
5. Add routes in `main.py` for the landing page, template view, and larder browser
|