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 |
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.
.md, .erb, .html,
.haml, .markdown, .mdx and .adoc. Folders named .git,
node_modules and vendor are skipped, and so are Markdown files at a
repository’s root (READMEs and contributor notes; no site publishes
them). At these commits every page is an .html.md.erb file._. There are 44 partials; 9 have headings, 34 headings in all. Each is
scanned as its own page, not inside the pages that include it.<%= vars.… %> variables as written.scan.py reads every page and skips the parts that cannot hold a heading:
--- lines at the top of
the file (glossary);` or
~, to the next line starting with the same character);<pre> blocks and HTML comments.In what is left it finds two kinds of heading:
# (an ATX
heading), at most three spaces in. The space after the #s may be
missing, as the book’s Markdown engine allows (see
No space after the #s). Closing #s are
dropped.<h1> to <h6> element, up to its closing tag.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.
From headings.csv and pages.csv:
h1 1, h2 1,027, h3 930, h4 202,
h5 4, h6 0.<a id> inside the heading; no heading has two. The 235 without
are on 46 pages; on 7 of those pages no heading has an id.h2. Three pages start at
h3 and two at h4; all but one
(managing-stacks)
are partials. One page starts at h1 (below).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:
access-control, twice:
L61
and
L107,
each a #### after a ##.restore, once:
L76,
a #### after the ## at L64.Two pages use HTML heading tags, both in docs-dev-guide. All 16 carry an
<a id> inside the tag.
deploy-apps/routes-domains: 15 <h4> tags among Markdown headings
(first at
L141).
The page has 42 headings, from h2 to h5.services/application-binding: one <h3>
(L32).<code>.python/index:
“Miniconda support (starting in buildpack version 1.5.6)”
(L190)
and “Pipenv support (starting in buildpack version 1.5.19)”
(L194).
The version number is the link.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.
#s97 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.
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:
uaa-performance: client-credentials four times
(L84,
L169,
L254,
L305).services/integrate-splunk: config on three
consecutive ### headings
(L32,
L40,
L60).To list them all, group headings.csv by repo, file and
ids.
h1 in the bodyOne 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>.
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).
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.
access-control.
This scan finds two; the second, restore, is in docs-bbr.python/index, which has two
such headings, not one.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.