@jaamd/jaad 0.11.0 → 1.0.0

package/src/docs/model/rendered.ts

@@ -0,0 +1,185 @@
+import type { DocsHeading } from '../types.ts'
+
+/** What Astro's renderer leaves on a markdown entry. */
+export interface RenderedMarkdown {
+    html: string
+    metadata?: { headings?: { depth: number; slug: string; text: string }[] }
+}
+
+/** Elements whose text is not prose: code, controls, icons, and in-page navigation. */
+const DROPPED = /<(pre|button|svg|nav|script|style|template)\b[^>]*>[\s\S]*?<\/\1>|<!--[\s\S]*?-->/gi
+
+const BLOCK =
+    /<\/?(address|article|aside|blockquote|br|dd|details|div|dl|dt|figcaption|figure|footer|h[1-6]|header|hr|li|ol|p|section|summary|table|tbody|td|tfoot|th|thead|tr|ul)\b[^>]*>/gi
+
+const NAMED: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' }
+
+function decodeEntities(text: string): string {
+    return text.replace(/&(#x[\da-f]+|#\d+|[a-z]+);/gi, (entity, name: string) => {
+        if (name[0] !== '#') return NAMED[name.toLowerCase()] ?? entity
+        const code = name[1] === 'x' || name[1] === 'X' ? parseInt(name.slice(2), 16) : parseInt(name.slice(1), 10)
+        return Number.isNaN(code) ? entity : String.fromCodePoint(code)
+    })
+}
+
+/** The readable text of an HTML fragment, on one line. */
+export function htmlText(html: string): string {
+    return decodeEntities(
+        html
+            .replace(DROPPED, ' ')
+            .replace(BLOCK, ' ')
+            .replace(/<[^>]*>/g, ''),
+    )
+        .replace(/\s+/g, ' ')
+        .trim()
+}
+
+const VOID = new Set([
+    'area',
+    'base',
+    'br',
+    'col',
+    'embed',
+    'hr',
+    'img',
+    'input',
+    'link',
+    'meta',
+    'source',
+    'track',
+    'wbr',
+])
+
+const TAG = /<(\/?)([a-zA-Z][\w-]*)([^>]*)>/g
+
+interface HeadingTag {
+    depth: number
+    id: string
+    /** Inside an element with `data-toc-ignore`, or carrying it. */
+    ignored: boolean
+    /** Where the opening tag starts, and where the closing one ends. */
+    start: number
+    end: number
+}
+
+/** Every heading of the page, and whether a `data-toc-ignore` element holds it.
+ *  Read from the HTML: an element written as raw HTML wraps what follows it
+ *  only there, not in the syntax tree. */
+function headingTags(html: string): HeadingTag[] {
+    const headings: HeadingTag[] = []
+    let ignored: { tag: string; depth: number } | null = null
+    let open: HeadingTag | null = null
+
+    for (const match of html.matchAll(TAG)) {
+        const [whole, closing, name, attrs] = match
+        const tag = name.toLowerCase()
+        const selfClosing = VOID.has(tag) || attrs.trimEnd().endsWith('/')
+
+        if (ignored && tag === ignored.tag && !selfClosing) {
+            ignored.depth += closing ? -1 : 1
+            if (ignored.depth === 0) ignored = null
+        } else if (!ignored && !closing && !selfClosing && /\sdata-toc-ignore\b/i.test(attrs)) {
+            ignored = { tag, depth: 1 }
+        }
+
+        const heading = /^h([1-6])$/.exec(tag)
+        if (!heading) continue
+        if (!closing) {
+            open = {
+                depth: Number(heading[1]),
+                id: /\sid="([^"]*)"/.exec(attrs)?.[1] ?? '',
+                ignored: ignored !== null || /\sdata-toc-ignore\b/i.test(attrs),
+                start: match.index,
+                end: match.index + whole.length,
+            }
+        } else if (open) {
+            open.end = match.index + whole.length
+            headings.push(open)
+            open = null
+        }
+    }
+
+    return headings
+}
+
+/** The first h1, as the renderer read it. */
+export function renderedTitle(rendered: RenderedMarkdown | undefined): string | null {
+    return rendered?.metadata?.headings?.find((heading) => heading.depth === 1)?.text ?? null
+}
+
+const isOutline = (heading: HeadingTag) => !heading.ignored && (heading.depth === 2 || heading.depth === 3)
+
+function headingOf(tag: HeadingTag, rendered: RenderedMarkdown): DocsHeading {
+    const known = rendered.metadata?.headings?.find((heading) => heading.slug === tag.id)
+    return {
+        depth: tag.depth as 2 | 3,
+        slug: tag.id,
+        text: known?.text ?? htmlText(rendered.html.slice(tag.start, tag.end)),
+    }
+}
+
+/** The h2 and h3 of the page outside `data-toc-ignore`: its table of contents. */
+export function pageHeadings(rendered: RenderedMarkdown | undefined): DocsHeading[] {
+    if (!rendered) return []
+    return headingTags(rendered.html)
+        .filter(isOutline)
+        .map((tag) => headingOf(tag, rendered))
+}
+
+/** A stretch of a page: the text under one h2 or h3, or before the first. */
+export interface DocsChunk {
+    heading: DocsHeading | null
+    text: string
+}
+
+/** The page cut at the headings of its table of contents. The h1 is left out;
+ *  any other heading stays in the text of the stretch it sits in. */
+export function pageChunks(rendered: RenderedMarkdown | undefined): DocsChunk[] {
+    if (!rendered) return [{ heading: null, text: '' }]
+    const { html } = rendered
+    const tags = headingTags(html)
+    const titles = tags.filter((tag) => tag.depth === 1)
+    const cuts = tags.filter(isOutline)
+
+    /** The text from `from` to `to`, without the h1. */
+    const between = (from: number, to: number) => {
+        let text = ''
+        let at = from
+        for (const title of titles) {
+            if (title.end <= from || title.start >= to) continue
+            text += html.slice(at, title.start) + ' '
+            at = title.end
+        }
+        return htmlText(text + html.slice(at, to))
+    }
+
+    return [
+        { heading: null, text: between(0, cuts[0]?.start ?? html.length) },
+        ...cuts.map((tag, at) => ({
+            heading: headingOf(tag, rendered),
+            text: between(tag.end, cuts[at + 1]?.start ?? html.length),
+        })),
+    ]
+}
+
+/** The first paragraph that is not the title, cut to `maxLength` at a word,
+ *  for `<meta name="description">`. */
+export function pageDescription(
+    rendered: RenderedMarkdown | undefined,
+    title: string,
+    maxLength: number = 155,
+): string | null {
+    if (!rendered) return null
+    const prose = rendered.html.replace(DROPPED, ' ')
+    const paragraphs = [...prose.matchAll(/<p\b([^>]*)>([\s\S]*?)<\/p>/gi)]
+        .filter(([, attrs]) => !/markdown-alert-title/.test(attrs))
+        .map(([, , inner]) => htmlText(inner))
+
+    const first = paragraphs.find((text) => text && text.toLowerCase() !== title.trim().toLowerCase())
+    if (!first) return null
+
+    if (first.length <= maxLength) return first
+    const truncated = first.slice(0, maxLength)
+    const lastSpace = truncated.lastIndexOf(' ')
+    return `${truncated.slice(0, lastSpace > 0 ? lastSpace : maxLength)}…`
+}

