cf-docs-rfc-proposal

Concept: Cross-repository links

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:

Progress

Test pages

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:

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.

Method

  1. Survey every link and resolve it against a model of the book’s site and server; check the model on published pages and live.
  2. Choose pages that link to each other across repositories and hold the book’s link forms, preferring pages already converted.
  3. Write the intent: each link’s target page and anchor.
  4. Convert into each tool, in each layout and mode. The mechanical part (headings in each tool’s syntax, links rewritten for native mode, AsciiDoc lists) was done with a scratch script; every page was then reviewed by hand.
  5. Build and check each variant with the links and outline checks, and run the probes.
  6. Record conventions per tool (sites/<tool>/CONVENTIONS.md).

Each tool keeps the version of the earlier rounds and their settings for headings; the URL settings are this round’s.

Layout

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.