cf-docs-rfc-proposal

Heading survey

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

This survey lists every heading in the source of the book’s 12 repositories. It was done to choose the test pages of the Headings round (test pages): pages whose headings show a case that a conversion could break. It reads the repositories at the commits the table survey used (shas.txt).

The round’s first scan of this kind was not kept. This survey redoes it with a committed script and data.

File What it is
headings.csv One row per heading, 2,164 rows, each with a GitHub link to the heading at the surveyed commit
pages.csv One row per page, 320 rows, pages without headings included
scan.py Finds and measures the headings in a set of clones

Scope

Repositories. The book is the set of repositories that Bookbinder, the tool that builds docs.cloudfoundry.org today, collects into one site (glossary). Its sections are the 12 cloudfoundry/docs-* repositories named in the book’s config.yml at commit 30dfa57. All 12 are scanned. The file also names sample apps and cf-release as dependent sections; those are not documentation pages and are not scanned.

Repository Commit (date) Pages With headings Headings
cloudfoundry/docs-bbr 5146595 (2026-07-09) 9 8 116
cloudfoundry/docs-buildpacks 239e5c8 (2026-10-09) 62 50 434
cloudfoundry/docs-cf-admin 13826fa (2026-07-22) 50 29 255
cloudfoundry/docs-cf-cli ee9aad5 (2026-07-22) 8 8 60
cloudfoundry/docs-cloudfoundry-concepts 97e0d0b (2026-09-14) 41 27 225
cloudfoundry/docs-credhub 21b0448 (2026-07-23) 8 8 47
cloudfoundry/docs-deploying-cf 1113cfa (2026-07-24) 13 11 66
cloudfoundry/docs-dev-guide 9c8df63 (2026-09-28) 67 53 503
cloudfoundry/docs-loggregator 8e027ba (2026-07-22) 12 9 84
cloudfoundry/docs-running-cf 956acc8 (2026-08-05) 32 22 221
cloudfoundry/docs-services ccb0036 (2026-07-22) 11 10 76
cloudfoundry/docs-uaa 216c797 (2026-07-22) 7 6 77
All   320 241 2,164

The date is the commit’s date. The commits are the ones in the table survey’s shas.txt; this folder does not keep its own copy.

Method

scan.py reads every page and skips the parts that cannot hold a heading:

In what is left it finds two kinds of heading:

For each heading, headings.csv records:

Column What it holds
repo, file, line where the heading starts
level 1 to 6 (## and <h2> are both 2)
kind markdown or html
ids, id_source the explicit id, and where it was found: inline (an <a id="…"> or <a name=…> inside the heading), line-before (an anchor alone on the line just above), attribute (id= on the <hN> tag), or empty
text the heading’s text, HTML tags removed, ERB tags kept
code it holds a backtick or <code>
link it holds a Markdown link or an <a href>
erb it holds an ERB tag (<%)
no_space a Markdown heading with no space after the #s
skipped_level it is more than one level deeper than the heading before it on the page
url a link to the heading’s line at the surveyed commit

An explicit id is one the source writes; a page’s other headings get an id the build makes from their text.

For each page, pages.csv records whether it is a partial, its heading count, the level of its first heading, the count per level, the Markdown and HTML counts, the headings with and without an explicit id, the number of skipped levels and the line of the first, and a link to the file. Two more columns count lines the scan does not take as headings: # lines indented four or more spaces (an indented code block in Markdown), and setext underlines (a line of === or --- under a line of text, the other Markdown heading syntax). Both are 0 on every page.

Totals

From headings.csv and pages.csv:

Findings

Skipped levels

A level is skipped when a heading is more than one level deeper than the heading before it, such as ## followed by ####. Only headings after a page’s first are checked. Three headings on two pages skip a level:

HTML heading tags

Two pages use HTML heading tags, both in docs-dev-guide. All 16 carry an <a id> inside the tag.

Variables in headings

27 headings on 15 pages hold an ERB tag, all of them a variable such as <%= vars.app_runtime_abbr %> (glossary). Example: docs-cf-admin troubleshooting_slow_requests L422.

No space after the #s

97 Markdown headings on 20 pages have no space after the #s, as in ##<a id='benchmark-setup'></a> Benchmarking (docs-running-cf uaa-performance L25). By repository: running-cf 40, buildpacks 25, deploying-cf 16, dev-guide 9, cloudfoundry-concepts 4, cf-admin 3.

The book renders them as headings: the published page (as served on 2026-10-10; not pinned) shows “Benchmarking” as an <h2>. CommonMark (glossary) requires the space (spec 0.31.2, ATX headings), so a tool built on it reads these lines as paragraphs. A conversion has to add the space.

The same id twice on a page

18 explicit ids appear on more than one heading of the same page: 40 headings on 17 pages. None of these pages uses an ERB if, so every copy is published. A link to such an id reaches only the first. Examples:

To list them all, group headings.csv by repo, file and ids.

An h1 in the body

One page has a # heading: docs-loggregator opentelemetry (L11). The book also prints the front-matter title as an h1, so the published page (as served on 2026-10-10; not pinned) has both the title and “Collector configuration structure” as <h1>.

Fences closed the book’s way

docs-bbr backup closes a code block with <br> ([L76](https://github.com/cloudfoundry/docs-bbr/blob/51465950ce3a2196d66a9339086b94feed280c3e/backup.html.md.erb#L76)), and opens one with four backticks and closes it with three ([L359](https://github.com/cloudfoundry/docs-bbr/blob/51465950ce3a2196d66a9339086b94feed280c3e/backup.html.md.erb#L359)). The [published page](https://docs.cloudfoundry.org/bbr/backup.html) (as served on 2026-10-10; not pinned) closes both blocks there: its six headings after L76 are all <h2>`s. The scan closes them the same way. In CommonMark neither line closes the block, so the rest of the page would become code. A conversion has to repair both lines (R-24 markup cleanup before conversion).

Compared with the round’s first scan

The round’s README and results describe a first scan of 11 repositories: about 1,950 headings on 225 pages with headings. Which repository it left out is not recorded. This scan covers all 12.

How to rerun

Run everything from a working directory outside this repository, with python3 -I (isolated mode: Python ignores the current directory and environment variables when it loads modules). SURVEY below stands for this folder, concepts/headings/survey.

Clone the 12 repositories at the table survey’s commits, then scan them:

grep -E '^docs-(bbr|buildpacks|cf-admin|cf-cli|cloudfoundry-concepts|credhub|deploying-cf|dev-guide|loggregator|running-cf|services|uaa) ' \
  SURVEY/../../tables/survey/shas.txt > shas-book.txt
mkdir -p repos
while read name sha date; do
  git clone --quiet "https://github.com/cloudfoundry/$name" "repos/$name"
  git -C "repos/$name" checkout --quiet "$sha"
done < shas-book.txt

python3 -I SURVEY/scan.py repos shas-book.txt out
cmp out.csv SURVEY/headings.csv
cmp out-pages.csv SURVEY/pages.csv

scan.py writes out.csv and out-pages.csv and prints the totals above. It was run twice on 2026-10-10 and both runs gave byte-identical files. The script reads files only; it runs nothing from the clones.