package/src/docs/model/tree.ts

@@ -0,0 +1,124 @@
+import type { DocsPageData } from '../types.ts'
+import type { DocsUrlOptions } from '../urls.ts'
+import type { RenderedMarkdown } from './rendered.ts'
+import { docsPageHref } from '../urls.ts'
+import { namedSlug, parseDocPath, slugToTitle } from './ids.ts'
+import { renderedTitle } from './rendered.ts'
+
+/** A markdown file of one locale: a collection entry, or a file read from disk. */
+export interface DocsSource {
+    /** Collection id. */
+    id: string
+    /** The id without its locale and its section. */
+    path: string
+    /** Set when the docs are localised. */
+    locale?: string
+    /** Set when the docs are split into sections. */
+    section?: string
+    data: Partial<DocsPageData>
+    rendered?: RenderedMarkdown
+}
+
+/** A page with everything its file, its frontmatter and its place in the docs decide. */
+export interface DocsPage<S extends DocsSource = DocsSource> {
+    /** What the page was built from. */
+    source: S
+    id: string
+    path: string
+    locale?: string
+    section?: string
+    /** The chapter directory, without its order prefix. */
+    chapter?: string
+    data: S['data']
+    /** The named url below the docs mount: its section, then its clean path. */
+    slug: string
+    /** Where it is served: empty for the opening page, the section for the first
+     *  page of a later one, `slug` otherwise. */
+    canonical: string
+    /** The other slugs it answers to, each redirecting to `canonical`. */
+    aliases: string[]
+    /** The url of `canonical`. */
+    href: string
+    /** Frontmatter title, then the first h1, then the file name. */
+    title: string
+    /** The name in navigation: frontmatter `label`, then `title`. */
+    label: string
+    /** What pairs it with its translations: frontmatter `translationKey`, then `slug`. */
+    translationKey: string
+    /** Position in reading order. */
+    index: number
+}
+
+/** The pages of one locale in reading order. */
+export interface DocsTree<S extends DocsSource = DocsSource> {
+    pages: DocsPage<S>[]
+    byId: Map<string, DocsPage<S>>
+    byKey: Map<string, DocsPage<S>>
+}
+
+export interface DocsTreeOptions {
+    /** Section keys, in their order. */
+    sections?: string[]
+    /** For `href`. */
+    urls: DocsUrlOptions
+}
+
+/** The order of `sections` first, then chapter order, then file order within
+ *  the chapter. Frontmatter `order` replaces a file's prefix number; root pages
+ *  interleave with chapters by their own number. */
+function sortSources<S extends DocsSource>(sources: S[], sections: string[]): S[] {
+    return sources
+        .map((source) => {
+            const parsed = parseDocPath(source.path)
+            const order = source.data.order ?? parsed.order
+            return {
+                source,
+                section: sections.indexOf(source.section ?? ''),
+                primary: parsed.orderChapter ?? order,
+                secondary: order,
+            }
+        })
+        .toSorted((a, b) => a.section - b.section || a.primary - b.primary || a.secondary - b.secondary)
+        .map((entry) => entry.source)
+}
+
+/** Resolves every page of one locale once. */
+export function buildDocsTree<S extends DocsSource>(sources: S[], options: DocsTreeOptions): DocsTree<S> {
+    const sorted = sortSources(sources, options.sections ?? [])
+
+    const pages = sorted.map((source, index): DocsPage<S> => {
+        const parsed = parseDocPath(source.path)
+        const slug = namedSlug(source.path, source.section)
+        const canonical =
+            index === 0 ? '' : source.section && sorted[index - 1].section !== source.section ? source.section : slug
+        const title = source.data.title ?? renderedTitle(source.rendered) ?? slugToTitle(parsed.slug)
+
+        return {
+            source,
+            id: source.id,
+            path: source.path,
+            locale: source.locale,
+            section: source.section,
+            chapter: parsed.chapter,
+            data: source.data,
+            slug,
+            canonical,
+            aliases: [
+                ...(slug === canonical ? [] : [slug]),
+                // The first section's key leads to the opening page.
+                ...(index === 0 && source.section ? [source.section] : []),
+            ],
+            href: docsPageHref(canonical, options.urls),
+            title,
+            label: source.data.label ?? title,
+            translationKey: source.data.translationKey ?? slug,
+            index,
+        }
+    })
+
+    return {
+        pages,
+        byId: new Map(pages.map((page) => [page.id, page])),
+        byKey: new Map(pages.map((page) => [page.translationKey, page])),
+    }
+}

