Status: draft, incomplete — covers what is known as of 2026-10-10.
This survey counts every table in the Cloud Foundry documentation and tutorial repositories and groups the tables by what they hold. It was done on 2026-10-09 to find which table styles the site template needs beyond the standard one (R-09 table styles by class). On the way it found markup defects that a conversion has to clean up (R-24 markup cleanup before conversion).
Decision (evaluation, 2026-10-09): class="table" is the standard style,
the one most tables use. Further style classes (a style class is a name the
site’s stylesheet gives a look to; glossary)
are chosen from what the docs repositories contain. The candidate names at
the start were compact, boxed, plain and striped.
| File | What it is |
|---|---|
| tables.csv | The data: one row per table, 238 rows, each with a GitHub link to the table at the surveyed commit |
| shas.txt | The 21 repositories and the commit surveyed in each |
| survey.py | Finds and measures the tables in a set of clones |
| families.py | Sorts the tables into families, gives each a style, and prints a summary |
| bosh_tables.py | Extra measurements for the bosh.io tables and its Markdown |
Repositories. All 15 cloudfoundry/docs-* repositories that are not
archived, plus the tutorial repositories, cloned from their default branch on
2026-10-09. Two docs-* repositories are archived and were skipped:
docs-cfcr and
docs-routing. The
cloudfoundry-tutorials organization is archived as a whole; its four
repositories were cloned anyway.
| Repository | Commit (date) | Tables |
|---|---|---|
| cloudfoundry/docs-bbr | 5146595 (2026-07-09) |
2 |
| cloudfoundry/docs-book-cloudfoundry | 30dfa57 (2026-10-08) |
0 |
| cloudfoundry/docs-bosh | 20a4122 (2026-10-01) |
40 |
| cloudfoundry/docs-buildpacks | 239e5c8 (2026-10-09) |
15 |
| cloudfoundry/docs-cf-admin | 13826fa (2026-07-22) |
31 |
| cloudfoundry/docs-cf-cli | ee9aad5 (2026-07-22) |
1 |
| cloudfoundry/docs-cloudfoundry-concepts | 97e0d0b (2026-09-14) |
37 |
| cloudfoundry/docs-credhub | 21b0448 (2026-07-23) |
1 |
| cloudfoundry/docs-deploying-cf | 1113cfa (2026-07-24) |
4 |
| cloudfoundry/docs-dev-guide | 9c8df63 (2026-09-28) |
42 |
| cloudfoundry/docs-dotnet-core-tutorial | 6e83c73 (2020-08-03) |
0 |
| cloudfoundry/docs-loggregator | 8e027ba (2026-07-22) |
9 |
| cloudfoundry/docs-running-cf | 956acc8 (2026-08-05) |
37 |
| cloudfoundry/docs-services | ccb0036 (2026-07-22) |
5 |
| cloudfoundry/docs-uaa | 216c797 (2026-07-22) |
11 |
| cloudfoundry/tutorials | e41b9de (2024-01-06) |
0 |
| cloudfoundry/what-is-cf | 9b48cc7 (2023-10-03) |
0 |
| cloudfoundry-tutorials/cf-and-k8s | 9df120b (2020-04-13) |
1 |
| cloudfoundry-tutorials/cf4k8s-do | 32e6e8c (2020-11-02) |
0 |
| cloudfoundry-tutorials/cf4k8s-gke | b7fba34 (2020-10-20) |
0 |
| cloudfoundry-tutorials/trycf | 7f7e44f (2020-12-15) |
2 |
The date is the commit’s date. In shas.txt a cft- prefix marks a
cloudfoundry-tutorials repository.
docs-book-cloudfoundry
holds its layout and settings and has no tables.docs-bosh is not part of the book. It
builds bosh.io/docs with MkDocs and the Material theme
(glossary;
mkdocs.yml),
a different site with a different look. Its tables are in the totals,
but reported in their own row and in bosh.io below..md, .erb, .html, .haml, .markdown, .mdx and
.adoc. Folders named .git, node_modules and vendor are skipped.
Markdown files at a repository’s root (contributor notes, READMEs) are
left out on purpose: no site publishes them.survey.py reads every file of those types and finds two kinds of table:
<table> up to its closing </table>, with tables
inside tables handled. Each is parsed with Python’s standard HTML parser,
which, like a browser, tolerates unclosed tags.---|---, one row per line, | between cells
(glossary). Lines inside fenced code
blocks are skipped. The script also looks next to each pipe table for an
attribute list ({: .class }). That is the syntax kramdown
(glossary) and Python-Markdown’s
attr_list use to attach a class to a block. bosh.io turns attr_list on
(mkdocs.yml);
the book’s Markdown engine is Redcarpet
(Bookbinder’s gemspec),
which has no such syntax. The survey found none.For each table it records, among other things:
class exactly as written;<col>, and width, style or alignment set on cells;<th> that starts a body row) and a spanning title row (a
first row with one cell spanning every column);<%, the template syntax the book uses for variables and
partials; glossary);<thead> that is never closed.Every row of tables.csv has a link to the table’s first line at the surveyed commit.
families.py then puts each table in one family. The rules are applied in this order, and the first that matches wins:
The families come from the data, not from a list of style names.
| HTML | Pipe | All | |
|---|---|---|---|
| Book repositories (docs.cloudfoundry.org) | 123 | 72 | 195 |
bosh.io (docs-bosh) |
0 | 40 | 40 |
| Tutorial repositories | 0 | 3 | 3 |
| All | 123 | 115 | 238 |
The book row counts every docs-* repository in the table above except
docs-bosh. Two of them, docs-book-cloudfoundry and
docs-dotnet-core-tutorial, are not sections in the book’s config.yml;
neither has a table, so the totals are the same either way.
Classes. Of the 123 HTML tables, 70 have class="table", 8 have
class=“table” with typographic quotes (so the browser does not read
table as the class), 1 has class="table' with mismatched quotes, and 44
have no class. No other class appears anywhere. No pipe table has a class:
there are no kramdown attribute lists next to tables.
Traits across all 238 tables.
width="20%" on
<th> and similar); one docs-cf-cli table accounts for 31 such cells.
One table sets widths with <col> (_oss_scale_table, a test page).metadata test page).<%= vars.name %> variables.border="1", which the published site’s stylesheet makes
redundant.Markup defects that browsers repair without a sign and strict tools do not (glossary):
<thead>, so a browser puts every row in the header:
_suspended_org_roles_table and _suspended_space_roles_table in
docs-cloudfoundry-concepts, and 3 in _c2c_oss_overlay in
docs-dev-guide;Correction (2026-10-09): an earlier note listed uaa-performance cells
ending in </td without >. That defect does not exist; at commit
956acc8 every one of the page’s twelve tables closes its cells. The page’s
real cleanup item is its headings, written ###<a id=…> with no space
after ###.
| Family | Count | HTML / pipe | Typical | Repositories with most |
|---|---|---|---|---|
| key-value | 126 | 51 / 75 | 2 columns, median 4 body rows (max 47), median cell 21 characters; code in 72 | dev-guide 26, running-cf 22, bosh 21, concepts 19 |
| reference-3-4 | 77 | 49 / 28 | median 4 body rows (max 59), median cell 16 characters | cf-admin 16, bosh 14, concepts 14, dev-guide 14 |
| media | 12 | 12 / 0 | 3–5 columns of chart thumbnails linked to full images | running-cf only (uaa-performance) |
| matrix | 11 | 5 / 6 | 4–12 columns of Yes/blank, numbers or short tokens | concepts 3, bosh 2, cf-admin 2, dev-guide 2 |
| wide | 10 | 4 / 6 | 5–6 columns of text | bosh 3, cf-admin 3, uaa 3 |
| titled | 2 | 2 / 0 | title in a spanning first row | cf-admin only (metadata) |
Long reference tables cut across the families: 14 key-value and
reference-3-4 tables have 15 or more body rows. The metrics partials in
docs-running-cf reach 41–59 rows; others are docs-cf-cli v8 (30),
docs-uaa uaa-deploy (33) and the concepts glossary (16). Tables of
short cells (median 12 characters or fewer) are 29 of the key-value and 24
of the reference-3-4 tables.
Decision (evaluation, tables round): a table title is a bold line above the table, not a row, so the titled family needs no style of its own (template conventions).
Links go to the table at the surveyed commit.
credential-types L17,
dev-guide using-tasks L165,
dev-guide environment-variable L255 (21 body rows)metadata L370,
loggregator data-sources L117metrics/_cloud_controller L10 (59 body rows),
running-cf metrics/_diego L35 (47),
cf-cli v8 L74 (30)_oss_roles_table L1 (12 columns × 42 body rows, Yes/blank),
dev-guide environment-variable L86 (variable × Running/Staging/Task),
cf-admin managing-stacks L28uaa-performance L88
(12 such tables on one page)uaa-metrics L37,
cf-admin troubleshooting-router-error-responses L314metadata L56Every table on docs.cloudfoundry.org looks the same, whatever its family
or class. The site’s stylesheet
(/stylesheets/all.css,
as served on 2026-10-10; not pinned, as it is a built file) has one table
style and no rule for any table class. Tables are full width with a 1-pixel
border, and header cells are shaded (#f8f8f8). Every cell is boxed
(.content td, .content th, .content tr { border: solid 1px grey }), and a
row changes color on hover. The stylesheet has a striping rule, but it
applies only under a has-sidenav class that no checked page carries
(adminguide/metadata.html), so no table is striped.
The evaluation’s reading of the data, not a decision:
table-media for it as the example of a second style
(template conventions).Which styles to offer is open; see Research areas. The style each table gets in a conversion is decided below.
Decision (2026-10-12): conversion gives every table one look and any
modifiers, as classes on the <table>. A pipe table takes them from a
<!-- table: .name --> comment
(Classes and ids on pipe tables).
table is the tool’s or theme’s default look; table-boxed is a border on
every cell, today’s book look, kept only where the grid helps reading.
families.py writes the classes into the style column of
tables.csv. The first rule that matches wins:
table-output: command output laid out as a table. No survey
column marks it, so the two are listed by hand: bosh.io
director-tasks.md L34
and
vsphere-esxi-host-failure.md L21;table-media: the media family;table-boxed for the matrix family (a grid of short
cells, up to 12 columns, read across) and the titled family (spanning
cells and row headers); table for every other table;table-compact added for the matrix family and for
any table of 15 or more body rows. The role matrices stay readable with
it once the wide-table first-column floor applies
(Wide tables).| Style | Tables | HTML | Pipe |
|---|---|---|---|
table |
197 | 103 | 94 |
table table-compact |
14 | 1 | 13 |
table-media |
12 | 12 | 0 |
table-boxed table-compact |
11 | 5 | 6 |
table-boxed |
2 | 2 | 0 |
table-output |
2 | 0 | 2 |
No table gets table-plain or table-striped: nothing in the sources asks
for either. Both stay in the set for authors to name (decision,
2026-10-12).
bosh.io/docs is built from docs-bosh with MkDocs and Material for MkDocs
(MkDocs is a Python static site generator, and Material a theme for it;
glossary), in the
squidfunk/mkdocs-material:9.7.6 image
(build task,
mkdocs.yml).
Everything below was read at commit 20a4122, not built.
Last checked 2026-10-10: repository cloudfoundry/docs-bosh, branch
master, commit 20a41223a7ba87700424634c42e94a22a669b45e. The 40 tables
and their families, the absence of alignment colons and \| escapes, and
the 302 admonitions, 809 heading ids and 221 indented code blocks all match.
The indented code blocks are on 48 pages, not 49 as first counted: one page
closes an unindented block with an indented fence.
The 40 tables. All are pipe tables with a header row, in families
key-value 21, reference-3-4 14, wide 3 and matrix 2 (from
tables.csv). bosh_tables.py tables found
no alignment colons, no \| escapes, no attribute lists, no images and no
title line. Nineteen are the same four small tables (concept mapping,
network type support, encryption, other features) repeated on the five
provider pages aws, azure, google, openstack and vsphere.
The Markdown around them. bosh_tables.py
constructs counted, outside code blocks:
!!! note; glossary) on 128 pages;{: #id } on 114 pages;The content/bpm folder is a link into another repository and was not
counted.
| # | Source | Columns | Body rows | Family | Holds | What matters for conversion |
|---|---|---|---|---|---|---|
| T1 | resolute-release-migration.md L265 | 2 | 7 | key-value | Noble library → Resolute replacement | code spans; prose in col 2 (89 chars) |
| T2 | networks.md L16 | 4 | 2 | reference-3-4 | IP assignment × network type | empty corner cell; row headers |
| T3 | networks.md L489 | 4 | 4 | reference-3-4 | networks per instance, IaaS × network type | <br> in 2 header cells; bold col 1; <sup>1</sup> note marker, note as a 1: line under the table; - for none |
| T4 | networks.md L500 | 4 | 11 | matrix | advanced network features, IaaS × type × feature | blank col-1 cells = same IaaS as above; 3 blank spacer rows between groups; <sup>1/2</sup> markers with 1:/2: lines below; — for none; 16 empty body cells |
| T5 | init-alicloud.md L86 | 4 | 5 | reference-3-4 | security group rules | in a numbered-list step, after an admonition (4-space indent) |
| T6 | vsphere.md L30 | 2 | 6 | key-value | BOSH concept → vSphere | 6 reference-style links |
| T7 | vsphere.md L54 | 2 | 3 | key-value | vSphere network type support | — |
| T8 | vsphere.md L70 | 2 | 3 | key-value | vSphere disk encryption | — |
| T9 | vsphere.md L78 | 2 | 3 | key-value | vSphere misc. features | reference link |
| T10 | init-openstack.md L103 | 6 | 6 | wide | OpenStack security group rules | 6 columns; in a list step after an admonition; 2 empty cells; ports and CIDRs |
| T11 | azure-compute-gallery.md L19 | 4 | 2 | reference-3-4 | Azure roles for the CPI | every header cell bolded; bold + italic lead-ins; long code token (49 chars); 3 reference links |
| T12 | init-aws.md L114 | 4 | 5 | reference-3-4 | AWS security group rules | in a list step after an admonition |
| T13 | cli-ops-files.md L349 | 2 | 3 | key-value | ops-file escape sequences | all cells code |
| T14 | cpi-api-v2.md L50 | 5 | 8 | matrix | Director/CPI/stemcell version matrix | one row fully bold (the case that matters); numeric 1/2 cells; *full agent settings** renders as italic with a stray * (marker for a \* note under the table) |
| T15 | prefix-delegation-networks.md L12 | 3 | 1 | reference-3-4 | prefix delegation support | one body row |
| T16 | cli-v2-diff.md L27 | 2 | 14 | key-value | v1 → v2 CLI commands | commands not in code spans; <manifest> and <ip> are read as HTML tags and vanish on the live page; dangling [3] |
| T17 | director-api-v1.md L46 | 2 | 3 | key-value | HTTP verbs | — |
| T18 | director-tasks.md L34 | 6 | 2 | wide | sample bosh tasks output |
6 columns; CLI output as a table; empty Result column |
| T19 | git-lfs-release-blobstore.md L34 | 4 | 6 | reference-3-4 | Git LFS vs S3 decision matrix | ✓ and - cells; prose Rationale column |
| T20 | links.md L527 | 4 | 4 | reference-3-4 | link provider conflicts | 19 code spans; long Example column |
| T21 | links.md L553 | 3 | 4 | reference-3-4 | implicit link matching | values padded with spaces, no colons |
| T22 | links.md L566 | 3 | 4 | reference-3-4 | explicit link matching | as T21 |
| T23 | google.md L13 | 2 | 8 | key-value | BOSH concept → GCP | 8 inline links (URLs up to 67 chars in the source) |
| T24 | google.md L33 | 2 | 3 | key-value | GCP network type support | — |
| T25 | google.md L41 | 2 | 4 | key-value | GCP misc. features | reference links |
| T26 | openstack.md L30 | 2 | 9 | key-value | BOSH concept → OpenStack | 10 inline links (URLs up to 87 chars); 184-char source cell |
| T27 | openstack.md L51 | 2 | 3 | key-value | OpenStack network type support | — |
| T28 | openstack.md L59 | 2 | 4 | key-value | OpenStack misc. features | reference links |
| T29 | pre-stop.md L53 | 2 | 4 | key-value | pre-stop env var combinations | three code spans per cell joined by <br> (9 <br>); one <br> in col 2 |
| T30 | aws.md L13 | 2 | 8 | key-value | BOSH concept → AWS | 7 inline links (URLs up to 96 chars) |
| T31 | aws.md L33 | 2 | 3 | key-value | AWS network type support | — |
| T32 | aws.md L46 | 4 | 6 | reference-3-4 | AWS disk encryption | Platform and Disk Type repeat down the rows (no blanks) |
| T33 | aws.md L66 | 2 | 4 | key-value | AWS misc. features | reference links |
| T34 | stemcell-lines.md L28 | 5 | 4 | wide | stemcell lines and support dates | links to /stemcells/#… (bosh-io-web, outside /docs); Markdown footnote [^windows-support] in a cell; five stacked <a id> anchors above |
| T35 | vsphere-esxi-host-failure.md L21 | 4 | 4 | reference-3-4 | sample bosh stemcells output |
in a nested list (6-space indent); 39-char CIDs; 1.585* literal asterisk |
| T36 | azure.md L16 | 2 | 8 | key-value | BOSH concept → Azure | 7 reference links, 1 relative link |
| T37 | azure.md L44 | 2 | 3 | key-value | Azure network type support | — |
| T38 | azure.md L60 | 3 | 3 | reference-3-4 | Azure managed-disk encryption | — |
| T39 | azure.md L72 | 3 | 3 | reference-3-4 | Azure storage-account encryption | — |
| T40 | azure.md L87 | 2 | 5 | key-value | Azure misc. features | reference links |
Two hints the list does not have yet. Hints are what a table asks for, independent of any tool (glossary; hints after the round). The bosh.io tables add two candidates, both open:
[3] with no target in T16).Two defects that show on the live site (checked 2026-10-09). In T16,
<manifest> and <ip> are read as HTML tags and disappear
(page). In T14, *full agent settings**
in a header cell renders in italics with a stray *
(page).
The look (checked 2026-10-09 on networks and init-openstack). bosh.io uses Material’s default table. It has a thin outer border, rules between rows, no rules between columns, no header shading, no striping, and text at 80% of body size. Tables are sized to their content and scroll sideways in their own box when too wide. The book boxes every cell and shades the header (see above).
bpm pages. Seven more tables publish under bosh.io/docs/bpm/ from the
bpm-release repository, which docs-bosh includes as a submodule at
6b9988a.
They were surveyed in a separate run and are not in tables.csv: six
pipe tables in
docs/config.md
(one YAML schema, one table per object, columns Property / Type / Required /
Description; reference-3-4) and one in
docs/runtime.md
(key-value). Last checked 2026-10-10: repository cloudfoundry/bpm-release
(the submodule URL, cloudfoundry-incubator/bpm-release, redirects there),
branch master, commit 6b9988a0271aefc2e0cd6444ad4f8d562f46b06e, the
commit docs-bosh pins at 20a4122; it is an ancestor of master, which
has moved on since. The seven tables and their families match. On the
live page
(checked 2026-10-09), eight Property names break in the middle of
the identifier, because Material lets code text break anywhere.
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/tables/survey.
The whole survey needs a clone of each repository in shas.txt, at its
commit:
mkdir -p repos
while read name sha date; do
case $name in
cft-*) url=https://github.com/cloudfoundry-tutorials/${name#cft-} ;;
*) url=https://github.com/cloudfoundry/$name ;;
esac
git clone --quiet "$url" "repos/$name"
git -C "repos/$name" checkout --quiet "$sha"
done < SURVEY/shas.txt
python3 -I SURVEY/survey.py repos SURVEY/shas.txt raw
python3 -I SURVEY/families.py raw.json tables
cmp tables.csv SURVEY/tables.csv
survey.py writes raw.json and raw.csv and prints the table count;
families.py prints the family summary and writes tables.json and
tables.csv with the family and style columns. tables.csv holds 238
tables. On 2026-10-10 survey.py was rerun on docs-bbr,
docs-book-cloudfoundry and docs-bosh, and its rows for them match the
file.
Only the families, from the data here, without clones:
python3 -I SURVEY/families.py SURVEY/tables.csv
This prints the families and the counts behind
traits across all 238 tables. With a second argument it writes a
copy of the data with the family column; on tables.csv that copy is
byte-identical to the input (checked 2026-10-10).
bosh.io needs a clone of docs-bosh at 20a4122:
git clone --quiet https://github.com/cloudfoundry/docs-bosh.git docs-bosh
git -C docs-bosh checkout --quiet 20a41223a7ba87700424634c42e94a22a669b45e
python3 -I SURVEY/bosh_tables.py constructs docs-bosh
python3 -I SURVEY/bosh_tables.py tables docs-bosh SURVEY/tables.csv > bosh-tables.csv
constructs prints the Markdown counts above; tables writes one CSV row
per table (indent, the list or admonition it sits in, alignment, inline
HTML, code spans, links, longest URL and word, empty cells, spacer rows,
bold header, column or rows, note markers, symbols). The “Holds” and “What
matters” columns in the list of 40 were written by hand from that output
and the source.
bpm pages need a clone of bpm-release at the commit docs-bosh pins:
mkdir -p bpm && git clone --quiet https://github.com/cloudfoundry/bpm-release.git bpm/bpm-release
git -C bpm/bpm-release checkout --quiet 6b9988a0271aefc2e0cd6444ad4f8d562f46b06e
echo "bpm-release 6b9988a0271aefc2e0cd6444ad4f8d562f46b06e 2021-10-07" > shas-bpm.txt
python3 -I SURVEY/survey.py bpm shas-bpm.txt bpm-raw
python3 -I SURVEY/families.py bpm-raw.json bpm
python3 -I SURVEY/bosh_tables.py tables bpm/bpm-release bpm.csv bpm-release B > bpm-tables.csv
The scripts read files only; they run nothing from the clones.