Status: Done, with open items (listed under Not yet written). The survey, the conversions, the checks and the probes are done; the content repositories stay separate. Results: results.md.
This round asks whether links between pages that come from different content repositories keep working after conversion, in each hands-on tool, whether the content stays in separate repositories or moves into one (R-08 cross-repository links). The RFC allows bulk conversion “as long as cross-repository links are preserved” (L131) and puts all content into one repository (L69); two requirements apply, R-15 URL identifies the source and R-16 old URLs keep working. The round adds a links check beside the outline, notes, variables and partials checks, and answers the two open items the variables and partials rounds left on relative links.
Terms used below:
cloudfoundry/docs-* repositories the
book collects. The book’s config.yml publishes each under a URL
directory: docs-cf-admin under adminguide/, docs-dev-guide under
devguide/, and so on
(config.yml L9-L90).
A link crosses a repository boundary when the page it renders on and
the page it reaches come from different repositories.../adminguide/x.html, resolved
against the page’s address), root-relative (/adminguide/x.html),
absolute (with a host), in-page (#id). The anchor or fragment
is the id after #.xref:, or the tool’s URL). Everything outside the links follows the
earlier rounds’ native conventions in both modes..html: pages published as <path>.html, the book’s
URLs; default: the tool’s default, <path>/index.html, used in one
extra variant per tool to show what breaks.docs-* repositories and the book
repository at the partials survey’s commits: 3,210 rows in the book
(2,892 in pages, partials and variable values), 1,693 in the two MkDocs
sites, and the book’s 85 redirect rules; 594 rows cross a repository
boundary; 55 already fail. The model is checked against 18 published
pages: 233 of 233 heading ids, 250 of 251 links. Script, data and
write-up: survey/.http-routing as served on
2026-10-11 in published/; the other three published pages
are the earlier rounds’ copies.| Page | Repository | Links | Cases |
|---|---|---|---|
http-routing |
cloudfoundry/docs-cloudfoundry-concepts (new) | 12 | links into two other repositories; four links held in variables, one written for its page’s depth; an absolute link to docs.cloudfoundry.org; a folder index page |
troubleshooting-router-error-responses |
cloudfoundry/docs-cf-admin (variables round) | 12 | the other end of a two-way pair with http-routing; a link whose target is a variable, into a third repository; three links already broken; an external link |
enabling-tcp-routing |
cloudfoundry/docs-cf-admin (partials round) | 7 | three links to ids on routes-domains; a fourth repository (docs-cf-cli) and its index page; a link in an indented list paragraph |
routes-domains |
cloudfoundry/docs-dev-guide (headings round) | 8 | a page two folders deep; the target of the links above, one id on an HTML heading; an HTML link; a link inside a partial; two links already broken |
How they were chosen. Decision (this round): from the survey’s rows,
pages that link to each other across repositories, taken from the earlier
rounds where possible, with together every link form the book’s content
uses (page-relative at one and two levels, root-relative, absolute, in-page,
a variable as target, links held in variable values and in a partial, an
HTML link, a folder index page) and links already broken. http-routing is
new: the earlier rounds’ test pages link to it more than to any other page
(seven links from three of them), it links back, and it holds one of the
two root-relative links in the book’s variable values. The four pages
come from three repositories; their 15 stub targets add docs-running-cf
and docs-cf-cli. Each page keeps every heading and the lines holding the
links (SOURCES).
checks/links.py reads a built page and checks its links. It needs only Python 3.
# Every link in the page's content area: href, form, target page and anchor, status
python3 -I checks/links.py SITE/concepts/http-routing.html --root SITE
# The same, against the page's links file
python3 -I checks/links.py SITE/concepts/http-routing.html --root SITE --expect intent/http-routing.links
# Links and outline checks on every test page in some variants of one site (run from sites/<tool>)
../../checks/check-site.sh build split-native mono-native
# The links check on the four published pages, at their paths
checks/check-published.sh
# What a built site serves at old URLs
python3 -I checks/redirects.py SITE /devguide/deploy-apps/domains-routes.html
What it does:
main#js-content), leaving out navigation, tables of contents, the
published page’s quick links, permalink icons and edit buttons.index.html, or PATH.html for a path with no extension (as GitHub
Pages serves it). A target that only redirects is reported as a redirect
page, not as resolving.id and <a name> of the target
page..html, a folder or no extension, absolute, external.no anchor and must stay
so.It knows nothing about these pages. make check in each site runs it and
the outline check on every test page; make check-other on the variants
that show what breaks.
<tool>/CONVENTIONS.md).Each tool keeps the version of the earlier rounds and their settings for headings; the URL settings are this round’s.
concepts/cross-repo-links/
├── README.md this file
├── results.md results per tool, across tools, conventions, requirements
├── survey/ survey.py, summary.py, ids.py, published.py, links.csv, redirects.csv, shas, checks of the model, README
├── source/ the new test page and redirects.rb, verbatim, plus SOURCES.md
├── published/ http-routing as served on 2026-10-11
├── intent/ per page: <page>.md, <page>.links (what the check compares), <page>.anchors
├── checks/ links.py, check-site.sh, check-published.sh, redirects.py
├── sites/ docusaurus/, zensical/, starlight/, antora/: pages per mode and layout, config, Makefile, probes, CONVENTIONS.md
└── results/ check output per tool, build warnings, probes, edit links, published check
Each site builds with make build and checks with make check; make
check-other, make probe-broken, make probe-depth and make
probe-redirects run the rest. Build output and installed packages are
ignored by git (each site’s .gitignore); the results in
results/ were produced from copies of the sites built outside
the repository, with the copies’ paths removed.
Decision (this round): the saved published page stays in the repository so the checks can be rerun after the live site changes, as in the earlier rounds.