@inditextech/docouture-antora-extensions 0.1.0-SNAPSHOT.40.1

package/index.js

@@ -0,0 +1,113 @@
+'use strict'
+
+const registerDuplicateLatestVersion = require('./lib/duplicate-latest-version')
+const registerFooter = require('./lib/footer')
+const registerKrokiPrewarm = require('./lib/kroki-prewarm')
+const registerLifecycleLog = require('./lib/lifecycle-log')
+const registerLlmsTxt = require('./lib/llms-txt')
+const registerNavModules = require('./lib/nav-modules')
+const registerNotFoundPage = require('./lib/not-found-page')
+const registerRedirects = require('./lib/redirects')
+const registerSearchIndex = require('./lib/search-index')
+const registerShikiPrewarm = require('./lib/shiki-prewarm')
+const registerVersionReport = require('./lib/version-report')
+
+/**
+ * Registers docouture' Antora pipeline extensions.
+ *
+ * These are ANTORA extensions, not Asciidoctor ones — a different contract
+ * and a different playbook key. They hook the site generator's own lifecycle
+ * (`antora.extensions` in the playbook), where the sibling
+ * @inditextech/docouture-asciidoc-extensions package hooks the AsciiDoc processor
+ * per page (`asciidoc.extensions`). Antora tells the two apart by inspecting
+ * `register.toString()` and warns when one is listed under the other's key.
+ *
+ * Declared with two named parameters, `(context, { config })` — GH redirects
+ * feature. @antora/site-generator's GeneratorContext._registerExtensions
+ * branches on `register.length`: zero parameters gets `register.call(context)`
+ * (no way to receive this extension entry's own playbook config at all);
+ * exactly one NAMED parameter gets `register(context)`, still no config;
+ * anything else — including this file's two — gets a plain
+ * `register(context, Object.assign({ config }, vars))` call, `config` being
+ * everything on this package's own `antora.extensions` entry in the playbook
+ * besides `enabled`/`id`/`require`. redirects.js's rules (see its own header)
+ * are authored there, not in `docs/antora.yml`, which is the one reason this
+ * package needs that config at all — every other sub-extension here still
+ * ignores it entirely. The one thing that still has to be avoided is the
+ * OTHER branch of that same detection: a parameter literally named `registry`
+ * is what trips the "Asciidoctor extension registered as an Antora extension"
+ * warning, so this stays `context`, never `registry`, same as before.
+ *
+ * REGISTRATION ORDER IS LOAD-BEARING. footer, search-index and llms-txt all
+ * listen on `navigationBuilt`, and GeneratorContext#notify awaits listeners
+ * in registration order (see nav-modules.js's own header for the citation),
+ * not declaration order within a single file — the order these calls are
+ * made IS that order. nav-modules MUST run first: it stamps `tree.module` /
+ * `tree.title` onto `componentVersion.navigation`, and both search-index and
+ * llms-txt (GH-95) read those same fields off the same event to build each
+ * record's/section's category. footer and llms-txt have no such dependency
+ * on each other and could run in either order after nav-modules; swap either
+ * of them with search-index and nothing throws — records/sections just fall
+ * back to filing themselves under the component title, as if no site
+ * declared `nav_modules` at all.
+ *
+ * shiki-prewarm (GH-89) listens on a DIFFERENT event (`contentAggregated`,
+ * not `navigationBuilt`) and touches none of the state the other four
+ * share, so its position in this list is not load-bearing the way theirs is
+ * — it is simply registered here too because this file is the one place
+ * `@antora/site-generator` is told about every docouture Antora extension.
+ *
+ * kroki-prewarm (GH-44) listens on the same `contentAggregated` event as
+ * shiki-prewarm, for the same reason (async work that must finish before
+ * Asciidoctor's synchronous conversion starts) but touches entirely
+ * different state (kroki-instance.js, not shiki-instance.js) — the two
+ * listeners are independent and their relative order is not load-bearing
+ * either.
+ *
+ * not-found-page also listens on `navigationBuilt`, but only to stash the
+ * `navigationCatalog` reference for later — it reads `tree.module` (which
+ * nav-modules.js stamps during THAT SAME event) only once `pagesComposed`
+ * fires, by which point every `navigationBuilt` listener, regardless of
+ * order, has already run to completion. Its position here is therefore not
+ * load-bearing either.
+ *
+ * version-report listens on yet another event (`contentClassified`, fired
+ * before `navigationBuilt`) and only reads `contentCatalog`, which none of
+ * the above write to — its position is not load-bearing either; it is
+ * simply a plain diagnostic report of what Antora already decided.
+ *
+ * lifecycle-log listens on EVERY documented generate-site.js event (see its
+ * own header for the full list and citation) purely to log when Antora
+ * itself enters each one and how long the previous phase took — it reads
+ * and writes no shared state at all, so its position is not load-bearing
+ * either. Registered FIRST anyway: for an event several extensions share
+ * (`contentAggregated`, `contentClassified`, `navigationBuilt`), that makes
+ * its "entering phase" trace line print before that event's own
+ * extension-specific work (and its logs) run, which reads chronologically
+ * rather than the other way round.
+ *
+ * redirects also listens on `navigationBuilt`, reading only real pages'
+ * already-computed `pub.url` — nothing nav-modules/footer/search-index/
+ * llms-txt/not-found-page write, and nothing that reads from it either — so
+ * its position is not load-bearing.
+ *
+ * duplicate-latest-version (GH #137) listens on `pagesComposed`, reading
+ * only `contentCatalog`'s already-rendered pages (`file.contents`,
+ * `file.out`, `file.pub`) and writing only new files into `siteCatalog` —
+ * nothing any other extension here reads or writes overlaps with it, so its
+ * position is not load-bearing either. Listed last simply because it's the
+ * newest addition.
+ */
+module.exports.register = function (context, { config }) {
+  registerLifecycleLog(context)
+  registerNavModules(context)
+  registerFooter(context)
+  registerSearchIndex(context)
+  registerLlmsTxt(context)
+  registerShikiPrewarm(context)
+  registerKrokiPrewarm(context)
+  registerNotFoundPage(context)
+  registerVersionReport(context)
+  registerRedirects(context, config?.redirects)
+  registerDuplicateLatestVersion(context, config)
+}

