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

package/lib/not-found-page.js

@@ -0,0 +1,170 @@
+'use strict'
+
+const createPageComposer = require('@antora/page-composer')
+
+/**
+ * Gives the generated 404 page a real side menu, version tag and site
+ * footer — instead of the bare shell it gets by default.
+ *
+ * Why: @antora/page-composer's own `create404Page` (site-generator's
+ * generate-site.js, only invoked when `site.url` is set) builds a page whose
+ * `src` has no `component` at all:
+ *
+ *     src: { stem: '404' }
+ *
+ * `buildPageUiModel` special-cases exactly that shape — `src.stem === '404'
+ * && !('component' in src)` — and returns immediately with
+ * `{ 404: true, attributes, layout: '404', title }`, before it would ever
+ * compute `page.navigation`, `page.componentVersion` or `page.versions`. On
+ * top of that, `create404Page` calls `composePage(file)` with only ONE
+ * argument, so `navigationCatalog` is `undefined` regardless of `src` —
+ * `attachNavProperties` is gated on `if (navigationCatalog)` and would never
+ * run even for a page with a real component. There is no playbook or
+ * descriptor knob that changes any of this: it is what the library's own
+ * 404 page composer does, full stop.
+ *
+ * So this extension composes its OWN 404 page instead, using a `src` that
+ * names a real, existing component/version/module, and swaps it in for
+ * Antora's own once that one has already been added to the site catalog.
+ * Every template partial that reads `page.component`, `page.componentVersion`
+ * or `page.navigation` — the side menu, the header's version tag and search
+ * trigger, the footer's per-module links — then renders exactly as it would
+ * on a real page in that module, because as far as the UI model is
+ * concerned, it IS one; only `page-layout: 404` (set on the synthetic file's
+ * `asciidoc.attributes`, the same attribute `:page-layout: 404` would set on
+ * a real page) tells `main.hbs` to swap in `article-404.hbs` instead of the
+ * hero/toc/article trio.
+ *
+ * Component and module selection, deliberately conservative:
+ *
+ *   - Only ever runs for a site with EXACTLY ONE component. A multi-component
+ *     site (this repo has none) would need its own choice of which
+ *     component's chrome a component-less 404 page should borrow, which is a
+ *     bigger decision than this extension makes for you — the plain,
+ *     unnavigated 404 page ships instead, same as if this extension were
+ *     absent, and a warning says why.
+ *   - That component's LATEST version — a 404 page isn't itself versioned,
+ *     so "the current one" is the only sensible choice.
+ *   - The module whose navigation the side menu shows: if the component has
+ *     exactly one navigation tree (the common case — see nav-modules.js's
+ *     own comment on what a single-nav-file component's `page.navigation`
+ *     looks like), that's it, no configuration needed. With more than one —
+ *     `example`'s seven modules are exactly this — `not_found_module` in
+ *     the component descriptor (`docs/antora.yml`) names which one:
+ *
+ *         not_found_module: main
+ *
+ *     Left unset on a multi-module component, the 404 page still gets its
+ *     real version tag, search trigger and footer (all keyed off the
+ *     component/version alone) — only the side menu's tree stays empty,
+ *     which is what nav-menu.hbs already does for a `page.module` that
+ *     matches no tree — same "no fallback to first tree, an empty menu is a
+ *     missing attribute" rule nav-modules.js's own header argues for the
+ *     switcher.
+ */
+module.exports = function registerNotFoundPage(context) {
+  const logger = context.getLogger('docouture-not-found-page')
+  // Keyed the same way nav-modules.js and footer.js key their own copies.
+  const notFoundModules = new Map()
+  let navigationCatalog
+
+  // Same two-phase shape as nav-modules.js/footer.js: `not_found_module`
+  // only survives on the raw aggregate, so it has to be copied out here,
+  // before `vars.remove('contentAggregate')` (generate-site.js) drops it.
+  context.on('contentAggregated', ({ contentAggregate }) => {
+    for (const bucket of contentAggregate) {
+      if (!bucket.notFoundModule) continue
+      notFoundModules.set(bucket.version + '@' + bucket.name, bucket.notFoundModule)
+    }
+  })
+
+  // `navigationBuilt` is the last event carrying `navigationCatalog` — see
+  // this file's own header on why it's needed and why create404Page never
+  // gets it. Captured here, read at `pagesComposed`, once nav-modules.js's
+  // own `navigationBuilt` listener (registered before this one, see index.js)
+  // has already stamped `tree.module` on every tree.
+  context.on('navigationBuilt', ({ navigationCatalog: catalog }) => {
+    navigationCatalog = catalog
+  })
+
+  context.on('pagesComposed', ({ playbook, contentCatalog, uiCatalog, siteCatalog, siteAsciiDocConfig }) => {
+    // Antora only composes a 404 page at all when site.url is set
+    // (generate-site.js) — nothing to enhance otherwise.
+    if (!playbook.site.url) return
+    if (!navigationCatalog) return // defensive; always set by this point when site.url is present
+
+    const components = contentCatalog.getComponents()
+    if (components.length !== 1) {
+      logger.warn(
+        'Not enhancing the generated 404 page: expected exactly one component, found %s. ' +
+          'It keeps the plain, unnavigated layout Antora composes by default.',
+        components.length
+      )
+      return
+    }
+
+    const component = components[0]
+    const componentVersion = component.latest
+    const navigation = navigationCatalog.getNavigation(component.name, componentVersion.version) || []
+
+    let module_
+    if (navigation.length === 1) {
+      // The common case: one nav file, so nothing to pick between — see
+      // nav-modules.js's own comment on why `page.navigation` looks like
+      // this for a single-nav-file component. `tree.module` is usually
+      // unset here too (no nav_modules declared), which nav-menu.hbs treats
+      // the same way: `(not ./module)` renders it unconditionally.
+      module_ = navigation[0].module
+    } else if (navigation.length > 1) {
+      const where = `${component.name}@${componentVersion.version || 'default'}`
+      const configured = notFoundModules.get(componentVersion.version + '@' + component.name)
+      if (!configured) {
+        logger.warn(
+          '%s has %s navigation modules and no not_found_module configured in its antora.yml: ' +
+            "the 404 page's side menu will render empty. Set not_found_module to the module whose " +
+            'navigation it should show.',
+          where,
+          navigation.length
+        )
+      } else if (!navigation.some((tree) => tree.module === configured)) {
+        logger.warn(
+          "not_found_module '%s' in %s matches no navigation file; the 404 page's side menu will render empty.",
+          configured,
+          where
+        )
+      } else {
+        module_ = configured
+      }
+    }
+
+    const file = {
+      mediaType: 'text/html',
+      out: { path: '404.html' },
+      pub: { url: '/404.html' },
+      src: {
+        component: component.name,
+        version: componentVersion.version,
+        module: module_,
+        family: 'page',
+        relative: 'index.adoc',
+      },
+      title: siteAsciiDocConfig?.attributes['404-page-title'] || 'Page Not Found',
+      // Cloned, not shared: mutating the site-wide asciidoc config in place
+      // would leak `page-layout: 404` onto every other page composePage
+      // touches from here on.
+      asciidoc: Object.assign({}, siteAsciiDocConfig, {
+        attributes: Object.assign({}, siteAsciiDocConfig?.attributes, { 'page-layout': '404' }),
+      }),
+    }
+
+    // A fresh composer, not the pipeline's own (createPageComposer's result
+    // isn't threaded through to extensions) — built from the same
+    // `uiCatalog`, so it compiles the identical layouts/partials/helpers the
+    // rest of the site just rendered with.
+    createPageComposer(playbook, contentCatalog, uiCatalog).composePage(file, contentCatalog, navigationCatalog)
+
+    const previous = siteCatalog.getFiles().find((candidate) => candidate.out?.path === '404.html')
+    if (previous) siteCatalog.removeFile(previous)
+    siteCatalog.addFile(file)
+  })
+}

