@cogenta/theme-docs 0.3.3 → 0.5.4

package/src/render/chrome.ts

@@ -5,120 +5,207 @@ import {
   escapeAttribute,
   escapeText,
   renderBrandMark,
+  renderFooterWidgets,
+  renderIcon,
   renderSocialLinks,
   renderThemeToggle,
   serialize,
 } from '@cogenta/theme-kit'
+import { renderSearchForm, SEARCH_PATH } from './search.js'
+import { splitSiteName, word } from './strings.js'
 
 /**
- * This theme's own header and footer — structurally distinct from the
- * canonical theme's, not a recolour of it: a docs site's header carries a
- * genuine CSS-only mobile menu (a `<details>` disclosure, never a script),
- * because "Docs / Guides / Reference / Blog" plus a header action does not
- * fit a narrow viewport the way three links do.
+ * The header and footer of a documentation site (`theme@1.4`).
  *
- * The mobile panel is a **second, hidden-by-default copy** of the same nav
- * markup, not a repositioned single copy: two static layouts (`display:none`
- * either way at a given viewport width) is the only zero-JS way to put the
- * links inline on a wide screen and inside a disclosure on a narrow one.
- * `display:none` removes the inactive copy from the accessibility tree, so a
- * screen reader is never offered two "Primary" navigations at once — only
- * the sighted, CSS-driven layout differs.
+ * Header: one bar held at the top of the window on the page's own ground,
+ * under a hairline (no blur, no translucency). The product's name as a text
+ * wordmark (or the uploaded logo), a real search field, the top sections of
+ * the site, the light/dark control, and the `headerAction` as a quiet
+ * outlined control when a site sets one.
  *
- * Footer: brand column (name + tagline), a footer nav column, social links,
- * a short "about" note, and Cogenta's own credit (or its white-label
- * replacement) — `brandingHtml` placed exactly once, unaltered.
+ * Below the wide breakpoint the sections and the search field move into a
+ * panel opened by a `<details>` disclosure: no script. The panel is a second,
+ * hidden-by-default copy of the same links: at any width exactly one copy is
+ * displayed, so a screen reader is never offered two primary navigations. A
+ * magnifier link to the search page stays in the bar, so a reader on a phone
+ * can search without opening the menu.
+ *
+ * Footer: columns, the way a developer tool's site is organised. The name,
+ * the `tagline`, the `footerNote` (a licence line, a support address) and the
+ * social profiles; then the footer navigation, split into columns at each
+ * unlinked heading (`submenu-placeholder`) an editor adds in the menu screen.
+ * Under a hairline, the copyright year and the product's name, beside the
+ * host's `brandingHtml`, placed once, as received.
+ *
+ * Footer widget columns (`theme@1.6`), when the site placed any, sit between
+ * the two, under their own hairline: a row of columns set like the footer
+ * navigation's, so a support address or a status link reads as part of the
+ * same footer rather than a band added above it.
  */
 
