# @aweftjs/ssg
Pages from a routed site, at build time and at run time. It renders every page a site declares,
writes each one as a file a static host can serve with no configuration, once per language when
the site has more than one, and hands the browser one function that takes the page over in place.
It decides nothing else: not where page data comes from, not which host serves the files, not what
that host does with a URL it has no file for, and not whether a page it could not enumerate should
fail your build.
## Quickstart
```ts
import { readFileSync } from 'node:fs';
import { createSite } from '@aweftjs/ssg';
import { h } from '@aweftjs/ui';
import { Site } from './site.tsx';
const site = createSite({
page: (router) => h(Site, { router }),
shell: readFileSync('dist/index.html', 'utf8'),
out: 'dist',
base: 'https://example.com',
});
const written = await site.write();
console.log(written.files); // every page, 404.html, shell.html, sitemap.xml
console.log(written.unenumerated); // the acts nothing could list
```
Four things go in. **`page`** builds the whole page from a router, and it is the same function your
browser entry mounts, which is what makes the markup here the markup the client renders. **`shell`**
is the `index.html` your bundler built, as text. **`out`** is the directory. **`base`** is the
site's absolute URL, needed for the sitemap and the language alternates. Two more for a site in
more than one language, below.
The browser half is one import:
```tsx
import { createRouter } from '@aweftjs/dom/router';
import { attach } from '@aweftjs/ssg/client';
const router = createRouter();
attach(document.body, );
router.links(document.body);
```
`attach` hydrates a page this package wrote and mounts anything else, so the development server and
the generated site share one entry file. It imports `mount` and `hydrate` from `@aweftjs/ui` and
nothing else, so a page bundle carries none of the rest of this package. `languageOf(document)`,
beside it, reads the language back off a page for the entry of a site in several languages.
## A site in several languages
```ts
const site = createSite({
page: (router) => h(Site, { router }),
shell, out, base: 'https://example.com',
locale: 'en',
locales: { fr: JSON.parse(readFileSync('text/fr.json', 'utf8')), uk: JSON.parse(readFileSync('text/uk.json', 'utf8')) },
});
```
**`locale`** is the language the pages are written in, a BCP 47 tag. **`locales`** is every other
language, each tag to its catalog, the plain object `@aweftjs/ui`'s text tokens look up (its README,
The text a page shows). With `locales` and no `locale` the site is refused (`locale-needed`),
because the layout below needs to know which language stands unprefixed.
**The layout.** The source language is written where the site was written before,
`/index.html`; every other language under its tag, `/fr//index.html`, with `/fr/404.html`
and `/fr/shell.html` beside it. A site that adds a language keeps every URL it had, and a host
serves every language with the same two rules it served one with. `write()` renders each URL the
walk found once per language, with the language's catalog on the render and a router whose `base`
is the language's prefix, so a link the page writes with `router.base` in front stays in its
language. `page('/fr/about')` is `about` in French: the URL carries the language. `write(urls)`
with a list writes a prefixed URL in that language and an unprefixed one in every language.
**The document.** `` gains `lang` with the page's tag, replacing one the shell wrote, and
`dir="rtl"` for a script that runs right to left, which `Intl.Locale` says and nothing here lists.
With a `base`, every page's head gains a `` per language and an
`x-default` naming the source language's URL, and the sitemap lists every language's URL with the
same alternates as `xhtml:link`. A site with `locale` alone writes `lang` and nothing else changes.
**The report.** The write result gains `text`: per language, `missing`, the keys the pages looked
up that its catalog has no entry for (those show the source), and `unused`, the entries no page
looked up. It reads what the renders resolved, so it says what the site would show; the build's own
report ([`packages/build/README.md`](/docs/packages/build)) reads the files, and the two differ on a page compiled at run
time. It fails nothing. An application that wants a build to stop on a missing translation reads it
and stops.
**The entry.** `languageOf(document)` answers `{ locale, base }`: the tag on ``, and
`/` when the address is under that prefix, `''` for the source language and for a site with
one language alike. A page with no `lang` answers `''` for both, which finds no catalog and which
`context()` reads as no language, so the entry below is the entry of a site with one language too.
```tsx
const catalogs = { fr: () => import('./text/fr.json'), uk: () => import('./text/uk.json') };
const { locale, base } = languageOf(document);
const catalog = (await catalogs[locale]?.())?.default;
attach(document.body, , context({ locale, catalog }));
```
The catalog is the application's own import, one request before `attach`, and a hydration waits
for it. How the visitor's language is chosen is not here: the pages are files, one per language,
and a host or a first page sends the reader to the right tree.
## The three things a site does
### `site.walk()`
Renders `/`, reads the stage list `ui`'s `render` holds, and turns every act the site declares into
a URL. It renders each URL it has not rendered yet and stops when a render adds none, which is what
finds the pages under a nested stage: a stage inside an act does not exist until that act has been
rendered once.
```ts
const { urls, unenumerated } = await site.walk();
```
The rules, per act:
| the act key | what the walk does |
|---|---|
| plain, no `entries` | one URL |
| plain, with `entries()` | one URL, unless `entries()` answers `[]` |
| has `:name` or `*rest`, with `entries()` | one URL per answered object |
| has `:name` or `*rest`, no `entries` | none. The act is reported in `unenumerated` |
An act's URL sits under its stage's prefix, and the prefix is what that stage's parent actually
matched: an act declared `:page` inside a stage that matched `posts/3` is `/posts/3/:page`.
**Every declared act is a page.** Nothing tells an act you route to from an act you only ever reach
with `stage.open`, so a dialog declared in `acts` is written out as a page of its own. Say so in its
head if you do not want it found:
```tsx
The dialog
```
**A URL the site has no page for is refused.** `page(url)` and `write(urls)` throw `not-a-page`
when a URL leaves a stage showing its fallback or showing nothing, because that page is the site's
`404.html` and writing it at another path publishes a "not found" page on a URL the site claims to
have. The limit is what routing can see: an act declared `posts/:id` matches any id, so a slug that
names no row is a page as far as this is concerned, and only your act knows better.
**An act with a parameter and no `entries()` is reported, not refused.** A site with a page per
database row is normal and a build tool that stops because it cannot see the database is not. Those
URLs are answered by `shell.html`, which mounts live. An application that wants the build to fail
reads `unenumerated` and fails on it.
### `site.page(url)`
One finished document, for a caller that serves or stores a page rather than writing it.
```ts
const { html, title, noindex } = await site.page('/posts/hello');
```
`noindex` is read off the page's head list, not out of the HTML, so a `robots` tag that lost its
group and was never emitted does not count.
A URL with a query or a hash on it is the page without them: `/docs?page=2#top`, `/docs/` and
`/docs` are one page and one file.
**A page whose `pending` never settles never finishes.** A render waits for everything a component
declared `pending` and there is no timeout anywhere in this package, so a fetch that hangs hangs the
build. The wait, and the timeout on it, are the application's.
### `site.write(urls?)`
With no list it walks the site and writes everything:
| file | what it is |
|---|---|
| `index.html`, `/index.html` | one per page. Every static host serves this layout with no configuration |
| `404.html` | the site rendered at `/_aweft-404`, a URL a site is not expected to declare, so what it shows is your fallback act. A site that declares a root `*rest` act matches that URL too, so `404.html` is that act's page instead, and the walk reports the `*rest` act as unenumerated |
| `shell.html` | the shell as it stands, with no stamp, so `attach` mounts it live |
| `sitemap.xml` | every indexable page, when the site has a `base`. With none there is no sitemap and the result says `sitemap: null` |
With a list it writes those pages and touches nothing else: no walk, no 404, no shell, no sitemap.
That is the call a running application makes when it publishes one thing, and it is why a scheduled
full write is how the sitemap stays current.
```ts
await site.write([`/posts/${id}`]); // inside a request
await site.write(); // nightly, or at build time
```
## The document
The shell is read as text, not parsed, and four things happen to it:
- the theme's `