Status: draft, incomplete — covers what is known as of 2026-10-10.
An input format is the kind of text an author writes and a tool reads to build a page. Each tool in this evaluation reads one or two formats. This page describes each format and shows one real table written in it, taken from the page sources built in the tables round (the first concept of this evaluation: tables from real pages converted by hand into each candidate tool; tables concept). Nothing here is written for this page: every snippet is copied from a file in this repository, and each one links to that file.
What these snippets look like once built, tool by tool, with screenshots: poc/tables.md. Requirements are cited by ID and a short phrase; the full list is in requirements/.
The table is the only table on credential-types.html.md.erb from the
cloudfoundry/docs-credhub repository
(lines 17–46 at commit e074f74),
published at
https://docs.cloudfoundry.org/credhub/credential-types.html. It has a
header row, seven body rows and two columns. The first column names a
credential type, written as code, and its header cell asks for 20% of the
table’s width; the second column holds one or two sentences.
What the table asks for, written as hints (tool-independent statements of intent, from its intent file, the page’s record of what each table needs, written once for all tools):
| Hint | Value | Where the source says it |
|---|---|---|
| header row | yes | <thead> |
| row-header column | yes | column 1 names the type |
| column 1 role | key (a short label) |
<code> type names |
| column 1 width | about 20% | <th style="width:20%"> |
| column 1 wrap | avoid (stay on one line) | single identifiers |
| column 2 role | prose (sentences) |
one or two sentences per cell |
The source has one defect: class=“table” is written with typographic
quotes. A typographic quote is not an attribute quote, so the value is read
as an
unquoted attribute value,
“table” with the quotes in it, and browsers never apply the class. Every
converted version makes the quotes straight
(R-24 markup cleanup before conversion).
The modes named below are defined in the Tooling README: raw passthrough (HTML exactly as written), passthrough (HTML after cleanup), extension (the tool’s extension point carries the hints), native (the tool’s own table syntax), and native-plain (native without widths).
| Format | What it is | Read by (modes) | Learn more |
|---|---|---|---|
| HTML | The markup language of web pages | today’s site; passthrough in every tool | WHATWG HTML, MDN |
| ERB | Ruby code in <% %> tags inside a text file |
today’s site; Middleman probe | ERB |
| EJS | JavaScript code in <% %> tags, the same tag shapes as ERB |
Eleventy probe | EJS |
| MDX | Markdown in which HTML is read as JSX | Docusaurus (passthrough, extension) | MDX, JSX |
| Pipe table | The Markdown table written with \| and --- |
Docusaurus native; Zensical and Starlight native-plain | GFM |
| Python-Markdown | The Markdown dialect Zensical reads; its attribute lists add widths to cells | Zensical native | Python-Markdown |
| Markdoc | Markdown with {% %} tags |
Starlight (all modes) | Markdoc |
| AsciiDoc | A plain-text format with its own table syntax | Antora (all modes) | AsciiDoc, Asciidoctor |
| List table | A table written as a nested list, one item per row and per cell | Docusaurus and Zensical extension | MyST list-table |
| MyST | Markdown with directives (named blocks with options) | Sphinx probe | MyST, MyST parser |
HTML (HyperText Markup Language) is the markup language browsers read:
<table>, <tr> (row), <th> (header cell), <td> (cell). Browsers
repair broken HTML without saying so: the HTML standard defines how a
browser recovers from each
parse error.
That is why defects in today’s source never showed. Learn more: WHATWG HTML,
MDN; see also the
glossary.
Today’s source is HTML inside a Markdown page inside an ERB file
(.html.md.erb). The table as written in
source/credential-types.html.md.erb,
lines 17–46, unchanged:
<table class=“table”>
<thead>
<tr>
<th style="width:20%">Type</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td><code>value</code></td>
<td>A single string value for arbitrary configurations and other non-generated or validated strings.</td>
</tr><tr>
<td><code>json</code></td>
<td>An arbitrary JSON object for static configurations with many values.</td>
</tr><tr>
<td><code>user</code></td>
<td>Three string values for username, password, and password hash.</td>
</tr><tr>
<td><code>password</code></td>
<td>A single string value for passwords and other random string credentials. Values for this type can be automatically generated.</td>
</tr><tr>
<td><code>certificate</code></td>
<td>An object containing a root CA, certificate, and private key. Use this type for key pair apps that utilize a certificate, such as TLS connections. Values for this type can be automatically generated.</td>
</tr><tr>
<td><code>rsa</code></td>
<td>An object containing an RSA public key and private key without a certificate. Values for this type can be automatically generated.</td>
</tr><tr>
<td><code>ssh</code></td>
<td>An object containing an SSH-formatted public key and private key. Values for this type can be automatically generated.</td>
</tr>
</table>
Raw passthrough in every tool keeps this HTML exactly (Antora wraps it in a passthrough block, below). Zensical, Starlight and Antora build it; Docusaurus does not (see MDX).
Passthrough in Zensical and Starlight is the same text with one change, the first line:
<table class="table">
Antora reads AsciiDoc, not Markdown, so the HTML goes inside an AsciiDoc
passthrough block, ++++ above and below, which hands the HTML to the
browser unread: Asciidoctor treats ++++ as a
raw block
with no substitutions
(file):
++++
<table class="table">
<thead>
<tr>
<th style="width:20%">Type</th>
<th>Description</th>
</tr>
</thead>
…
</table>
++++
A table that holds a variable also needs [subs=attributes+] on the line
above ++++, so the variable is filled in
(custom subs on a block);
this table has none.
ERB (Embedded Ruby) puts Ruby code in a text file between <% and %>;
<%= … %> inserts the result into the page
(ERB’s tag kinds, in lib/erb.rb).
Today’s pages use it for variables (defined in the book’s
template_variables.yml)
and for including one file in another. Learn more:
ERB; see also the
glossary.
The credential-types table holds no ERB tag. The
Middleman probe built
this page from the source file itself, unchanged, and every table matched
the published page cell for cell. ERB as it appears in other test pages:
A variable inside a table cell, from
_oss_scale_table
(cell text shortened here):
<td>You might run a single NATS instance … <%= vars.recommended_by %> recommends scaling NATS VMs to 2 or more CPU.</td>
Including a partial (a file inserted into another page), from the probe’s host page:
<%= partial 'oss_scale_table' %>
EJS (Embedded JavaScript templates) uses the same tag shapes as ERB, with
JavaScript inside. One difference matters: EJS’s <%= escapes HTML (shows
<p> as text), and <%- inserts it as markup
(tag modes
and what each outputs
in EJS’s source). In Middleman, ERB’s <%= does not escape
(Middleman probe). Learn more: EJS; see also the
glossary.
No EJS copy of credential-types exists in this repository. The
Eleventy probe built
uaa-concepts and the scale table from unchanged copies of the source, and
their tables came out byte for byte as written. credential-types holds no
ERB tags, so its EJS form would be the source file as it is; that was not
built. EJS from the probe’s files:
An HTML-valued variable, both ways, from src/escaping.md:
<%= vars.route_services %>
<%- vars.route_services %>
The first shows the variable’s <p class="note"> as text; the second
renders the note.
An include, from
src/scale-table-host.md.
It needs <%- and the full file name, where ERB’s partial needs
neither:
<%- include('/_oss_scale_table.md') %>
MDX is Markdown in which HTML is read as JSX. JSX is the HTML-like syntax
of React, a JavaScript library: it requires every tag to be closed, writes
a style as a JavaScript object, and treats {…} as JavaScript code. The
MDX project’s own documentation says so
(HTML replaced by JSX, { must be escaped;
a style object).
Docusaurus reads .md and .mdx files
(default include). Learn more: MDX,
JSX; see also the
glossary entries for MDX and JSX.
Raw passthrough does not build. MDX stops at the first error: the
typographic “ before an attribute value
(raw passthrough errors).
Passthrough after cleanup
(file).
Three things differ from the source: straight quotes, the width written as a
JSX object, and the body rows wrapped in <tbody> (without it the page
builds, but React reports an error in the browser):
<table class="table">
<thead>
<tr>
<th style={{width: '20%'}}>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>value</code></td>
<td>A single string value for arbitrary configurations and other non-generated or validated strings.</td>
</tr><tr>
<td><code>json</code></td>
<td>An arbitrary JSON object for static configurations with many values.</td>
</tr><tr>
<td><code>user</code></td>
<td>Three string values for username, password, and password hash.</td>
</tr><tr>
<td><code>password</code></td>
<td>A single string value for passwords and other random string credentials. Values for this type can be automatically generated.</td>
</tr><tr>
<td><code>certificate</code></td>
<td>An object containing a root CA, certificate, and private key. Use this type for key pair apps that utilize a certificate, such as TLS connections. Values for this type can be automatically generated.</td>
</tr><tr>
<td><code>rsa</code></td>
<td>An object containing an RSA public key and private key without a certificate. Values for this type can be automatically generated.</td>
</tr><tr>
<td><code>ssh</code></td>
<td>An object containing an SSH-formatted public key and private key. Values for this type can be automatically generated.</td>
</tr>
</tbody>
</table>
Every .mdx page that uses variables also imports them once, after the
front matter (the settings block at the top of a page):
import vars from '@site/vars.json';
and a variable is then written {vars.recommended_by}. Native mode in
Docusaurus is a pipe table; extension mode is a
list table.
A pipe table is the table syntax most Markdown tools share, from GFM
(GitHub Flavored Markdown, GitHub’s dialect of CommonMark, the common
Markdown specification;
GFM spec).
Each row is one line; | separates cells; a line
of --- ends the header row. A cell holds one line of text: no lists or
paragraphs unless written as inline HTML, and no widths; the delimiter row
carries only alignment
(GFM spec, tables). Learn more:
GFM, CommonMark; see also the
glossary.
Docusaurus native (file). Zensical native-plain and Starlight native-plain are the same table (Zensical, Starlight):
| Type | Description |
| --- | --- |
| `value` | A single string value for arbitrary configurations and other non-generated or validated strings. |
| `json` | An arbitrary JSON object for static configurations with many values. |
| `user` | Three string values for username, password, and password hash. |
| `password` | A single string value for passwords and other random string credentials. Values for this type can be automatically generated. |
| `certificate` | An object containing a root CA, certificate, and private key. Use this type for key pair apps that utilize a certificate, such as TLS connections. Values for this type can be automatically generated. |
| `rsa` | An object containing an RSA public key and private key without a certificate. Values for this type can be automatically generated. |
| `ssh` | An object containing an SSH-formatted public key and private key. Values for this type can be automatically generated. |
The 20% width and the row headers are gone; the columns are sized by their content. A pipe table also needs a blank line before it, where an HTML table does not (Docusaurus finding 3, Zensical conventions).
Python-Markdown is the Markdown dialect Zensical reads (Zensical
depends on markdown,
the Python-Markdown package). Its attribute lists
extension (attr_list) lets an author attach HTML attributes to an element
by writing {: … } after it, including at the end of a table cell
(attr_list.py).
It works on a single table cell, not on a whole table
(Zensical conventions). Learn more: Python-Markdown;
see also the glossary.
Zensical native is the pipe table with one attribute list on the first header cell (file):
| Type {: style="width:20%" } | Description |
| --- | --- |
| `value` | A single string value for arbitrary configurations and other non-generated or validated strings. |
| `json` | An arbitrary JSON object for static configurations with many values. |
| `user` | Three string values for username, password, and password hash. |
| `password` | A single string value for passwords and other random string credentials. Values for this type can be automatically generated. |
| `certificate` | An object containing a root CA, certificate, and private key. Use this type for key pair apps that utilize a certificate, such as TLS connections. Values for this type can be automatically generated. |
| `rsa` | An object containing an RSA public key and private key without a certificate. Values for this type can be automatically generated. |
| `ssh` | An object containing an SSH-formatted public key and private key. Values for this type can be automatically generated. |
The width is kept; row headers are not. {: .class } on the line after a
pipe table does not attach to the table: it becomes an extra row showing
that text (Zensical finding 6).
Zensical keeps today’s variable form, <%= vars.recommended_by %>, as
written: its template engine is set to read ERB-style tags
(zensical.toml).
Markdoc is Markdown with tags written {% name %} … {% /name %}
(tag delimiters). Its
own {% table %} tag writes a table as a list: * starts a cell and ---
starts a new row
(table transform),
so a cell can hold lists and paragraphs
(cell schema).
Starlight, a documentation theme for the Astro site builder
(depends on astro),
reads Markdoc pages (.mdoc) in this evaluation, through Astro’s Markdoc
integration
(@astrojs/markdoc). Learn more: Markdoc,
Starlight; see also the
glossary.
Starlight native, Markdoc’s table tag with only what Markdoc defines, here
width on a header cell (Markdoc defines width for th only:
schema)
(file):
{% table %}
* Type {% width="20%" %}
* Description
---
* `value`
* A single string value for arbitrary configurations and other non-generated or validated strings.
---
* `json`
* An arbitrary JSON object for static configurations with many values.
---
* `user`
* Three string values for username, password, and password hash.
---
* `password`
* A single string value for passwords and other random string credentials. Values for this type can be automatically generated.
---
* `certificate`
* An object containing a root CA, certificate, and private key. Use this type for key pair apps that utilize a certificate, such as TLS connections. Values for this type can be automatically generated.
---
* `rsa`
* An object containing an RSA public key and private key without a certificate. Values for this type can be automatically generated.
---
* `ssh`
* An object containing an SSH-formatted public key and private key. Values for this type can be automatically generated.
{% /table %}
Starlight extension is the same table tag with hint attributes on the opening line. The attributes are added by list-table.mjs; the rest of the table does not change, except that the width moves from the cell to the tag (file):
{% table widths="20 auto" header-rows=1 stub-columns=1 roles="key prose" %}
* Type
* Description
---
…
{% /table %}
Starlight native-plain is the pipe table. Starlight
passthrough is the HTML after cleanup, but Markdoc reads text
inside HTML as Markdown, so on other pages it needed more changes than the
cleanup (Starlight summary).
A variable is written {% $vars.recommended_by %}.
AsciiDoc is a plain-text format with its own syntax for headings, lists
and tables; Asciidoctor is the program that reads it, and Antora builds
sites from it
(Antora depends on @asciidoctor/core).
A table is written between |=== lines
(delimiters);
settings in [ ] above it describe the columns. Learn more:
AsciiDoc, Asciidoctor;
see also the glossary.
Antora native (file):
[%header,cols=".<20%h,.<~"]
|===
|Type |Description
|`value`
|A single string value for arbitrary configurations and other non-generated or validated strings.
|`json`
|An arbitrary JSON object for static configurations with many values.
|`user`
|Three string values for username, password, and password hash.
|`password`
|A single string value for passwords and other random string credentials. Values for this type can be automatically generated.
|`certificate`
|An object containing a root CA, certificate, and private key. Use this type for key pair apps that utilize a certificate, such as TLS connections. Values for this type can be automatically generated.
|`rsa`
|An object containing an RSA public key and private key without a certificate. Values for this type can be automatically generated.
|`ssh`
|An object containing an SSH-formatted public key and private key. Values for this type can be automatically generated.
|===
The settings line, read left to right: %header makes the first row the
header row; cols describes each column. .< is top alignment, 20% the
width, h makes the column’s cells row headers, and ~ sizes the second
column by its content
(Antora conventions;
in Asciidoctor’s source:
cols parsing,
< is top, h is header,
%header).
The other Antora modes change only the settings line:
Native-plain
(file).
With no cols, Asciidoctor gives both columns the same width
(assign_column_widths):
[%header]
Extension
(file).
The words after each . are roles (class names;
shorthand parsing)
that a stylesheet gives meaning to: column 1 is a key that does not wrap, column 2 is prose:
[.hinted.col1-key.col2-prose.col1-nowrap%header,cols=".<20%h,.<~"]
Passthrough is the HTML inside a ++++ block. A variable is
written {recommended_by}, an AsciiDoc attribute.
A list table writes a table as a nested list: each row is a list item, and
each cell is an item inside it. Because a cell is a list item, it can hold
lists and paragraphs. The form is the list-table directive of
reStructuredText (a plain-text markup format from the Python world),
defined in docutils, the Python library that reads it
(ListTable, in the GitHub mirror of docutils),
which MyST also reads (see MyST). The Docusaurus and Zensical
extensions built for this evaluation use the same option names (widths,
header-rows, stub-columns) plus the hint options (roles, wrap,
title). Learn
more: MyST parser, tables,
reStructuredText list-table; see also the
glossary.
Docusaurus extension, a :::list-table block read by a remark plugin (a
step that Docusaurus’s Markdown reader, remark, runs on each page; it can
change the page before it is built) written for this evaluation,
plugins/list-table.js
(file):
:::list-table{widths="20 auto" header-rows="1" stub-columns="1" roles="key prose"}
- - Type
- Description
- - `value`
- A single string value for arbitrary configurations and other non-generated or validated strings.
- - `json`
- An arbitrary JSON object for static configurations with many values.
- - `user`
- Three string values for username, password, and password hash.
- - `password`
- A single string value for passwords and other random string credentials. Values for this type can be automatically generated.
- - `certificate`
- An object containing a root CA, certificate, and private key. Use this type for key pair apps that utilize a certificate, such as TLS connections. Values for this type can be automatically generated.
- - `rsa`
- An object containing an RSA public key and private key without a certificate. Values for this type can be automatically generated.
- - `ssh`
- An object containing an SSH-formatted public key and private key. Values for this type can be automatically generated.
:::
Zensical extension, a /// list-table block read by a Python-Markdown
extension written for this evaluation,
list_table.py
(file).
Python-Markdown’s list rules need four-space indents and a blank line
between rows:
/// list-table
widths: 20 auto
header-rows: 1
stub-columns: 1
roles: key prose
- - Type
- Description
- - `value`
- A single string value for arbitrary configurations and other non-generated or validated strings.
- - `json`
- An arbitrary JSON object for static configurations with many values.
- - `user`
- Three string values for username, password, and password hash.
- - `password`
- A single string value for passwords and other random string credentials. Values for this type can be automatically generated.
- - `certificate`
- An object containing a root CA, certificate, and private key. Use this type for key pair apps that utilize a certificate, such as TLS connections. Values for this type can be automatically generated.
- - `rsa`
- An object containing an RSA public key and private key without a certificate. Values for this type can be automatically generated.
- - `ssh`
- An object containing an SSH-formatted public key and private key. Values for this type can be automatically generated.
///
Starlight’s extension carries the same options as attributes on Markdoc’s own table tag (see Markdoc), so it needs no new block syntax.
MyST (Markedly Structured Text) is Markdown with directives: named blocks,
written as a fenced code block whose first line names the directive in
braces ({list-table}), with options on :name: value lines (MyST
parser source:
fence with {name},
option lines).
Sphinx, a documentation generator from the Python world, reads it through
the MyST parser
(which depends on Sphinx). Learn more:
MyST, MyST parser;
see also the glossary.
No MyST copy of credential-types exists in this repository. The
Sphinx probe wrote the
scale table (_oss_scale_table) instead. Its opening lines, from
docs/_oss_scale_table.md
(the rest of the rows omitted here):
```{list-table}
:header-rows: 1
:stub-columns: 1
:widths: 25 25 50
:class: table hinted col1-key col2-value col3-prose col1-nowrap
* - Component
- Total Instances
- Notes
* - Diego Cell
- ≥ 2
- The optimal balance between …
```
:header-rows:, :stub-columns: (row headers), :widths: and :class:
are the options of docutils’ list-table
(option list),
which MyST passes through. :class: puts classes on the table, and a stylesheet gives
the role and no-wrap classes their meaning, with no code. A variable is
written {{recommended_by}}.
For the sample table, measured in a browser at a 1280-pixel window (columns as percent of the table). Source: results.md; screenshots in poc/tables.md.
| Tool | Mode | Format | 20% width | Row headers | No-wrap key column |
|---|---|---|---|---|---|
| Docusaurus | passthrough | MDX (HTML as JSX) | yes | no | no |
| Docusaurus | extension | list table | yes | yes | yes |
| Docusaurus | native | pipe table | no (18/82) | no | no |
| Zensical | passthrough | HTML | yes (20/80) | no | no |
| Zensical | extension | list table | yes (20/80) | yes | yes |
| Zensical | native | pipe table with attribute list | yes (20/80) | no | no |
| Zensical | native-plain | pipe table | no (15/84) | no | no |
| Starlight | passthrough | HTML in Markdoc | yes (20/80) | no | no |
| Starlight | extension | Markdoc table tag with hint attributes | yes (20/80) | yes | yes |
| Starlight | native | Markdoc table tag | yes (20/80) | no | no |
| Starlight | native-plain | pipe table | no (18/82) | no | no |
| Antora | passthrough | HTML in a ++++ block |
yes (20/80) | no | no |
| Antora | extension | AsciiDoc table with roles | yes (20/80) | yes | yes |
| Antora | native | AsciiDoc table | yes (20/80) | yes | no |
| Antora | native-plain | AsciiDoc table, no cols |
no (50/50) | no | no |
The passthrough rows keep the source’s <th> header row but have no row
headers, because the source has none: its first column is ordinary cells.
Every mode in every tool passes the table’s three spot checks (seven rows
of two cells, type names as code, no stray typographic quotes) after
cleanup. The Middleman probe built the source unchanged and matched the
published table cell for cell; the Eleventy and Sphinx probes did not build
this page.
Not yet written: Hugo’s input (Markdown read by goldmark, a Hugo dependency, with shortcodes) and VitePress’s input (Markdown read by markdown-it, with Vue components; VitePress dependencies, markdown-it). Neither tool has been assessed; no page source exists for either.
Not yet written: Markua, a Markdown-like format for books and courses (Markua Spec, version 0.31.50 of 2026-08-11, read 2026-10-10). Its spec was developed at Leanpub, is based on the CommonMark Spec 0.31.2 and is licensed CC-BY-SA 4.0. To Markdown it adds attribute lists, document settings, and “resources” such as tables, including CSV tables. It also removes raw HTML: “in Markua all raw HTML elements are removed”, because HTML is only one of its outputs, next to LaTeX and PDF. It does produce HTML; the spec defines how Markua maps to HTML fragments, and leaves the rest of the page to the processor. Every test page uses HTML, so the test is whether Markua’s own syntax carries what that HTML does (R-10 simple text plus HTML where needed). No maintained open-source Markua processor was found (R-19 open source only). The spec’s own note says Markua 0.30 is “currently in beta on Leanpub”, a hosted publishing service. A GitHub search on 2026-10-10 found only parsers that predate Markua 0.30 and have not changed since: dshafik/markua (PHP, last change 2015), danhunsaker/markua (PHP, built on League\CommonMark, 2018), and krtek4/Markua-py (Python, 2016). The one active project, fatpub (GPL-3.0, last change 2026-09-19), preprocesses Markua for Pandoc to make Word files, not web pages.
This page shows one table only, by design. The other test pages, in each
tool and mode, are in each site folder under
concepts/tables/sites/, and the conventions
for each tool are in its CONVENTIONS.md, for example
Docusaurus.