@lincyaw/web 0.0.0-stage → 1.0.0-rc.1

package/src/node/publish.ts

@@ -0,0 +1,169 @@
+import { createHash } from 'node:crypto'
+import { statSync } from 'node:fs'
+import { join } from 'node:path'
+import { irBlocks, mapHtmlUrls, NON_FILE_URL, publishedUrl, withPublishedAssets } from '@lincyaw/kernel'
+import type { DocumentLink, IRBlock, IRDocument, IRSection, LocalAsset, MdastNode, RenderContext, SourcePos } from '@lincyaw/kernel'
+import { copyPublished, fileVersion } from '@lincyaw/kernel/node'
+import katex from 'katex'
+
+export const MEDIA = 'media'
+
+/** The IR revision of an IR written as JSON. */
+export function irRevisionOfJson(json: string): string {
+  return createHash('sha256').update(json).digest('hex').slice(0, 16)
+}
+
+const LINKED = new Set(['image', 'link', 'definition', 'card'])
+
+interface Asset extends LocalAsset {
+  version: string
+}
+
+const assets = new Map<string, Asset>()
+
+function localAsset(ctx: RenderContext, source: SourcePos, url: string): Asset | undefined {
+  const key = `${source.file}\0${url}`
+  const known = assets.get(key)
+  const now = known && statSync(known.file, { bigint: true, throwIfNoEntry: false })
+  if (known && now && fileVersion(now) === known.version) return known
+  const found = ctx.localAsset(source, url)
+  const stat = found && statSync(found.file, { bigint: true, throwIfNoEntry: false })
+  if (!found || !stat) {
+    assets.delete(key)
+    return undefined
+  }
+  const asset = { ...found, version: fileVersion(stat), directory: found.directory ?? stat.isDirectory() }
+  if (asset.directory) assets.delete(key)
+  else assets.set(key, asset)
+  return asset
+}
+
+const rendered = new Map<string, string>()
+const PUBLICATION_CACHE_BYTES = 16 << 20
+
+function renderMath(tex: string, display: boolean): string {
+  const key = `${display ? 'D' : 'I'}${tex}`
+  let html = rendered.get(key)
+  if (html === undefined) {
+    html = katex.renderToString(tex, { displayMode: display, throwOnError: false })
+    rendered.set(key, html)
+  }
+  return html
+}
+
+export type DocumentPage = (link: DocumentLink) => string | undefined
+
+export class PublicationCache {
+  readonly #sections = new Map<string, { key: string, section: IRSection, bytes: number }>()
+  #bytes = 0
+
+  lookup(section: IRSection): { key: string, section?: IRSection } {
+    const key = JSON.stringify(section)
+    const known = this.#sections.get(section.id)
+    return { key, ...known?.key === key ? { section: known.section } : {} }
+  }
+
+  store(original: IRSection, key: string, section: IRSection): void {
+    const old = this.#sections.get(original.id)
+    if (old) this.#bytes -= old.bytes
+    this.#sections.delete(original.id)
+    // Local files and raw HTML can change independently of the IR. Revisit them.
+    const local = (node: MdastNode): boolean => node.type === 'html'
+      || (LINKED.has(node.type) && typeof node.url === 'string' && !NON_FILE_URL.test(node.url))
+      || Boolean(node.children?.some(local))
+    for (const block of irBlocks(original.blocks)) {
+      if (block.node.type === 'markdown' && local(block.node.mdast)) return
+      if (block.node.type === 'component' && (Object.keys(block.node.assets ?? {}).length || (block.node.fallback && local(block.node.fallback)))) return
+      if (block.stepStates?.some(state => Object.keys(state.assets ?? {}).length)) return
+    }
+    const bytes = (key.length + JSON.stringify(section).length) * 2
+    if (bytes > PUBLICATION_CACHE_BYTES) return
+    this.#sections.set(original.id, { key, section, bytes })
+    this.#bytes += bytes
+    while (this.#bytes > PUBLICATION_CACHE_BYTES || this.#sections.size > 2048) {
+      const first = this.#sections.keys().next().value!
+      this.#bytes -= this.#sections.get(first)!.bytes
+      this.#sections.delete(first)
+    }
+  }
+
+  prune(ids: Set<string>): void {
+    for (const [id, entry] of this.#sections) {
+      if (ids.has(id)) continue
+      this.#sections.delete(id)
+      this.#bytes -= entry.bytes
+    }
+  }
+}
+
+export function publishedDocument(doc: IRDocument, ctx: RenderContext, publicDir: string, base: string, documentPage?: DocumentPage, cache?: PublicationCache): IRDocument {
+  const { deckDir } = ctx
+  const copy: IRDocument = structuredClone(cache ? { ...doc, sections: [] } : doc)
+  const media = join(publicDir, MEDIA)
+  const relative = (pos: { file: string }) => {
+    pos.file = ctx.portable(pos.file, deckDir) as string
+  }
+  const publish = (url: string, source: SourcePos): string | undefined => {
+    const linked = documentPage && ctx.documentLink?.(source, url)
+    if (linked) return documentPage(linked)
+    const asset = localAsset(ctx, source, url)
+    if (!asset) return undefined
+    copyPublished(asset, media)
+    return publishedUrl(asset, url, { prefix: `${base}${MEDIA}/` })
+  }
+  const mdast = (node: MdastNode, source: SourcePos) => {
+    if (LINKED.has(node.type) && typeof node.url === 'string') node.url = publish(node.url, source) ?? node.url
+    if (node.type === 'html' && typeof node.value === 'string') node.value = mapHtmlUrls(node.value, url => publish(url, source))
+    if ((node.type === 'math' || node.type === 'inlineMath') && typeof node.value === 'string') node.html = renderMath(node.value, node.type === 'math')
+    node.children?.forEach(child => mdast(child, source))
+  }
+  const block = (b: IRBlock) => {
+    const { node, source } = b
+    if (node.type === 'markdown') mdast(node.mdast, source)
+    if (node.type === 'component') {
+      if (node.fallback) mdast(node.fallback, source)
+      for (const state of b.stepStates ?? []) {
+        if (!state.parameters) continue
+        // Plugins can declare state-only resources. Other components inherit
+        // their declared asset paths, resolved against the current parameters.
+        const assets = state.assets ?? Object.fromEntries(Object.entries(node.assets ?? {}).flatMap(([path, original]) => {
+          const at = (props: Record<string, unknown>) => path.split('.').reduce<unknown>((current, key) => current && typeof current === 'object' ? (current as Record<string, unknown>)[key] : undefined, props)
+          const value = at(state.parameters!)
+          return typeof value === 'string' ? [[path, value !== at(node.props) ? value : original]] : []
+        }))
+        state.parameters = withPublishedAssets({ ...node, props: state.parameters, assets }, url => publish(url, source)).props
+      }
+      node.props = withPublishedAssets(node, url => publish(url, source)).props
+    }
+  }
+  copy.meta.entry = ctx.portable(copy.meta.entry, deckDir) as string
+  copy.config.presmium = ctx.portable(copy.config.presmium, deckDir) as IRDocument['config']['presmium']
+  for (const original of cache ? doc.sections : copy.sections) {
+    const known = cache?.lookup(original)
+    if (known?.section) {
+      copy.sections.push(known.section)
+      continue
+    }
+    const section = cache ? structuredClone(original) : original
+    relative(section.source)
+    if (section.config) section.config = ctx.portable(section.config, deckDir) as typeof section.config
+    for (const b of irBlocks(section.blocks)) block(b)
+    for (const b of irBlocks(section.blocks)) relative(b.source)
+    if (cache) {
+      copy.sections.push(section)
+      cache.store(original, known!.key, section)
+    }
+  }
+  cache?.prune(new Set(doc.sections.map(section => section.id)))
+  for (const finding of copy.diagnostics) {
+    if (finding.source) relative(finding.source)
+  }
+  return copy
+}
+
+export function publishedFile(ctx: RenderContext, publicDir: string, base: string, source: SourcePos, url: string): string | undefined {
+  const asset = localAsset(ctx, source, url)
+  if (!asset || asset.directory) return undefined
+  copyPublished(asset, join(publicDir, MEDIA))
+  return publishedUrl(asset, url, { prefix: `${base}${MEDIA}/` })
+}