package/lib/redirects.js

@@ -0,0 +1,249 @@
+'use strict'
+
+const produceRedirects = require('@antora/redirect-producer')
+
+/**
+ * Generates static redirect stubs from literal, arbitrary legacy URLs (e.g.
+ * a Fumadocs-era `/weavejs/docs/main/quickstart`) to whatever real page
+ * currently answers the equivalent URL in this site (e.g.
+ * `/weavejs/latest/main/quickstart`) — for migrated content whose old URL
+ * shape doesn't fit Antora's own `component:version:module:family/relative`
+ * page-ID grammar, so the built-in `page-aliases` attribute can't reach it.
+ *
+ * Configured on the EXTENSION'S OWN registration entry in the playbook, not
+ * in `docs/antora.yml` — unlike nav_modules/footer/llms, which are
+ * versioned per ref (see nav-modules.js's own header for why those live in
+ * the component descriptor instead of `site.keys`), these rules are
+ * evaluated fresh against whatever pages a given build actually resolves,
+ * regardless of which refs that build aggregates, so there is nothing to
+ * gain from repeating the list on every tag — one copy, in the one
+ * playbook, covers every build:
+ *
+ *     antora:
+ *       extensions:
+ *         - require: '@inditextech/docouture-antora-extensions'
+ *           redirects:
+ *             - from: '/weavejs/docs/main/build/node/comment'
+ *               to: '/weavejs/latest/main/build/nodes/comment'
+ *             - from: '/weavejs/docs/**'
+ *               to: '/weavejs/latest/**'
+ *
+ * Both `from` and `to` are literal URL templates, not resource IDs — `*`
+ * captures exactly one path segment, `**` captures everything remaining
+ * (potentially several segments). `to` is the side that gets matched
+ * against every REAL page's own already-computed `pub.url`: only actually
+ * published content can be a redirect target, so matching against it (and
+ * never against another alias/redirect Antora itself may have produced,
+ * e.g. urls.latest_version_segment's own stubs) is what keeps a rule from
+ * ever chaining two redirects together. A `to` naming a segment that's
+ * currently just an alias itself — `/weavejs/stable/**` while
+ * `latest_version_segment`'s default `replace` strategy is active — matches
+ * nothing, on purpose: `/weavejs/latest/**` is the only target guaranteed
+ * to always be real content, release after release.
+ *
+ * `from`'s wildcards are filled in, in the order they appear, with the
+ * segment(s) `to`'s matching wildcards captured — so a rule's `from` and
+ * `to` must carry the same number of wildcards, checked once per rule at
+ * registration time, not per match.
+ *
+ * Rules are tried in authoring order and are first-match-wins: once a
+ * legacy URL has been claimed by an earlier rule, a later rule computing
+ * the same legacy URL is silently skipped — this is the intended mechanism
+ * for layering a handful of exact overrides ahead of one broad `**`
+ * catch-all, not a bug. A rule whose computed legacy URL collides with a
+ * REAL page's own URL is different — that's never silently allowed, since
+ * it would mean overwriting real content with a redirect stub.
+ *
+ * A rule that matches zero real pages warns (and, under this site's
+ * `runtime.log.failure_level: warn`, fails the build) — the same treatment
+ * as a broken xref — rather than silently shipping a rule that never does
+ * anything, which is how a typo, or a `to` accidentally naming an
+ * alias-only segment, would otherwise go unnoticed.
+ *
+ * Reuses @antora/redirect-producer, the same library `urls.
+ * latest_version_segment` and the built-in `page-aliases` attribute are
+ * built on, so whatever `redirect_facility` the playbook is configured with
+ * (static — the default, and what this site and any plain static host like
+ * GitHub Pages need — or nginx/httpd/netlify/gitlab) gets the right output
+ * format for these rules too, for free.
+ */
+module.exports = function registerRedirects(context, rules) {
+  const logger = context.getLogger('docouture-redirects')
+  if (rules === undefined) return
+  if (!Array.isArray(rules)) {
+    logger.warn('Ignoring redirects extension config: expected a list of {from, to} rules, got %s', typeof rules)
+    return
+  }
+
+  const compiled = compileRules(rules, logger)
+  if (!compiled.length) return
+
+  context.on('navigationBuilt', ({ contentCatalog, siteCatalog, playbook }) => {
+    const htmlExtensionStyle = playbook.urls?.htmlExtensionStyle
+    const pages = contentCatalog.getPages((page) => page.out)
+    // Trailing-slash-normalized: a real page's own pub.url and a computed
+    // alias's pub.url are both built from this same html_extension_style,
+    // so in a real build they already agree — normalizing here is just
+    // cheap insurance, not a workaround for a real discrepancy.
+    const realUrls = new Set(pages.map((page) => stripTrailingSlash(page.pub.url)))
+    const aliasFiles = []
+
+    // Raw match count per rule, computed independently of precedence below
+    // — a rule that never matches ANY real page is worth flagging even when
+    // every page it WOULD have matched was going to lose to an earlier,
+    // higher-priority rule anyway (so it can't be derived from the
+    // precedence loop, which stops looking at a page once an earlier rule
+    // already claims it).
+    const rawMatchCounts = compiled.map((rule) => pages.filter((page) => rule.toRegex.test(page.pub.url)).length)
+
+    for (const page of pages) {
+      // First rule (in authoring order) whose `to` matches this page wins —
+      // a later rule (e.g. a broad `**` catch-all) never gets a say once an
+      // earlier, more specific rule already claims the same real page, even
+      // if it would have computed a different legacy URL.
+      for (const rule of compiled) {
+        const match = rule.toRegex.exec(page.pub.url)
+        if (!match) continue
+
+        const legacyPath = substitute(rule.from, match.slice(1))
+        const { pubUrl, outPath } = buildUrlAndOutPath(legacyPath, htmlExtensionStyle)
+
+        if (realUrls.has(stripTrailingSlash(pubUrl))) {
+          logger.warn(
+            "Skipping redirects rule (from: '%s', to: '%s'): computed legacy URL %s collides with a real page",
+            rule.from,
+            rule.to,
+            pubUrl
+          )
+        } else {
+          aliasFiles.push({ out: { path: outPath }, pub: { url: pubUrl }, rel: { pub: { url: page.pub.url } } })
+        }
+        break // this page is claimed (matched or collided) — no lower-priority rule gets to touch it
+      }
+    }
+
+    compiled.forEach((rule, i) => {
+      if (!rawMatchCounts[i]) {
+        logger.warn("redirects rule (from: '%s', to: '%s') matched no real pages", rule.from, rule.to)
+      }
+    })
+
+    if (!aliasFiles.length) return
+
+    // Mirrors what @antora/site-generator's own generate-site.js does with
+    // Antora's own alias family: for the 'static' facility (this site's
+    // default, and the only one a plain static host like GitHub Pages can
+    // use) produceRedirects mutates each file's `contents` in place and
+    // returns an empty array; for nginx/httpd/netlify/gitlab it instead
+    // returns the one rewrite-rule file to add, having stripped `out` off
+    // the (now unpublished as individual files) aliases itself.
+    const produced = produceRedirects(playbook, aliasFiles)
+    if (produced.length) {
+      for (const file of produced) siteCatalog.addFile(file)
+    } else {
+      for (const file of aliasFiles) if (file.out) siteCatalog.addFile(file)
+    }
+  })
+}
+
+function compileRules(rules, logger) {
+  const compiled = []
+  for (const rule of rules) {
+    if (!rule || typeof rule.from !== 'string' || typeof rule.to !== 'string') {
+      logger.warn('Ignoring malformed redirects rule: %s', JSON.stringify(rule))
+      continue
+    }
+    const { regex, wildcardCount } = compilePattern(rule.to)
+    const fromWildcardCount = countWildcards(rule.from)
+    if (fromWildcardCount !== wildcardCount) {
+      logger.warn(
+        "Ignoring redirects rule (from: '%s', to: '%s'): wildcard count mismatch (%s vs %s)",
+        rule.from,
+        rule.to,
+        fromWildcardCount,
+        wildcardCount
+      )
+      continue
+    }
+    compiled.push({ from: rule.from, to: rule.to, toRegex: regex })
+  }
+  return compiled
+}
+
+// Compiles a literal URL template into a matching RegExp: '*' captures one
+// path segment, '**' captures everything remaining (including slashes).
+// Longest-token-first so '**' is never mistaken for two '*' matches.
+function compilePattern(template) {
+  let pattern = ''
+  let wildcardCount = 0
+  let i = 0
+  while (i < template.length) {
+    if (template[i] === '*') {
+      if (template[i + 1] === '*') {
+        pattern += '(.+)'
+        i += 2
+      } else {
+        pattern += '([^/]+)'
+        i += 1
+      }
+      wildcardCount++
+    } else {
+      pattern += escapeRegExp(template[i])
+      i += 1
+    }
+  }
+  return { regex: new RegExp('^' + pattern + '$'), wildcardCount }
+}
+
+function countWildcards(template) {
+  let count = 0
+  let i = 0
+  while (i < template.length) {
+    if (template[i] === '*') {
+      count++
+      i += template[i + 1] === '*' ? 2 : 1
+    } else {
+      i += 1
+    }
+  }
+  return count
+}
+
+// Fills a template's wildcards, in the order they appear, with the given
+// captured segments — the counterpart to compilePattern's capture order.
+function substitute(template, captures) {
+  let result = ''
+  let captureIdx = 0
+  let i = 0
+  while (i < template.length) {
+    if (template[i] === '*') {
+      result += captures[captureIdx++]
+      i += template[i + 1] === '*' ? 2 : 1
+    } else {
+      result += template[i]
+      i += 1
+    }
+  }
+  return result
+}
+
+function escapeRegExp(char) {
+  return /[.*+?^${}()|[\]\\]/.test(char) ? '\\' + char : char
+}
+
+// Mirrors @antora/content-classifier's own URL/out-path computation for the
+// two html_extension_style values that matter here — 'indexify' (this
+// site's own setting) and Antora's 'default' — since a synthetic redirect
+// stub gets no calculatePub pass of its own; it has to be built by hand
+// to match the shape everything else on the site already uses.
+function buildUrlAndOutPath(literalPath, htmlExtensionStyle) {
+  const trimmed = literalPath.replace(/^\/+/, '').replace(/\/+$/, '')
+  if (htmlExtensionStyle === 'indexify') {
+    return { pubUrl: '/' + trimmed + '/', outPath: trimmed + '/index.html' }
+  }
+  return { pubUrl: '/' + trimmed + '.html', outPath: trimmed + '.html' }
+}
+
+function stripTrailingSlash(url) {
+  return url.endsWith('/') ? url.slice(0, -1) : url
+}