package/src/docs/model/validate.ts

@@ -0,0 +1,75 @@
+import type { DocsSource } from './tree.ts'
+import { getCleanSlug, namedSlug } from './ids.ts'
+
+/** Within a section, like `id`; across them, the section is part of the name. */
+const inSection = (page: DocsSource, id: string) => (page.section ? `${page.section}/${id}` : id)
+
+/** Fail before route generation when the file tree cannot produce one clear
+ * navigation and URL for every page. */
+export function validateDocsStructure(pages: DocsSource[], locale?: string): void {
+    const idsBySlug = new Map<string, string[]>()
+    const directoriesByChapter = new Map<string, Set<string>>()
+    const issues: string[] = []
+    // Messages name the file on disk, locale directory included.
+    const named = (id: string) => (locale ? `${locale}/${id}` : id)
+
+    const byId = pages.map((page) => ({ page, id: inSection(page, page.path) }))
+    for (const { page, id } of byId.toSorted((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))) {
+        const parts = page.path.split('/')
+        if (parts.length > 2) {
+            issues.push(`${named(id)}: only one chapter directory is supported inside docs/`)
+        }
+
+        const slug = namedSlug(page.path, page.section)
+        const ids = idsBySlug.get(slug) ?? []
+        ids.push(id)
+        idsBySlug.set(slug, ids)
+
+        if (parts.length === 2) {
+            const directory = inSection(page, parts[0])
+            const chapter = inSection(page, getCleanSlug(parts[0]))
+            const directories = directoriesByChapter.get(chapter) ?? new Set()
+            directories.add(directory)
+            directoriesByChapter.set(chapter, directories)
+        }
+    }
+
+    for (const [slug, ids] of idsBySlug) {
+        if (ids.length > 1) {
+            issues.push(`${ids.map(named).join(', ')} all resolve to /${slug}`)
+        }
+    }
+
+    // A page outside the sections cannot take a section's url.
+    const keys = new Set(pages.flatMap((page) => page.section ?? []))
+    for (const page of pages) {
+        const first = namedSlug(page.path, page.section).split('/')[0]
+        if (!page.section && keys.has(first)) {
+            issues.push(`${named(page.path)} resolves into section /${first}`)
+        }
+    }
+
+    const byKey = new Map<string, string[]>()
+    for (const page of pages) {
+        const key = page.data.translationKey
+        if (!key) continue
+        const ids = byKey.get(key) ?? []
+        ids.push(inSection(page, page.path))
+        byKey.set(key, ids)
+    }
+    for (const [key, ids] of byKey) {
+        if (ids.length > 1) {
+            issues.push(`${ids.map(named).join(', ')} all claim translationKey ${key}`)
+        }
+    }
+
+    for (const [chapter, directories] of directoriesByChapter) {
+        if (directories.size > 1) {
+            issues.push(`${[...directories].map(named).join(', ')} all resolve to chapter /${chapter}`)
+        }
+    }
+
+    if (issues.length > 0) {
+        throw new Error(`jaad: invalid documentation structure\n${issues.map((issue) => `  ${issue}`).join('\n')}`)
+    }
+}

