cf-docs-rfc-proposal

Cross-repository links round — results

Status: draft, incomplete — covers what is known as of 2026-10-11.

What each tool did with the links of the four test pages, laid out as separate content sources and as one repository with directories. A summary across tools comes first, then one section per tool, then the questions across tools, the conventions to record and the requirements. How the pages were chosen, the terms and the modes: README. How the book writes and resolves links today: survey. Per-page links: intent/.

How to read the results:

All builds ran on 2026-10-11 with the tool versions the earlier rounds pinned: Docusaurus 3.10.2, Zensical 0.0.69, Starlight 0.42.6 (Astro 7.3.8, @astrojs/markdoc 2.0.11), Antora 3.2.1.

Summary

With each tool set to write pages as <path>.html, the book’s URLs, every link of the four test pages is as expected in every tool, in native form and in every layout the tool supports: 39 of 39. The book’s own relative .html links also work unchanged in three tools; in Starlight two links to folder index pages break. The tools differ in what a link across content sources looks like in the source, whether the build checks it, and what each tool’s layout of separate repositories allows.

  Docusaurus Zensical Starlight Antora
Separate content sources one docs plugin instance per repository folders of the one docs folder (submodules); linked folders are not built folders of the one collection, checked out or linked one component per repository, each a content source
One repository with directories one docs instance one docs folder one collection one ROOT component, a module per directory
Same URLs in both layouts yes yes yes yes
<path>.html URLs trailingSlash: false use_directory_urls = false build.format: 'file'; a folder’s index page becomes <folder>.html html_extension_style: default
Links check, native 39 of 39 (split and mono) 39 of 39 39 of 39 (mono and linked) 39 of 39 (split and mono)
Links check, passthrough 39 of 39 39 of 39 37 of 39 39 of 39
Links check, default URLs 13 of 39 15 of 39 13 of 39 13 of 39
Native link to another repository file path in mono; root-relative URL in split file path (.md) root-relative URL xref: with component (split) or module (mono)
Build reports a missing page in another source yes, broken link native only, warning with line no native only, error with page; exit 0 by default
Build reports a missing anchor in another source native only, broken anchor native only, warning with line no no
Edit link names each page’s repository yes, both layouts no, one base no, one base (per-page override possible) yes, split
Old URL redirects client-redirects plugin; not at ….html redirects plugin Astro redirects page-aliases

Docusaurus 3.10.2

Site: sites/docusaurus/ — conventions: CONVENTIONS.md.

Summary

Grid

Variant http-routing troubleshooting enabling-tcp-routing routes-domains
split-passthrough 12/12 12/12 7/7 8/8
split-native 12/12 12/12 7/7 8/8
mono-passthrough 12/12 12/12 7/7 8/8
mono-native 12/12 12/12 7/7 8/8
split-filelinks 5/12 7/12 2/7 6/8
default-passthrough 3/12 7/12 1/7 2/8

Links as expected; every outline is the same as the published page’s.

Zensical 0.0.69

Site: sites/zensical/ — conventions: CONVENTIONS.md.

Summary

Grid

Variant http-routing troubleshooting enabling-tcp-routing routes-domains
mono-passthrough 12/12 12/12 7/7 8/8
mono-native 12/12 12/12 7/7 8/8
linked-native not built not built not built not built
default-passthrough 4/12 7/12 2/7 2/8

Starlight 0.42.6

Site: sites/starlight/ — conventions: CONVENTIONS.md.

Summary

Grid

Variant http-routing troubleshooting enabling-tcp-routing routes-domains
mono-passthrough 11/12 12/12 6/7 8/8
mono-native 12/12 12/12 7/7 8/8
linked-native 12/12 12/12 7/7 8/8
default-passthrough 3/12 7/12 1/7 2/8

Antora 3.2.1

Site: sites/antora/ — conventions: CONVENTIONS.md.

Summary

Grid

Variant http-routing troubleshooting enabling-tcp-routing routes-domains
split-passthrough 12/12 12/12 7/7 8/8
split-native 12/12 12/12 7/7 8/8
mono-passthrough 12/12 12/12 7/7 8/8
mono-native 12/12 12/12 7/7 8/8
default-passthrough 3/12 7/12 1/7 2/8

Across tools

Separate sources or one repository

The RFC puts all content into “ONE single documentation repository” (L69); under R-15 URL identifies the source, its directories keep the book’s config.yml mapping. Both layouts were built in every tool:

Decision (Docs WG lead, 2026-10-11): keep separate content repositories, which differs from the RFC’s L69. Access in the cloudfoundry organization is granted per repository: each Working Group area’s approvers get “Write access for all repos in the area” (RFC-0014 L39). In one repository every team named in CODEOWNERS needs write access to all of it, so merge and push rights are no longer per area, and a CODEOWNERS line is satisfied by any one of its owners, so it cannot require both the area’s Working Group and the Docs WG. Review by path does still work: the generated branch protection sets require_code_owner_reviews: true (orgs/readme.md L59). Today all 15 docs repositories are one area of the Docs WG (docs.md L38-L60). How the site collects the repositories, Git submodules pinned by the site’s repository or a checkout at build as Bookbinder does today, is decided later. Submodules are real folders, so each tool reads them as it reads one repository.

URLs and old URLs

The same link, from enabling-tcp-routing (docs-cf-admin) to an id on routes-domains (docs-dev-guide), in each tool’s native form:

[Create a Route](../devguide/deploy-apps/routes-domains.html#create-route)
[Create a Route](../devguide/deploy-apps/routes-domains.mdx#create-route)   (mono)
[Create a Route](/devguide/deploy-apps/routes-domains#create-route)         (split)
[Create a Route](../devguide/deploy-apps/routes-domains.md#create-route)
[Create a Route](/devguide/deploy-apps/routes-domains.html#create-route)
xref:devguide::deploy-apps/routes-domains.adoc#create-route[Create a Route]   (split)
xref:devguide:deploy-apps/routes-domains.adoc#create-route[Create a Route]    (mono)

Docusaurus (mono), Zensical and Antora name the target’s source file, so the build can find it and report it when it is gone (R-11 readable source). Starlight and Docusaurus (split) name a URL.

What the build reports

  Docusaurus Zensical Starlight Antora
missing page, native broken link warning, file:line — ERROR, page
missing anchor, native broken anchor warning, file:line — —
missing page, passthrough broken link — — —
missing anchor, passthrough broken link — — —
in-page id missing broken anchor warning, file:line — INFO, at --log-level=info
the build fails onBrokenLinks: 'throw' (default) --strict — --log-failure-level (exit 2)

From the broken-link probes. Of the five links already broken in the test pages, native builds report all five in Docusaurus and Zensical, and the three in-page ones in Antora at the info level.

Two earlier rounds left this open: values with page-relative links work only at their page’s depth (variables round), and relative links inside a partial resolve against the including page (partials round). The depth probe put each link form in a variable and in a partial, on a page one folder deep and on one two folders deep:

Form Docusaurus Zensical Starlight Antora
relative URL, in a variable one depth one depth one depth one depth
relative URL, in a partial one depth one depth one depth one depth
root-relative URL, either any depth any depth any depth any depth
the tool’s own form, in a variable <Link to>: any depth file path: one depth root URL: any depth xref:: any depth
the tool’s own form, in a partial file path: any depth file path: one depth root URL: any depth xref:: any depth

So the book’s behaviour carries over to every tool for relative links, and the book’s two variables for one link (port_limitations, port_limitations_1) exist for that reason. Root-relative links, Antora xrefs, and Docusaurus file links in a partial remove the dependence on depth (probes).

The published pages

The links check on the four published pages, placed at their paths, finds the same five broken ids the book’s source has, plus one outside the excerpt (#create-route-w-port), and shows the book’s forms: of the links between site pages, 26 are root-relative, 5 page-relative (all HTML links) and 3 absolute (published check). The 4 links to /cdn-cgi/l/email-protection on routes-domains are Cloudflare’s (survey).

Conventions to record

For cf-docs-migrate convert. Decisions of this round, for review:

  1. Pages are published at the book’s URLs, <directory>/<path>.html: trailingSlash: false (Docusaurus), use_directory_urls = false (Zensical), build.format: 'file' (Starlight), html_extension_style: default (Antora). A folder’s index page keeps <folder>/index.html where the tool allows (Docusaurus slug: index); in Starlight its old URL gets a redirect. Accepted (Docs WG lead, 2026-10-11).
  2. Each content repository keeps its URL directory as a top-level folder (one repository) or as its component, instance or folder name (separate repositories), as the book’s config.yml maps it (R-15 URL identifies the source). Accepted (Docs WG lead, 2026-10-11), with separate repositories (decision).
  3. Internal links are converted to the tool’s own form: file paths (Docusaurus within one instance, Zensical), xref: (Antora), the root-relative URL the tool writes (Starlight, and Docusaurus across instances). This applies to page-relative, root-relative and absolute docs.cloudfoundry.org links alike, and to HTML <a> links to site pages.
  4. A link inside a variable’s value or a partial uses a form that does not depend on the including page: root-relative URL, xref:, or (in a Docusaurus partial) a file path. Values written for one depth, such as port_limitations and port_limitations_1, become one.
  5. Links already broken in the book are listed and fixed at the source, not changed silently by the converter; the list starts with the 55 in the survey (status broken). Accepted (Docs WG lead, 2026-10-11): fixed at the source before conversion (R-24 markup cleanup before conversion), and merged into the headings round’s broken-links.md list.
  6. The build checks internal links and anchors and fails on them in pull requests: onBrokenLinks and onBrokenAnchors: 'throw' (Docusaurus), --strict (Zensical), --log-failure-level=error (Antora, which still does not check anchors in xrefs), and a link checker such as this round’s links.py run over the built site for what a tool does not check (Starlight entirely; anchors in Antora). Accepted (Docs WG lead, 2026-10-11).
  7. Every old URL that redirects.rb still serves gets the tool’s redirect page, and old URLs whose target is gone are listed for a decision (R-16 old URLs keep working). Decided (Docs WG lead, 2026-10-11): the 30 rules whose target is gone are dropped or retargeted in the cleanup before conversion; they are listed in broken-links.md.
  8. Each page’s edit link names its own repository and file: an editUrl function (Docusaurus), edit_url per content source (Antora), editUrl front matter written by the converter (Starlight). Accepted (Docs WG lead, 2026-10-11), with separate repositories. Zensical cannot meet it as tested: repo_url and edit_uri are site settings, so every edit link points into one repository (Zensical conventions).
  9. The links check runs on every converted page, beside the outline check: checks/links.py.

Requirements

Not yet written