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:
.html and without a
final /index), the anchor, and whether that id exists. “39 of
39” means every link of the four pages is as expected: 33 resolve, 1 is
external, and 5 already broken in the book stay broken.intent/<page>.anchors). It passes on every page in every variant
(results/)./. split lays
the repositories out as separate content sources, mono as folders of
one repository, linked as folders that are symbolic links;
passthrough writes links as the source does, native in the tool’s own
form; default uses the tool’s default URL style instead of .html.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.
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 |
/adminguide/x.html); HTML links are
published as written (survey).
Docusaurus does the same with relative URL links; Zensical and Antora
publish page-relative URLs; Starlight publishes what the page says.<path>.html URLs are the setting that matters most. With each
tool’s default folder URLs, 24 to 26 of the 39 links break in passthrough,
in every tool, since ../x.html then reaches neither the right folder
nor an existing file (check-other results).Site: sites/docusaurus/ — conventions: CONVENTIONS.md.
….mdx URLs that reach nothing
(split-filelinks, 20 of 39); the native split pages link to other
instances by root-relative URL instead..html link resolves, while Docusaurus reports 24 of them as broken
(build warnings).throw stops the
build (probe).editUrl
function (edit links).slug: index to keep …/index.html.| 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.
Site: sites/zensical/ — conventions: CONVENTIONS.md.
linked-native: no test page), so
docs-bosh’s way of mounting the bpm-release docs would not carry over..md file links are native and checked: a missing page or anchor is
a warning with file, line and column, and --strict stops the build
(probe). .html links are neither
rewritten nor checked.use_directory_urls =
false. With the default, Zensical moves relative URLs one folder
deeper and 15 of 39 links are as expected.| 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 |
Site: sites/starlight/ — conventions: CONVENTIONS.md.
linked-native passes every check (check)./adminguide/x.html, which works at any depth.<folder>.html, with format: 'file' and
'preserve' alike, so passthrough’s two links to …/index.html break
(37 of 39) and the old URLs need redirects.editUrl override.| 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 |
Site: sites/antora/ — conventions: CONVENTIONS.md.
ROOT component with a
module per directory. The URLs are the same, and the xrefs differ only in
:: against : (check).xref: is the cross-source reference: named by component or module
and path, resolved by Antora on whatever page renders it, attributes and
partials included (depth probe).page-aliases makes old URLs, across components too, as static
redirect pages or server rules
(probe).| 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 |
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.
<path>.html URLs, so no page
needs a redirect for that. Docusaurus links to its pages without the
extension, and GitHub Pages serves /x from x.html
(spot check of this repository’s site).<folder>/index.html; Docusaurus does with slug: index; Starlight
publishes <folder>.html. The book also publishes the folder form
(/concepts/architecture/), which a static host serves from
<folder>/index.html where that file exists.<old>/index.html, so an old ….html URL is not covered.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.
| 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 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).
For cf-docs-migrate convert. Decisions of this round, for review:
<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).config.yml maps it
(R-15 URL identifies the source).
Accepted (Docs WG lead, 2026-10-11), with separate repositories
(decision).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.xref:, or (in a
Docusaurus partial) a file path. Values written for one depth, such as
port_limitations and port_limitations_1, become one.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.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).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.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).config.yml directory. An edit link per repository is possible in
Docusaurus and Antora; in Starlight only per page; in Zensical not with
separate repositories..html URLs, so redirects are needed only for the
book’s existing rules and, in Starlight, for folder index pages. On a
static host a redirect is a page; anchors survive it only through
Docusaurus’s and Zensical’s scripts.starlight-links-validator and Docusaurus’s file links
to another instance by @site/ path were not tried.