uniweb 1.25.3 → 1.25.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,155 @@
1
+ # Backend: when the site is also an app
2
+
3
+ On-demand guide (`uniweb guide backend`); AGENTS.md is assumed read. Only for a site with its own `backend` service — accounts, per-visitor data, records its members create and edit. A site without one is the normal case; a foundation that assumes one breaks everywhere else.
4
+
5
+ ```bash
6
+ npm install @uniweb/api # in the FOUNDATION, beside @uniweb/kit — and in the site, if it has a $devBackend mock
7
+ ```
8
+
9
+ ## Ask before you draw
10
+
11
+ ```jsx
12
+ import { isBackendEnabled } from '@uniweb/kit'
13
+ import { useSession, SignedIn, SignedOut } from '@uniweb/api'
14
+ if (!isBackendEnabled()) return <StaticVersion /> // synchronous
15
+ ```
16
+
17
+ When the site has no backend, draw nothing — not a disabled control, not "sign-in unavailable". Render the version that never needed one.
18
+
19
+ ## Reading
20
+
21
+ ```jsx
22
+ const { status, records } = useRecords({ schema: '@/track' }) // summaries: record.brief, no items
23
+ const { entity } = useEntity({ schema: '@/track', uuid: record.uuid })
24
+ const sessions = entity?.hydrated?.items.filter((item) => item.section === 'sessions')
25
+ ```
26
+
27
+ - Name your foundation's own types `@/track`, as `meta.js` and `queries.yml` do; a built foundation sends them in its registered scope (`@acme/track`), `uniweb dev` as written. Any other type in full (`@std/person`). Outside a Uniweb build `@/track` is refused (`kind: 'invalid'`).
28
+ - **What a member wrote is text.** `{record.brief.name}` or `<PlainText>`, never `<P text>`, `<H1>`–`<H6>`, `SafeHtml` — a member who typed `<img onerror=…>` would run it as whoever views the page. A rich-text field renders through kit's `Render`.
29
+ - **A listed record is a summary, not the entity.** `record.brief.name`, not `record.name`; no items — read one entity for them. Each item carries `section` (the word a write takes) and `id` (what update/move/remove take). `scope: 'mine'` lists only the viewer's own; without it, also what was shared with them and what a role reaches.
30
+ - **`absent` ≠ empty `ready`.** `absent` = no live source (no backend, or nobody signed in) → render authored content. `ready` with `records: []` = the service answered, nothing there → your empty state. Confusing them tells a visitor their content is gone when it was never requested.
31
+
32
+ ## Writing
33
+
34
+ ```jsx
35
+ const writer = useEntityWriter({ schema: '@/track', uuid: track.uuid })
36
+ await writer.create({ title: 'Keynote' }, { section: 'sessions', position: 'last' })
37
+ await writer.update(itemId, { ...item.data, room: 'Hall A' }) // whole-data replace — spread what you aren't editing
38
+ await writer.move(itemId, { after: previousItemId }) // 'first', 'last' or { after } — never an index
39
+ await writer.remove(itemId)
40
+ ```
41
+
42
+ - `section` is required on `create`: an entity has several, and a rule declared on one (insert-only) doesn't reach an item that landed in another.
43
+ - Ordering is the server's; never compute an order number.
44
+ - `writer.conflict` is reported, not retried — a retry would overwrite a change nobody looked at. Tell the person.
45
+
46
+ ## Translated fields
47
+
48
+ A `localized` field holds `{ en: '…', fr: '…' }` or one plain value for every language; a read answers in the page's language. Never write that one value back as the whole field — it becomes every language's value.
49
+
50
+ ```jsx
51
+ const { entity } = useEntity({ schema: '@/profile', uuid, languages: 'all' }) // every language, as stored
52
+ await writer.update(item.id, { ...item.data, bio: 'Bonjour' }, { language: 'fr' }) // one language, merged
53
+ ```
54
+
55
+ `update` with `{ language }` merges the translated fields you name and keeps the ones you leave out. On a multilingual site, an update without it that writes a plain value over a translated field read in the page's language is refused. `languagesOf`, `inLanguage`, `withLanguage` read and set one language of a value, `@` metadata kept.
56
+
57
+ ## Permissions are the server's; your UI is a courtesy
58
+
59
+ Gate controls on what the viewer may do — a record's `can_edit` from a single-entity read — but never rely on that for safety: a foundation runs with the viewer's authority, so hiding a button hides a button. Not on `viewer.roles` alone: a session holds its roles as a reader's until elevated, so a gate on `system_admin` shows the operator nothing until then. Draw a role-acting control from `useElevation().rolesInFull` and let the record answer.
60
+
61
+ What protects content is the **entry**: a member writes their own entries and not another's, enforced by the store. **Models are open** — anyone signed in may create entries of any Model. A schema protects how an item changes and who reads an entry:
62
+
63
+ ```yaml
64
+ # schemas/attendance.yml
65
+ sections:
66
+ checkins: { many: true, append_only: true } # added, never edited or removed, by anyone — holds against the author
67
+
68
+ # schemas/submission.yml
69
+ grantable: false # never shared one at a time
70
+ fields:
71
+ course: { ref: '@/course', readable_with: edit } # the course's editors read it (read only), via: 'rbac'
72
+
73
+ # schemas/course.yml
74
+ fields:
75
+ lessons: { ref: '@/lesson', many: true, sold_with: true } # a buyer of the course reads its lessons (up to three steps)
76
+ ```
77
+
78
+ `readable_with` (`read` | `edit` | `admin`, only on a reference) is one step; a backend refuses adding it to a field entries already fill. `grantable: false` keeps entries from being shared with a person or team. `sold_with` only on a reference; an unmarked one carries nothing.
79
+
80
+ ## Acting as an administrator
81
+
82
+ An administrator's session reads what their role reaches and changes nothing through the role until they confirm it is them; their own records they edit as always.
83
+
84
+ ```jsx
85
+ const { available, elevated, until, elevate, lower, error } = useElevation()
86
+ // available: the account holds a role that does more than read — offer it only then
87
+ // elevate({ password, code }) — code when the account has a second factor; refusal: error.kind === 'auth'
88
+ // elevated turns false at `until`; lower() ends early; elevateWithProvider(provider) for a passwordless account
89
+ ```
90
+
91
+ While elevated, `viewer.roles` names the role and every record read before is read again. Nothing says whether the account has a second factor — offer the code field. It does not open the backend's administration — the Admin link does:
92
+
93
+ ```jsx
94
+ const { adminHref } = useSession()
95
+ {adminHref && <a href={adminHref}>Admin</a>} // navigate, never fetch: the answer is a redirect with a one-time credential
96
+ ```
97
+
98
+ `adminHref` is set only for an account the backend's administration admits; `null` otherwise.
99
+
100
+ ## Mailed links, invitations, access, units
101
+
102
+ **Mailed links** (sign-up confirmation `?verify=`, password reset `?reset=`, invitation `?offer=`) arrive at the site's root; the landing page finishes the step:
103
+
104
+ ```jsx
105
+ const { step, status, result, error, confirm } = useMailedLink()
106
+ // step: null | 'verify' | 'reset' | 'offer' status: 'idle' | 'working' | 'done' | 'error'
107
+ ```
108
+
109
+ `verify` finishes by itself. `reset` waits for `confirm({ new_password })` (`error.extensions.reason === 'password_too_short'`; the link works again). `offer` waits for a sign-in then claims; `result` is counts `{ invitations, grants }`; `error.kind === 'absent'` means unknown, revoked or used, alike — one sentence, no cause. Render it where the root renders (a header or layout). Never copy the token anywhere.
110
+
111
+ **Invitations** wait for the member's answer, mailed link or not:
112
+
113
+ ```jsx
114
+ const { status, invitations, accept, decline, answering } = useInvitations()
115
+ // invitations: [{ id, unit_uuid, unit_handle, unit_name, invited_by_account_id, created_at }]
116
+ ```
117
+
118
+ Draw it wherever a signed-in member lands. One that no longer waits is refused with `kind: 'rule'` and leaves the list.
119
+
120
+ **Access to an entry** — whoever administers it gives `read` | `edit` | `admin` and takes it back:
121
+
122
+ ```jsx
123
+ const { status, grants, grant, revoke, working } = useAccess({ schema: '@/course', uuid: course.uuid })
124
+ // status 'ready' for whoever administers it; 'forbidden' → draw nothing
125
+ await grant({ handle: 'sam' }, 'read') // or an account id; many ids → { results }
126
+ await revoke(grants[0])
127
+ ```
128
+
129
+ Giving access is a person's decision through your UI — not a grant per entry from code; for "the course's staff read every submission" declare `readable_with` on the schema. Giving again replaces (`read` after `edit` lowers). An entry given to the viewer lists with `via: 'grant'`; `leaveAccess({ schema, uuid })` gives it up.
130
+
131
+ **Where a create lands:** the root of the organization the backend is founded with, unless the create names a unit the viewer is placed in:
132
+
133
+ ```jsx
134
+ const { units } = useUnits() // [{ unit, id, handle?, name?, parent?, depth, primary }]
135
+ await createEntity({ schema: '@/submission', unit: course.unit, items: [...] })
136
+ ```
137
+
138
+ Nested items in one create: give an item `uuid: uuidv7()` and a later item names it as `parent` (`{ section: 'degrees/thesis', parent: degree, data }`); those uuids serve the write alone.
139
+
140
+ ## A backend on your machine
141
+
142
+ ```yaml
143
+ # site.yml
144
+ services:
145
+ backend: true # ask the host for it when you publish
146
+ $devBackend: ./mock/api.js # what answers in `uniweb dev`; `$` keys are never published
147
+ ```
148
+
149
+ ```js
150
+ // site/mock/api.js
151
+ import { createMockBackend } from '@uniweb/api/mock'
152
+ export default createMockBackend({ seed }).fetch
153
+ ```
154
+
155
+ `uniweb dev` answers the `backend` service with it at an address on its own origin (cookies behave as in production). Write no address of your own: under `services:` an address means a backend you run. The mock **enforces** entry ownership and `append_only`; it doesn't model `readable_with`, `sold_with`, second factors or password rules. Mail it would send prints in the terminal with its link on the site's root. Seed `offers: [{ email, invitations: 1 }]` to try an invitation; a seeded entity takes `grants: { member: 'read' }`; `units: [{ handle, parent?, members, floor? }]` gives a create somewhere to land. The seed names your own types `@/track`. State is in memory; restart to reset. `uniweb create my-event --template conference` is a worked example.
@@ -0,0 +1,312 @@
1
+ # Guide: content
2
+
3
+ Lane guide — AGENTS.md procedure step 6 loads it before any content is written. When in doubt about any rule here, `uniweb inspect <path>` settles it.
4
+
5
+ ## Sections
6
+
7
+ **A section with no `type:` renders through the foundation's default section type** — a component named `Section`, unless the foundation's `main.js` sets `defaultSection`. This is what lets a folder of plain markdown with no frontmatter become pages: mounted documentation, an imported wiki. If such content renders blank, the foundation has no `Section` — that, not the markdown, is what to fix.
8
+
9
+ **Content before the first heading changes the parse:** headings after body content become items, not the section title. That's how repeating groups are made. An icon counts: `![](lu-globe)` above `# Title` leaves `content.title` empty and puts the heading in `items[0]`. For an icon that belongs to the title, write it under the heading, where it is still `content.icons[0]`; `uniweb inspect` shows the shape, and warns about an icon above one heading. An image above the title empties it too, with the heading in `content.headings` and no warning.
10
+
11
+ ### The parsed object
12
+
13
+ ```js
14
+ content = {
15
+ title: '', // string, or string[] for multi-line
16
+ pretitle: '', // `#>` label line(s); also smaller headings stacked above the title (older content)
17
+ subtitle: '', // line(s) one step below the title — each further one-step descent is another line
18
+ paragraphs: [],
19
+ links: [], // { href, label, role, iconBefore, iconAfter } — links alone in a paragraph; not a sentence's, and a list item has its own
20
+ images: [], // { url, alt, caption, role, href, target } — `url`, where a video has `src`
21
+ icons: [], // { library, name }, or { url } for your own SVG
22
+ videos: [], // { src, alt, caption, role, poster, href, target }
23
+ media: [], // images, videos and insets on their own line, in the order written, each with its `kind`
24
+ documents: [], // { url, alt, caption, role: 'pdf', preview?, author?, description? } — from {role=pdf}
25
+ insets: [], // inline @Component references — { refId }
26
+ lists: [], // [[{ paragraphs, links, lists, … }]] — each item is an object, not a string
27
+ quotes: [],
28
+ snippets: [], // fenced code — [{ language, code }]
29
+ data: {}, // tagged blocks — yaml:/json: give the parsed value, md: gives { items, sequence }
30
+ tables: [], // only when present — [{ rows: [{ cells: [{ children, header, align }] }], attrs? }]
31
+ math: [], // only when present — display math, [{ id, latex, mathml }]; inline math stays in its paragraph
32
+ headings: [], // from nested content (quote/list bodies), or when an image sits above the title
33
+ items: [], // each has this same flat structure
34
+ sequence: [], // every element in document order
35
+ }
36
+ ```
37
+
38
+ ### Items have the full content shape
39
+
40
+ Each item has `title`, `pretitle`, `subtitle`, `paragraphs`, `links`, `icons`, `lists`, `snippets`, and `data`. Heading hierarchy inside an item follows the same rules (`####` inside a `###` item is that item's `subtitle`). A tagged block inside an item is that item's (`items[n].data`) and needs no `meta.js` declaration:
41
+
42
+ ````markdown
43
+ ### Starter ← items[0].title
44
+ $9/month ← items[0].paragraphs[0]
45
+
46
+ ```yaml:details
47
+ trial: 14 days
48
+ seats: 1
49
+ ``` ← items[0].data.details = { trial: "14 days", seats: 1 }
50
+ ````
51
+
52
+ ### Subtitle vs items
53
+
54
+ A heading right after the title is `subtitle` **only when exactly one step smaller** (H1→H2); each further one-step line continues the subtitle (`subtitle: [line2, line3]`). **Two steps smaller starts items** — the idiom for entries with no lead paragraph:
55
+
56
+ ```markdown
57
+ # Our Stats │ content.title
58
+ ### 15,000+ │ content.items[0].title
59
+ Students from 90 countries │ content.items[0].paragraphs[0]
60
+ ### 200+ │ content.items[1].title
61
+ ```
62
+
63
+ With `## 15,000+` the first stat would join the headline as `subtitle`. A `---`, or any body content after the headline, also closes it. A later heading as large as the first leaves no title at all: `# A`, a paragraph, `# B` gives `items: [A, B]`.
64
+
65
+ ### Multi-line headings
66
+
67
+ Consecutive headings at the same level merge into one title array; kit's `<H1>`…`<H6>` render arrays as one tag with line breaks.
68
+
69
+ ```markdown
70
+ # Build the future │ content.title = ["Build the future", "<span accent=\"true\">with confidence</span>"]
71
+ # [with confidence]{accent} │
72
+ ```
73
+
74
+ A repeated size always continues the part it repeats. Use `---` to force separate items where adjacent headings would otherwise continue the headline.
75
+
76
+ ### Sequence
77
+
78
+ `content.sequence` is the flat, ordered list of all elements before grouping. Each element has a `type` (`heading`, `paragraph`, `image`, `codeBlock`, `dataBlock`, `list`, `link`, `divider`, `inset`, …) plus type-specific fields. Grouped fields suit structured layouts (cards, features); `sequence` suits prose and cross-group searching:
79
+
80
+ ```js
81
+ for (const el of content.sequence) if (el.type === 'dataBlock') allData[el.tag] = el.data
82
+ ```
83
+
84
+ ### Choosing how to model content
85
+
86
+ The rule: **would a content author need to change this?** Yes → markdown, frontmatter, or a tagged block. No → component code. Start with the content, not the component: write the markdown an author would naturally write, check the shape with `inspect`, then build the component to receive it.
87
+
88
+ - **Pure markdown** — headings, paragraphs, links, images, lists, items. The default.
89
+ - **Frontmatter params** — `columns: 3`, `variant: centered`. Presentation, not meaning.
90
+ - **Tagged data blocks** — products with SKUs, team members with roles, schedules, form definitions. When information is structured data an author still owns, a well-named block (`yaml:pricing`, `yaml:speakers`) beats contorted markdown. Formats: `yaml`, `json`.
91
+
92
+ Read the markdown out loud. If an author understands every line, you've chosen right. When you build a foundation you *design* these names; when you write against an existing foundation the vocabulary is fixed — the types in `sections/**`, the params each `meta.js` lists.
93
+
94
+ **A section may hold more than its type renders.** `meta.js content:` says what a type reads, not what a file may contain; extra content is ignored, never an error. Write for the type — extra content isn't a goal — but the tolerance is what makes changing `type:` or a `variant` a one-line trial: compare, switch back, nothing to rewrite first. When you make the switch, don't strip what the new rendering ignores; whether it stays is the author's decision once the trial is settled.
95
+
96
+ ### Placeholders
97
+
98
+ A value that appears on many pages goes in `site.yml` once:
99
+
100
+ ```yaml
101
+ placeholders:
102
+ product: Uniweb
103
+ vendor: { email: billing@acme.example }
104
+ ```
105
+
106
+ Pages reference it as `{vendor.email}`; dot paths work, and a record's own field of the same name always wins (`{title}` on an article page is that article's). Resolution needs a foundation with a content handler (`createLoomHandlers` from `@uniweb/loom` in `main.js handlers:`); without one the literal `{…}` renders. Placeholders are the simplest case of Loom expressions, which also filter, sort, count and format data (`{COUNT OF publications WHERE refereed}`) — see the `data` guide.
107
+
108
+ ### Icons
109
+
110
+ ```markdown
111
+ ![](lucide:house) colon + friendly name — every library
112
+ ![](lu:house) colon + short code
113
+ ![](lu-house) dash — short codes only
114
+ ```
115
+
116
+ Short codes: `lu` Lucide, `hi`/`hi2` Heroicons v1/v2, `fi` Feather, `pi` Phosphor, `tb` Tabler, `bs` Bootstrap, `md` Material, `ai` Ant Design, `ri` Remix, `si` Simple Icons, `io5` Ionicons, `bi` Boxicons, `vsc` VS Code, `wi` Weather, `gi` Game, `fa`/`fa6` Font Awesome 5/6. Browse at react-icons.github.io: the name is the component name without prefix, kebab-cased (`LuBuilding2` → `lu-building2`, `LuGrid2X2` → `lu-grid2-x2`); Lucide, Heroicons and Feather also accept the family's own spelling (`lu-building-2`). Attributes: `{size=20}`, `{color=red}`. Custom SVG: `![Logo](./logo.svg){role=icon}` or `![Logo](icon:./logo.svg)`. An icon the build cannot fetch is named in its prerender warning.
117
+
118
+ ### Links and media attributes
119
+
120
+ ```markdown
121
+ [text](url){target=_blank} open in new tab
122
+ [text](./file.pdf){download}
123
+ [Go](/start){button} role "button" (also `button:/start`), plus a `variant`
124
+ ![alt](./img.jpg){role=banner} role picks the array: images, icons, videos, documents
125
+ ![alt](./demo.mp4){role=video} → content.videos
126
+ ![alt](./report.pdf){role=pdf} → content.documents — a file, drawn as a link
127
+ ![alt](./img.jpg){href=/products} clickable media: href + target ride along
128
+ ```
129
+
130
+ Image attributes: `{width=800 height=600 loading=lazy fit=cover position=center author="Jane Doe"}`. Video: `{poster=./thumb.jpg autoplay muted loop controls}` — name a poster; a static build makes one only when none is named and ffmpeg is installed, and `uniweb publish` sends only a named poster. A `{role=pdf}` document adds `{preview=./cover.jpg author=… description=…}` and arrives as `{ url, name, mime, size?, alt, caption, … }`.
131
+
132
+ **Section links:** `page:about#team` → `/about#section-team`; `page:/#features` → a homepage section. The id is the file name without its number (`2-features.md` → `features`) or `id:` in frontmatter.
133
+
134
+ **Where media lives.** `./x` is beside the page, `/x` is in `public/`; both reach a static build and a published site. Keep a page's media beside it, and in `public/` what belongs to the whole site: the favicon, fonts. **Only a static host gives a file a fixed address** at the site root. A site published with Uniweb serves a file that something names from an address the upload gives it, and nothing at `/x` — so for a file other sites or scripts fetch by URL, keep it somewhere with its own address and add a page whose `redirect:` goes there. A static build copies `public/` whole and adds its own copy of each file a page names there. `uniweb push` uploads a file beside a page wherever the page is (mounted folders included); a file outside the site and its mounts is not uploaded — put that in `public/`. There is no `assets/` folder for media; a build stops on a `/x` only `assets/` holds.
135
+
136
+ **Placement** (`{placement=left|right|wide|full}`) on an image or video, or on a table's caption line, which follows the table after a blank line (`: Plans and prices {placement=wide #tbl-plans}`, which also sets caption and id; with no blank line it becomes a row). It's the author's intent, honoured by kit's `<Render>`, `<Prose>` and `<Article>` and ignored by other components; a section type declares which it honours in `meta.js` (`sequence: { placement: true }`) and the build warns on a mismatch.
137
+
138
+ **Attribute syntax.** Quote values with spaces (`{note="Ready to go"}`). `:` works wherever `=` does; pairs separate by whitespace, comma, or both. The separator must touch the key (`{note : warning}` is two flags); a value with a comma must be quoted; a colon in a value needs no quoting (`{href:https://example.com}`).
139
+
140
+ Standalone links (alone in a paragraph, or several sharing a links-only paragraph) are promoted to `content.links`; how they're drawn is the component's choice. Leave a blank line above one: a link on the line after text joins that text's paragraph. A link inside a sentence stays an `<a>` in `paragraphs` and is not in `links`.
141
+
142
+ **Footnotes.** `[^1]` in text and a `[^1]: the note` paragraph in the same file. `<Prose>` renders them as numbered links with the notes listed at the end; a component that draws `content.paragraphs` itself sees them as the text they are.
143
+
144
+ ### Inline text styling
145
+
146
+ ```markdown
147
+ # Build [faster]{accent} with structure
148
+ This is [less important]{muted} context.
149
+ ```
150
+
151
+ `accent` and `callout` (accent color + bold) and `muted` are built in and adapt to context. `--accent` is the brand color unless `colors.accent` is declared, at the shade you authored. Components receive `<span accent="true">faster</span>`.
152
+
153
+ Sites adjust these or add named styles in `theme.yml` `inline:` — a name is a letter then letters, digits, `_`, `-`, never starting with `on`. Overrides merge property by property; to drop a default property give it `initial`/`inherit`/`unset`. On a site synced with the Uniweb app, built-in names round-trip editable in the visual editor; a name the editor doesn't know is preserved exactly but not editable.
154
+
155
+ ### HTML is not content
156
+
157
+ A tag in markdown — `<strong>`, `<span class=…>`, `<div>` — shows as written, and the build names the file. Use `**bold**`, `[text]{accent}`, a link. The exception is `<br>`, a hard break anywhere. A newline inside a paragraph is a space; a deliberate line break is `<br>` or a `\` at the end of the line.
158
+
159
+ ### Fenced code
160
+
161
+ Three uses by info string: `yaml:`/`json:` data (parsed into `content.data.tag`, for a key the component declares — otherwise it stays out of `data` and the dev console says so; still in `sequence`), `md:` a named kind of prose (`content.data.tag = { items, sequence }`; a body with no headings is one titleless item — a callout), and a bare language for a snippet (`content.snippets`, filter by `language`). `<Prose>` highlights snippets and skips tagged blocks.
162
+
163
+ Two tags, not a tag plus a variant: a warning and a note are `md:warning` and `md:note`. The fence takes no params.
164
+
165
+ ### Math
166
+
167
+ LaTeX compiles to MathML Core at build time — no runtime library. `$x^2$` inline; `$$x^2$$` display (block on its own line, inline display mid-paragraph); a ` ```math ` fence for multi-line; `\$` for a literal dollar. A `$…$` span is math only when no whitespace touches the delimiters *and* the closing `$` isn't followed by a digit — so `$5 and $10` stays prose and `Let $f(x) = 5$ be` is math. Math survives prerender, epub/pagedjs output and the editor. Display math lands in `content.math`, and inline math stays in its paragraph. A foundation that draws equations imports `@uniweb/kit/math-tokens.css` (theme guide).
168
+
169
+ ### Lists as navigation
170
+
171
+ Each list item is a full content object (`paragraphs`, `links`, `icons`, nested `lists`):
172
+
173
+ ```markdown
174
+ - ![](lu-home) [Home](/) ← content.lists[0]; each item.links[0], with the icon as its iconBefore
175
+ - Product ← nested: group.paragraphs[0] is the label, group.lists[0] the sub-items
176
+ - [Features](/features)
177
+ ```
178
+
179
+ To change a nav item, first check how nav is produced: if `layout/header.md` lists the links (a list, or a `yaml:nav` block), edit it there; if it doesn't, the Header is generating nav from the page hierarchy — change page titles and order in `site.yml` / `page.yml` instead.
180
+
181
+ For richer navigation use a `yaml:nav` block — `[{ label, href, icon, text, children, target }]`, icons in any icon spelling or an SVG path — read as `content.data.nav` (declared `data: { nav: {} }`); components can fall back to `website.getPageHierarchy()`. Full pattern: `reference/navigation-patterns.md`.
182
+
183
+ ### Section backgrounds
184
+
185
+ ```yaml
186
+ background: /images/hero.jpg # image
187
+ background: /videos/hero.mp4 # video
188
+ background: linear-gradient(135deg, #667eea, #764ba2) # gradient — quote if it contains #
189
+ background: '#1a1a2e' # color (quote)
190
+ background: primary-900 # palette token (bare name or var())
191
+ background:
192
+ image: { src: /img.jpg, position: center top }
193
+ overlay: { enabled: true, type: dark, opacity: 0.5 }
194
+ background:
195
+ video: { src: /videos/hero.mp4, poster: /images/hero.jpg }
196
+ ```
197
+
198
+ Components that draw their own declare `background: 'self'` in `meta.js`; they can still render the author's with `<SectionBackground block={block} />`.
199
+
200
+ ## Pages
201
+
202
+ ```
203
+ site/layout/ # header.md, footer.md, left.md — rendered on every page
204
+ site/pages/home/
205
+ ├── page.yml # title, description, order
206
+ ├── 1-hero.md
207
+ └── 2-features.md
208
+ ```
209
+
210
+ Decimals insert between (`2.5-x.md`). Ignored: `README.md`, `_*.md`, `_*/`.
211
+
212
+ ```yaml
213
+ # page.yml
214
+ title: About Us
215
+ id: about # stable identity for page: links; the app may write a code (id: 3f58142d) — keep it
216
+ order: 2
217
+ sections: [hero, team, ...]
218
+ pages: [team, history, ...] # child page order when this page has child folders
219
+ redirect: academic # to a child page (relative/absolute path, or URL)
220
+ slug: { fr: a-propos } # localized URL segment per language
221
+ layout: marketing
222
+
223
+ # folder.yml — a folder OF PAGES (page.yml means a page built from sections)
224
+ title: Getting Started
225
+ pages: [quickstart, app-tour, ...]
226
+
227
+ # site.yml
228
+ index: home
229
+ pages: [home, about, ...]
230
+ foundation: '@acme/ui@1.2.0'
231
+ extensions: ['@acme/fx@0.3.1']
232
+ ```
233
+
234
+ **The trailing `...`** in `pages:` and `sections:`: `[a, b, ...]` pins those first and includes the rest; `['...']` equals omitting the key; `[a, b]` is strict, and nothing warns: an unlisted page is dropped from every menu but stays routed, in `dist/` and in `llms.txt`; an unlisted section isn't rendered at all.
235
+
236
+ **Cascade:** `page.yml → folder.yml → site.yml → foundation defaults`. Put `layout: marketing` in a `folder.yml` and every page inherits it; one page can still override.
237
+
238
+ **Routes:** folders map 1:1 to routes; `pages:` controls order only. The site root is the exception: the first of `pages:` sets `/`, else `index:`, declared in `site.yml` or in the pages directory's own `folder.yml`/`page.yml`, with `site.yml` winning. A folder with `page.yml` but no markdown is a structural group (`hasContent: false`); visiting it redirects to the first descendant with content.
239
+
240
+ **Mounted folders:** a local folder for a mounted route says how *this site* presents it. Keep `layout:`, `title:` and SEO in a `folder.yml` there; the mounted repo's own `folder.yml` supplies ordering and title where the stub is silent. A `page.yml` with markdown of its own makes a real page above the mounted pages — a landing page for the branch. A mount is one level under `pages/`, and a subfolder in the local folder isn't read, since the branch's pages come from the mount; the build says so. What a site can't do from outside a repo it mounts: leave a file out, title or order a nested folder, or use a `README.md` as a page — those are the mounted repo's to do. A relative link to a markdown file (`./deploying.md#setup`), which is how docs in a repo link to each other, leads to the page that file became; the build names one that leads nowhere.
241
+
242
+ **Visibility flags:** `hidden: true` is a draft (not published; `uniweb dev` previews it; on a page it takes the pages below with it; on a section it's also kept from the component's params and takes its children with it); `hideIn: ['*']` or `[header]` controls nav placement only; `knowledge: true` is a different audience (below). An authored `pages/404/` needs no flag — `hidden: true` there makes it a draft and the site falls back to the generic 404.
243
+
244
+ **SEO and social cards.** Site-wide defaults in `site.yml`; any page overrides per field in `page.yml` (page wins, site fills gaps). Each page's static `<head>` carries Open Graph, Twitter Card, canonical, robots, and hreflang on a multilingual site. Set the social `image` once at site level — a 1200×630 JPEG/PNG. The site's `description` is the home page's; each page's own reads best under ~160 characters. A `head.html` tag of the same name is replaced. `uniweb doctor` checks the image and descriptions.
245
+
246
+ ```yaml
247
+ # site.yml
248
+ keywords: [components, react, cms]
249
+ favicon: /favicon.svg # name it even when the file exists; a published site links only what's named
250
+ touchIcon: /touch-icon.png # 180×180 PNG, no transparency (iOS draws transparent as black)
251
+ seo:
252
+ origin: https://acme.com # scheme + host only; set where no host states the address
253
+ image: /og-default.png
254
+ noindex: false # true keeps the whole site out of search
255
+ # page.yml
256
+ seo:
257
+ image: /og-about.png
258
+ canonical: https://acme.com/team # only to name ANOTHER URL
259
+ ```
260
+
261
+ **Where the site lives:** every absolute URL (canonical, `og:url`, sitemap, `llms.txt` links) is built on the site's origin plus base path. The GitHub Pages workflow asks GitHub; Netlify and Vercel state their URL; on any other static host set `seo.origin`. With no address, pages state no canonical and no `sitemap.xml` is written — `uniweb doctor` says so.
262
+
263
+ **Localized URLs:** on a multilingual site, `slug: { <lang>: <segment> }` gives a native segment per language; the folder name stays canonical. See the `i18n` guide.
264
+
265
+ ### Older versions of docs
266
+
267
+ Most docs need one version. When a release is about to stop being the latest and its readers need its docs kept, run `uniweb add version v2` (`--in <folder>`, `--label "2.x"`). It copies the docs to a folder named `v2` beside them, at `/docs/v2/…`, with the copy's links leading into the copy, no page ids in it, and search engines told to leave it out. Keep writing where you were: the pages beside version folders are the latest, and their URLs never change. **Don't copy a version folder by hand.** A foundation draws versions with kit's `useVersion` (foundation guide). Reference: `reference/versioning.md`.
268
+
269
+ ### Knowledge pages
270
+
271
+ `knowledge: true` in `page.yml`/`folder.yml` marks a page as agent-only: never rendered (no route, no HTML), cascading to the subtree by route prefix (`/kb` never claims `/kbase`). It isn't how to make a site AI-readable: ordinary pages already are (below). It is source material for an assistant the site offers to its visitors; it's kept out of `llms.txt`, the `.md` projections and the search index because it was never a page. It is **not a security control** — the assistant can quote it to whoever asks. Anything that must not reach a visitor doesn't belong in site content at all.
272
+
273
+ Who can read it depends on the host: `uniweb publish` (backend-hosted) carries it for an assistant; `uniweb export` / `deploy --host` (static) drops these pages and says so. `agents.exclude` and any `_`-prefixed segment outrank it. A site can be nothing but knowledge (root `knowledge: true`) — then it exists to *be* an agent at `/_agent/chat`, and only on a host that runs one: a static host yields an empty shell with a build that says "complete" and `Collected 0 pages`. Confirm with the host before building an integration against it.
274
+
275
+ ### Agent-readable output
276
+
277
+ A static build emits `/llms.txt` (an annotated index of every page) and `/{route}.md` (each page as clean markdown); a host that serves the site derives its own. Descriptions come from `page.yml description:`, then `seo.ogDescription`, then the opening paragraph. A top-level folder with no page of its own and ≥5 pages gets `/docs/llms.txt`; each language gets its own (`/fr/llms.txt`, `/fr/search-index.json`). Excluded deliberately: `seo.noindex`, `hidden`, `_`-prefixed, and a parametric page's URL pattern; `noindex`/`hidden` on a folder with no page of its own takes the branch.
278
+
279
+ ```yaml
280
+ agents:
281
+ index: true # /llms.txt
282
+ markdown: true # /{route}.md
283
+ branchIndexes: true
284
+ branchMinPages: 5
285
+ exclude: [/internal]
286
+ expectedOrigins: [https://app.example.com] # declared callers of the site's agent — see below
287
+ agents: false # or off entirely
288
+ ```
289
+
290
+ `expectedOrigins` is a declaration a host may honour by declining agent requests whose browser-sent `Origin` isn't listed; the site's own origin is always fine, and a request with no `Origin` (a server) is allowed — server callers are authenticated by other means arranged with the host. It is not a spend limit. `uniweb doctor` flags unknown keys here since the block is forwarded opaquely.
291
+
292
+ ```yaml
293
+ seo:
294
+ robots:
295
+ contentSignals: { search: true, ai-input: true, ai-train: false } # emits Content-Signal in robots.txt
296
+ ```
297
+
298
+ Declare only what you mean — an omitted signal says nothing.
299
+
300
+ ## Composition from the author's side
301
+
302
+ | Pattern | Authored as | Use when |
303
+ |---|---|---|
304
+ | Items | heading groups in one `.md` | repeating content: cards, features, FAQ entries |
305
+ | Concept blocks | ` ```md:<tag> ` fence | a named kind of content: FAQ, callout, steps |
306
+ | Child sections | `@`-prefixed files + `nest:` | children needing their own type, rich content, independent editing |
307
+ | Insets | `![](@Component){params}` | self-contained visuals/widgets |
308
+ | Block insets | ` ```@Component{params} ` fence | a component that wraps authored prose |
309
+
310
+ **Child sections:** `@`-prefixed files are excluded from the top-level list; `@@` nests deeper. `nest:` in `page.yml` maps parent → children and is flat (`{ features: [a, b], a: [sub-1] }`); children render in array order. A parent that lays children out in a grid takes `grid: 3` / `grid: '40/60'` in its frontmatter — a section key, not a param.
311
+
312
+ **Block insets:** the body is parsed like the rest of the page (headings, lists, tables, icons, further insets). To nest a fence inside, open the outer one with more backticks. A name the foundation doesn't define renders `Component not found` on purpose.