package/src/docs/navigation.ts

@@ -0,0 +1,75 @@
+import type { DocsTree } from './model/tree.ts'
+import type { DocsNavItem } from './types.ts'
+
+/** A page, or a chapter and its pages. */
+export type DocsNavEntry =
+    | { type: 'page'; item: DocsNavItem }
+    | { type: 'chapter'; chapter: string; items: DocsNavItem[] }
+
+/** A top-level entry. With sections, the pages outside them come first, then
+ *  every section and its entries. */
+export type DocsNavGroup = DocsNavEntry | { type: 'section'; section: string; label: string; entries: DocsNavEntry[] }
+
+export interface DocsNavigation {
+    /** The whole tree, in reading order. */
+    groups: DocsNavGroup[]
+    previousPage: DocsNavItem | null
+    nextPage: DocsNavItem | null
+}
+
+/** Each chapter sits where its first page does. */
+function groupByChapter(items: DocsNavItem[]): DocsNavEntry[] {
+    const chapters = new Map<string, DocsNavItem[]>()
+    const groups: DocsNavEntry[] = []
+
+    for (const item of items) {
+        if (!item.chapter) {
+            groups.push({ type: 'page', item })
+            continue
+        }
+
+        let pages = chapters.get(item.chapter)
+        if (!pages) {
+            pages = []
+            chapters.set(item.chapter, pages)
+            groups.push({ type: 'chapter', chapter: item.chapter, items: pages })
+        }
+        pages.push(item)
+    }
+
+    return groups
+}
+
+/** Each section with pages, under its label, in the order of `sections`. */
+function groupBySection(items: DocsNavItem[], sections: { key: string; label: string }[]): DocsNavGroup[] {
+    return sections.flatMap(({ key, label }) => {
+        const own = items.filter((item) => item.section === key)
+        return own.length > 0 ? [{ type: 'section' as const, section: key, label, entries: groupByChapter(own) }] : []
+    })
+}
+
+/** The navigation seen from one page of `tree`: every group, the page marked
+ *  active, and its neighbours. */
+export function buildDocsNavigation(
+    tree: DocsTree,
+    currentId: string,
+    sections: { key: string; label: string }[] = [],
+): DocsNavigation {
+    const position = tree.byId.get(currentId)?.index ?? -1
+    const items = tree.pages.map((page): DocsNavItem => ({
+        title: page.label,
+        section: page.section,
+        chapter: page.chapter,
+        href: page.href,
+        isActive: page.index === position,
+    }))
+
+    return {
+        groups:
+            sections.length > 0
+                ? [...groupByChapter(items.filter((item) => !item.section)), ...groupBySection(items, sections)]
+                : groupByChapter(items),
+        previousPage: position > 0 ? items[position - 1] : null,
+        nextPage: position >= 0 && position < items.length - 1 ? items[position + 1] : null,
+    }
+}