-function navItems(links: readonly ChromeNavLink[]): string {
-  return links
-    .filter((link) => link.href !== null || link.kind === 'submenu-placeholder')
-    .map((link) => {
-      const label = escapeText(link.label)
-      const titleAttr = link.title === null ? '' : ` title="${escapeAttribute(link.title)}"`
-      if (link.href === null) return `<li><span${titleAttr}>${label}</span></li>`
-      const href = escapeAttribute(link.href)
-      const target = link.openInNewTab ? ' target="_blank" rel="noopener"' : ''
-      return `<li><a href="${href}"${target}${titleAttr}>${label}</a></li>`
-    })
-    .join('')
+interface FooterGroup {
+  readonly heading: string | null
+  readonly links: readonly ChromeNavLink[]
+}
+
+function usable(links: readonly ChromeNavLink[]): readonly ChromeNavLink[] {
+  return links.filter((link) => link.href !== null || link.kind === 'submenu-placeholder')
+}
+
+function linkItem(link: ChromeNavLink, className: string): string {
+  const label = escapeText(link.label)
+  const titleAttr = link.title === null ? '' : ` title="${escapeAttribute(link.title)}"`
+  if (link.href === null) return `<li class="${className}"><span${titleAttr}>${label}</span></li>`
+  const target = link.openInNewTab ? ' target="_blank" rel="noopener"' : ''
+  return `<li class="${className}"><a href="${escapeAttribute(link.href)}"${target}${titleAttr}>${label}</a></li>`
 }
 
-function renderNav(links: readonly ChromeNavLink[], className: string, label: string): string {
-  const items = navItems(links)
-  return items === ''
-    ? ''
-    : `<nav class="${className}" aria-label="${label}"><ul class="cg-menu">${items}</ul></nav>`
+/** The footer menu, split into columns at each unlinked heading. */
+export function footerGroups(links: readonly ChromeNavLink[]): readonly FooterGroup[] {
+  const groups: { heading: string | null; links: ChromeNavLink[] }[] = []
+  for (const link of usable(links)) {
+    if (link.kind === 'submenu-placeholder' && link.href === null) {
+      groups.push({ heading: link.label, links: [] })
+      continue
+    }
+    const current = groups[groups.length - 1]
+    if (current === undefined) groups.push({ heading: null, links: [link] })
+    else current.links.push(link)
+  }
+  return groups.filter((group) => group.links.length > 0)
 }
 
-/** The header's own call-to-action link (`theme@1.4`), reusing `.cg-action`'s own look. */
-function renderHeaderAction(action: ChromeInput['headerAction'], className: string): string {
-  if (action === undefined) return ''
-  return (
-    `<a class="cg-action ${className}" data-emphasis="primary" ` +
-    `href="${escapeAttribute(action.href)}">${escapeText(action.label)}</a>`
-  )
+/** `footerNote` as paragraphs at blank lines, each keeping its own line breaks. */
+function renderFooterNote(note: string): string {
+  const paragraphs = note
+    .replace(/\r\n?/g, '\n')
+    .split(/\n\s*\n/)
+    .map((paragraph) =>
+      paragraph
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line !== ''),
+    )
+    .filter((lines) => lines.length > 0)
+  if (paragraphs.length === 0) return ''
+  return `<div class="cd-footer__note">${paragraphs
+    .map((lines) => `<p>${lines.map((line) => escapeText(line)).join('<br>')}</p>`)
+    .join('')}</div>`
 }
 
-/** Three bars, drawn once for this file — not part of `renderIcon`'s closed vocabulary, since a "menu" glyph names no contract B field. */
-const HAMBURGER_SVG =
-  '<svg class="cg-nav-toggle__icon" viewBox="0 0 24 24" width="22" height="22" fill="none" ' +
-  'stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true" focusable="false">' +
-  '<path d="M4 6h16M4 12h16M4 18h16"/></svg>'
+/** "Relay Docs" as the product in ink and the kind of site in grey; any other name as it is. */
+function wordmark(name: string): string {
+  const { product, suffix } = splitSiteName(name)
+  const productHtml = `<span class="cd-wordmark__product">${escapeText(product)}</span>`
+  if (suffix === null) return `<span class="cd-wordmark">${productHtml}</span>`
+  return `<span class="cd-wordmark">${productHtml} <span class="cd-wordmark__kind">${escapeText(suffix)}</span></span>`
+}
 
 export function renderChrome(input: ChromeInput): ChromeResult {
-  const siteName = escapeAttribute(input.site.name)
-  const siteNameText = escapeText(input.site.name)
-  const mark = renderBrandMark(input.brand, { className: 'cg-site-header__logo' }) ?? siteNameText
-
-  const desktopNav = renderNav(input.headerNav, 'cg-site-header__nav', 'Primary')
-  const themeToggle = serialize(renderThemeToggle(input.locale, { className: 'cg-theme-toggle' }))
-  const desktopAction = renderHeaderAction(input.headerAction, 'cg-site-header__action')
-
-  const mobileNavItems = navItems(input.headerNav)
-  const mobileAction = renderHeaderAction(input.headerAction, 'cg-nav-toggle__action')
-  const mobilePanel =
-    mobileNavItems === '' && mobileAction === ''
+  const locale = input.locale
+  const siteName = escapeText(input.site.name)
+  const home = escapeAttribute(input.homeHref)
+  const headerLinks = usable(input.headerNav)
+    .map((link) => linkItem(link, 'cd-header__item'))
+    .join('')
+
+  const logo = renderBrandMark(input.brand, { className: 'cd-header__logo' })
+  const mark = logo ?? wordmark(input.site.name)
+  const toggle = serialize(renderThemeToggle(locale, { className: 'cg-theme-toggle' }))
+  const action =
+    input.headerAction === undefined
       ? ''
-      : `<nav class="cg-nav-toggle__panel" aria-label="Primary">` +
-        `${mobileNavItems === '' ? '' : `<ul class="cg-menu">${mobileNavItems}</ul>`}` +
-        `${mobileAction}</nav>`
+      : `<a class="cg-action cd-header__action" data-emphasis="outline" href="${escapeAttribute(
+          input.headerAction.href,
+        )}">${escapeText(input.headerAction.label)}</a>`
 
-  const toggle =
-    mobilePanel === ''
+  const nav =
+    headerLinks === ''
+      ? ''
+      : `<nav class="cd-header__nav" aria-label="${escapeAttribute(word(locale, 'primary'))}">` +
+        `<ul class="cd-header__links">${headerLinks}</ul></nav>`
+
+  const searchIcon = renderIcon('search', { className: 'cd-header__search-icon', size: 20 })
+  const searchLink =
+    `<a class="cd-header__search-link" href="${SEARCH_PATH}" ` +
+    `aria-label="${escapeAttribute(word(locale, 'search'))}">` +
+    `${searchIcon === null ? '' : serialize(searchIcon)}</a>`
+
+  const panelLinks =
+    headerLinks === ''
+      ? ''
+      : `<nav class="cd-menu__nav" aria-label="${escapeAttribute(word(locale, 'primary'))}">` +
+        `<ul class="cd-menu__links">${usable(input.headerNav)
+          .map((link) => linkItem(link, 'cd-menu__item'))
+          .join('')}</ul></nav>`
+  const panelAction =
+    input.headerAction === undefined
       ? ''
-      : `<details class="cg-nav-toggle"><summary class="cg-nav-toggle__button" aria-label="Menu">${HAMBURGER_SVG}</summary>${mobilePanel}</details>`
+      : `<a class="cg-action cd-menu__action" data-emphasis="outline" href="${escapeAttribute(
+          input.headerAction.href,
+        )}">${escapeText(input.headerAction.label)}</a>`
+  const menu =
+    `<details class="cd-menu">` +
+    `<summary class="cd-menu__button" aria-label="${escapeAttribute(word(locale, 'menu'))}">` +
+    `<span class="cd-menu__bar"></span><span class="cd-menu__bar"></span></summary>` +
+    `<div class="cd-menu__panel">` +
+    `${serialize(renderSearchForm(locale, 'cd-search-menu', 'compact'))}${panelLinks}${panelAction}` +
+    `</div></details>`
 
   const header =
-    `<header class="cg-site-header"><div class="cg-site-header__inner">` +
-    `<a class="cg-site-header__home" href="${escapeAttribute(input.homeHref)}">${mark}</a>` +
-    `${desktopNav}${themeToggle}${desktopAction}${toggle}` +
+    `<header class="cd-header"><div class="cd-header__inner">` +
+    `<a class="cd-header__brand" href="${home}">${mark}</a>` +
+    `<div class="cd-header__search">${serialize(renderSearchForm(locale, 'cd-search-header', 'compact'))}</div>` +
+    `${nav}` +
+    `<div class="cd-header__end">${searchLink}${action}${toggle}${menu}</div>` +
     `</div></header>`
 
-  const footerNav = renderNav(input.footerNav, 'cg-site-footer__nav', 'Footer')
   const tagline =
     input.tagline === undefined
       ? ''
-      : `<p class="cg-site-footer__tagline">${escapeText(input.tagline)}</p>`
-  const socialElement =
-    input.social === undefined
-      ? null
-      : renderSocialLinks(input.social, {
-          className: 'cg-site-footer__social',
-          itemClassName: 'cg-site-footer__social-item',
-        })
-  const social = socialElement === null ? '' : serialize(socialElement)
-  const footerNote =
-    input.footerNote === undefined
+      : `<p class="cd-footer__tagline" data-field="tagline">${escapeText(input.tagline)}</p>`
+  const note = input.footerNote === undefined ? '' : renderFooterNote(input.footerNote)
+  const social = renderSocialLinks(input.social, {
+    className: 'cd-footer__social',
+    itemClassName: 'cd-footer__social-item',
+  })
+  const groups = footerGroups(input.footerNav)
+  const footerNav =
+    groups.length === 0
       ? ''
-      : `<p class="cg-site-footer__note">${escapeText(input.footerNote)}</p>`
+      : `<nav class="cd-footer__nav" aria-label="${escapeAttribute(word(locale, 'footer'))}" data-columns="${Math.min(groups.length, 4)}">${groups
+          .map(
+            (group) =>
+              `<div class="cd-footer__group">${
+                group.heading === null
+                  ? ''
+                  : `<p class="cd-footer__heading">${escapeText(group.heading)}</p>`
+              }<ul class="cd-footer__links">${group.links
+                .map((link) => linkItem(link, 'cd-footer__item'))
+                .join('')}</ul></div>`,
+          )
+          .join('')}</nav>`
+  const year = new Date().getFullYear()
+  const owner = escapeText(splitSiteName(input.site.name).product)
+  const footerWidgets = renderFooterWidgets(input.widgets, {
+    className: 'cd-footer__widgets',
+    headingLevel: 'h2',
+  })
 
   const footer =
-    `<footer class="cg-site-footer"><div class="cg-site-footer__grid">` +
-    `<div class="cg-site-footer__brand"><a href="${escapeAttribute(input.homeHref)}">${siteName}</a>${tagline}${social}</div>` +
-    `<div class="cg-site-footer__nav-col">${footerNav}</div>` +
-    `<div class="cg-site-footer__about-col">${footerNote}<div class="cg-site-footer__branding">${input.brandingHtml}</div></div>` +
-    `</div><div class="cg-site-footer__bottom"><span>${siteName}</span></div></footer>`
+    `<footer class="cd-footer"><div class="cd-footer__inner">` +
+    `<div class="cd-footer__about">` +
+    `<a class="cd-footer__name" href="${home}">${siteName}</a>` +
+    `${tagline}${note}` +
+    `${social === null ? '' : serialize(social)}` +
+    `</div>` +
+    `${footerNav}` +
+    `${footerWidgets === null ? '' : serialize(footerWidgets)}` +
+    `<div class="cd-footer__legal">` +
+    `<p class="cd-footer__copyright">© ${year} ${owner}</p>` +
+    `${input.brandingHtml === '' ? '' : `<div class="cd-footer__branding">${input.brandingHtml}</div>`}` +
+    `</div>` +
+    `</div></footer>`
 
   return { header, footer }
 }

package/src/render/doc-index.ts

@@ -0,0 +1,65 @@
+import type { CollectionListBlock, VocabularyBlock } from '@cogenta/blocks'
+import type { ContentEntry, RenderContext } from '@cogenta/theme-kit'
+
+/**
+ * The documentation's own order, shared by the sidebar, the home page index
+ * and previous/next.
+ *
+ * A doc page carries two plain fields: `section` (the group it belongs to)
+ * and `order` (its place in that group). Neither is a sort field contract B
+ * allows a `collectionList` to ask for (`id`/`createdAt`/`updatedAt` only),
+ * so the list is fetched by creation date and ordered here: pages within a
+ * section by `order`, then by the order they were fetched in; sections by the
+ * smallest `order` they hold, then by the order they first appear. Two pages
+ * created in the same millisecond can come back in either order, so the
+ * documentation never depends on creation time alone.
+ */
+
+export const DOC_PAGE_COLLECTION = 'doc_page'
+
+export interface DocGroup {
+  readonly section: string
+  readonly entries: readonly ContentEntry[]
+}
+
+export function isDocIndexBlock(block: VocabularyBlock): block is CollectionListBlock {
+  return block._type === 'collectionList' && block.collection === DOC_PAGE_COLLECTION
+}
+
+export function groupDocPages(
+  entries: readonly ContentEntry[],
+  ctx: RenderContext,
+): readonly DocGroup[] {
+  const groups = new Map<string, { entry: ContentEntry; position: number }[]>()
+  entries.forEach((entry, position) => {
+    const section =
+      typeof entry.section === 'string' && entry.section.trim() !== ''
+        ? entry.section.trim()
+        : ctx.t('entry.untitled')
+    const list = groups.get(section) ?? []
+    list.push({ entry, position })
+    groups.set(section, list)
+  })
+  const orderOf = (entry: ContentEntry): number =>
+    typeof entry.order === 'number' ? entry.order : Number.POSITIVE_INFINITY
+  return [...groups.entries()]
+    .map(([section, list], appearance) => ({
+      section,
+      appearance,
+      first: Math.min(...list.map((item) => orderOf(item.entry))),
+      entries: [...list]
+        .sort((a, b) => {
+          const orderA = orderOf(a.entry)
+          const orderB = orderOf(b.entry)
+          return orderA === orderB ? a.position - b.position : orderA - orderB
+        })
+        .map((item) => item.entry),
+    }))
+    .sort((a, b) => (a.first === b.first ? a.appearance - b.appearance : a.first - b.first))
+    .map(({ section, entries }) => ({ section, entries }))
+}
+
+/** The reading order of the whole documentation: every group, in turn. */
+export function readingOrder(groups: readonly DocGroup[]): readonly ContentEntry[] {
+  return groups.flatMap((group) => group.entries)
+}

package/src/render/doc-page.ts

@@ -0,0 +1,303 @@
+import type { BlockRegistry, CollectionListBlock, VocabularyBlock } from '@cogenta/blocks'
+import {
+  type ContentEntry,
+  entryHref,
+  entryTitle,
+  type FetchedEntries,
+  type HtmlElement,
+  h,
+  type PageContent,
+  pageHasOwnHeading,
+  type RenderContext,
+  withBlockKey,
+} from '@cogenta/theme-kit'
+import { type DocGroup, groupDocPages, readingOrder } from './doc-index.js'
+import { longDate } from './layout.js'
+import { type HeadingAnchor, type HeadingAnchors, headingAnchors } from './rich-text.js'
+import { word } from './strings.js'
+
+/**
+ * A documentation page: navigation, the reading column, the table of
+ * contents.
+ *
+ * The navigation comes from the page's own first block, a `collectionList` on
+ * `doc_page` that the documentation blueprint seeds on every page for this
+ * purpose (contract B has no "this block is chrome" flag, and inventing one
+ * would be a contract change for one theme's layout). It is rendered as the
+ * sidebar and dropped from the stream of content blocks.
+ *
+ * Three columns on a wide screen: the sidebar held in view as the page
+ * scrolls, the article on its measure, and "On this page" built from the
+ * article's own `h2`/`h3`. The table of contents has no scroll spy (that
+ * would need a script); it is a plain list of links that stays in view. Two
+ * columns on a laptop (the table of contents goes), one on a phone, where the
+ * navigation folds into a `<details>` disclosure at the top of the article.
+ *
+ * The sidebar is in two copies: a plain `<nav>` for wide screens, and the
+ * same links inside the disclosure for narrow ones. A closed `<details>`
+ * hides its content through the browser's own `::details-content` box, which
+ * a stylesheet cannot reliably reopen on a wide screen (verified in Chrome in
+ * L25), so the desktop column is never a disclosure. Exactly one copy is
+ * displayed at any width, so a screen reader is never offered two.
+ *
+ * Under the article: the date the page last changed, and links to the
+ * previous and next pages in the documentation's reading order. No comment
+ * form and no "was this helpful" widget: neither could be answered honestly
+ * by a static page.
+ */
+
+function sidebarLinks(
+  groups: readonly DocGroup[],
+  ctx: RenderContext,
+  current: string,
+): readonly HtmlElement[] {
+  return groups.map((group) =>
+    h(
+      'div',
+      { class: 'cd-sidenav__group' },
+      h('p', { class: 'cd-sidenav__heading' }, group.section),
+      h(
+        'ul',
+        { class: 'cd-sidenav__links' },
+        group.entries.map((entry) => {
+          const target = entryHref(entry, ctx)
+          return h(
+            'li',
+            { class: 'cd-sidenav__item' },
+            h(
+              'a',
+              {
+                class: 'cd-sidenav__link',
+                href: target,
+                'aria-current': target === current ? 'page' : undefined,
+              },
+              entryTitle(entry, ctx),
+            ),
+          )
+        }),
+      ),
+    ),
+  )
+}
+
+function renderSidebar(
+  groups: readonly DocGroup[],
+  ctx: RenderContext,
+  current: string,
+  currentEntry: ContentEntry | undefined,
+  title: string,
+): readonly HtmlElement[] {
+  const label = word(ctx.locale, 'documentation')
+  const section = typeof currentEntry?.section === 'string' ? currentEntry.section : undefined
+  return [
+    h(
+      'nav',
+      { class: 'cd-sidenav cd-sidenav--wide', 'aria-label': label },
+      sidebarLinks(groups, ctx, current),
+    ),
+    h(
+      'details',
+      { class: 'cd-sidenav-disclosure' },
+      h(
+        'summary',
+        { class: 'cd-sidenav-disclosure__summary' },
+        h('span', { class: 'cd-sidenav-disclosure__label' }, word(ctx.locale, 'menu')),
+        h(
+          'span',
+          { class: 'cd-sidenav-disclosure__where' },
+          section === undefined ? title : `${section} / ${title}`,
+        ),
+      ),
+      h(
+        'nav',
+        { class: 'cd-sidenav cd-sidenav--narrow', 'aria-label': label },
+        sidebarLinks(groups, ctx, current),
+      ),
+    ),
+  ]
+}
+
+function renderBreadcrumb(
+  ctx: RenderContext,
+  section: string | undefined,
+  title: string,
+): HtmlElement {
+  return h(
+    'nav',
+    { class: 'cd-breadcrumb', 'aria-label': word(ctx.locale, 'breadcrumb') },
+    h(
+      'ol',
+      { class: 'cd-breadcrumb__items' },
+      h('li', {}, h('a', { href: ctx.link('/') }, word(ctx.locale, 'docsHome'))),
+      section === undefined ? null : h('li', {}, section),
+      h('li', { 'aria-current': 'page' }, title),
+    ),
+  )
+}
+
+function renderToc(ctx: RenderContext, anchors: HeadingAnchors): HtmlElement | null {
+  const list = [...anchors.values()]
+  if (list.length < 2) return null
+  const items: HtmlElement[] = []
+  let children: HeadingAnchor[] = []
+  let parent: HeadingAnchor | undefined
+  const close = (): void => {
+    if (parent === undefined) {
+      for (const orphan of children) items.push(tocItem(orphan, []))
+    } else {
+      items.push(tocItem(parent, children))
+    }
+    children = []
+    parent = undefined
+  }
+  for (const anchor of list) {
+    if (anchor.level === 2) {
+      close()
+      parent = anchor
+    } else {
+      children.push(anchor)
+    }
+  }
+  close()
+  return h(
+    'nav',
+    { class: 'cd-toc', 'aria-labelledby': 'cd-toc-label' },
+    h('p', { class: 'cd-toc__label', id: 'cd-toc-label' }, word(ctx.locale, 'onThisPage')),
+    h('ol', { class: 'cd-toc__items' }, items),
+  )
+}
+
+function tocItem(anchor: HeadingAnchor, children: readonly HeadingAnchor[]): HtmlElement {
+  return h(
+    'li',
+    { class: 'cd-toc__item', 'data-level': String(anchor.level) },
+    h('a', { class: 'cd-toc__link', href: `#${anchor.id}` }, anchor.text),
+    children.length === 0
+      ? null
+      : h(
+          'ol',
+          { class: 'cd-toc__items' },
+          children.map((child) => tocItem(child, [])),
+        ),
+  )
+}
+
+function pagerLink(
+  ctx: RenderContext,
+  entry: ContentEntry | undefined,
+  direction: 'previous' | 'next',
+): HtmlElement | null {
+  if (entry === undefined) return null
+  return h(
+    'a',
+    {
+      class: 'cd-pager__link',
+      'data-direction': direction,
+      href: entryHref(entry, ctx),
+      rel: direction === 'previous' ? 'prev' : 'next',
+    },
+    h('span', { class: 'cd-pager__label' }, word(ctx.locale, direction)),
+    h('span', { class: 'cd-pager__title' }, entryTitle(entry, ctx)),
+  )
+}
+
+function renderFoot(
+  page: PageContent,
+  ctx: RenderContext,
+  order: readonly ContentEntry[],
+  currentIndex: number,
+): HtmlElement {
+  const updated = page.entry?.updatedAt
+  const previous = currentIndex > 0 ? order[currentIndex - 1] : undefined
+  const next = currentIndex >= 0 ? order[currentIndex + 1] : undefined
+  const pager =
+    previous === undefined && next === undefined
+      ? null
+      : h(
+          'nav',
+          { class: 'cd-pager', 'aria-label': word(ctx.locale, 'pager') },
+          pagerLink(ctx, previous, 'previous'),
+          pagerLink(ctx, next, 'next'),
+        )
+  return h(
+    'footer',
+    { class: 'cd-doc__foot' },
+    updated === undefined
+      ? null
+      : h(
+          'p',
+          { class: 'cd-doc__updated' },
+          `${word(ctx.locale, 'lastUpdated')} `,
+          h('time', { datetime: updated }, longDate(updated, ctx.locale)),
+        ),
+    pager,
+  )
+}
+
+export type BlockRenderer = (
+  block: VocabularyBlock,
+  ctx: RenderContext,
+  entries: FetchedEntries,
+  registry: BlockRegistry | undefined,
+  anchors: HeadingAnchors,
+) => HtmlElement | null
+
+export function renderDocPage(
+  page: PageContent,
+  ctx: RenderContext,
+  sidebarBlock: CollectionListBlock,
+  entries: FetchedEntries,
+  registry: BlockRegistry | undefined,
+  renderOne: BlockRenderer,
+): HtmlElement {
+  const groups = groupDocPages(entries[sidebarBlock._key] ?? [], ctx)
+  const order = readingOrder(groups)
+  const current = ctx.url.pathname
+  const currentIndex = order.findIndex((entry) => entryHref(entry, ctx) === current)
+  const currentEntry = currentIndex >= 0 ? order[currentIndex] : undefined
+  const section = typeof currentEntry?.section === 'string' ? currentEntry.section : undefined
+
+  const content = page.blocks.slice(1)
+  const anchors = headingAnchors(content)
+  const ownHeading = pageHasOwnHeading(content)
+  const toc = renderToc(ctx, anchors)
+
+  return h(
+    'main',
+    { class: 'cg-main cd-doc', id: 'cg-main', 'data-toc': toc === null ? 'false' : 'true' },
+    h(
+      'div',
+      { class: 'cd-doc__layout' },
+      withBlockKey(
+        h(
+          'div',
+          { class: 'cd-doc__sidebar' },
+          renderSidebar(groups, ctx, current, currentEntry, page.title),
+        ),
+        sidebarBlock._key,
+      ),
+      h(
+        'article',
+        { class: 'cd-doc__article' },
+        h(
+          'header',
+          { class: 'cd-doc__head' },
+          renderBreadcrumb(ctx, section, page.title),
+          ownHeading ? null : h('h1', { class: 'cd-doc__title' }, page.title),
+          page.entry?.excerpt === undefined
+            ? null
+            : h('p', { class: 'cd-doc__lede' }, page.entry.excerpt),
+        ),
+        h(
+          'div',
+          { class: 'cd-doc__body' },
+          content.map((block) =>
+            withBlockKey(renderOne(block, ctx, entries, registry, anchors), block._key),
+          ),
+        ),
+        renderFoot(page, ctx, order, currentIndex),
+      ),
+      toc === null ? null : h('div', { class: 'cd-doc__toc' }, toc),
+    ),
+  )
+}