cf-docs-rfc-proposal

Concept: Tables

Status: Done, with open items (listed under Open questions). Results: results.md.

Terms used below:

Progress

What has been done in this round, newest last. Each line links to the work.

What we learned

Why tables first

The Docs WG lead identified five pages whose tables are hard to express outside HTML. They are the core of the concern that the current content cannot simply be rewritten in Markdown. Headings would be an easier first concept, but would not address that concern.

Test pages

Page Repository Tables
_oss_scale_table.html.md.erb (partial) cloudfoundry/docs-cloudfoundry-concepts 1
metadata.html.md.erb cloudfoundry/docs-cf-admin 2 HTML, 1 Markdown
troubleshooting_slow_requests.html.md.erb cloudfoundry/docs-cf-admin 6
uaa-concepts.html.md.erb cloudfoundry/docs-uaa 2
credential-types.html.md.erb cloudfoundry/docs-credhub 1
uaa-performance.html.md.erb (first section) cloudfoundry/docs-running-cf 1 of 12
_oss_roles_table.html.md.erb (partial) cloudfoundry/docs-cloudfoundry-concepts 1

uaa-performance was added after the round, as the example for a second table style (see Template conventions). _oss_roles_table was added on 2026-10-12 as a real wide table: 12 columns, wider than the content column, with note markers in its cells (intent). The traits below are the first five pages’.

What the pages have in common

Markup that only browsers tolerate

A strict parse of each table (ERB replaced, entities numeric) shows 5 of 12 tables, on 4 of 5 pages, are not well-formed:

Page Defect
_oss_scale_table <col width="25%"> is not self-closed
metadata (both HTML tables) A <td> containing a <ul> is never closed before the next <td>
credential-types class=“table” uses typographic quotes
uaa-concepts The implicit row ends with </td> instead of </tr>

Browsers repair these silently. Tools that parse HTML as JSX (MDX) or as XML need well-formed markup, so cleanup is a likely first step of any conversion. What each tool did with them: results.md.

Hints for tables

First draft, taken from what the test pages do. Hints are written once per table, independent of any tool. Superseded by Hints after the round; kept as the record.

Level Hint Values Seen in
Table title text metadata: a centered row spanning all four columns, above the column headers
Table header row yes / no all
Table row-header column yes / no first column acting as row labels
Table pattern name troubleshooting_slow_requests: Result / Explanation / Action, six times
Column role key, value, prose first and last columns everywhere
Column width range or relative weight (e.g. 10–15%, 40%) four of five pages
Column wrap avoid, normal key columns
Column align horizontal left / center / right; vertical top / middle —
Cell block content lists, paragraphs metadata, uaa-concepts

Default: role: key implies a narrow column, wrap: avoid, and top alignment, so most tables need only one or two hints.

Example: a five-column table with widths 10–15% / 10–15% / 40% / 10–15% / 10–15%, where column 1 avoids wrapping and is top-aligned, and column 4 is centered vertically and horizontally.

Hints after the round

Superseded by the Specification; kept as the record.

Level Hint Values Change from the first draft
Table title text Shown as a bold line above the table, not a row or caption: Markdown tables have one header row
Table header row yes / no Unchanged; every table in the docs repos has one
Table row-header column yes / no Unchanged; row headers are styled apart from column headers and body cells
Table style table (standard), table-media (example); further names to be picked New. HTML tables carry it as a class; a Markdown table gets the standard style
Table pattern — Dropped: the Result / Explanation / Action tables set no widths, and the roles decide
Column role key, value, prose Unchanged; carried as classes
Column width relative weight Kept where the source sets one; roles decide otherwise
Column wrap avoid, normal avoid wins over a width, up to a cap the template sets
Column align horizontal, vertical Defaults differ by theme (Docusaurus pipe tables center cells vertically); Antora’s specs carry top alignment natively; elsewhere the extensions set it
Cell block content lists, paragraphs <br/><br/> between two blocks of text is a paragraph break

Template conventions

Some source markup only restates what the site template should do anyway. Conversions drop that markup and rely on the template instead:

Specification

Status: draft.

What a table can ask for, and what each request means, independent of any tool. A site that follows it gives every style and hint below the meaning written here; how a tool lets an author write them, and the markup it produces, are in each site’s CONVENTIONS.md. The page layout rules that apply to every table (a wide table scrolls in its own box, header cells are bold, and the rest) are the Template conventions above.

General rules

Styles

A table has one look and any number of modifiers. With none named, it has the look table. The set is open: these are the styles defined so far, and a style is added when the tables show a need for one.

Style Kind In words
table look The theme’s default table look, whatever that is. The standard style.
table-boxed look A border around every cell, a shaded header row, no stripes. The look the published docs have today.
table-plain look No cell borders. A rule under the header row and a thin line between body rows; the header is not shaded.
table-output look Command output shown as a table: text in the code font, as the terminal prints it; cells never wrap, so each output row stays one line and the table scrolls sideways in its own box when it does not fit; tight padding; a rule under the header row and no other borders; no shading.
table-media look A grid of images: no cell borders, a rule under the header row and a thin line between body rows, no header shading, cells centred both ways, an image fills its cell. It shrinks to fit the content column instead of scrolling.
table-compact modifier Tight padding and smaller text, for long tables and comparison grids.
table-striped modifier Every other body row shaded.

Which style a converted table gets comes from its survey family: see The style each table gets. table-plain and table-striped are in the set for authors to choose; no surveyed table gets either from the rule.

Hints