package/src/{routes → docs/routes}/404.astro

@@ -1,6 +1,6 @@
 ---
+import { withDeploymentBase } from '../../site/urls.ts'
 import Layout from '../layouts/Page.astro'
-import { withDeploymentBase } from '../urls.ts'
 
 const homeHref = withDeploymentBase('/', import.meta.env.BASE_URL)
 ---

package/src/docs/routes/docs-index.astro

@@ -0,0 +1,19 @@
+---
+import { render } from 'astro:content'
+import { withDeploymentBase } from '../../site/urls.ts'
+import { getDocsTree } from '../collection.ts'
+import DocsPage from '../components/DocsPage.astro'
+
+const tree = await getDocsTree()
+
+const page = tree.pages[0]
+if (!page) {
+    return Astro.redirect(withDeploymentBase('/404', import.meta.env.BASE_URL))
+}
+
+const { Content } = await render(page.source)
+---
+
+<DocsPage {page} {tree}>
+    <Content />
+</DocsPage>

package/src/docs/routes/docs-slug.astro

@@ -0,0 +1,54 @@
+---
+import { render } from 'astro:content'
+import { buildLocales, localePrefix } from '../../site/runtime.ts'
+import { withDeploymentBase } from '../../site/urls.ts'
+import { getDocsTree } from '../collection.ts'
+import DocsPage from '../components/DocsPage.astro'
+import { docsUrls } from '../runtime.ts'
+import { docsPageHref } from '../urls.ts'
+
+interface DocsPath {
+    params: { slug: string }
+    /** `redirect` is the canonical slug of a page reached by another name. */
+    props: { id: string; locale?: string; redirect?: string }
+}
+
+export async function getStaticPaths() {
+    const paths: DocsPath[] = []
+
+    for (const locale of buildLocales()) {
+        const { pages } = await getDocsTree(locale)
+        const prefix = localePrefix(locale)
+
+        for (const page of pages) {
+            const add = (slug: string, redirect?: string) =>
+                paths.push({ params: { slug }, props: { id: page.id, locale, redirect } })
+
+            // Empty is the index route's; a prefixed locale has none, so /it is this page.
+            const own = `${prefix}${page.canonical}`.replace(/\/$/, '')
+            if (own) add(own)
+            for (const alias of page.aliases) add(`${prefix}${alias}`, page.canonical)
+        }
+    }
+
+    return paths
+}
+
+const { id, locale, redirect } = Astro.props
+
+if (redirect !== undefined) {
+    return Astro.redirect(docsPageHref(redirect, docsUrls(locale)), 301)
+}
+
+const tree = await getDocsTree(locale)
+const page = tree.byId.get(id)
+if (!page) {
+    return Astro.redirect(withDeploymentBase('/404', import.meta.env.BASE_URL))
+}
+
+const { Content } = await render(page.source)
+---
+
+<DocsPage {page} {tree} headTitle={page.title}>
+    <Content />
+</DocsPage>

package/src/{routes → docs/routes}/docs-slug.md.ts

@@ -1,7 +1,6 @@
 import type { APIRoute, GetStaticPaths } from 'astro'
