# Public web, SEO and cache
Public rendering is opt-in. A headless Worker serves Views and Triggers only; this page shows how to add server-rendered pages, their agent-readable mirrors and discovery files, and what the cache contract guarantees.
## Three inputs that must agree
1. `mountPublicRoutes(app, ref, { collectionRoutes, ... })` inside `extend.mount` declares which collections have URLs.
2. A `TemplateRegistry` with an entry template (and optionally a list template) for each of those collections, passed as `templates`.
3. A `PublicPathResolver` from `createPublicPathResolver({ collectionRoutes })`, passed as `publicPathResolver`, so canonical URLs, sitemap entries and hreflang siblings match the mounted routes.
Mounting every Schema automatically is not supported: some collections are private even when they carry a slug. Without a `publicPathResolver`, `/sitemap.xml` returns `500`.
## Worked example: a blog
```ts
// src/web/templates.ts
import { createPublicPathResolver, TemplateRegistry, renderSeoTagsHtml } from "@aotter/mantle-web";
export const publicPathResolver = createPublicPathResolver({
collectionRoutes: { posts: { segment: "posts" } },
});
export const collectionRoutes = [
{ collection: "posts", segment: "posts", listRoute: true },
] as const;
export function createBlogTemplates(): TemplateRegistry {
const templates = new TemplateRegistry();
templates.registerEntryTemplate("posts", ({ entry, site, seo }) => {
const title = String(entry.data.title ?? site.title);
const meta = seo && {
...seo,
jsonLd: { "@context": "https://schema.org", "@type": "BlogPosting", headline: title, url: seo.canonical },
};
return `${escape(title)}
${meta ? renderSeoTagsHtml(meta) : ""}
`;
});
return templates;
}
```
```ts
// worker entry
export default createMantleWorker({
plan,
templates: createBlogTemplates(),
publicPathResolver,
siteDefaults: (env) => ({ /* ... */ origin: env.PUBLIC_ORIGIN, locales: ["en", "zh-TW"] }),
extend: ({ env }) => ({
mount({ app, ref }) {
mountPublicRoutes(app as never, ref, {
collectionRoutes: [...collectionRoutes],
notFoundRenderer: async () => htmlNotFound(),
liveDev: new URL(env.PUBLIC_ORIGIN).hostname === "localhost",
});
},
}),
});
```
Templates return complete HTML strings; the renderer prepends the doctype. Escape every value you interpolate.
## Template signatures
```ts
templates.registerEntryTemplate(collection, ({ entry, site, mediaAssets?, seo? }) => string);
templates.registerListTemplate(collection, ({ collection, locale, entries, site, mediaAssets?, seo? }) => string);
```
`seo` is a composed `SeoMeta`:
| Field | Content |
|---|---|
| `canonical` | Absolute canonical URL from `site.origin` and the resolved path |
| `alternateMarkdown` | Absolute `.md` mirror URL, or `null` when the entry has no Markdown body |
| `hreflangs` | One row per locale plus `x-default` on multi-locale sites |
| `description`, `og`, `twitter` | Description, Open Graph and Twitter card blocks |
| `jsonLd` | A default object; replace it before rendering, as the example does |
`renderSeoTagsHtml(seo)` emits the corresponding tags. Entry pages also get `` so crawlers and agents can fetch clean Markdown.
## Routes produced
| Route | Condition |
|---|---|
| `GET /` → `302` to `/` | `homeRenderer` set |
| `GET /:locale`, `GET /:locale.md` | `homeRenderer` set; body from `homeMarkdown` or the `homeSlug` entry |
| `GET /:locale/`, `GET /:locale/.md` | `listRoute: true` |
| `GET /:locale//:slug` | always |
| `GET /:locale//:slug.md` | `markdownMirror` not `false` (default on) |
| `GET /:locale//:slug?preview=1` | staff session; renders live, `private, no-store` |
| `GET /llms.txt`, `GET /:locale/llms.txt` | always |
| `GET /sitemap.xml` | always; a urlset, or a sitemap index linking `/sitemap.xml?part=1&cursor=...` parts |
| `GET /robots.txt` | always; `Allow: /` plus the sitemap URL |
`CollectionRouteConfig` fields: `collection`, `segment` (empty string mounts entries directly under `/:locale/`), `listRoute` (default `false`), `markdownMirror` (default `true`), `homeSlug` (collapse one slug to `/:locale`). `slugOverrides` serve one `(collection, slug)` pair from your own renderer and take precedence over preview and standard rendering. `notFoundRenderer` is required; every miss falls through it. `liveDev` switches entry and list responses to `private, no-store` for local work.
Only entries with `status: published` render. Drafts never appear on pages, mirrors, `llms.txt` or the sitemap; preview needs a staff session and answers `401` or `403` otherwise.
## Pagination
Lists and `llms.txt` return 50 entries per page, ordered `updatedAt DESC, id DESC`, with a forward `cursor`. A continuation adds `Link: <...?cursor=...>; rel="next"`; HTML lists also get a visible `