package/lib/duplicate-latest-version.js

@@ -0,0 +1,148 @@
+'use strict'
+
+/**
+ * Duplicates a component's LATEST version's already-rendered pages, images
+ * and attachments as a second, fully independent copy published under a
+ * fixed `latest` URL segment — so `/…/<real-version>/…` (`stable` in
+ * standalone mode, whichever release tag Antora computed as latest in
+ * versioned mode) AND `/…/latest/…` both serve real, non-redirect content.
+ *
+ * Why this exists instead of `urls.latest_version_segment`: every one of
+ * Antora's own `latest_version_segment_strategy` values (`replace` — the
+ * default — `redirect:to`, `redirect:from`) treats one of the two segments
+ * as a symbolic alias and reduces the OTHER one to a single root-page
+ * redirect stub; every other page under the aliased-away segment stops
+ * being real at all. For a standalone (stable/prerelease) site that meant
+ * `/…/stable/…` — the URL its own feature name promises — silently stopped
+ * resolving to real content the moment a release existed. See GH #137 and
+ * this repo's `docs-site-package` skill (`reference/versioning-modes.md`,
+ * "URL routing") for the full story.
+ *
+ * Hooked on `pagesComposed` — after Antora has rendered every page's final
+ * HTML (`file.contents`) but before redirects/sitemap/publish — so what
+ * this does is add plain, already-rendered files straight to `siteCatalog`
+ * (the same catalog redirects.js and not-found-page.js add their own
+ * site-level files to), not `contentCatalog`: nothing here needs
+ * `contentCatalog`'s key-based duplicate bookkeeping or Vinyl wrapping,
+ * since Antora's own file-publisher only ever looks at two fields on a
+ * published file — `out.path` and `contents` — regardless of which catalog
+ * it came from.
+ *
+ * No HTML rewriting is needed to make this correct. This UI bundle's own
+ * `relativize` helper (see `packages/ui-bundle/src/helpers/relativize.ts`)
+ * computes every internal href as a PATH-RELATIVE offset from the current
+ * page's own directory — a pure function of directory DEPTH, never of the
+ * literal version string. Swapping one version segment for another
+ * (`stable` → `latest`) never changes how many segments a path has, so
+ * every href already baked into a real page's rendered `contents` — nav,
+ * breadcrumbs, pagination, even the version switcher's links to sibling
+ * versions — resolves exactly as correctly from the `/latest/…` clone as it
+ * did from the source version's own tree. This also means
+ * `<link rel="canonical">` (computed off the SOURCE page's own `pub.url`
+ * and already baked into `contents` before this extension ever sees it)
+ * keeps pointing at the source version by construction — the desired
+ * default, since it avoids duplicate-content SEO issues while both URLs
+ * still return full, real, 200-status content.
+ *
+ * Mode-agnostic on purpose: this always duplicates `component.latest` (the
+ * ComponentVersion Antora itself computes as latest, excluding
+ * prereleases by default) to the `latest` segment, for every component.
+ * That happens to be `stable` in standalone mode and whichever release tag
+ * is newest in versioned mode — no mode branching needed here at all. A
+ * versioned-mode site's `/latest/…` duplicate therefore moves to a new tag
+ * automatically the next time a newer one ships; nothing here has to know
+ * that happened.
+ *
+ * Deliberately does nothing when:
+ *   - `config.duplicateLatestVersion` is not truthy (opt-in, like
+ *     `redirects.js`'s own `rules` config).
+ *   - a component has no non-prerelease version yet (`component.latest` is
+ *     itself the prerelease — no real release exists to duplicate; a fresh
+ *     standalone site with no `stable` tag yet, or a fresh versioned site
+ *     with no release tag yet, should show only `/…/prerelease/…`, not a
+ *     `/latest/…` alias for content that was never actually released).
+ *   - `component.latest.version` already equals the `latest` segment
+ *     itself (nothing to duplicate onto itself).
+ *
+ * Configured on the extension's own registration entry in the playbook —
+ * same place `redirects.js`'s rules live, for the same reason (this is
+ * build behaviour, not per-ref content). MUST be authored snake_case, like
+ * every other playbook key (`html_extension_style`, `latest_version_segment`,
+ * ...): `@antora/playbook-builder` lowercases every playbook key and only
+ * re-cases `_`/`-` boundaries back to camelCase (`build-playbook.js`'s own
+ * `camelCaseKeys`) — a camelCase-authored `duplicateLatestVersion: true`
+ * survives as `duplicatelatestversion`, which `config?.duplicateLatestVersion`
+ * below then reads as `undefined` and silently no-ops (GH #137 follow-up;
+ * this is exactly what happened the first time this shipped):
+ *
+ *     antora:
+ *       extensions:
+ *         - require: '@inditextech/docouture-antora-extensions'
+ *           duplicate_latest_version: true
+ */
+module.exports = function registerDuplicateLatestVersion(context, config) {
+  const logger = context.getLogger('docouture-duplicate-latest-version')
+  if (!config?.duplicateLatestVersion) return
+
+  const ALIAS_SEGMENT = 'latest'
+
+  context.on('pagesComposed', ({ contentCatalog, siteCatalog }) => {
+    for (const component of contentCatalog.getComponents()) {
+      const latest = component.latest
+      if (!latest || latest.prerelease) continue // no real release yet — nothing to duplicate
+      const sourceVersion = latest.version
+      if (sourceVersion === ALIAS_SEGMENT) continue // already the alias segment itself
+
+      const componentSegment = component.name === 'ROOT' ? '' : component.name
+      const sourceFiles = contentCatalog
+        .getFiles()
+        .filter((file) => file.out && file.src.component === component.name && file.src.version === sourceVersion)
+
+      let cloned = 0
+      for (const file of sourceFiles) {
+        const outPath = withReplacedVersionSegment(file.out.path, componentSegment, sourceVersion, ALIAS_SEGMENT)
+        if (outPath === undefined) {
+          logger.warn(
+            "Could not compute a '%s' alias path for %s (component '%s', version '%s') — skipping",
+            ALIAS_SEGMENT,
+            file.out.path,
+            component.name,
+            sourceVersion
+          )
+          continue
+        }
+        const clone = { out: { path: outPath }, contents: file.contents }
+        if (file.pub?.url) {
+          const pubUrl = withReplacedVersionSegment(file.pub.url, componentSegment, sourceVersion, ALIAS_SEGMENT, true)
+          if (pubUrl !== undefined) clone.pub = { url: pubUrl }
+        }
+        siteCatalog.addFile(clone)
+        cloned++
+      }
+
+      if (cloned) {
+        logger.info(
+          "Duplicated %s file(s) of %s's '%s' version under '/%s/' as a second, independent copy",
+          cloned,
+          component.name,
+          sourceVersion,
+          ALIAS_SEGMENT
+        )
+      }
+    }
+  })
+}
+
+// Replaces the `<version>` path segment in a real file's already-computed
+// `out.path` (no leading slash) or `pub.url` (leading slash) with the alias
+// segment — anchored to the exact `<component>/<version>/` (or `<version>/`
+// for the ROOT component) prefix Antora's own computeOut/computePub always
+// produce, so this never touches anything past that prefix even if the
+// version string happens to reappear later in the path (e.g. inside a page
+// name).
+function withReplacedVersionSegment(str, componentSegment, oldVersion, newVersion, leadingSlash = false) {
+  const prefix = (leadingSlash ? '/' : '') + (componentSegment ? componentSegment + '/' : '')
+  const oldSegment = prefix + oldVersion + '/'
+  if (!str.startsWith(oldSegment)) return undefined
+  return prefix + newVersion + '/' + str.slice(oldSegment.length)
+}