-import { getSortedDocsPages } from '../collection.ts'
-import { buildLocales, localePrefix } from '../docs-config.ts'
-import { getCleanSlug, routedId } from '../utils/docs.ts'
+import { buildLocales, localePrefix } from '../../site/runtime.ts'
+import { getDocsTree } from '../collection.ts'
 
 /** Raw markdown at the page's own url plus `.md`, for readers and for LLMs. */
 export const getStaticPaths: GetStaticPaths = async () => {
@@ -11,12 +10,12 @@ export const getStaticPaths: GetStaticPaths = async () => {
     }[] = []
 
     for (const locale of buildLocales()) {
-        const sortedPages = await getSortedDocsPages(locale)
+        const { pages } = await getDocsTree(locale)
         const prefix = localePrefix(locale)
 
-        for (const page of sortedPages) {
+        for (const page of pages) {
             paths.push({
-                params: { slug: `${prefix}${getCleanSlug(routedId(page))}` },
+                params: { slug: `${prefix}${page.slug}` },
                 props: { id: page.id, locale },
             })
         }
@@ -27,11 +26,10 @@ export const getStaticPaths: GetStaticPaths = async () => {
 
 export const GET: APIRoute = async ({ props }) => {
     const { id, locale } = props as { id: string; locale?: string }
-    const pages = await getSortedDocsPages(locale)
-    const entry = pages.find((page) => page.id === id)
-    if (!entry) return new Response('Not found', { status: 404 })
+    const page = (await getDocsTree(locale)).byId.get(id)
+    if (!page) return new Response('Not found', { status: 404 })
 
-    return new Response(entry.body ?? '', {
+    return new Response(page.source.body ?? '', {
         headers: { 'Content-Type': 'text/markdown; charset=utf-8' },
     })
 }

package/src/{routes → docs/routes}/llms-locale.txt.ts

@@ -1,6 +1,6 @@
 import type { APIRoute, GetStaticPaths } from 'astro'
 import { getServedLocales } from '../collection.ts'
-import { llmsResponse } from '../utils/endpoints.ts'
+import { llmsResponse } from '../endpoints.ts'
 
 export const getStaticPaths: GetStaticPaths = async () =>
     (await getServedLocales()).map((locale) => ({ params: { locale } }))

package/src/{routes → docs/routes}/llms.txt.ts

@@ -1,4 +1,4 @@
 import type { APIRoute } from 'astro'
-import { llmsResponse } from '../utils/endpoints.ts'
+import { llmsResponse } from '../endpoints.ts'
 
 export const GET: APIRoute = ({ site }) => llmsResponse(site)

package/src/{routes → docs/routes}/search-index-locale.json.ts

@@ -1,6 +1,6 @@
 import type { APIRoute, GetStaticPaths } from 'astro'
 import { getServedLocales } from '../collection.ts'
-import { searchIndexResponse } from '../utils/endpoints.ts'
+import { searchIndexResponse } from '../endpoints.ts'
 
 export const getStaticPaths: GetStaticPaths = async () =>
     (await getServedLocales()).map((locale) => ({ params: { locale } }))

package/src/{routes → docs/routes}/search-index.json.ts

@@ -1,4 +1,4 @@
 import type { APIRoute } from 'astro'
-import { searchIndexResponse } from '../utils/endpoints.ts'
+import { searchIndexResponse } from '../endpoints.ts'
 
 export const GET: APIRoute = () => searchIndexResponse()

package/src/docs/runtime.ts

@@ -0,0 +1,17 @@
+import type { DocsSection } from './config.ts'
+import type { DocsUrlOptions } from './urls.ts'
+import config from 'virtual:jaad/config'
+import { DEFAULT_LOCALE } from '../site/runtime.ts'
+
+/** The virtual config, read once. */
+export const SECTIONS: DocsSection[] = config.docs.sections
+
+/** The four fields every href builder takes, in one place. */
+export function docsUrls(locale?: string): DocsUrlOptions {
+    return {
+        docsBase: config.docs.base,
+        deploymentBase: import.meta.env.BASE_URL,
+        locale,
+        defaultLocale: DEFAULT_LOCALE,
+    }
+}

package/src/docs/search-index.ts

@@ -0,0 +1,39 @@
+import type { SearchIndex } from '../site/search.ts'
+import type { DocsSection } from './config.ts'
+import type { DocsTree } from './model/tree.ts'
+import { formatChapterTitle } from './model/ids.ts'
+import { pageChunks } from './model/rendered.ts'
+
+/** One entry per h2 and h3 of every page, plus one for the text before them. */
+export function buildSearchIndex(tree: DocsTree, sections: Pick<DocsSection, 'key' | 'label'>[]): SearchIndex {
+    const index: SearchIndex = {
+        sections: sections
+            .filter(({ key }) => tree.pages.some((page) => page.section === key))
+            .map(({ key, label }) => ({ key, label })),
+        pages: [],
+        entries: [],
+    }
+
+    for (const page of tree.pages) {
+        const chapter = formatChapterTitle(page.chapter)
+        const keywords = page.data.keywords ?? []
+        index.pages.push({
+            title: page.title,
+            href: page.href,
+            ...(page.section ? { section: page.section } : {}),
+            ...(chapter ? { chapter } : {}),
+            ...(keywords.length > 0 ? { keywords } : {}),
+        })
+
+        for (const { heading, text } of pageChunks(page.source.rendered)) {
+            if (!heading && !text) continue
+            index.entries.push({
+                page: page.index,
+                ...(heading ? { heading: heading.text, anchor: heading.slug } : {}),
+                text,
+            })
+        }
+    }
+
+    return index
+}