cf-docs-rfc-proposal

Input formats

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 sample table

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

Formats at a glance

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

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">

Files: Zensical, Starlight.

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

Antora passthrough (first and last lines)
++++
<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

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:

EJS

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:

MDX

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.

Pipe 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

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

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

Starlight extension: the changed lines
{% 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

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:

Antora native-plain and extension: 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.

List table

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

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
  - &ge; 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}}.

What each format carried

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.

Formats not yet written

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.