package/lib/duplicate-latest-version.spec.js

@@ -0,0 +1,204 @@
+'use strict'
+
+import { describe, expect, it, vi } from 'vitest'
+
+const registerDuplicateLatestVersion = require('./duplicate-latest-version')
+
+function createContext(logger = { warn: vi.fn(), info: vi.fn() }) {
+  const listeners = {}
+  return {
+    logger,
+    getLogger: () => logger,
+    on(event, fn) {
+      ;(listeners[event] ||= []).push(fn)
+    },
+    async emit(event, payload) {
+      for (const fn of listeners[event] || []) await fn(payload)
+    },
+  }
+}
+
+function createFile(component, version, module_, relative, outPath, pubUrl, contents = 'CONTENTS') {
+  return {
+    src: { component, version, module: module_, family: 'page', relative },
+    out: { path: outPath },
+    pub: { url: pubUrl },
+    contents,
+  }
+}
+
+async function run(config, { components, files, logger } = {}) {
+  const context = createContext(logger)
+  registerDuplicateLatestVersion(context, config)
+
+  const contentCatalog = {
+    getComponents: () => components,
+    getFiles: () => files,
+  }
+  const added = []
+  const siteCatalog = { addFile: (f) => added.push(f) }
+
+  await context.emit('pagesComposed', { contentCatalog, siteCatalog })
+  return { added, logger: context.logger }
+}
+
+describe('registerDuplicateLatestVersion', () => {
+  it('does nothing when duplicateLatestVersion is not set', async () => {
+    const { added } = await run(undefined, {
+      components: [{ name: 'weavejs', latest: { version: 'stable', prerelease: false } }],
+      files: [
+        createFile(
+          'weavejs',
+          'stable',
+          'main',
+          'quickstart.adoc',
+          'weavejs/stable/main/quickstart/index.html',
+          '/weavejs/stable/main/quickstart/'
+        ),
+      ],
+    })
+    expect(added).toHaveLength(0)
+  })
+
+  it('duplicates every real file of the latest (non-prerelease) version under /latest/…', async () => {
+    const { added } = await run(
+      { duplicateLatestVersion: true },
+      {
+        components: [{ name: 'weavejs', latest: { version: 'stable', prerelease: false } }],
+        files: [
+          createFile(
+            'weavejs',
+            'stable',
+            'main',
+            'quickstart.adoc',
+            'weavejs/stable/main/quickstart/index.html',
+            '/weavejs/stable/main/quickstart/'
+          ),
+          createFile(
+            'weavejs',
+            'stable',
+            'main',
+            'index.adoc',
+            'weavejs/stable/main/index.html',
+            '/weavejs/stable/main/'
+          ),
+          // a different version's own file must never be touched
+          createFile(
+            'weavejs',
+            'prerelease',
+            'main',
+            'quickstart.adoc',
+            'weavejs/prerelease/main/quickstart/index.html',
+            '/weavejs/prerelease/main/quickstart/'
+          ),
+        ],
+      }
+    )
+
+    expect(added).toHaveLength(2)
+    expect(added.map((f) => f.out.path)).toEqual(
+      expect.arrayContaining(['weavejs/latest/main/quickstart/index.html', 'weavejs/latest/main/index.html'])
+    )
+    expect(added.map((f) => f.pub.url)).toEqual(
+      expect.arrayContaining(['/weavejs/latest/main/quickstart/', '/weavejs/latest/main/'])
+    )
+    // contents are carried over verbatim — no HTML rewriting needed, since
+    // the UI's relativize helper computes hrefs from directory depth alone.
+    expect(added.every((f) => f.contents === 'CONTENTS')).toBe(true)
+  })
+
+  it('handles the ROOT component (no component URL segment)', async () => {
+    const { added } = await run(
+      { duplicateLatestVersion: true },
+      {
+        components: [{ name: 'ROOT', latest: { version: 'stable', prerelease: false } }],
+        files: [createFile('ROOT', 'stable', 'ROOT', 'index.adoc', 'stable/index.html', '/stable/')],
+      }
+    )
+
+    expect(added).toHaveLength(1)
+    expect(added[0].out.path).toBe('latest/index.html')
+    expect(added[0].pub.url).toBe('/latest/')
+  })
+
+  it('does nothing for a component with no non-prerelease version yet', async () => {
+    const { added, logger } = await run(
+      { duplicateLatestVersion: true },
+      {
+        components: [{ name: 'weavejs', latest: { version: 'prerelease', prerelease: true } }],
+        files: [
+          createFile(
+            'weavejs',
+            'prerelease',
+            'main',
+            'quickstart.adoc',
+            'weavejs/prerelease/main/quickstart/index.html',
+            '/weavejs/prerelease/main/quickstart/'
+          ),
+        ],
+      }
+    )
+
+    expect(added).toHaveLength(0)
+    expect(logger.warn).not.toHaveBeenCalled()
+  })
+
+  it('does nothing when the latest version already IS the alias segment', async () => {
+    const { added } = await run(
+      { duplicateLatestVersion: true },
+      {
+        components: [{ name: 'weavejs', latest: { version: 'latest', prerelease: false } }],
+        files: [
+          createFile(
+            'weavejs',
+            'latest',
+            'main',
+            'quickstart.adoc',
+            'weavejs/latest/main/quickstart/index.html',
+            '/weavejs/latest/main/quickstart/'
+          ),
+        ],
+      }
+    )
+
+    expect(added).toHaveLength(0)
+  })
+
+  it('duplicates each component independently across a multi-component catalog', async () => {
+    const { added } = await run(
+      { duplicateLatestVersion: true },
+      {
+        components: [
+          { name: 'weavejs', latest: { version: 'stable', prerelease: false } },
+          { name: 'other-lib', latest: { version: '2.0.0', prerelease: false } },
+        ],
+        files: [
+          createFile(
+            'weavejs',
+            'stable',
+            'main',
+            'quickstart.adoc',
+            'weavejs/stable/main/quickstart/index.html',
+            '/weavejs/stable/main/quickstart/'
+          ),
+          createFile(
+            'other-lib',
+            '2.0.0',
+            'main',
+            'quickstart.adoc',
+            'other-lib/2.0.0/main/quickstart/index.html',
+            '/other-lib/2.0.0/main/quickstart/'
+          ),
+        ],
+      }
+    )
+
+    expect(added).toHaveLength(2)
+    expect(added.map((f) => f.out.path)).toEqual(
+      expect.arrayContaining([
+        'weavejs/latest/main/quickstart/index.html',
+        'other-lib/latest/main/quickstart/index.html',
+      ])
+    )
+  })
+})