package/lib/redirects.spec.js

@@ -0,0 +1,129 @@
+'use strict'
+
+import { describe, expect, it, vi } from 'vitest'
+
+const registerRedirects = require('./redirects')
+
+function createContext(logger = { warn: vi.fn(), info: () => {} }) {
+  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 createPage(url) {
+  return { out: true, pub: { url } }
+}
+
+function warnedAbout(logger, text) {
+  return logger.warn.mock.calls.some((call) => typeof call[0] === 'string' && call[0].includes(text))
+}
+
+async function run(rules, { pages, htmlExtensionStyle = 'indexify', logger } = {}) {
+  const context = createContext(logger)
+  registerRedirects(context, rules)
+
+  const contentCatalog = { getPages: (filterFn) => pages.filter(filterFn) }
+  const files = []
+  const siteCatalog = { addFile: (f) => files.push(f) }
+  const playbook = { site: {}, urls: { htmlExtensionStyle, redirectFacility: 'static' } }
+
+  await context.emit('navigationBuilt', { contentCatalog, siteCatalog, playbook })
+  return { files, logger: context.logger }
+}
+
+describe('registerRedirects', () => {
+  it('redirects an exact legacy URL to the real page it now lives at', async () => {
+    const { files } = await run([{ from: '/weavejs/docs/main', to: '/weavejs/latest/main' }], {
+      pages: [createPage('/weavejs/latest/main')],
+    })
+
+    expect(files).toHaveLength(1)
+    const [file] = files
+    expect(file.pub.url).toBe('/weavejs/docs/main/')
+    expect(file.out.path).toBe('weavejs/docs/main/index.html')
+    expect(file.contents.toString()).toContain('location="../../latest/main"')
+  })
+
+  it('carries a single-segment wildcard through from `to` into `from`', async () => {
+    const { files } = await run([{ from: '/weavejs/docs/main/*', to: '/weavejs/latest/main/*' }], {
+      pages: [createPage('/weavejs/latest/main/quickstart'), createPage('/weavejs/latest/sdk/index')],
+    })
+
+    expect(files).toHaveLength(1)
+    expect(files[0].pub.url).toBe('/weavejs/docs/main/quickstart/')
+  })
+
+  it('carries a multi-segment ** wildcard through unchanged', async () => {
+    const { files } = await run([{ from: '/weavejs/docs/**', to: '/weavejs/latest/**' }], {
+      pages: [
+        createPage('/weavejs/latest/main/build/nodes/comment/'),
+        createPage('/weavejs/prerelease/main/build/nodes/comment/'), // different version, should not match
+      ],
+    })
+
+    expect(files).toHaveLength(1)
+    expect(files[0].pub.url).toBe('/weavejs/docs/main/build/nodes/comment/')
+  })
+
+  it('applies an exact override ahead of a broader ** catch-all, first-match-wins', async () => {
+    const { files } = await run(
+      [
+        { from: '/weavejs/docs/main/build/node/comment', to: '/weavejs/latest/main/build/nodes/comment' },
+        { from: '/weavejs/docs/**', to: '/weavejs/latest/**' },
+      ],
+      { pages: [createPage('/weavejs/latest/main/build/nodes/comment')] }
+    )
+
+    // Both rules match the same real page; only the first rule's computed
+    // legacy URL should win — the catch-all's own (different) legacy URL
+    // for the same page must not also be emitted.
+    expect(files).toHaveLength(1)
+    expect(files[0].pub.url).toBe('/weavejs/docs/main/build/node/comment/')
+  })
+
+  it('warns and skips a rule whose from/to wildcard counts do not match', async () => {
+    const logger = { warn: vi.fn(), info: () => {} }
+    const { files } = await run([{ from: '/weavejs/docs/*/*', to: '/weavejs/latest/**' }], {
+      pages: [createPage('/weavejs/latest/main/quickstart/')],
+      logger,
+    })
+
+    expect(files).toHaveLength(0)
+    expect(warnedAbout(logger, 'wildcard count mismatch')).toBe(true)
+  })
+
+  it('warns when a rule matches no real pages', async () => {
+    const logger = { warn: vi.fn(), info: () => {} }
+    const { files } = await run([{ from: '/weavejs/docs/main', to: '/weavejs/stable/main' }], {
+      pages: [createPage('/weavejs/latest/main/')],
+      logger,
+    })
+
+    expect(files).toHaveLength(0)
+    expect(warnedAbout(logger, 'matched no real pages')).toBe(true)
+  })
+
+  it('warns and skips when a computed legacy URL collides with a real page', async () => {
+    const logger = { warn: vi.fn(), info: () => {} }
+    const { files } = await run([{ from: '/weavejs/latest/main', to: '/weavejs/docs/main' }], {
+      pages: [createPage('/weavejs/docs/main'), createPage('/weavejs/latest/main')],
+      logger,
+    })
+
+    expect(files).toHaveLength(0)
+    expect(warnedAbout(logger, 'collides with a real page')).toBe(true)
+  })
+
+  it('does nothing when no redirects config is provided', async () => {
+    const { files } = await run(undefined, { pages: [] })
+    expect(files).toHaveLength(0)
+  })
+})

package/lib/resolve-url.js

@@ -0,0 +1,45 @@
+'use strict'
+
+// A page ID always names an AsciiDoc source file, so that extension is what
+// tells the two forms apart — not the presence of a colon, which both use:
+//
+//   ROOT:index.adoc        page ID (module-qualified)
+//   weavejs:sdk:index.adoc page ID (component-qualified)
+//   https://example.com    URL
+//   mailto:docs@example    URL
+//   /weavejs/index.html    URL (root-relative)
+//
+// Matching on "looks like a URI scheme" instead is what a first cut of this
+// did, and it is wrong: `ROOT:` is a perfectly good scheme as far as a
+// case-insensitive pattern is concerned, so every module-qualified page ID
+// written in the conventional uppercase ROOT sailed through unresolved and
+// rendered as a literal href.
+const PAGE_ID_RX = /\.adoc$/
+
+/**
+ * Resolve an authored link target to a URL.
+ *
+ * Page IDs are resolved against `context` — a component/version/module triple
+ * — so a bare `index.adoc` or a module-qualified `sdk:index.adoc` both work
+ * from a component descriptor, the same way they would from a page in that
+ * component's ROOT module. A trailing `#fragment` is kept and re-attached to
+ * the resolved URL; Antora's own resolvePage does not take one.
+ *
+ * Returns undefined for a page ID that resolves to nothing, so the caller can
+ * drop the link rather than render one that goes nowhere. Anything that is
+ * not a page ID is returned unchanged.
+ *
+ * @param {String} spec - a page ID or a literal URL
+ * @param {Object} contentCatalog - Antora's content catalog
+ * @param {Object} context - { component, version, module } to resolve against
+ * @returns {String|undefined}
+ */
+module.exports = function resolveUrl(spec, contentCatalog, context) {
+  if (typeof spec !== 'string' || !spec) return undefined
+  const hashIdx = spec.indexOf('#')
+  const target = hashIdx === -1 ? spec : spec.slice(0, hashIdx)
+  const hash = hashIdx === -1 ? '' : spec.slice(hashIdx)
+  if (!PAGE_ID_RX.test(target)) return spec
+  const url = contentCatalog.resolvePage(target, context)?.pub?.url
+  return url ? url + hash : undefined
+}