Level Hint Values Meaning Left out
Table title text A line that names the table, shown in bold above it. Not a row and not a caption: a Markdown table has one header row, which stays for the column headers. no title
Table header row yes / no The first row holds the column headers. no header row
Table row-header column number of leading columns The cells in those columns label their rows, and are styled apart from column headers and body cells. none
Table style one look, any modifiers See Styles. table
Table id name An anchor, so a link can point at the table. none
Column role key, value, prose What the column holds. key: the short label or identifier each row is about. value: a short value. prose: sentences or paragraphs. The template may style a role; a role sets no other hint. no role
Column width relative weight The column’s share of the table width, relative to the other columns that have one. A wrap: avoid column can grow past it. the browser’s automatic layout
Column wrap avoid, normal avoid: each cell stays on one line, growing the column, up to a cap the template sets; past the cap the text wraps between words. normal: text wraps as the column width allows. theme default
Column align left, center, right Horizontal alignment of the cell content. theme default
Column valign top, middle, bottom Vertical alignment of the cell content. theme default
Column padding none, tight, normal, loose Space inside each cell. The theme sets the size of each step; tight is what table-compact uses. the style’s padding
Row group label text A row across the whole table that labels the rows under it, up to the next group row or the end of the table. A column that only repeated the label, or left it blank for “same as above”, goes, as do spacer rows between groups. no groups
Row emphasis the row This row is the one the table is about. The template styles it as a row; bold text in each of its cells is replaced by this hint. no emphasis
Cell note marker marker text Links to a note. Usually the note is under the same table, in marker order; it may be anywhere in the document. the marker stays plain text
Cell block content lists, paragraphs A cell may hold more than one line of text. <br/><br/> between two blocks of text is a paragraph break. inline content only
Inline path — This code is a file or URL path. It stays on one line, and the template can give it a look that shows it is one value. ordinary inline code

Column hints name a set of columns. A column hint applies to one column, a range, a list, or every column, written once for the set. It covers the whole column, header cell included, unless the hint says to leave the header cell out. Two hints of the same kind may cover the same column; the one written later wins for that column. For example, “every column valign: top” then “column 4 valign: middle” leaves column 4 in the middle and the rest at the top.

Theme variables

A theme adjusts the styles and hints through these CSS custom properties. Where every site uses the same value, it is the template’s value; the others follow the theme.

Variable Adjusts Value
--table-nowrap-max the cap for a wrap: avoid column 16em
--table-prose-min the narrowest the first column of a wide table (eight or more columns) gets 24ch
--table-row-header-weight font weight of row headers theme
--table-row-header-align horizontal alignment of row headers theme
--table-font-size text size in every table theme
--table-line-height line height in every table theme
--table-edge-bg the background behind the scroll shadow theme
--table-edge-shadow the colour of the shadow on a side that has more columns theme
--table-padding-tight, --table-padding-normal, --table-padding-loose the padding steps (none is no padding) theme
--table-compact-font-size text size in table-compact theme
--table-stripe-bg the shading of every other row in table-striped theme
--table-group-bg, --table-group-weight the look of a group row theme
--table-emphasis-bg, --table-emphasis-weight the look of an emphasized row theme

Method

For each table on each test page:

  1. Read the intent. Translate the source’s exact values into hints (for example, width="25%" on a <code> column becomes role: key). Record any deviation from the source and the reason. Output: intent/<page>.md.
  2. Convert by hand into each hands-on tool, three ways:
    • passthrough — the HTML unchanged, translating only variables and partials to the tool’s syntax;
    • extension — the tool’s own extension mechanism carrying the hints;
    • native — the tool’s native table syntax plus whatever hint mechanism it offers.
  3. Build and judge. Does it build? Are content and outline preserved ideally? Which hints are honored? How readable is the source for an author?
  4. Record the convention for each tool and mode that works. These become the rules cf-docs-migrate convert implements.

The pages use variables and one partial, so each site needs minimal variable and include support to build. That support is part of this concept, not a separate one. Each tool’s default theme is used; hints must work under any theme.

Probes

Tool Question
Eleventy Do <%= vars.* %> tags render unchanged as EJS?
Sphinx/MyST Can list-table directive options carry the hints?
Middleman without Bookbinder What is the smallest change that removes Bookbinder and keeps ERB and HTML?

Layout

concepts/tables/
├── README.md          this file
├── source/            test pages, verbatim, plus SOURCES.md
├── intent/<page>.md   hints per table and recorded deviations
├── sites/
│   ├── zensical/      ┐ one minimal site per hands-on tool, versions pinned,
│   ├── docusaurus/    │ each page in passthrough/, extension/, native/,
│   ├── starlight/     │ and native-plain/ where it differs, with
│   └── antora/        ┘ `make build`, `make serve` and `make check`
├── checks/            spot checks and text comparison shared by every site
├── probes/            eleventy/, sphinx-myst/, middleman/
├── survey/            table style survey: tables.csv, scripts, README
└── results.md         comparison grid; screenshots in results/

source/SOURCES.md records, for each page, the repository, path, commit, and license. The content repositories are Apache-2.0 licensed (docs-uaa via its NOTICE file). Source copies stay verbatim; all changes live in sites/ and probes/.

Results grid

results.md has one row per page × tool × mode:

Column Values
Builds yes / no (error)
Content and outline preserved / changed (note) / lost (note)
Hints honored list of hints, with screenshots
Source readability short judgment from an author’s point of view
Convention the pattern used, linked from the tool’s conventions

The content and outline check is manual in this round. An automated check (text and heading extraction compared against the published page) belongs to cf-docs-migrate, and must treat build-time values such as the copyright year as expected differences.

Toolchains

Node for Docusaurus, Starlight, and Antora; uv for Zensical and Sphinx. Each site pins its tool versions so results can be reproduced. Nothing is installed globally.

Open questions

Left open by this round:

From before the round: