uniweb 1.31.3 → 1.31.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.
- package/README.md +10 -8
- package/package.json +7 -7
- package/partials/agents.md +15 -13
- package/partials/guides/content.md +11 -11
- package/partials/guides/data.md +10 -10
- package/partials/guides/foundation.md +6 -6
- package/partials/guides/i18n.md +2 -2
- package/partials/guides/services.md +3 -3
- package/partials/guides/ship.md +5 -5
- package/partials/guides/start.md +1 -1
- package/partials/guides/theme.md +1 -1
- package/src/framework-index.json +6 -6
package/README.md
CHANGED
|
@@ -101,7 +101,7 @@ my-project/
|
|
|
101
101
|
└── AGENTS.md # The project's manual, for developers and AI agents
|
|
102
102
|
```
|
|
103
103
|
|
|
104
|
-
**Pages are
|
|
104
|
+
**Pages are directories.** Create `pages/about/` with markdown files inside → visit `/about`. That's the whole routing model.
|
|
105
105
|
|
|
106
106
|
**Batteries included:** File-based routing, pre-rendering, localization, dynamic routes, media processing, search indexing, and more. See [Building with Uniweb](https://github.com/uniweb/docs/blob/main/development/building-with-uniweb.md) for the full list.
|
|
107
107
|
|
|
@@ -244,7 +244,7 @@ The `build` command outputs to `site/dist/`. With pre-rendering enabled (the def
|
|
|
244
244
|
|
|
245
245
|
After creating your project:
|
|
246
246
|
|
|
247
|
-
1. **Explore the structure** — Browse `site/pages/` to see how content is organized. Each page
|
|
247
|
+
1. **Explore the structure** — Browse `site/pages/` to see how content is organized. Each page's directory contains `page.yml` (metadata) and `.md` files (sections).
|
|
248
248
|
|
|
249
249
|
2. **Generate component docs** — Run `uniweb docs` to create `COMPONENTS.md` with all available components, their parameters, and presets.
|
|
250
250
|
|
|
@@ -287,16 +287,16 @@ The parser extracts semantic elements from markdown—`title` from the first hea
|
|
|
287
287
|
|
|
288
288
|
## Foundations Are Portable
|
|
289
289
|
|
|
290
|
-
The `src/`
|
|
290
|
+
The `src/` directory (your project's foundation) ships with your project as a convenience, but sites reference a foundation by configuration, not by where its directory is.
|
|
291
291
|
|
|
292
292
|
**Two ways to use a foundation:**
|
|
293
293
|
|
|
294
294
|
| Mode | How it works | Best for |
|
|
295
295
|
| ---------------- | ---------------------------------- | -------------------------------------------------- |
|
|
296
|
-
| **Local
|
|
296
|
+
| **Local directory** | Foundation lives in your workspace | Developing site and components together |
|
|
297
297
|
| **Runtime link** | Foundation loads from a URL | Independent release cycles, platform-managed sites |
|
|
298
298
|
|
|
299
|
-
Develop a foundation locally, then register it for other sites to use. A site can also name a registered foundation instead of a local one — a project made by `uniweb clone` does — and `uniweb dev`
|
|
299
|
+
Develop a foundation locally, then register it for other sites to use. A site can also name a registered foundation instead of a local one — a project made by `uniweb clone` does — and both `uniweb dev` and Uniweb hosting run it. The site doesn't care where its components come from.
|
|
300
300
|
|
|
301
301
|
**This enables two development patterns:**
|
|
302
302
|
|
|
@@ -356,7 +356,7 @@ uniweb add ci --host=github-pages
|
|
|
356
356
|
|
|
357
357
|
**Other free static hosts.** Cloudflare Pages, Netlify, and Vercel work three ways: `uniweb add ci --host=<adapter>` scaffolds a workflow (and a per-PR preview that comments the URL), connecting the repo through their dashboard lets the host build it with no config at all, or `uniweb deploy --host=<adapter>` uploads from your machine.
|
|
358
358
|
|
|
359
|
-
**When to choose Uniweb hosting instead** (paid): when you need
|
|
359
|
+
**When to choose Uniweb hosting instead** (paid): when you need pages prerendered over live data (records fetched at runtime, not just at build time), foundation/runtime version propagation without redeploying every site, or edge SSR. If your site's content lives in markdown and updates ship via git, free CI is the right call.
|
|
360
360
|
|
|
361
361
|
### Your clients manage the content, in the app
|
|
362
362
|
|
|
@@ -364,9 +364,11 @@ You're building a foundation for clients, content authors, or any team that won'
|
|
|
364
364
|
|
|
365
365
|
```bash
|
|
366
366
|
cd src
|
|
367
|
-
uniweb register
|
|
367
|
+
uniweb register
|
|
368
368
|
```
|
|
369
369
|
|
|
370
|
+
It registers under the scope of the Uniweb workspace you logged in to (`uniweb login --org @your-org`); `--scope` names another scope.
|
|
371
|
+
|
|
370
372
|
Real sites built on your foundation are managed in the **Uniweb app** — a visual editor designed for non-technical authors. They never see git, markdown, yaml, or React. They see *your* components, with live previews and visual controls for the params you defined. The foundation becomes the editor's native vocabulary for that site: you keep creative control of the design system, they get an editor that feels custom-built for them.
|
|
371
373
|
|
|
372
374
|
This is the best path when site content has a life independent of the foundation's release cycle — agencies, design studios, multi-client teams, or any project where content authors aren't the same people as the developers.
|
|
@@ -381,7 +383,7 @@ This is the best path when site content has a life independent of the foundation
|
|
|
381
383
|
| `uniweb publish` | Go live on Uniweb hosting (paid) — brings the site's foundation along, pushes the content, and serves the site dynamically. The canonical verb for Uniweb hosting. |
|
|
382
384
|
| `uniweb deploy --host=<adapter>` | Ship to a third-party static host in one step — builds `dist/`, uploads, invalidates. Drives that host's own CLI. |
|
|
383
385
|
| `uniweb export` | Produce a self-contained `dist/` for any static host. You upload it yourself. `--host=<adapter>` adds host-specific helper files. |
|
|
384
|
-
| `uniweb register
|
|
386
|
+
| `uniweb register` | Register a foundation to the registry, under your Uniweb workspace's scope, for sites managed in the app. |
|
|
385
387
|
| `uniweb build` | Inspect a build locally. For shipping, use `publish` (Uniweb hosting) or `deploy`/`export` (static hosts). |
|
|
386
388
|
| `uniweb guide [name]` | Print a guide to building with Uniweb: `content`, `foundation`, `theme` and more. A project's `AGENTS.md` says which a task needs. |
|
|
387
389
|
| `uniweb update` | Align this project with the CLI you're running: bump `@uniweb/*` deps in every `package.json` to the CLI's matrix (then install), and refresh `AGENTS.md`. Pins to *this* CLI's matrix — run `npx uniweb@latest update` to align to the latest release. Updating the CLI itself is your package manager's job (`npm i -g uniweb@latest`). |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "uniweb",
|
|
3
|
-
"version": "1.31.
|
|
3
|
+
"version": "1.31.5",
|
|
4
4
|
"description": "Create structured Vite + React sites with content/code separation",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -41,15 +41,15 @@
|
|
|
41
41
|
"js-yaml": "^4.3.2",
|
|
42
42
|
"prompts": "^2.4.2",
|
|
43
43
|
"tar": "^7.5.21",
|
|
44
|
-
"@uniweb/
|
|
45
|
-
"@uniweb/
|
|
46
|
-
"@uniweb/
|
|
47
|
-
"@uniweb/
|
|
44
|
+
"@uniweb/content-writer": "~1.3.1",
|
|
45
|
+
"@uniweb/schemas": "~1.7.1",
|
|
46
|
+
"@uniweb/core": "~1.6.11",
|
|
47
|
+
"@uniweb/semantic-parser": "~1.13.2"
|
|
48
48
|
},
|
|
49
49
|
"peerDependencies": {
|
|
50
|
-
"@uniweb/
|
|
50
|
+
"@uniweb/build": "~1.20.5",
|
|
51
51
|
"@uniweb/content-reader": "~1.5.9",
|
|
52
|
-
"@uniweb/
|
|
52
|
+
"@uniweb/semantic-parser": "~1.13.2"
|
|
53
53
|
},
|
|
54
54
|
"peerDependenciesMeta": {
|
|
55
55
|
"@uniweb/build": {
|
package/partials/agents.md
CHANGED
|
@@ -10,7 +10,7 @@ The foundation is the React that receives that object, under a runtime that owns
|
|
|
10
10
|
|
|
11
11
|
## 1. Why this is worth doing right
|
|
12
12
|
|
|
13
|
-
Uniweb is an implementation of **Component Content Architecture (CCA)**: content and components are separate artifacts — different files, packages and maintainers — joined by a thin runtime
|
|
13
|
+
Uniweb is an implementation of **Component Content Architecture (CCA)**: content and components are separate artifacts — different files, packages and maintainers — joined by a thin runtime wherever a page renders: in a build, on the host and in the browser. Full argument: `uniweb.io/docs/architecture/component-content-architecture.md`. What it buys you:
|
|
14
14
|
|
|
15
15
|
**You write less.** A section type carries no theme maps, null checks, hardcoded strings, wrapper element, sticky-spacer arithmetic or fetch lifecycle: the runtime does each once, for every section. What remains is rendering logic.
|
|
16
16
|
|
|
@@ -38,7 +38,7 @@ The principles to reason from when a table in §2 doesn't cover the case:
|
|
|
38
38
|
|
|
39
39
|
- **The foundation provides options; the site configures.** The foundation doesn't know which site it serves; the site doesn't know how the foundation is built.
|
|
40
40
|
- **Components render from content, not context.** Never the URL, the router or the layout; variation comes through params or a different type, chosen by the author.
|
|
41
|
-
- **Configuration cascades** page → folder → site → foundation, like CSS specificity: defaults high, exceptions local.
|
|
41
|
+
- **Configuration cascades** `page.yml` → `folder.yml` → `site.yml` → foundation, like CSS specificity: defaults high, exceptions local.
|
|
42
42
|
- **Metadata declares the interface.** `meta.js` drives defaults, the editor's controls, the schema and the docs.
|
|
43
43
|
- **The site owns the theme.** Foundations declare variables, sites set values, components use tokens.
|
|
44
44
|
|
|
@@ -51,11 +51,12 @@ When a rule in §2 feels like friction, that is the moment you are about to take
|
|
|
51
51
|
| By reflex you'd… | Here | Signal |
|
|
52
52
|
|---|---|---|
|
|
53
53
|
| Write `package.json`, `vite.config.js`, `index.html`, an entry file | `npx uniweb@latest create <name> --template <t>`; `uniweb add site / foundation / section / project / extension`. The CLI owns those files. | build fails far from the cause |
|
|
54
|
+
| Add a build step for the site: a Vite plugin, an npm script, code in `entry.js` | Nothing in the site's build runs on Uniweb hosting: `publish` sends the content, and the host renders it with the runtime and the registered foundation. Put code in the foundation and everything else in content. | silent — right under `uniweb dev` and `export`, missing once published |
|
|
54
55
|
| `npm install` a foundation or theme; `npm install @uniweb/runtime` | A foundation is a workspace `file:` dependency or a catalog ref in `site.yml`, never an npm package. In a foundation the runtime arrives through `@uniweb/build`. Everything else — a carousel, a chart library, a date utility, `@uniweb/api` — you install in the foundation as in any project. | npm 404 / silent version skew |
|
|
55
56
|
| `npm update` / `pnpm update` the `@uniweb/*` packages; `npx uniweb update` | `npx uniweb@latest update --yes` (`--yes` because there is no terminal to answer the prompt). The packages are a matched set and AGENTS.md updates with them. Without `@latest` it runs the CLI the project already pins and reports "aligned". | `status` and `doctor` name the drift |
|
|
56
57
|
| Assume `localhost:5173`; run `npm run dev` inside the site | `uniweb dev` serves the site you are in (from the workspace root, the first, with a notice); read `Serving <site> at <url>`. `uniweb dev --status` / `--stop` know only that server. | wrong server, silent |
|
|
57
58
|
| Read `foundation:` in `site.yml` as a path | A **package name**. Follow the `file:` dep in the site's `package.json`. `@org/name@1.2.3` means the source is not in this repo. | the build: `did not resolve` |
|
|
58
|
-
| Trust
|
|
59
|
+
| Trust directory names for the workspace layout | `pnpm-workspace.yaml` globs decide (§3.2). | — |
|
|
59
60
|
| `main.jsx`; JSX in a `.js` file | `main.js` is plain JS; JSX lives in `.jsx`. | build stops |
|
|
60
61
|
| Guess which section types exist or what a param is called | `ls <foundation>/sections/`, `cat …/<Type>/meta.js`. Every foundation's vocabulary is different; `uniweb docs --from-source` writes it all to `COMPONENTS.md`. | red box / silent |
|
|
61
62
|
| Predict what markdown parses to | `uniweb inspect <file>` prints the shape. | silent (wrong field) |
|
|
@@ -76,15 +77,16 @@ When a rule in §2 feels like friction, that is the moment you are about to take
|
|
|
76
77
|
| Strip the content a new `type:` / `variant:` won't render before switching | Nothing to strip (§1): the switch is a one-line trial, and what stays afterwards is the author's call. | content loss |
|
|
77
78
|
| `pages/fr/about.md` for French | `locales/` beside `pages/`; `pages/` holds the default language only. | silent — it becomes a page at `/fr` |
|
|
78
79
|
| `t('key')`, `<Trans>` | Nothing — content arrives translated; each language is its own build. | — |
|
|
79
|
-
| `src/assets/`, `assets/img.png` | `./img.png` beside the page, or `/img.png` in `public/`. There is no assets
|
|
80
|
+
| `src/assets/`, `assets/img.png` | `./img.png` beside the page, or `/img.png` in `public/`. There is no assets directory. | build stops, or warns |
|
|
80
81
|
| `fetch: /api/posts`, `fetch: ./data.json` | `fetch:` names a query from `queries.yml`; a URL belongs on the query (`url:`). | build stops |
|
|
81
|
-
| `records/blog/2025/post.md`; one YAML file holding a list | Flat: `records/<schema>/<name>.md`, one record per file; the file name is `$name`. |
|
|
82
|
+
| `records/blog/2025/post.md`; one YAML file holding a list | Flat: `records/<schema>/<name>.md`, one record per file; the file name is `$name`. | a directory read as a schema, silent |
|
|
82
83
|
| `` `/blog/${slug}` `` | `item.$route` — never compose a URL. | works until a page moves |
|
|
83
|
-
| `page.yml` in a
|
|
84
|
+
| `page.yml` in a directory of pages | It makes one page, each `.md` a section. `folder.yml` keeps them pages and carries `layout`, `title` and SEO. Over a mount, `page.yml` with markdown of its own is a landing page *above* the mounted pages; a mount is one level under `pages/`, and a local subdirectory beside it isn't read. | silent; the build names that subdirectory |
|
|
84
85
|
| Paste the gtag / GTM / Meta pixel snippet into a component, `index.html`, or `services.tracking.scripts` | Uniweb Cloud (`publish`): `services.google: { id: G-… }`, or `GTM-…` for a container, and the host loads Google's tag, free, with no code, on any foundation. `head.html` isn't applied there, and `scripts` takes URLs only. Static build (`export`, `deploy --host`): the snippet in `head.html` beside `site.yml`. More: `uniweb guide services`. | silent — Google reports nothing |
|
|
85
86
|
| Expect `{company}` to resolve | Only under a foundation with `createLoomHandlers`; otherwise it renders literally. | build warns if `site.yml` has `placeholders:` |
|
|
86
87
|
| `hidden: true` on `pages/404/` to keep it out of nav | That makes it a draft. `hideIn: ['*']` controls nav. | silent |
|
|
87
88
|
| Treat `@child.md` / `_draft.md` as names | `@` = child section, placed by `nest:` (with none it renders last; a `sections:` list drops it); `_` = ignored. | build warns, unless `sections:` dropped it |
|
|
89
|
+
| Treat the files as the only copy of the content; regenerate pages from a script | On a synced site authors edit the same pages in the app, and a pull writes their edits into the files. Take what changed before you edit (`status` names it), and edit the files rather than regenerate them, or your next push replaces the authors' work. | silent after a pull; a push refuses a section changed on both sides |
|
|
88
90
|
|
|
89
91
|
### 2.3 Section types and the components behind them
|
|
90
92
|
|
|
@@ -126,7 +128,7 @@ When a rule in §2 feels like friction, that is the moment you are about to take
|
|
|
126
128
|
| `font-serif`, `font-sans` | Tailwind's stack, not the site's — unless the foundation declares it as a `font-*` var in `main.js`. Families are the site's (`theme.yml fonts:`). | silent |
|
|
127
129
|
| `@import url(fonts.googleapis…)` in CSS | `theme.yml fonts.import` / `faces`. | — |
|
|
128
130
|
| `@tailwind base;` | Tailwind v4: `@import "tailwindcss"` plus kit's token imports (theme guide). | silent — most utilities missing |
|
|
129
|
-
| Trust the foundation's own build to prove a class works | A site build and `uniweb dev` read what `styles.css` names: the whole foundation with `@import "tailwindcss" source("./")`, as the scaffold writes, else only the
|
|
131
|
+
| Trust the foundation's own build to prove a class works | A site build and `uniweb dev` read what `styles.css` names: the whole foundation with `@import "tailwindcss" source("./")`, as the scaffold writes, else only the directories `@source` lists. | each names a directory a list missed, as does `doctor` |
|
|
130
132
|
| `prose` from `@tailwindcss/typography`, `prose-invert` | `@import "@uniweb/kit/prose-tokens.css"`; no invert — colors are already the theme's. | build warns; unstyled lists |
|
|
131
133
|
| `html { scroll-behavior: smooth }` | Never on `html`/`body`; the runtime owns scrolling. | route transitions misbehave |
|
|
132
134
|
| `filter: blur(80px)` for a glow | Radial gradient + `mask-image`. | Safari jank |
|
|
@@ -148,7 +150,7 @@ When a rule in §2 feels like friction, that is the moment you are about to take
|
|
|
148
150
|
| `*/src`, `*/sites/*` | projects with sites | each project's foundation with its own sites |
|
|
149
151
|
| plus a package whose `main.js` has `extension: true` | extensions | extra section types, runtime-loaded |
|
|
150
152
|
|
|
151
|
-
A site is any package with a `site.yml`. `paths:` in `site.yml` can mount another
|
|
153
|
+
A site is any package with a `site.yml`. `paths:` in `site.yml` can mount another directory or repo into the page tree, so a route's markdown may not live under `pages/`.
|
|
152
154
|
|
|
153
155
|
**3. Find the foundation by the wiring.** `"docs-src": "file:../src"` in the site's `package.json` → `docs/src/`.
|
|
154
156
|
|
|
@@ -183,7 +185,7 @@ On a content task and tempted to open the foundation: stop — usually a param a
|
|
|
183
185
|
**7. Work in the lane, and check as you go.**
|
|
184
186
|
|
|
185
187
|
```bash
|
|
186
|
-
uniweb inspect pages/home/hero.md # from the site dir: the parsed shape (--full, --sequence, --raw; a
|
|
188
|
+
uniweb inspect pages/home/hero.md # from the site dir: the parsed shape (--full, --sequence, --raw; a directory = the page)
|
|
187
189
|
uniweb doctor # project configuration (--fix repairs)
|
|
188
190
|
uniweb validate # records against declared schemas
|
|
189
191
|
uniweb <command> --help # exact flags, no side effects
|
|
@@ -202,7 +204,7 @@ uniweb <command> --help # exact flags, no side effects
|
|
|
202
204
|
| Pages missing from the nav | a strict `pages:` list — add `...` |
|
|
203
205
|
| A color is empty | unquoted `#` in YAML |
|
|
204
206
|
| Literal `{name}` on the page | no Loom content handler |
|
|
205
|
-
| A class works in the foundation's build, not in the site's or `uniweb dev` | `styles.css` lists
|
|
207
|
+
| A class works in the foundation's build, not in the site's or `uniweb dev` | `styles.css` lists directories and not this one — `uniweb doctor` names it; `source("./")` on the Tailwind import reads them all |
|
|
206
208
|
| Sticky header scrolls away | `sticky` class instead of `sticky: true` in `meta.js` |
|
|
207
209
|
| Modal under the header | z-index instead of `<Overlay>` |
|
|
208
210
|
| Entrance animation never plays | JS-started; write it in CSS; `uniweb dev` doesn't prerender |
|
|
@@ -250,17 +252,17 @@ content = { title, pretitle, subtitle, paragraphs, links, images, icons, videos,
|
|
|
250
252
|
|
|
251
253
|
**Backgrounds and theme are frontmatter.** `background:` takes an image, video, gradient, quoted color or palette token, or an object (`image`, `video`, `overlay`); `theme: light | medium | dark`, or a map with token overrides (`section: neutral-100`).
|
|
252
254
|
|
|
253
|
-
**Pages.** `pages/<name>/` → `/<name>`; a name or `slug:` holding `?`, `#` or `%` stops the build. `page.yml`: `title`, `description`, `id`, `order`, `sections: [a, b, ...]`, `pages: [...]`, `nest`, `redirect`, `slug: { fr: … }`, `hidden` (draft; takes the pages below it), `hideIn` (nav only), `knowledge` (agent-only, never rendered — not a security control), `query` / `fetch`, `seo`, `layout`. `folder.yml` for a
|
|
255
|
+
**Pages.** `pages/<name>/` → `/<name>`; a name or `slug:` holding `?`, `#` or `%` stops the build. `page.yml`: `title`, `description`, `id`, `order`, `sections: [a, b, ...]`, `pages: [...]`, `nest`, `redirect`, `slug: { fr: … }`, `hidden` (draft; takes the pages below it), `hideIn` (nav only), `knowledge` (agent-only, never rendered — not a security control), `query` / `fetch`, `seo`, `layout`. `folder.yml` for a directory *of pages*. Numeric prefixes (a number then a dash) order section files, page files and page directories and never reach a URL: `2-about/` is `/about`, and `pages:`/`index:` name it `about`; `2.5-x.md` slots between; `3d-printing` has no number. Config cascades `page.yml → folder.yml → site.yml → foundation`. `layout/header.md`, `footer.md` render on every page — a markdown list is the nav, a standalone link the CTA, `yaml:nav` for richer menus. Child sections: `@child.md` + `nest: { parent: [child] }`.
|
|
254
256
|
|
|
255
257
|
**`site.yml`.** `index`, `pages`, `foundation`, `extensions`, `paths`, `placeholders`, `languages`, `services`, `agents`, `seo` (`origin`: scheme + host, `image`: 1200×630), `favicon`, `touchIcon`. Everything in `site.yml` and `queries.yml` ships to the browser — **never a secret**.
|
|
256
258
|
|
|
257
|
-
**Records — run `uniweb guide data` before touching them.** `records/<schema>/<name>.md|yml|json|bib` (`records/article/` → `@/article`); `queries.yml` names → `{ schema, where, sort, limit, scope }`; a page or section shows one with `query: name` or `fetch: { query, … }` (narrows, never widens); a `[slug]/`
|
|
259
|
+
**Records — run `uniweb guide data` before touching them.** `records/<schema>/<name>.md|yml|json|bib` (`records/article/` → `@/article`); `queries.yml` names → `{ schema, where, sort, limit, scope }`; a page or section shows one with `query: name` or `fetch: { query, … }` (narrows, never widens); a `[slug]/` directory inside the query's page gives each record a page.
|
|
258
260
|
|
|
259
261
|
### Foundation
|
|
260
262
|
|
|
261
263
|
```
|
|
262
264
|
src/
|
|
263
|
-
├── sections/ # section types — PascalCase file or
|
|
265
|
+
├── sections/ # section types — PascalCase file or directory at the root; a directory when it needs meta.js
|
|
264
266
|
├── layouts/ # custom layouts, auto-discovered
|
|
265
267
|
├── components/ # ordinary React — any props, any library, no meta.js, invisible to authors
|
|
266
268
|
├── utils/
|
|
@@ -4,7 +4,7 @@ Lane guide — AGENTS.md procedure step 6 loads it before any content is written
|
|
|
4
4
|
|
|
5
5
|
## Sections
|
|
6
6
|
|
|
7
|
-
**A section with no `type:` renders through the foundation's default section type** — the `defaultSection` its `main.js` sets, else a section type named `Section` where the foundation has one, the fallback for foundations that declare none. This is what lets a
|
|
7
|
+
**A section with no `type:` renders through the foundation's default section type** — the `defaultSection` its `main.js` sets, else a section type named `Section` where the foundation has one, the fallback for foundations that declare none. This is what lets a directory of plain markdown with no frontmatter become pages: mounted documentation, an imported wiki. If such content shows "Component not found", the foundation has neither: declare `defaultSection` in its `main.js`, naming the type that content should render with. `uniweb doctor` states each foundation's default, and suggests one where a type stands out.
|
|
8
8
|
|
|
9
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: `` 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
10
|
|
|
@@ -131,7 +131,7 @@ Image attributes: `{width=800 height=600 loading=lazy fit=cover position=center
|
|
|
131
131
|
|
|
132
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
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
|
|
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 directories included); a file outside the site and its mounts is not uploaded — put that in `public/`. There is no `assets/` directory for media; a build stops on a `/x` only `assets/` holds.
|
|
135
135
|
|
|
136
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
137
|
|
|
@@ -217,7 +217,7 @@ site/pages/home/
|
|
|
217
217
|
└── 2-features.md
|
|
218
218
|
```
|
|
219
219
|
|
|
220
|
-
Decimals insert between (`2.5-x.md`). A page
|
|
220
|
+
Decimals insert between (`2.5-x.md`). A page directory's number works the same way: `pages/2-about/` orders second and is `/about`, named `about` in `pages:` and `index:`. A number counts only with a dash after it, or as the whole name (`404`): `3d-printing.md` keeps its name. Ignored: `README.md`, `_*.md`, `_*/`.
|
|
221
221
|
|
|
222
222
|
```yaml
|
|
223
223
|
# page.yml
|
|
@@ -225,12 +225,12 @@ title: About Us
|
|
|
225
225
|
id: about # stable identity for page: links; the app may write a code (id: 3f58142d) — keep it
|
|
226
226
|
order: 2
|
|
227
227
|
sections: [hero, team, ...]
|
|
228
|
-
pages: [team, history, ...] # child page order when this page has child
|
|
228
|
+
pages: [team, history, ...] # child page order when this page has child pages
|
|
229
229
|
redirect: academic # to a child page (relative/absolute path, or URL)
|
|
230
230
|
slug: { fr: a-propos } # localized URL segment per language
|
|
231
231
|
layout: marketing
|
|
232
232
|
|
|
233
|
-
# folder.yml — a
|
|
233
|
+
# folder.yml — a directory OF PAGES (page.yml means a page built from sections)
|
|
234
234
|
title: Getting Started
|
|
235
235
|
pages: [quickstart, app-tour, ...]
|
|
236
236
|
|
|
@@ -245,13 +245,13 @@ extensions: ['@acme/fx@0.3.1']
|
|
|
245
245
|
|
|
246
246
|
**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.
|
|
247
247
|
|
|
248
|
-
**A
|
|
248
|
+
**A directory of pages holds pages of one section.** Under a `folder.yml`, each page is one `.md` file of one section, and each subdirectory is a directory of pages too. The build stops on a subdirectory with a `page.yml` of its own, a parametric `[slug]/` included. A page of several sections goes outside that directory. In the app, such a page takes no second section, and a pull holds one made there.
|
|
249
249
|
|
|
250
250
|
**Such a page's frontmatter holds its page's settings**, beside its section's `type:` and params: `title` (else its H1), `description`, `label`, `keywords`, `slug`, `hideIn`, `layout`, `seo`, `knowledge`, `trackSections`, as in a `page.yml`. A section param with one of those names goes under `props:` (`props: { label: … }`); the build warns where the section type declares one. `id:` is the section's id there too, and `hidden:` drafts the page. A pull writes the app's changes to them back into the file.
|
|
251
251
|
|
|
252
|
-
**Routes:**
|
|
252
|
+
**Routes:** pages map 1:1 to routes, and under `pages/` every directory is a page; `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 directory with `page.yml` but no markdown is a page with no sections (`hasContent: false`); visiting it redirects to the first descendant with content.
|
|
253
253
|
|
|
254
|
-
**Mounted
|
|
254
|
+
**Mounted directories:** a local directory 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 subdirectory in the local directory 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 directory, 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. A mount that is its own repository (a submodule, or a clone beside the site) takes its edits as commits there, and `uniweb refresh` takes its latest; a push or publish stops on one that is behind its remote or holds uncommitted changes, and `--mounts-as-is` sends it as it is. A pull writes an author's app edits into a mounted directory where the site's own repository holds it, or a submodule of it does (a commit there, to push before the site's repository). A directory it cannot merge into — a clone beside the site — keeps its text and the app keeps the author's: the pull and `status` name each such page as held, and a push leaves it alone while its file is unchanged. A mount is its directory, `pages/docs: ../docs`; the object form is refused.
|
|
255
255
|
|
|
256
256
|
**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.
|
|
257
257
|
|
|
@@ -274,11 +274,11 @@ seo:
|
|
|
274
274
|
|
|
275
275
|
**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.
|
|
276
276
|
|
|
277
|
-
**Localized URLs:** on a multilingual site, `slug: { <lang>: <segment> }` gives a native segment per language; the
|
|
277
|
+
**Localized URLs:** on a multilingual site, `slug: { <lang>: <segment> }` gives a native segment per language; the directory name stays canonical. See the `i18n` guide.
|
|
278
278
|
|
|
279
279
|
### Older versions of docs
|
|
280
280
|
|
|
281
|
-
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
|
|
281
|
+
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 directory 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 directories are the latest, and their URLs never change. **Don't copy a version directory by hand.** A foundation draws versions with kit's `useVersion` (foundation guide). Reference: `reference/versioning.md`.
|
|
282
282
|
|
|
283
283
|
### Knowledge pages
|
|
284
284
|
|
|
@@ -288,7 +288,7 @@ Who can read it depends on the host: `uniweb publish` (backend-hosted) carries i
|
|
|
288
288
|
|
|
289
289
|
### Agent-readable output
|
|
290
290
|
|
|
291
|
-
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
|
|
291
|
+
A static build emits `/llms.txt` (an annotated index of every page) and `/{route}.md` (each page as clean markdown, and, where the build prerenders it, the records each section shows, as JSON after that section); 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 directory with no content 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 directory with no content of its own takes the branch.
|
|
292
292
|
|
|
293
293
|
```yaml
|
|
294
294
|
agents:
|
package/partials/guides/data.md
CHANGED
|
@@ -9,8 +9,8 @@ A small database, not a page tree. Three things, deliberately separate:
|
|
|
9
9
|
```
|
|
10
10
|
site/
|
|
11
11
|
├── pages/
|
|
12
|
-
├── records/ # the site's records — every file in a schema
|
|
13
|
-
│ ├── article/ #
|
|
12
|
+
├── records/ # the site's records — every file in a schema directory is one
|
|
13
|
+
│ ├── article/ # directory names the data schema
|
|
14
14
|
│ ├── person/
|
|
15
15
|
│ └── folder.yml # optional: sorts records into folders
|
|
16
16
|
├── queries.yml # how content is REACHED
|
|
@@ -23,9 +23,9 @@ site/
|
|
|
23
23
|
| `records/std/person/…` | `@std/person` — the shared standard set |
|
|
24
24
|
| `records/acme/project/…` | `@acme/project` — an org's |
|
|
25
25
|
|
|
26
|
-
Keep
|
|
26
|
+
Keep directories flat — `records/article/2025/x.md` reads as the `2025` schema of an `article` org. A `_`-prefixed file is not a record.
|
|
27
27
|
|
|
28
|
-
**Formats:** `.md` (frontmatter fields, body prose; auto-excerpt and first-image extraction), `.yml`/`.yaml` and `.json` (structured, no body), `.bib` (each `@entry{key, …}` is a record named by its cite key, normalized to CSL-JSON, LaTeX accents → Unicode). Mix freely in one
|
|
28
|
+
**Formats:** `.md` (frontmatter fields, body prose; auto-excerpt and first-image extraction), `.yml`/`.yaml` and `.json` (structured, no body), `.bib` (each `@entry{key, …}` is a record named by its cite key, normalized to CSL-JSON, LaTeX accents → Unicode). Mix freely in one directory. **One record per file**; the file name is `$name`, the one name it carries on every site (no `slug` field). Conventional fields: `title`, `date`, `tags`, `image`, `description`, `author`, plus whatever the content needs. Images sit beside the file (`./`). `draft: true` keeps a record off the live site: still a record, previewed by `pnpm dev`, excluded from a production build, kept undelivered on a backend.
|
|
29
29
|
|
|
30
30
|
**Links and files are records too.** `records/uniweb/link/x.yml` holding only `url:` (absolute) is a `@uniweb/link`; any file in `records/uniweb/file/` is a `@uniweb/file` named by its file name. Label and tags go on their `records/folder.yml` entry. Declare `data: { videos: '@uniweb/link' }` → `{ url, $name, $label, $tags }`; `data: { downloads: '@uniweb/file' }` → `{ file: { url, name, mime, size }, $name, $label, $tags }`. Two files of one name with different extensions clash. On a backend a component must declare the type for a query over it to be accepted.
|
|
31
31
|
|
|
@@ -53,7 +53,7 @@ The body — `body.content`.
|
|
|
53
53
|
|
|
54
54
|
Paths are relative to `records/`, one file or a glob. An entry can be `{ path, tags, label }` — delivered beside the record as `$tags` (in order) and `$label` (one text or `{ en, fr }`, resolved to the page's language); a query reads them like any key (`where: { $tags: featured }`). `scope: archive` reads the folder and everything inside. A record sits in one folder; a computed subset is a query. The build refuses a top-level bare path (every file is a record already).
|
|
55
55
|
|
|
56
|
-
**With a backend, `records/` is what `uniweb push` sends.** No `records/` leaves the backend alone; an *empty* `records/` takes them out of the site's folder (the CLI asks). Records with a data schema reach published pages only when `services.records: true`; once the site has been published, a push changes its records on the live site with no republish (pages wait for `uniweb publish`). To move records to another schema, move their files into its
|
|
56
|
+
**With a backend, `records/` is what `uniweb push` sends.** No `records/` leaves the backend alone; an *empty* `records/` takes them out of the site's folder (the CLI asks). Records with a data schema reach published pages only when `services.records: true`; once the site has been published, a push changes its records on the live site with no republish (pages wait for `uniweb publish`). To move records to another schema, move their files into its directory, renamed or not, and keep each file's `$uuid` line: the push sends each as a new record in the place the old one had. A record taken out of the folder stays on the backend, and the push that took it out offers to delete it (`--yes` deletes without asking).
|
|
57
57
|
|
|
58
58
|
## Queries
|
|
59
59
|
|
|
@@ -83,7 +83,7 @@ query: recent | type: ArticleTeaser
|
|
|
83
83
|
|
|
84
84
|
### Parametric pages
|
|
85
85
|
|
|
86
|
-
A `[slug]/`
|
|
86
|
+
A `[slug]/` directory inside the page that names the query gives each record its own page:
|
|
87
87
|
|
|
88
88
|
```
|
|
89
89
|
pages/blog/
|
|
@@ -98,7 +98,7 @@ pages/blog/
|
|
|
98
98
|
|
|
99
99
|
**Link with `item.$route`, never a composed URL.** Every record a query delivers carries `$route` (the URL of the parametric page whose route query is that query), wherever the list appears. No page or no value → no `$route`, never a broken one. `detailPage: page:<id>` on a fetch links to another page instead. `$` marks framework-filled fields; a record's own `route` is untouched.
|
|
100
100
|
|
|
101
|
-
**The route query** — which query the URL narrows: the `[slug]` page's own `query:`, else its parent's, else `site.yml`'s (top-level `pages/[slug]/` only); if none, the query its sections all declare. The
|
|
101
|
+
**The route query** — which query the URL narrows: the `[slug]` page's own `query:`, else its parent's, else `site.yml`'s (top-level `pages/[slug]/` only); if none, the query its sections all declare. The directory name says what the segment matches: `[slug]` the record's name (`$name`) — or the field the route query binds `:slug` to (`where: { slug: :slug }`, how an external API's records get pages); `[uuid]` its `$uuid`; any other `[name]` the record's field of that name (several values → any member matches; non-unique → the build warns). A directory inside `[slug]/` (`[slug]/cv/`) is a parametric page about the same record.
|
|
102
102
|
|
|
103
103
|
**`current:`** on a section's own `fetch:` chooses how it uses the page's record: `only` (default — the record), `exclude` (the others, "related"), `include` (all, a pager). `fetch: { query: articles, as: related, current: exclude, limit: 3 }`. It follows the query, not the key: a fetch of the route query gets the record unless it says otherwise; a fetch of another query reads `current:` only when written.
|
|
104
104
|
|
|
@@ -134,9 +134,9 @@ data: {
|
|
|
134
134
|
}
|
|
135
135
|
```
|
|
136
136
|
|
|
137
|
-
`single`/`whole` are refused over a schema whose root is a list (`@std/nav`, `@std/form`). A `whole` key its source cannot answer whole is `null`. An optional `schemas.config.js` routes a scope to a
|
|
137
|
+
`single`/`whole` are refused over a schema whose root is a list (`@std/nav`, `@std/form`). A `whole` key its source cannot answer whole is `null`. An optional `schemas.config.js` routes a scope to a directory: `export default { '@acme': '../shared/acme-schemas' }` — a routed scope wins, has no package fallback, and `@/`/`@uniweb` are never routable. Worked examples: `development/schemas-in-practice.md`.
|
|
138
138
|
|
|
139
|
-
**Any foundation can use a data schema another defines, by its full name** — `data: { members: '@acme/member' }`, `schema: '@acme/member'` in `queries.yml`. No backend is involved, and in a workspace nothing to configure: a local build, `uniweb dev` included, reads the type from the foundation whose name gives the `@acme` scope and whose own `schemas/` defines it. Two packages of the workspace defining it stop the build, naming both. A type outside the workspace comes from `schemas.config.js` (`'@acme/member': '../elsewhere/member.yml'`, or the scope's
|
|
139
|
+
**Any foundation can use a data schema another defines, by its full name** — `data: { members: '@acme/member' }`, `schema: '@acme/member'` in `queries.yml`. No backend is involved, and in a workspace nothing to configure: a local build, `uniweb dev` included, reads the type from the foundation whose name gives the `@acme` scope and whose own `schemas/` defines it. Two packages of the workspace defining it stop the build, naming both. A type outside the workspace comes from `schemas.config.js` (`'@acme/member': '../elsewhere/member.yml'`, or the scope's directory), which wins over the workspace, or an installed `@acme/schemas` package. A scope is a namespace that keeps names from colliding, not a limit on who uses a type. So a type another foundation defines is named, never copied: a copy of its file is a second definition of the same type, which `doctor` points out where the two foundations' names give one scope (`type-defined-twice`). Registering, which only a site with a backend does, names such a type and sends no definition of it. A push also needs one of the site's foundations to declare the type, as a section type's data key or a schema of its own: the backend refuses a query whose type none of them declares, since nothing there would render it. A site can hold another site's records of a type too: `paths: { 'records/acme/member': '../../hub/site/records/acme/member' }` in its `site.yml` reads them as its own, a push adds them by reference rather than as copies once their own site has pushed them, and a pull leaves those files alone. A site's records of it sit in `records/acme/member/`; in `records/member/` they'd be the foundation's own `@/member`.
|
|
140
140
|
|
|
141
141
|
```jsx
|
|
142
142
|
function Article({ content, block }) { // data: { article: { schema: '@std/article', single: true } }
|
|
@@ -166,7 +166,7 @@ posts:
|
|
|
166
166
|
url: https://api.example.com/posts/{id}
|
|
167
167
|
```
|
|
168
168
|
|
|
169
|
-
Also `method: POST` + `body`, `where`/`sort`/`limit` (over what arrived, after `transform`), `queryable`. Its records have no `$name`, so a `[slug]` page over it binds the URL field in the query's own `where` (`where: { slug: :slug }`). `record:` takes `url`, `method`, `body`, `transform` (`url`/`method` default to the query's; a placeholder named by the
|
|
169
|
+
Also `method: POST` + `body`, `where`/`sort`/`limit` (over what arrived, after `transform`), `queryable`. Its records have no `$name`, so a `[slug]` page over it binds the URL field in the query's own `where` (`where: { slug: :slug }`). `record:` takes `url`, `method`, `body`, `transform` (`url`/`method` default to the query's; a placeholder named by the directory — `{id}` for `[id]` — is the segment). `schema`, `scope`, `deferred`, `excerpt`, `path` are refused beside `url:`. The visitor's browser fetches it (a `fetch:` with `prerender: true` makes the build fetch instead); it compiles no `/data` file. A site's own schema records are another matter: on a published site they need `services.records: true`.
|
|
170
170
|
|
|
171
171
|
A backend needing a key, headers, paging or its own wire language is a **transport** — a named `{ resolve, cacheKey? }` exported by the foundation (or an extension), selected by the site per data key:
|
|
172
172
|
|
|
@@ -4,9 +4,9 @@ Lane guide — AGENTS.md procedure step 6 loads it before any foundation code is
|
|
|
4
4
|
|
|
5
5
|
## Discovery and entry
|
|
6
6
|
|
|
7
|
-
PascalCase files and
|
|
7
|
+
PascalCase files and directories at the root of `sections/` are auto-discovered; nested levels need a `meta.js`; lowercase directories are organizational; `hidden: true` excludes a component entirely. Discovery accepts a `.js` component only without JSX — JSX compiles in `.jsx`/`.tsx` only, and the build stops on a `.js` file holding it.
|
|
8
8
|
|
|
9
|
-
**Source root.** The `src/`
|
|
9
|
+
**Source root.** The `src/` directory *is* the foundation; the build reads `package.json::main` (`./_entry.generated.js` for new scaffolds). Older foundations nest source in `foundation/src/` with `main` pointing at `./src/_entry.generated.js`; both work.
|
|
10
10
|
|
|
11
11
|
**`main.js`.** One `export default { … }`: identity (`name`, `description`) and capabilities (`defaultLayout`, `defaultSection`, `viewTransitions`, `defaultInsets`, `xref`, `outputs`, `handlers`, `data`), plus an optional named `vars` export. Section types and layouts are merged in by `@uniweb/build`; you never write that wrapper. The build carries into `dist/entry.js` only what a published page reads — code it calls and lean data (`defaultLayout`, each var's `default`/`type`/`applyTo`, each `data:` key's schema ref); `name`, `description`, labels stay out and reach the editor via the schema. The file is plain JavaScript: a component it declares lives in a `.jsx` it imports. When you import your **own** `main.js` from a component (e.g. `compileDocument(website, { foundation })`), you get the bare default object — pass it through.
|
|
12
12
|
|
|
@@ -67,7 +67,7 @@ Skip it and prose is unstyled (lists lose bullets) while the markup looks right;
|
|
|
67
67
|
|
|
68
68
|
Things you won't discover from exports:
|
|
69
69
|
|
|
70
|
-
- **`<Link>` takes `to` or `href`.** `to="page:about"` resolves a page id (survives moves) or a route, never a
|
|
70
|
+
- **`<Link>` takes `to` or `href`.** `to="page:about"` resolves a page id (survives moves) or a route, never a directory's name: the homepage is `page:/`, or `page:home` only when its `page.yml` says `id: home`. External URLs get `target="_blank"`; `reload` forces a full load.
|
|
71
71
|
- **A link back to a list is `<Link to="/store" back>`.** A link opens its page at the top, even the page the visitor just left, since the runtime restores a page's scroll only on back and forward. `back` steps back when the page before was that page (steps within this page don't count), so the list returns where they left it, and is an ordinary link otherwise. `useGoBack('/store')` does the same for a button. Keep the list's filter in `usePageState`, which stays with the page, so the view comes back too.
|
|
72
72
|
- **A modal needs `<Overlay>`, not a bigger z-index.** Each layout area's wrapper has its own layer, which makes it a stacking context; a `fixed` dialog inside one paints at its area's place in the stack, under the header/footer. `<Overlay onClose={close}>` renders into `document.body`, contains focus (moves it in, cycles Tab, marks the rest `inert`, returns it), handles Escape, scrim click, scroll lock; a dimmed scrim you override with `className` (`bg-transparent` removes it). `modal={false}` for a toast. Your dialog markup stays yours.
|
|
73
73
|
- **A reader can open a picture larger.** `components={{ image: EnlargeableImage }}` does it for an image in a page's body, and `Mermaid` does it on its own (`enlarge={false}` turns it off). `<Enlargeable>` goes around a picture a section draws itself. It's offered only when opening shows the picture noticeably larger, and the prerendered page doesn't change.
|
|
@@ -163,7 +163,7 @@ export default function Pricing({ content, params }) {
|
|
|
163
163
|
|
|
164
164
|
### Code several foundations share
|
|
165
165
|
|
|
166
|
-
Code that more than one foundation of a workspace uses lives in a workspace package, not in copies: components are imported as from any package, and Vite bundles them into each foundation. Give the package a stylesheet that reads its own
|
|
166
|
+
Code that more than one foundation of a workspace uses lives in a workspace package, not in copies: components are imported as from any package, and Vite bundles them into each foundation. Give the package a stylesheet that reads its own directory, as kit's does — `@source "./**/*.{js,jsx}";` in its `styles.css` — and import it in each foundation's `styles.css` (`@import "@acme/ui/styles.css";`), so Tailwind finds its classes wherever it is installed. A section type the package holds is still each foundation's to offer: a directory in the foundation's `sections/` whose `index.jsx` is `export { default } from '@acme/ui/sections/Banner/index.jsx'`, and whose `meta.js` re-exports the package's the same way. A fix in the package reaches every foundation at its next build and release.
|
|
167
167
|
|
|
168
168
|
### The Front Desk pattern
|
|
169
169
|
|
|
@@ -303,9 +303,9 @@ export default function DocsLayout({ header, body, footer, left, right, params }
|
|
|
303
303
|
|
|
304
304
|
Layouts are auto-discovered in `layouts/`. Set `defaultLayout` in `main.js` or name one `Default`; with neither, a page gets the built-in layout: header, page, footer and nothing else, so `layout/left.md` isn't drawn. A `defaultLayout` naming no layout stops the build. Layouts have their own `params` in `meta.js` (header height, sidebar width).
|
|
305
305
|
|
|
306
|
-
**Layout `meta.js`:** `{ areas: ['header', 'footer', 'left'], scroll: 'self' }`. Area names are arbitrary; a page renders the areas its site's `layout/`
|
|
306
|
+
**Layout `meta.js`:** `{ areas: ['header', 'footer', 'left'], scroll: 'self' }`. Area names are arbitrary; a page renders the areas its site's `layout/` directory fills. `scroll`: unset = runtime manages `window`; `'self'` = the layout scrolls itself; a selector (`'main'`) = runtime manages that element. `transitions` names an area for a move of its own (`{ left: 'sidebar' }`). With no names the page crossfades, and chrome that stays in place stays steady, so name one only to morph it: the name moves its box from where it was on screen to where it lands, so anything `fixed` in a box that scrolls drops through the page. Naming the body (`{ body: 'main' }`) freezes Safari on long pages. `layers` sets which area paints on top (`{ header: 2, left: 1 }`); every area is above the body by default, and a sticky area above non-sticky ones. A `z-index` inside an area cannot lift it past another — use `layers`, or `<Overlay>` to escape entirely.
|
|
307
307
|
|
|
308
|
-
**Layout content** lives in `site/layout/`: `header.md`, `footer.md` for the default layout, or a named subdirectory (`site/layout/marketing/`) for named layouts — self-contained, no inheritance; the name matches regardless of case and a trailing `Layout` (`layout/docs/` serves `DocsLayout`). An area with several sections is a
|
|
308
|
+
**Layout content** lives in `site/layout/`: `header.md`, `footer.md` for the default layout, or a named subdirectory (`site/layout/marketing/`) for named layouts — self-contained, no inheritance; the name matches regardless of case and a trailing `Layout` (`layout/docs/` serves `DocsLayout`). An area with several sections is a directory inside a layout's directory (`layout/default/header/1-topbar.md`); areas have no `page.yml` and render in filename order. Cascade: `page.yml → folder.yml → site.yml → defaultLayout → "default"`.
|
|
309
309
|
|
|
310
310
|
Layout sections are regular section types; each content category takes a role:
|
|
311
311
|
|
package/partials/guides/i18n.md
CHANGED
|
@@ -45,13 +45,13 @@ locales/freeform/es/records/article/x.md
|
|
|
45
45
|
|
|
46
46
|
**Data blocks** translate by the shape their key declares in `meta.js data:` — text fields, never an enum, URL or `translatable: false` field. A key declared `{}` falls to a heuristic that may offer structural strings (`style: display-black`) — declare the shape of every block a translator will see.
|
|
47
47
|
|
|
48
|
-
**Images** translate by alt text. Words alone give the alt text in that language; a translation that is an image also names the file: `"2d093636": ""` — a `/` path in `public/` (a `./` path has no page
|
|
48
|
+
**Images** translate by alt text. Words alone give the alt text in that language; a translation that is an image also names the file: `"2d093636": ""` — a `/` path in `public/` (a `./` path has no page directory to start from). Captions and a video's `poster` work the same way. Give every image alt text.
|
|
49
49
|
|
|
50
50
|
**Records** translate in the same `extract` run into `locales/records/manifest.json`, keyed by the record. A record whose query has a data schema translates exactly the fields the schema says are text; mark a code-like string `translatable: false`. Excerpts re-derive per language.
|
|
51
51
|
|
|
52
52
|
**A data schema's own labels** are not in `locales/`: write them in `source_locale`, other languages in the schema's `i18n` keyed by path (`i18n: { fr: { model.label: Séance, section.brief.field.title.label: Titre } }`). See `development/data-schemas.md`.
|
|
53
53
|
|
|
54
|
-
**Localized URLs:** `slug: { fr: a-propos }` in `page.yml` — the
|
|
54
|
+
**Localized URLs:** `slug: { fr: a-propos }` in `page.yml` — the directory name stays canonical; nested directories compose; flows through navigation, switcher and sitemap. Each language gets its own `/fr/llms.txt` and `/fr/search-index.json`.
|
|
55
55
|
|
|
56
56
|
## Component side
|
|
57
57
|
|
|
@@ -108,10 +108,10 @@ The endpoint must accept the framework's batched `{ "events": [ … ] }` POST (`
|
|
|
108
108
|
|
|
109
109
|
### Google Analytics, Tag Manager, Meta's pixel
|
|
110
110
|
|
|
111
|
-
**A `scripts` entry is a URL and nothing else, so these can't be installed that way.** Each one's install runs inline lines; from a URL alone GA sends nothing and Tag Manager never gets its page-load event. A tag carrying an attribute the vendor reads (`data-domain`, `data-website-id`) has the same problem. What works depends on who
|
|
111
|
+
**A `scripts` entry is a URL and nothing else, so these can't be installed that way.** Each one's install runs inline lines; from a URL alone GA sends nothing and Tag Manager never gets its page-load event. A tag carrying an attribute the vendor reads (`data-domain`, `data-website-id`) has the same problem. What works depends on who makes the pages:
|
|
112
112
|
|
|
113
|
-
- **
|
|
114
|
-
- **Uniweb Cloud
|
|
113
|
+
- **A build makes them** (`uniweb export`, `uniweb deploy --host=<adapter>`): the vendor's snippet goes in `head.html` next to `site.yml`, and the build adds it to every page's `<head>`. A `services.google` entry does nothing here.
|
|
114
|
+
- **Uniweb Cloud serves them, with no build** (`uniweb publish`, or publishing from the app): `head.html` is kept and synced but **not applied**. For Google's two, name the ID and the host loads the tag from the next publish, free, with no code, on any foundation:
|
|
115
115
|
|
|
116
116
|
```yaml
|
|
117
117
|
services:
|
package/partials/guides/ship.md
CHANGED
|
@@ -36,7 +36,7 @@ No lock-in and no default you're pushed toward:
|
|
|
36
36
|
| Any static host | `uniweb export` | full control; no account |
|
|
37
37
|
| Uniweb Cloud | `uniweb publish` | non-technical content authors, client work |
|
|
38
38
|
|
|
39
|
-
Adapters: `github-pages`, `cloudflare-pages`, `netlify`, `vercel`, plus `s3-cloudfront` for `deploy`. On Cloudflare Pages / Netlify / Vercel, `add ci` also adds per-PR previews. With nothing configured, `deploy` opens a picker and records the choice in `deploy.yml` beside `site.yml` — **the CLI writes it**; later deploys rewrite only `deploys:`; edit `targets:` to change where a site ships. A bare `deploy` goes to the default target, and when that's the `host: uniweb` target a publish recorded, it runs `publish`. Host credentials come from the environment. GitHub runs workflows only from the top of a repository: in a project that is a
|
|
39
|
+
Adapters: `github-pages`, `cloudflare-pages`, `netlify`, `vercel`, plus `s3-cloudfront` for `deploy`. On Cloudflare Pages / Netlify / Vercel, `add ci` also adds per-PR previews. With nothing configured, `deploy` opens a picker and records the choice in `deploy.yml` beside `site.yml` — **the CLI writes it**; later deploys rewrite only `deploys:`; edit `targets:` to change where a site ships. A bare `deploy` goes to the default target, and when that's the `host: uniweb` target a publish recorded, it runs `publish`. Host credentials come from the environment. GitHub runs workflows only from the top of a repository: in a project that is a directory of a larger repo, its own `.github/` never runs — `status` says so and `add ci` refuses to write one there.
|
|
40
40
|
|
|
41
41
|
**Three independent facts** `status` opens with:
|
|
42
42
|
|
|
@@ -54,7 +54,7 @@ A site can be in more than one place. `publish` makes a change live on Cloud, `g
|
|
|
54
54
|
|
|
55
55
|
**Sync is developer-only and one-sided.** The app is the live source of truth for content; git is the reviewed, durable record. Authors never push or pull.
|
|
56
56
|
|
|
57
|
-
**Nobody's work is overwritten without asking.** `push` is refused if the site changed on the backend since your last pull, and reports what changed. In a git repository `pull` merges like `git pull`: it commits the backend's content (*"The site's content on …"*) and merges into your branch against the last shared state. Your work and a teammate's are kept; a file the backend never had is never deleted; only a genuine overlap leaves conflict markers and a non-zero exit — settle it as in any merge, then `git commit` (where your uncommitted changes overlap, settle, `git add`, then `git stash drop`). A push or publish is refused while a file is in conflict. **In a repository a push sends what you have committed**: uncommitted site content is refused before anything is sent — commit, or `uniweb push --commit -m "…"` (commits the site's content only; `publish` and `sync` take `--commit` too). The ids the backend assigns are committed by the push itself, as `uniweb`. A push is also refused when your branch doesn't hold what this copy last took from the backend (after `git merge --abort`, or a fresh clone) — pull, then push. Outside git (including a
|
|
57
|
+
**Nobody's work is overwritten without asking.** `push` is refused if the site changed on the backend since your last pull, and reports what changed. In a git repository `pull` merges like `git pull`: it commits the backend's content (*"The site's content on …"*) and merges into your branch against the last shared state. Your work and a teammate's are kept; a file the backend never had is never deleted; only a genuine overlap leaves conflict markers and a non-zero exit — settle it as in any merge, then `git commit` (where your uncommitted changes overlap, settle, `git add`, then `git stash drop`). A push or publish is refused while a file is in conflict. **In a repository a push sends what you have committed**: uncommitted site content is refused before anything is sent — commit, or `uniweb push --commit -m "…"` (commits the site's content only; `publish` and `sync` take `--commit` too). The ids the backend assigns are committed by the push itself, as `uniweb`. A push is also refused when your branch doesn't hold what this copy last took from the backend (after `git merge --abort`, or a fresh clone) — pull, then push. Outside git (including a directory the surrounding repo ignores), `pull` takes the backend's version over your files, asking first. `--force` is the deliberate overwrite in either direction. `sync` is `refresh` then `push`; neither publishes.
|
|
58
58
|
|
|
59
59
|
**Working on a site others edit:** `status` when you begin, when you come back, before push/publish/deploy, after any refusal. It reads the backend without taking anything: what changed file by file, what you hold that it lacks, who has a page open in the app right now, what in the project is uncommitted (an update, foundation source — a push neither sends nor waits for that, but a push or publish releases a changed foundation from the files). Take what changed (`pull` or `refresh`) before you edit; when someone has a page open in the app, tell the person before changing that page.
|
|
60
60
|
|
|
@@ -68,7 +68,7 @@ A site can be in more than one place. `publish` makes a change live on Cloud, `g
|
|
|
68
68
|
|
|
69
69
|
## Publishing vs registering
|
|
70
70
|
|
|
71
|
-
Foundations on Cloud live in the catalog as `@org/name@version` (`name` from `main.js`). When a foundation powers one site, **don't run `uniweb register` yourself** — `uniweb publish` from the site releases the local foundation (when its code changed) and goes live in one step. A registered version is immutable, so a changed foundation is released under the next **patch** version, written into its `package.json` and committed by the push in a git repository (`--no-release` sends content only). For a change that isn't backwards compatible, set a higher minor/major yourself first. They stop when the registry holds a newer version released from another copy: pull it, or `--bump` to release above it. Register deliberately only when the foundation is a product for multiple sites; consuming sites pin `foundation: '@org/name@1.2.3'`. **The catalog is private and access-segregated** — people see only foundations licensed to sites they own or edit; the site carries the license. Schemas can be registered on their own from a schemas-only package (`@org/schemas`, or a bare `schemas/*.{yml,json,js}`
|
|
71
|
+
Foundations on Cloud live in the catalog as `@org/name@version` (`name` from `main.js`). When a foundation powers one site, **don't run `uniweb register` yourself** — `uniweb publish` from the site releases the local foundation (when its code changed) and goes live in one step. A registered version is immutable, so a changed foundation is released under the next **patch** version, written into its `package.json` and committed by the push in a git repository (`--no-release` sends content only). For a change that isn't backwards compatible, set a higher minor/major yourself first. They stop when the registry holds a newer version released from another copy: pull it, or `--bump` to release above it. Register deliberately only when the foundation is a product for multiple sites; consuming sites pin `foundation: '@org/name@1.2.3'`. **The catalog is private and access-segregated** — people see only foundations licensed to sites they own or edit; the site carries the license. Schemas can be registered on their own from a schemas-only package (`@org/schemas`, or a bare `schemas/*.{yml,json,js}` directory). Auth via `uniweb login` or `UNIWEB_TOKEN`; preview with `--dry-run`.
|
|
72
72
|
|
|
73
73
|
**Extensions.** An extension is a foundation: register it (`uniweb register` in its directory) and reference it like one. A site-relative URL (`/effects/entry.js`) works only where the site serves its own files (`export`, `deploy --host`); a site published to Uniweb hosting ships no JS, so `publish` rejects it and points to the catalog-ref form. A workspace-local extension is brought along by `publish` exactly as the primary is — released if its code changed, pinned on the published site.
|
|
74
74
|
|
|
@@ -105,12 +105,12 @@ When `status` names a newer release, take it: update, restart any running dev se
|
|
|
105
105
|
| top-level `search:`, `submit:`, `assistant:`, `tracking:`, `api:`; `services.api`; `$devApi` | `services.<name>`; `services.backend`; `$devBackend` |
|
|
106
106
|
| `published: false` on a record | `draft: true` |
|
|
107
107
|
| `slug:` key in a record file; a file holding a list | the file name is the record's name; one record per file |
|
|
108
|
-
| `[dir]` / `[path]` as parametric
|
|
108
|
+
| `[dir]` / `[path]` as parametric directory names; a directory inside `[...path]/` | `[slug]`, `[uuid]`, `[<field>]`, `[...path]` |
|
|
109
109
|
| `fonts.mono` | `fonts.code` |
|
|
110
110
|
| `seo.baseUrl`; `seo.defaultImage`; `seo.locales`; `url:`, `trailingSlash:` in `site.yml` | `seo.origin` (scheme + host, no path); `seo.image`; `languages:`; `seo.origin` again |
|
|
111
111
|
| `creatable_by` in a schema | who adds a type's entries is `blueprint.yml`'s `access.<type>.add`; a schema protects them with `append_only`, `readable_with`, `grantable` |
|
|
112
112
|
| `uniweb.id`, `uniweb.scope` in a foundation's `package.json` | `name: '@scope/name'` in `main.js` |
|
|
113
113
|
| `main.jsx`, `foundation.js`; JSX in a `.js` component | `main.js` (plain JS); `.jsx` |
|
|
114
114
|
| `visuals:` in `meta.js`; `data` as a `content:` element | a `media:` element in `content:`; declare the tag in `data:` |
|
|
115
|
-
| `versions:` in a folder | a
|
|
115
|
+
| `versions:` in a `folder.yml` or `page.yml` | a directory named `v1` (`uniweb add version`) |
|
|
116
116
|
| `runtimePolicy: auto-patch / auto-minor` | omit; the framework doesn't read it |
|
package/partials/guides/start.md
CHANGED
|
@@ -45,7 +45,7 @@ uniweb add section Hero [--foundation ui] # sections/Hero/{index.jsx,me
|
|
|
45
45
|
uniweb rename <foundation|site|extension> <old> <new> # rename across the whole workspace
|
|
46
46
|
```
|
|
47
47
|
|
|
48
|
-
The CLI creates exactly the
|
|
48
|
+
The CLI creates exactly the directory you ask for — no silent nesting under `foundations/` or `sites/`. If the target directory exists or another package of the same kind has the name, it stops with a precise error and suggests alternatives; a name held by the other kind gets a suffix (`add site marketing` beside a foundation named `marketing` makes `marketing-site`). `uniweb add section` scaffolds a starter the dev server picks up with no build or install.
|
|
49
49
|
|
|
50
50
|
Workspace layouts and their wiring (single, segregated, co-located, projects with several sites): `development/project-structures.md`. The same `@scope/name` shape means different things by position: a `foundation:` value is a catalog ref; a data-schema ref in `meta.js` resolves from an npm package (`@uniweb/schemas`, `@org/schemas`); `@uniweb/kit` in `dependencies` is an ordinary npm package.
|
|
51
51
|
|
package/partials/guides/theme.md
CHANGED
|
@@ -108,7 +108,7 @@ The build adds preconnect hints, emits `@font-face` + preload, drops unreference
|
|
|
108
108
|
|
|
109
109
|
Two more imports are opt-in: `@uniweb/kit/math-tokens.css` lays out equations, and `@uniweb/kit/callout-tokens.css` draws concept blocks such as `md:warning`, which are otherwise plain prose.
|
|
110
110
|
|
|
111
|
-
**Tailwind reads the whole foundation.** `source("./")` on the import has it read every file under the foundation, in the foundation's own build and in a site's, so a class in any
|
|
111
|
+
**Tailwind reads the whole foundation.** `source("./")` on the import has it read every file under the foundation, in the foundation's own build and in a site's, so a class in any directory reaches both — one kept in a string for code elsewhere to write too, such as a map of colours to classes in `utils/`. A stylesheet that names directories instead (`@source "./sections/**/*.{js,jsx}"`, as older projects do) must name every directory that writes classes: the foundation's own build finds them all, but a site build and `uniweb dev` read only what those lines name, so a class in a directory left out is in one CSS and missing from the other. `uniweb dev`, a site build and `uniweb doctor` (`unread-folder`) name such a directory, and give the `source("./")` line that ends it. `theme-tokens.css` also tells Tailwind to read kit's source, so kit's own classes reach your CSS wherever your package manager put kit; a foundation that skips that import names kit itself, by where kit is (`./node_modules/@uniweb/kit/src/**` under pnpm, `../node_modules/@uniweb/kit/src/**` under npm).
|
|
112
112
|
|
|
113
113
|
Custom CSS is expected alongside Tailwind — shadow systems, border hierarchies, gradients, glass. Tokens are a floor; add vocabulary that references them so it adapts per context:
|
|
114
114
|
|
package/src/framework-index.json
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
|
-
"generatedAt": "2026-11-
|
|
3
|
+
"generatedAt": "2026-11-10T03:51:29.247Z",
|
|
4
4
|
"packages": {
|
|
5
5
|
"@uniweb/api": {
|
|
6
6
|
"version": "1.7.0"
|
|
7
7
|
},
|
|
8
8
|
"@uniweb/build": {
|
|
9
|
-
"version": "1.20.
|
|
9
|
+
"version": "1.20.5"
|
|
10
10
|
},
|
|
11
11
|
"@uniweb/content-reader": {
|
|
12
12
|
"version": "1.5.9"
|
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
"version": "1.3.1"
|
|
16
16
|
},
|
|
17
17
|
"@uniweb/core": {
|
|
18
|
-
"version": "1.6.
|
|
18
|
+
"version": "1.6.11"
|
|
19
19
|
},
|
|
20
20
|
"@uniweb/frame-bridge": {
|
|
21
21
|
"version": "1.0.3"
|
|
@@ -33,16 +33,16 @@
|
|
|
33
33
|
"version": "1.2.2"
|
|
34
34
|
},
|
|
35
35
|
"@uniweb/projections": {
|
|
36
|
-
"version": "1.2.
|
|
36
|
+
"version": "1.2.15"
|
|
37
37
|
},
|
|
38
38
|
"@uniweb/runtime": {
|
|
39
|
-
"version": "1.5.
|
|
39
|
+
"version": "1.5.6"
|
|
40
40
|
},
|
|
41
41
|
"@uniweb/scene": {
|
|
42
42
|
"version": "1.0.1"
|
|
43
43
|
},
|
|
44
44
|
"@uniweb/schemas": {
|
|
45
|
-
"version": "1.7.
|
|
45
|
+
"version": "1.7.1"
|
|
46
46
|
},
|
|
47
47
|
"@uniweb/scholar": {
|
|
48
48
|
"version": "1.1.0"
|