package/lib/footer.js

@@ -0,0 +1,122 @@
+'use strict'
+
+const resolveUrl = require('./resolve-url')
+
+/**
+ * Reads the site footer's authored link groups out of the component
+ * descriptor and attaches them, resolved, to the component version — where
+ * the UI bundle's `site-footer` partial finds them as
+ * `page.componentVersion.footer`.
+ *
+ * Why here and not in the playbook: `site.keys` is declared
+ * `format: 'primitive-map'` in @antora/playbook-builder's schema, so it takes
+ * flat primitives and nothing else — no list of groups, no list of links —
+ * and convict rejects any playbook key that isn't in the schema at all. The
+ * component descriptor is the one place a site can author a nested structure,
+ * which is the same conclusion nav-modules.js reached; see its header for the
+ * full list of dead ends, all of which apply here unchanged.
+ *
+ * Authored shape — lists all the way down, never a map keyed by an author's
+ * own string:
+ *
+ *     footer:
+ *       groups:
+ *         - title: Resources          # optional — GH-77, an unlabelled group renders no heading
+ *           links:
+ *             - text: Home
+ *               url: ROOT:index.adoc
+ *             - text: Repository
+ *               url: https://github.com/example/example
+ *
+ * @antora/content-aggregator runs the descriptor through `camelCaseKeys`,
+ * which recurses into nested objects and rewrites their KEYS. Fixed key names
+ * (`groups`, `links`, `text`, `url`) survive that intact; a map keyed by, say,
+ * a group's title would not. `footer` itself is untouched, and `start_page`
+ * inside nav_modules arrives as `startPage`, which is what this file and
+ * nav-modules.js read.
+ *
+ * `url` is either a page ID — the same string you would write inside
+ * `xref:...[]`, resolved against this component — or a literal URL. A page ID
+ * that resolves to nothing is dropped with a warning, so the footer never
+ * renders a dead link; that is the same rule repo-link.hbs and nav-brand.hbs
+ * follow for their own optional targets.
+ *
+ * The UI decides what to DO with the groups (the first fills the links
+ * column; the second is used for the modules column only when the component
+ * has fewer than two switchable modules). Nothing about that policy lives
+ * here: this extension resolves what was authored and stops.
+ */
+module.exports = function registerFooter(context) {
+  const logger = context.getLogger('docouture-footer')
+  // Keyed the same way @antora/navigation-builder keys its own accumulator,
+  // and the same way nav-modules.js keys its copy of the descriptors.
+  const descriptors = new Map()
+
+  // The aggregate is the last point at which the descriptor's unknown keys
+  // still exist — see nav-modules.js's own note on why this is a two-phase
+  // extension rather than a one-liner.
+  context.on('contentAggregated', ({ contentAggregate }) => {
+    for (const bucket of contentAggregate) {
+      if (!bucket.footer) continue
+      descriptors.set(bucket.version + '@' + bucket.name, bucket.footer)
+    }
+  })
+
+  // Deliberately the same event nav-modules.js uses: the content catalog is
+  // complete (so page IDs resolve) and page-composer has not yet built any UI
+  // model, so attaching to the componentVersion object is enough to reach
+  // every page of it.
+  context.on('navigationBuilt', ({ contentCatalog }) => {
+    for (const component of contentCatalog.getComponents()) {
+      for (const componentVersion of component.versions) {
+        const footer = descriptors.get(componentVersion.version + '@' + componentVersion.name)
+        if (!footer) continue
+        const resolved = resolveFooter(footer, componentVersion, contentCatalog, logger)
+        if (resolved) componentVersion.footer = resolved
+      }
+    }
+  })
+}
+
+function resolveFooter(footer, componentVersion, contentCatalog, logger) {
+  const where = `${componentVersion.name}@${componentVersion.version || 'default'}`
+
+  if (footer.constructor !== Object || !Array.isArray(footer.groups)) {
+    logger.warn('Ignoring footer in %s: expected a groups list', where)
+    return undefined
+  }
+
+  // Page IDs are resolved as if from the component's ROOT module, so a bare
+  // `index.adoc` means what an author would expect it to mean and a
+  // module-qualified `sdk:index.adoc` works without naming the component.
+  const context = { component: componentVersion.name, version: componentVersion.version, module: 'ROOT' }
+
+  const groups = []
+  for (const group of footer.groups) {
+    if (!group || group.constructor !== Object || !Array.isArray(group.links)) {
+      logger.warn('Ignoring footer group in %s: every group needs a links list', where)
+      continue
+    }
+    const links = []
+    for (const link of group.links) {
+      if (!link || link.constructor !== Object || !link.text || !link.url) {
+        logger.warn('Ignoring footer link in %s: every link needs a text and a url', where)
+        continue
+      }
+      const url = resolveUrl(link.url, contentCatalog, context)
+      if (!url) {
+        logger.warn('Dropping footer link %s in %s: %s resolves to no page', link.text, where, link.url)
+        continue
+      }
+      links.push({ text: link.text, url })
+    }
+    // An empty group would render as a blank column; drop it instead, the
+    // same way the partial itself omits a column it has no data for.
+    // `title` is optional (GH-77) — a group with links but no title still
+    // renders, just without a heading, same "omit what's unauthored" rule
+    // every other bit of this descriptor follows.
+    if (links.length) groups.push({ title: group.title, links })
+  }
+
+  return groups.length ? { groups } : undefined
+}