package/src/node/renderer.ts

@@ -0,0 +1,108 @@
+import { join, resolve } from 'node:path'
+import type { IRDocument, RenderContext, RenderDevServer, Renderer, SiteDevServer, SiteDocument, SiteSpec } from '@lincyaw/kernel'
+import launchEditor from 'launch-editor'
+import { rendererConfig } from '../domain/index.ts'
+import { buildSite as buildPages } from './site-build.ts'
+import type { BuiltDocument } from './site-build.ts'
+import { documentContext, documentSourceFiles } from './site-model.ts'
+import { startSiteServer } from './site-server.ts'
+import { viewerAppCache } from './viewer-app.ts'
+
+const BUILD_DIR = '.presmium/web/build'
+const LOOPBACK = '127.0.0.1'
+
+/** One document as a site of its own: at the root of its site path, with no home page. */
+function documentSite(doc: IRDocument, ctx: RenderContext): SiteSpec {
+  return { title: doc.meta.title, documents: [{ dir: '', title: doc.meta.title, doc, ...ctx.translations ? { translations: ctx.translations } : {} }], config: ctx.config }
+}
+
+function documentWorkDir(ctx: RenderContext, dir: string): string {
+  return join(ctx.workDir, 'documents', dir ? encodeURIComponent(dir) : '_')
+}
+
+/** The dev server of one document (`presmium dev`): its pages, or its slides. */
+export async function devDocument(doc: IRDocument, ctx: RenderContext, form: 'web' | 'slides'): Promise<RenderDevServer> {
+  let current = doc
+  const { port } = rendererConfig(ctx)
+  const server = await startSiteServer({
+    site: () => documentSite(current, ctx),
+    form,
+    ctx,
+    cacheDir: viewerAppCache(),
+    workDir: join(ctx.outDir, 'site'),
+    document: async () => current,
+    context: () => ctx,
+    nodePlugins: () => ctx.nodeVitePlugins ?? [],
+    translations: () => (form === 'web' ? ctx.translations ?? [] : []),
+    listen: { host: LOOPBACK, port: port ?? 0 },
+    openSource(file, line) {
+      if (!documentSourceFiles(current).has(file)) return
+      launchEditor(`${resolve(ctx.deckDir, file)}:${line}`, (opened, error) => {
+        console.error(`[presmium] could not open ${opened} in an editor${error ? `: ${error}` : ''}; set $EDITOR or $LAUNCH_EDITOR`)
+      })
+    },
+  })
+  return {
+    url: server.url,
+    async update(next) {
+      current = next
+      server.update('', next)
+    },
+    close: () => server.close(),
+  }
+}
+
+export const renderer: Renderer = {
+  id: 'web',
+  site: true,
+  support: () => 'full',
+
+  async build(doc: IRDocument, ctx: RenderContext) {
+    const work = join(ctx.deckDir, BUILD_DIR)
+    const entry: BuiltDocument = { dir: '', doc, ctx, nodePlugins: ctx.nodeVitePlugins ?? [], translations: ctx.translations ?? [] }
+    await buildPages(documentSite(doc, ctx), { ...ctx, workDir: work }, [entry])
+    return { outDir: ctx.outDir, skipped: [] }
+  },
+
+  dev: (doc, ctx) => devDocument(doc, ctx, 'web'),
+
+  async buildSite(site: SiteSpec, ctx: RenderContext) {
+    const documents: BuiltDocument[] = site.documents.flatMap((entry) => {
+      if (!entry.doc) return []
+      const own = documentContext(ctx, site, entry.dir, entry.doc, join(ctx.outDir, entry.dir), documentWorkDir(ctx, entry.dir))
+      return [{ dir: entry.dir, doc: entry.doc, ctx: own, nodePlugins: entry.nodeVitePlugins ?? [], translations: entry.translations ?? [] }]
+    })
+    await buildPages(site, ctx, documents)
+    return { outDir: ctx.outDir, skipped: [] }
+  },
+
+  async devSite(site: SiteSpec, ctx: RenderContext, compile: (dir: string) => Promise<IRDocument>): Promise<SiteDevServer> {
+    const entryOf = (dir: string) => site.documents.find(entry => entry.dir === dir)
+    const host = typeof ctx.config.host === 'string' && ctx.config.host ? ctx.config.host : LOOPBACK
+    const server = await startSiteServer({
+      site: () => site,
+      ctx,
+      cacheDir: viewerAppCache(),
+      workDir: join(ctx.workDir, 'viewer'),
+      document: compile,
+      context: (dir, doc) => documentContext(ctx, site, dir, doc, documentWorkDir(ctx, dir), documentWorkDir(ctx, dir)),
+      nodePlugins: dir => entryOf(dir)?.nodeVitePlugins ?? [],
+      translations: dir => entryOf(dir)?.translations ?? [],
+      listen: { host, port: Number(ctx.config.port) || 0 },
+    })
+    return {
+      url: server.url,
+      async update(dir, doc) {
+        const known: SiteDocument = { dir, title: doc.meta.title, ...doc.meta.lang ? { lang: doc.meta.lang } : {}, ...Array.isArray(doc.meta.tags) ? { tags: (doc.meta.tags as unknown[]).filter((t): t is string => typeof t === 'string') } : {} }
+        const entry = entryOf(dir)
+        if (entry) Object.assign(entry, known)
+        else site.documents.push(known)
+        server.update(dir, doc)
+      },
+      target: async () => server.origin,
+      app: (dir, wait) => server.app(dir, wait),
+      warm: dir => server.warm(dir),
+      close: () => server.close(),
+    }
+  },
+}

package/src/node/site-assets.ts

@@ -0,0 +1,17 @@
+import { join, resolve } from 'node:path'
+import { ABSOLUTE_URL, isRecord } from '@lincyaw/kernel'
+import type { RenderContext, SiteSpec } from '@lincyaw/kernel'
+import { publishedFile } from './publish.ts'
+import { isSingle } from './site-model.ts'
+
+/** Publish shell assets from the site's configuration owner, once for every document in the site. */
+export function publishedSite(site: SiteSpec, ctx: RenderContext, outDir = ctx.outDir, base = ctx.base): SiteSpec {
+  const params = isRecord(site.config.params) ? site.config.params : undefined
+  if (!params || typeof params.logo !== 'string') return site
+  const logo = params.logo.trim()
+  const file = isSingle(site) ? resolve(ctx.deckDir, site.documents[0]!.doc?.meta.entry ?? 'lecture.json') : join(ctx.workspaceRoot, 'presmium.workspace.yaml')
+  const source = { file, line: 1 }
+  const url = ABSOLUTE_URL.test(logo) ? logo : logo.startsWith('/') ? `${ctx.base}${logo.slice(1)}` : publishedFile(ctx, outDir, base, source, logo)
+  const { logo: _source, ...rest } = params
+  return { ...site, config: { ...site.config, params: { ...rest, ...url ? { logo: url } : {} } } }
+}

package/src/node/site-build.ts

@@ -0,0 +1,297 @@
+import { cpSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { Readable } from 'node:stream'
+import { pathToFileURL } from 'node:url'
+import { ABSOLUTE_URL, errorMessage, isRecord } from '@lincyaw/kernel'
+import type { IRDocument, NodeVitePlugin, RenderContext, SiteSpec } from '@lincyaw/kernel'
+import { FONT_LICENSE, fontLicense } from '@lincyaw/kernel/node'
+import { SitemapStream, streamToPromise } from 'sitemap'
+import { offlineEnabled, pageLink, SERVICE_WORKER, searchDocuments, sitePageLayout, translationPages, webPages } from '../domain/index.ts'
+import type { AppConfig, SiteConfig, SiteShell, WebPage } from '../domain/index.ts'
+import { BUNDLE_ENTRY, buildDocumentBundle, documentComponents } from './document-bundle.ts'
+import type { DocumentBundle } from './document-bundle.ts'
+import { writeServiceWorker } from './offline.ts'
+import { publishedDocument, publishedFile } from './publish.ts'
+import { APP_DIR, CODE_DIR, contentKey, copyApp, copyPublic, copyRuntimeAssets, runtimeAssets, searchIndex } from './site-files.ts'
+import { documentBase, documentPage, documentSiteConfig, homeDocument, homeDocuments, isSingle, landingConfig, landingDocument, languageLabel, LIST_PAGE, siteLanguage, siteLanguages, siteNeighbours, siteShellBelow, siteTitle, sitemapPages, translationOf } from './site-model.ts'
+import { publishedSite } from './site-assets.ts'
+import { loadLanding, publishLanding, siteContent } from './landing.ts'
+import { buildLandingTemplate, writeLandingTemplate } from './landing-template.ts'
+import { pageHtml, redirectHtml } from './site-page.ts'
+import type { MetaTag } from './site-page.ts'
+import { appEntry, appPlugin, buildViewerApp, buildViewerServer, viewerAppCache } from './viewer-app.ts'
+import type { AppPlugin, ViewerApp } from './viewer-app.ts'
+
+/**
+ * A built site of the web form: the viewer app copied once below the site's path, and each document as data beside its
+ * pages: its IR (and its translations'), its own code, its search index, its published files and its plugins' run-time
+ * files. Every page is rendered on the server, so that it reads without its script, and the app then hydrates it.
+ */
+
+/** A document of the site, as its build has it. */
+export interface BuiltDocument {
+  dir: string
+  doc: IRDocument
+  /** Its render context: below its own site path and output directory. */
+  ctx: RenderContext
+  nodePlugins: readonly NodeVitePlugin[]
+  translations: readonly { lang: string, doc: IRDocument }[]
+}
+
+interface ServerRender {
+  render(input: { config: AppConfig, doc?: IRDocument, components: string[] }): Promise<string>
+}
+
+interface Built {
+  app: ViewerApp
+  /** The app's directory in the site, named by its content. */
+  appDir: string
+  appUrl: string
+  server: ServerRender
+  plugins: Map<string, AppPlugin>
+}
+
+// A document's directory as one segment of a path; the document at the root as `~` (a `.` would be taken out of the address).
+const segment = (dir: string) => (dir ? encodeURIComponent(dir) : '~')
+
+/** The URL of the site's Open Graph image: an absolute URL as written, a local file published (with the sitemap's host name when there is one). */
+function headImage(shell: SiteShell, publish: (url: string) => string | undefined): string | undefined {
+  const image = shell.head?.image
+  if (!image || ABSOLUTE_URL.test(image)) return image
+  const published = publish(image)
+  return published && shell.sitemap ? `${shell.sitemap.hostname}${published}` : published
+}
+
+function metaTags(shell: SiteShell, image: string | undefined, title: string): MetaTag[] {
+  const head = shell.head
+  return [
+    ...head?.description ? [{ name: 'description', content: head.description }] : [],
+    ...head ? [{ property: 'og:type', content: 'website' }, { property: 'og:title', content: title }] : [],
+    ...head?.description ? [{ property: 'og:description', content: head.description }] : [],
+    ...image ? [{ property: 'og:image', content: image }] : [],
+  ]
+}
+
+function pageTitle(page: WebPage, doc: IRDocument): string {
+  return page.title === doc.meta.title ? page.title : `${page.title} | ${doc.meta.title}`
+}
+
+function pageFile(page: WebPage): string {
+  return page.path === 'index' ? 'index.html' : `${page.path}.html`
+}
+
+async function writeSitemap(file: string, hostname: string, base: string, pages: string[]): Promise<void> {
+  const stream = new SitemapStream({ hostname: `${hostname}${base}` })
+  const xml = await streamToPromise(Readable.from(pages.map(url => ({ url }))).pipe(stream))
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, xml)
+}
+
+/** Builds the app (with its server-side render) for the plugins of every document and the operator's, and copies it into the site. */
+async function prepareApp(ctx: RenderContext, documents: readonly BuiltDocument[]): Promise<Built> {
+  const dirs = new Map<string, string>()
+  for (const { ctx: own } of documents) for (const name of own.plugins) if (own.pluginDirs[name]) dirs.set(name, own.pluginDirs[name]!)
+  for (const name of ctx.plugins) if (ctx.pluginDirs[name]) dirs.set(name, ctx.pluginDirs[name]!)
+  const plugins = new Map<string, AppPlugin>()
+  for (const [name, dir] of dirs) plugins.set(name, await appPlugin(name, dir))
+  const started = Date.now()
+  const app = await buildViewerApp(viewerAppCache(), [...plugins.values()])
+  const server = await import(pathToFileURL(await buildViewerServer(app, [...plugins.values()])).href) as ServerRender
+  ctx.log?.(`the viewer app is ready in ${((Date.now() - started) / 1000).toFixed(1)} s`)
+  const key = copyApp(app, join(ctx.outDir, APP_DIR))
+  return { app, appDir: join(ctx.outDir, APP_DIR, key), appUrl: `${ctx.base}${APP_DIR}/${key}/`, server, plugins }
+}
+
+async function renderPage(built: Built, file: string, config: AppConfig, title: string, meta: MetaTag[], doc: IRDocument | undefined, components: string[]): Promise<void> {
+  const body = await built.server.render({ config, doc, components })
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, pageHtml({ entry: appEntry(built.app), appUrl: built.appUrl, shared: built.app.manifest.shared, config, title, meta, body }))
+}
+
+/** A document's files beside its pages: its own code, its plugins' run-time files, its `public/`, the fonts' license. */
+async function documentFiles(ctx: RenderContext, built: Built, entry: BuiltDocument): Promise<{ code?: string, components: string[] }> {
+  const { dir, ctx: own } = entry
+  const out = own.outDir
+  // The document's own code, built to import the app's modules by name.
+  const bundle: DocumentBundle | null = await buildDocumentBundle({
+    deckDir: own.deckDir,
+    workspaceRoot: own.workspaceRoot,
+    outDir: join(ctx.workDir, 'bundles', segment(dir)),
+    externals: Object.keys(built.app.manifest.shared),
+    nodePlugins: entry.nodePlugins.map(({ entry: file, config }) => ({ entry: file, config })),
+    components: documentComponents(entry.doc),
+  })
+  // Named by its content, as the app is: the same in any checkout.
+  const code = bundle && contentKey(bundle.dir, file => file === 'bundle.json')
+  if (bundle && code) cpSync(bundle.dir, join(out, CODE_DIR, code), { recursive: true, filter: source => !source.endsWith('bundle.json') })
+  copyRuntimeAssets(await runtimeAssets(entry.nodePlugins, own), out)
+  copyPublic(own.deckDir, out)
+  mkdirSync(dirname(join(out, FONT_LICENSE)), { recursive: true })
+  writeFileSync(join(out, FONT_LICENSE), fontLicense(import.meta.url))
+  const components = [...new Set([...own.plugins.flatMap(name => Object.keys(built.plugins.get(name)?.components ?? {})), ...bundle?.components ?? []])]
+  return { ...code ? { code } : {}, components }
+}
+
+async function buildDocumentPages(site: SiteSpec, ctx: RenderContext, built: Built, entry: BuiltDocument, docs: ReadonlyMap<string, IRDocument>, workspace: boolean): Promise<void> {
+  const { dir, doc, ctx: own } = entry
+  const out = own.outDir
+  const base = documentBase(ctx.base, dir)
+  mkdirSync(out, { recursive: true })
+  const linked = workspace ? documentPage(site, ctx.base, docs) : undefined
+  const published = publishedDocument(doc, own, out, base, linked)
+  const pages = webPages(published)
+  const translations = entry.translations.map(({ lang, doc: translated }) => {
+    const shown = publishedDocument(translated, own, out, base, linked)
+    return { lang, doc: shown, pages: translationPages(shown, pages) }
+  })
+  const lang = doc.meta.lang ?? own.lang ?? 'zh-CN'
+  const { code, components } = await documentFiles(ctx, built, entry)
+  const others = workspace ? siteNeighbours(site, ctx.base, dir, docs).search : []
+  const shell = siteShellBelow(site, ctx.base)
+  const image = headImage(shell, url => publishedFile(own, out, base, { file: resolve(own.deckDir, doc.meta.entry), line: 1 }, url))
+  const offline = offlineEnabled(doc.config.presmium)
+  const locales = [{ prefix: '', lang, doc: published, pages, translated: false }, ...translations.map(t => ({ prefix: `${t.lang}/`, lang: t.lang, doc: t.doc, pages: t.pages, translated: true }))]
+  for (const locale of locales) {
+    const root = `${base}${locale.prefix}`
+    mkdirSync(join(out, locale.prefix), { recursive: true })
+    writeFileSync(join(out, locale.prefix, 'ir.json'), JSON.stringify(locale.doc))
+    writeFileSync(join(out, locale.prefix, 'search.json'), searchIndex([...searchDocuments(locale.doc, root, locale.pages), ...others]))
+    for (const page of locale.pages) {
+      const config: AppConfig = {
+        kind: 'document',
+        document: dir,
+        base,
+        lang: locale.lang,
+        ir: `${root}ir.json`,
+        ...code ? { bundle: `${base}${CODE_DIR}/${code}/${BUNDLE_ENTRY}` } : {},
+        search: `${root}search.json`,
+        page: page.path,
+        ...locale.translated ? { pages: locale.pages } : {},
+        site: { ...documentSiteConfig({ site, base: ctx.base, dir, doc, lang: locale.lang, docs, workspace }), brandTitle: workspace ? siteTitle(site, locale.lang) : locale.doc.meta.title, layout: sitePageLayout(isRecord(locale.doc.config.renderers.web) ? locale.doc.config.renderers.web : {}, locale.lang) },
+        plugins: [...new Set([...own.plugins, ...ctx.plugins])],
+        origins: [],
+        ...offline ? { serviceWorker: `${base}${SERVICE_WORKER}` } : {},
+        rendered: true,
+      }
+      const title = pageTitle(page, locale.doc)
+      await renderPage(built, join(out, locale.prefix, pageFile(page)), config, title, metaTags(shell, image, title), locale.doc, components)
+      if (page.path === 'index' && landingDocument(site)?.dir === dir) {
+        const landing = landingConfig(config, locale.doc, site, ctx.base, locale.translated ? locale.lang : '')
+        const title = siteTitle(site, locale.lang)
+        await renderPage(built, join(ctx.outDir, locale.prefix, 'index.html'), landing, title, metaTags(shell, image, title), locale.doc, components)
+      }
+    }
+  }
+  if (offline) writeServiceWorker(out, base, { dir: built.appDir, url: built.appUrl })
+}
+
+/** A page that shows no document (the home page, a missing page), below the site's path. */
+function pageConfig(kind: 'home' | 'missing', base: string, lang: string, site: SiteConfig, extra: Partial<AppConfig> = {}): AppConfig {
+  return { kind, document: '', base, lang, site, origins: [], rendered: true, ...extra }
+}
+
+async function buildHome(site: SiteSpec, ctx: RenderContext, built: Built, docs: ReadonlyMap<string, IRDocument>): Promise<void> {
+  const lang = siteLanguage(site, ctx.lang)
+  const shell = siteShellBelow(site, ctx.base)
+  const others = siteLanguages(site, lang)
+  const locales = [{ lang, label: languageLabel(lang), base: ctx.base }, ...others.map(other => ({ lang: other.lang, label: languageLabel(other.lang), base: `${ctx.base}${other.lang}/` }))]
+  const target = homeDocument(site)
+  const landing = landingDocument(site)
+  const independent = loadLanding(site, ctx)
+  const page = independent?.kind === 'page' ? publishLanding(independent, site, ctx) : undefined
+  const image = headImage(shell, url => publishedFile(ctx, ctx.outDir, ctx.base, { file: join(ctx.workspaceRoot, 'presmium.workspace.yaml'), line: 1 }, url))
+  for (const locale of [{ lang, title: site.title, prefix: '' }, ...others.map(other => ({ ...other, prefix: `${other.lang}/` }))]) {
+    const config = pageConfig('home', ctx.base, locale.lang, { title: locale.title, brandTitle: locale.title, root: `${ctx.base}${locale.prefix}`, shell, locales, links: {} }, {
+      documents: homeDocuments(site, ctx.base, docs, locale.prefix ? locale.lang : undefined),
+      plugins: ctx.plugins,
+    })
+    const list = join(ctx.outDir, locale.prefix, target || site.config.landing !== undefined ? `${LIST_PAGE}.html` : 'index.html')
+    await renderPage(built, list, config, locale.title, metaTags(shell, image, locale.title), undefined, [])
+    if (page) {
+      const metadata = { ...shell, head: { ...shell.head, description: page.description ?? shell.head?.description } }
+      await renderPage(built, join(ctx.outDir, locale.prefix, 'index.html'), { ...config, landingPage: page }, page.title, metaTags(metadata, image, page.title), undefined, [])
+    }
+    if (independent?.kind === 'template') {
+      const output = await buildLandingTemplate(independent.file, join(ctx.workDir, 'landing', locale.lang), ctx.base, siteContent(site, ctx.base, locale.lang, config.documents ?? []), ctx.workspaceRoot)
+      writeLandingTemplate(output, ctx.outDir, locale.prefix)
+    }
+    if (target) {
+      const translated = locale.prefix && translationOf(target, locale.lang) ? `${documentBase(ctx.base, target.dir)}${locale.lang}/` : documentBase(ctx.base, target.dir)
+      writeFileSync(join(ctx.outDir, locale.prefix, 'index.html'), redirectHtml(translated, target.title, locale.lang))
+    }
+    if (landing && locale.prefix && !translationOf(landing, locale.lang)) {
+      writeFileSync(join(ctx.outDir, locale.prefix, 'index.html'), redirectHtml(ctx.base, site.title, locale.lang))
+    }
+  }
+}
+
+async function buildMissing(site: SiteSpec, ctx: RenderContext, built: Built, title: string, lang: string): Promise<void> {
+  const shell = siteShellBelow(site, ctx.base)
+  const config = pageConfig('missing', ctx.base, lang, { title, brandTitle: site.title, root: ctx.base, shell, locales: [{ lang, label: languageLabel(lang), base: ctx.base }], links: {} }, { plugins: ctx.plugins })
+  await renderPage(built, join(ctx.outDir, '404.html'), config, title, [], undefined, [])
+}
+
+/** Builds the site of `documents` into `ctx.outDir`: a workspace's (with its home page), or one document's at the root. */
+export async function buildSite(site: SiteSpec, ctx: RenderContext, documents: readonly BuiltDocument[]): Promise<void> {
+  const workspace = !isSingle(site)
+  // Invalid presentation settings fail before replacing an existing build.
+  siteShellBelow(site, ctx.base)
+  landingDocument(site)
+  loadLanding(site, ctx)
+  for (const entry of documents) for (const doc of [entry.doc, ...entry.translations.map(locale => locale.doc)]) sitePageLayout(isRecord(doc.config.renderers.web) ? doc.config.renderers.web : {}, doc.meta.lang)
+  // A build starts empty, as the pages and files of an earlier one may be gone from the document.
+  rmSync(ctx.outDir, { recursive: true, force: true })
+  if (workspace) copyPublic(ctx.workspaceRoot, ctx.outDir)
+  site = publishedSite(site, ctx)
+  const built = await prepareApp(ctx, documents)
+  // Also allow publishing from a branch without Jekyll filtering the viewer's _app and _code directories.
+  writeFileSync(join(ctx.outDir, '.nojekyll'), '')
+  const docs = new Map(documents.map(entry => [entry.dir, entry.doc] as const))
+  if (workspace && ctx.config.home !== false) await buildHome(site, ctx, built, docs)
+  for (const entry of documents) {
+    try {
+      await buildDocumentPages(site, ctx, built, entry, docs, workspace)
+    } catch (error) {
+      throw new Error(workspace ? `document ${entry.dir || '.'}: ${errorMessage(error)}` : errorMessage(error))
+    }
+  }
+  const lang = siteLanguage(site, ctx.lang)
+  await buildMissing(site, ctx, built, workspace ? site.title : documents[0]?.doc.meta.title ?? site.title, lang)
+  const { sitemap } = siteShellBelow(site, ctx.base)
+  if (sitemap) {
+    const pages = workspace ? ['', ...sitemapPages(site)] : documents.flatMap(({ doc, translations }) => [
+      ...webPages(doc).map(page => pageLink(page).replace(/^\//, '')),
+      ...translations.flatMap(t => translationPages(t.doc, webPages(doc)).map(page => pageLink(page, `/${t.lang}`).replace(/^\//, ''))),
+    ])
+    await writeSitemap(join(ctx.outDir, 'sitemap.xml'), sitemap.hostname, ctx.base, pages)
+  }
+}
+
+/**
+ * Builds a document's slides into `ctx.outDir`: one page that shows them (the slides form of the viewer), with the
+ * document's slides view (`{only} slides`), its code and files, as the web form's are built.
+ */
+export async function buildSlidesSite(doc: IRDocument, ctx: RenderContext, nodePlugins: readonly NodeVitePlugin[]): Promise<void> {
+  rmSync(ctx.outDir, { recursive: true, force: true })
+  const entry: BuiltDocument = { dir: '', doc, ctx, nodePlugins, translations: [] }
+  const built = await prepareApp(ctx, [entry])
+  mkdirSync(ctx.outDir, { recursive: true })
+  const published = publishedDocument(doc, ctx, ctx.outDir, ctx.base)
+  const { code } = await documentFiles(ctx, built, entry)
+  writeFileSync(join(ctx.outDir, 'ir.json'), JSON.stringify(published))
+  const lang = doc.meta.lang ?? ctx.lang ?? 'zh-CN'
+  const site: SiteSpec = { title: doc.meta.title, documents: [{ dir: '', title: doc.meta.title, doc }], config: ctx.config }
+  const config: AppConfig = {
+    kind: 'document',
+    document: '',
+    base: ctx.base,
+    lang,
+    form: 'slides',
+    ir: `${ctx.base}ir.json`,
+    ...code ? { bundle: `${ctx.base}${CODE_DIR}/${code}/${BUNDLE_ENTRY}` } : {},
+    site: documentSiteConfig({ site, base: ctx.base, dir: '', doc, lang, docs: new Map(), workspace: false }),
+    plugins: ctx.plugins,
+    origins: [],
+  }
+  writeFileSync(join(ctx.outDir, 'index.html'), pageHtml({ entry: appEntry(built.app), appUrl: built.appUrl, shared: built.app.manifest.shared, config, title: doc.meta.title }))
+}