cf-docs-rfc-proposal

Table style survey

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

Scope

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.

Method

survey.py reads every file of those types and finds two kinds of table:

For each table it records, among other things:

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:

  1. media: an image in a cell;
  2. matrix: 4 or more columns and a median cell of 5 characters or fewer (the median cell is the middle value of the table’s cell lengths in characters; HTML cells are measured as text, pipe cells as written);
  3. titled: a spanning title row;
  4. key-value: 2 columns;
  5. reference-3-4: 3 or 4 columns;
  6. wide: 5 or more columns.

The families come from the data, not from a list of style names.

Totals

  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.

Markup defects that browsers repair without a sign and strict tools do not (glossary):

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 ###.

Families

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).

Examples

Links go to the table at the surveyed commit.

How the book renders them today

Every 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.

What the families say about the candidate names

The evaluation’s reading of the data, not a decision:

Which styles to offer is open; see Research areas. The style each table gets in a conversion is decided below.

The style each table gets

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:

  1. 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;
  2. table-media: the media family;
  3. the look: 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;
  4. the modifier: 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

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:

The content/bpm folder is a link into another repository and was not counted.

All 40 tables (T1–T40)
# 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:

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.

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/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.