Status: draft — all seven test pages written as of 2026-10-12, for review.
This file puts each test page’s tables next to what the candidate tools
made of them. For each page: the table as published on docs.cloudfoundry.org
today, the text an author writes in each tool, and the page that tool builds
from it. The test pages are five pages the Docs WG lead picked because
their tables are hard to express outside HTML, plus two pages added later:
uaa-performance, a second table style, and _oss_roles_table, a table
wider than the content column (see the glossary). How the work was done is in
the README; the full grids and measurements are in
results.md.
How to read the comparisons:
_oss_scale_tablehigh-availability
page, https://docs.cloudfoundry.org/concepts/high-availability.html
(include line in the host page’s source).
The table on the page: Recommended instance counts for high availability_oss_scale_table.html.md.erb in cloudfoundry/docs-cloudfoundry-concepts, commit 4ac2fb1The partial, from docs-cloudfoundry-concepts, holds one table: Component / Total Instances / Notes. The source sets widths 25/25/50. The key column’s longest entry, “Cloud Controller Worker”, pushes against its 25% in the tools where the no-wrap hint wins.
What the table asks for (R-02 rich tables):
<col width="…"> elements before the header
(R-03 column widths as hints).≥ 2 should
not break between ≥ and 2. Column 3 is prose.<col> elements are not closed. <col> is a void element (one with
no closing tag), so browsers accept that, but XML and JSX parsers do not.
Every passthrough version closes them, <col width="25%" />
(R-24 markup cleanup before conversion).class="table",
the standard style, as every HTML table names its style
(R-09 table styles by class).<strong>. The intent file drops it, since
bold header cells are a template convention, and every converted input
drops it. (Until 2026-10-12 the passthrough inputs kept it and Antora’s
AsciiDoc wrote it as *Component*; the inputs and screenshots were
corrected.)<%= vars.recommended_by %>, which
renders as “Cloud Foundry”
(R-04 variables everywhere).scale-table-host, instead
of copying all of high-availability
(R-05 partials and reuse;
SOURCES.md, “The partial and its host”).At a glance, from the screenshots below. Column widths are the measured values in results.md, percent of the table; results.md has no measurement for the published page, so its cell is empty:
| Output | Column widths | Header cells | Body cells, vertically | Component cells as row headers | “Cloud Controller Worker” on one line | Rule between the columns |
|---|---|---|---|---|---|---|
| Published | left | centered | no | no | yes | |
| Docusaurus native | 18/15/67, sized by content | centered | centered | no | no | yes |
| Docusaurus passthrough | 25/25/50 | centered | centered | no | no | yes |
| Zensical native and passthrough | 25/25/50 | left | top | no | no | no |
| Starlight native and passthrough | 25/25/50 | left | top | no | no | no |
| Antora native | 25/25/50 | left | top | yes (bold) | yes | yes |
| Antora passthrough | 25/25/50 | left | centered | no | yes | yes |
| Docusaurus extension | 30/24/46 | “Component” left, the other two centered | top | yes (bold) | yes | yes |
| Zensical extension | 26/25/49 | left | top | yes (bold) | yes | no |
| Starlight extension | 31/24/45 | left | top | yes (bold) | yes | no |
| Antora extension | 25/25/50 | left | top | yes (bold) | yes | yes |
All thirteen rows and three columns are present in every output. ≥
renders twelve times, the 0 in the PostgreSQL Server row renders as code,
the NATS Server row reads “Cloud Foundry recommends …”, the two empty Notes
cells keep their rows at three cells, and the table renders inside its host
page: the spot checks (per-table checks listed in the intent file and run on
every build) pass in every mode of every tool.

The source asks for 25, 25 and 50%. Header cells are bold and on the left. Cells sit in the vertical middle of their row, and every cell has a border. “Cloud Controller Worker” wraps onto two lines.
<col> elements)The following table provides recommended instance counts for a high-availability deployment. You can
decrease the footprint of your deployment by specifying fewer instances and combining multiple components onto a
single VM.
<table>
<col width="25%">
<col width="25%">
<col width="50%">
<thead>
<tr>
<th><strong>Component</strong></th>
<th><strong>Total Instances</strong></th>
<th><strong>Notes</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td>Diego Cell</td>
<td>≥ 2</td>
<td>The optimal balance between CPU/memory sizing and instance count depends on the performance characteristics of the apps that run on Diego cells. Scaling vertically with larger Diego cells makes for larger points of failure, and more apps go down when a cell fails. On the other hand, scaling horizontally decreases the speed at which the system rebalances apps. Rebalancing 100 cells takes longer and demands more processing overhead than rebalancing 20 cells.</td>
</tr>
<tr>
<td>Diego Brain</td>
<td>≥ 2</td>
<td>One per AZ, or two if only one AZ.</td>
</tr>
<tr>
<td>Diego BBS</td>
<td>≥ 2</td>
<td>One per AZ, or two if only one AZ.</td>
</tr>
<tr>
<td>PostgreSQL Server</td>
<td>0 or 1</td>
<td><code>0</code> if Postgres database is external.</td>
</tr>
<tr>
<td>MySQL Proxy</td>
<td>≥ 2</td>
<td></td>
</tr>
<tr>
<td>NATS Server</td>
<td>≥ 2</td>
<td>You might run a single NATS instance if you lack the resources to deploy two stable NATS servers. Components using NATS are resilient to message failures and the BOSH resurrector recovers the NATS VM quickly if it becomes non-responsive. NATS includes metrics as well as route registration and deregistration messages. <%= vars.recommended_by %> recommends scaling NATS VMs to 2 or more CPU.</td>
</tr>
<tr>
<td>Cloud Controller API</td>
<td>≥ 2</td>
<td>Scale the Cloud Controller to accommodate the number of requests to the API and the number of apps in the system.</td>
</tr>
<tr>
<td>Cloud Controller Worker</td>
<td>≥ 2</td>
<td>Scale the Cloud Controller to accommodate the number of asynchronous requests to the API and background jobs.</td>
</tr>
<tr>
<td>Router</td>
<td>≥ 2</td>
<td>Scale the router to accommodate the number of incoming requests. Additional instances increase available bandwidth. In general, this load is much less than the load on host VMs.</td>
</tr>
<tr>
<td>UAA</td>
<td>≥ 2</td>
<td></td>
</tr>
<tr>
<td>Doppler Server</td>
<td>≥ 2</td>
<td>Deploying additional Doppler servers splits traffic across them. For high availability, use at least two per Availability Zone (AZ).</td>
</tr>
<tr>
<td>Loggregator TC</td>
<td>≥ 2</td>
<td>Deploying additional Loggregator Traffic Controllers allows you to direct traffic to them in a round-robin manner. For high availability, use at least two per AZ.</td>
</tr>
<tr>
<td>Log Cache</td>
<td>≥ 1</td>
<td>Deploying additional Log Cache instances increases the total storage, sharding data by app ID. If app logs and metrics are sharded to an unavailable instance, they are unavailable when the designated instance is unavailable regardless of the number of instances or AZs.</td>
</tr>
</tbody>
</table>
ERB (Embedded Ruby, <%= … %> tags in a page; see the
glossary) is how today’s pages insert variables and
partials. This partial uses one variable, <%= vars.recommended_by %>, and
the high-availability page includes it with
<%= partial 'oss_scale_table' %>
(glossary: partial).
Pages are MDX: Markdown that also accepts JSX, the HTML-like syntax of
React components (see the glossary). A partial is an
MDX file whose name starts with _, so it has no page of its own. The host
page imports it and uses it as a component; the partial imports the
variables itself (import vars from '@site/vars.json';, its first line)
(conventions,
“Partials”).
---
title: Scale table host
---
import OssScaleTable from './_oss_scale_table.mdx';
Host page for the `_oss_scale_table` partial, standing in for
`high-availability.html.md.erb`, which includes it with
`<%= partial 'oss_scale_table' %>`.
<OssScaleTable />
The host page is the same in every mode.
| Component | Total Instances | Notes |
| --- | --- | --- |
| Diego Cell | ≥ 2 | The optimal balance between CPU/memory sizing and instance count depends on the performance characteristics of the apps that run on Diego cells. Scaling vertically with larger Diego cells makes for larger points of failure, and more apps go down when a cell fails. On the other hand, scaling horizontally decreases the speed at which the system rebalances apps. Rebalancing 100 cells takes longer and demands more processing overhead than rebalancing 20 cells. |
| Diego Brain | ≥ 2 | One per AZ, or two if only one AZ. |
| Diego BBS | ≥ 2 | One per AZ, or two if only one AZ. |
| PostgreSQL Server | 0 or 1 | `0` if Postgres database is external. |
| MySQL Proxy | ≥ 2 | |
| NATS Server | ≥ 2 | You might run a single NATS instance if you lack the resources to deploy two stable NATS servers. Components using NATS are resilient to message failures and the BOSH resurrector recovers the NATS VM quickly if it becomes non-responsive. NATS includes metrics as well as route registration and deregistration messages. {vars.recommended_by} recommends scaling NATS VMs to 2 or more CPU. |
| Cloud Controller API | ≥ 2 | Scale the Cloud Controller to accommodate the number of requests to the API and the number of apps in the system. |
| Cloud Controller Worker | ≥ 2 | Scale the Cloud Controller to accommodate the number of asynchronous requests to the API and background jobs. |
| Router | ≥ 2 | Scale the router to accommodate the number of incoming requests. Additional instances increase available bandwidth. In general, this load is much less than the load on host VMs. |
| UAA | ≥ 2 | |
| Doppler Server | ≥ 2 | Deploying additional Doppler servers splits traffic across them. For high availability, use at least two per Availability Zone (AZ). |
| Loggregator TC | ≥ 2 | Deploying additional Loggregator Traffic Controllers allows you to direct traffic to them in a round-robin manner. For high availability, use at least two per AZ. |
| Log Cache | ≥ 1 | Deploying additional Log Cache instances increases the total storage, sharding data by app ID. If app logs and metrics are sharded to an unavailable instance, they are unavailable when the designated instance is unavailable regardless of the number of instances or AZs. |
<col /> closed and wrapped in <colgroup><table class="table">
<colgroup>
<col width="25%" />
<col width="25%" />
<col width="50%" />
</colgroup>
<thead>
<tr>
<th>Component</th>
<th>Total Instances</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td>Diego Cell</td>
<td>≥ 2</td>
<td>The optimal balance between CPU/memory sizing and instance count depends on the performance characteristics of the apps that run on Diego cells. Scaling vertically with larger Diego cells makes for larger points of failure, and more apps go down when a cell fails. On the other hand, scaling horizontally decreases the speed at which the system rebalances apps. Rebalancing 100 cells takes longer and demands more processing overhead than rebalancing 20 cells.</td>
</tr>
<tr>
<td>Diego Brain</td>
<td>≥ 2</td>
<td>One per AZ, or two if only one AZ.</td>
</tr>
<tr>
<td>Diego BBS</td>
<td>≥ 2</td>
<td>One per AZ, or two if only one AZ.</td>
</tr>
<tr>
<td>PostgreSQL Server</td>
<td>0 or 1</td>
<td><code>0</code> if Postgres database is external.</td>
</tr>
<tr>
<td>MySQL Proxy</td>
<td>≥ 2</td>
<td></td>
</tr>
<tr>
<td>NATS Server</td>
<td>≥ 2</td>
<td>You might run a single NATS instance if you lack the resources to deploy two stable NATS servers. Components using NATS are resilient to message failures and the BOSH resurrector recovers the NATS VM quickly if it becomes non-responsive. NATS includes metrics as well as route registration and deregistration messages. {vars.recommended_by} recommends scaling NATS VMs to 2 or more CPU.</td>
</tr>
<tr>
<td>Cloud Controller API</td>
<td>≥ 2</td>
<td>Scale the Cloud Controller to accommodate the number of requests to the API and the number of apps in the system.</td>
</tr>
<tr>
<td>Cloud Controller Worker</td>
<td>≥ 2</td>
<td>Scale the Cloud Controller to accommodate the number of asynchronous requests to the API and background jobs.</td>
</tr>
<tr>
<td>Router</td>
<td>≥ 2</td>
<td>Scale the router to accommodate the number of incoming requests. Additional instances increase available bandwidth. In general, this load is much less than the load on host VMs.</td>
</tr>
<tr>
<td>UAA</td>
<td>≥ 2</td>
<td></td>
</tr>
<tr>
<td>Doppler Server</td>
<td>≥ 2</td>
<td>Deploying additional Doppler servers splits traffic across them. For high availability, use at least two per Availability Zone (AZ).</td>
</tr>
<tr>
<td>Loggregator TC</td>
<td>≥ 2</td>
<td>Deploying additional Loggregator Traffic Controllers allows you to direct traffic to them in a round-robin manner. For high availability, use at least two per AZ.</td>
</tr>
<tr>
<td>Log Cache</td>
<td>≥ 1</td>
<td>Deploying additional Log Cache instances increases the total storage, sharding data by app ID. If app logs and metrics are sharded to an unavailable instance, they are unavailable when the designated instance is unavailable regardless of the number of instances or AZs.</td>
</tr>
</tbody>
</table>
The variable is written {vars.recommended_by} in every mode, a JSX
expression.
Files: native, passthrough, passthrough as written, extension; host page. Docusaurus has no native-plain page: its native page already has no width settings.
Native output:

Passthrough output:

Differences seen:
<col> because it is not closed. Passthrough also needed the
<col /> elements wrapped in <colgroup>
(R-24 markup cleanup before conversion;
raw passthrough errors).| between cells; see the glossary)
carries none, so the columns are sized by their content, 18/15/67. Column
1 is too narrow for most component names: “PostgreSQL Server” takes two
lines and “Cloud Controller Worker” three. The “Total Instances” header
takes two lines. Passthrough keeps 25/25/50.Extension mode. A :::list-table block, read by a remark plugin added
to the site:
plugins/list-table.js,
with hints.css.
:::list-table{widths="25 25 50" header-rows="1" stub-columns="1" roles="key value prose"}
- - Component
- Total Instances
- Notes
- - Diego Cell
- ≥ 2
- The optimal balance between CPU/memory sizing and instance count depends on the performance characteristics of the apps that run on Diego cells. Scaling vertically with larger Diego cells makes for larger points of failure, and more apps go down when a cell fails. On the other hand, scaling horizontally decreases the speed at which the system rebalances apps. Rebalancing 100 cells takes longer and demands more processing overhead than rebalancing 20 cells.
- - Diego Brain
- ≥ 2
- One per AZ, or two if only one AZ.
- - Diego BBS
- ≥ 2
- One per AZ, or two if only one AZ.
- - PostgreSQL Server
- 0 or 1
- `0` if Postgres database is external.
- - MySQL Proxy
- ≥ 2
-
- - NATS Server
- ≥ 2
- You might run a single NATS instance if you lack the resources to deploy two stable NATS servers. Components using NATS are resilient to message failures and the BOSH resurrector recovers the NATS VM quickly if it becomes non-responsive. NATS includes metrics as well as route registration and deregistration messages. {vars.recommended_by} recommends scaling NATS VMs to 2 or more CPU.
- - Cloud Controller API
- ≥ 2
- Scale the Cloud Controller to accommodate the number of requests to the API and the number of apps in the system.
- - Cloud Controller Worker
- ≥ 2
- Scale the Cloud Controller to accommodate the number of asynchronous requests to the API and background jobs.
- - Router
- ≥ 2
- Scale the router to accommodate the number of incoming requests. Additional instances increase available bandwidth. In general, this load is much less than the load on host VMs.
- - UAA
- ≥ 2
-
- - Doppler Server
- ≥ 2
- Deploying additional Doppler servers splits traffic across them. For high availability, use at least two per Availability Zone (AZ).
- - Loggregator TC
- ≥ 2
- Deploying additional Loggregator Traffic Controllers allows you to direct traffic to them in a round-robin manner. For high availability, use at least two per AZ.
- - Log Cache
- ≥ 1
- Deploying additional Log Cache instances increases the total storage, sharding data by app ID. If app logs and metrics are sharded to an unavailable instance, they are unavailable when the designated instance is unavailable regardless of the number of instances or AZs.
:::
widths sets 25/25/50, header-rows="1" makes the first row the header,
stub-columns="1" makes column 1 row headers, and roles names column 1 a
key column, column 2 a value column and column 3 prose. A key column does
not wrap, up to a cap. An empty cell is a bare -.
Extension output:

Differences seen, against the published page and the other two modes:
--table-nowrap-max, 16em);
past it the text wraps between words
(Docusaurus finding 1;
screenshot).credential-types.Pages are Markdown read by Python-Markdown, which passes HTML blocks through
unchanged (see the glossary). An
attribute list, {: … } after a cell’s text, sets HTML attributes on that
cell. A partial lives in partials/<mode>/, outside docs/, so it never
becomes a page. The host includes it with the template engine’s include,
which also renders the partial’s variables; a --8<-- snippet include
would leave <%= vars.recommended_by %> as literal text
(Zensical finding 7).
---
title: Scale table host
---
Host page for the `_oss_scale_table` partial, standing in for
`high-availability.html.md.erb`, which includes it with
an ERB `partial 'oss_scale_table'` call.
<% include "native/_oss_scale_table.md" %>
Each mode’s host page includes that mode’s partial. The host page names the
ERB call in words, not as a tag: every <%= … %> on a page goes through the
template engine, and an earlier draft that showed the tag produced a page
that said “Macro Syntax Error” while the build reported success
(Zensical finding 3).
| Component {: style="width:25%" } | Total Instances {: style="width:25%" } | Notes {: style="width:50%" } |
| --- | --- | --- |
| Diego Cell | ≥ 2 | The optimal balance between CPU/memory sizing and instance count depends on the performance characteristics of the apps that run on Diego cells. Scaling vertically with larger Diego cells makes for larger points of failure, and more apps go down when a cell fails. On the other hand, scaling horizontally decreases the speed at which the system rebalances apps. Rebalancing 100 cells takes longer and demands more processing overhead than rebalancing 20 cells. |
| Diego Brain | ≥ 2 | One per AZ, or two if only one AZ. |
| Diego BBS | ≥ 2 | One per AZ, or two if only one AZ. |
| PostgreSQL Server | 0 or 1 | `0` if Postgres database is external. |
| MySQL Proxy | ≥ 2 | |
| NATS Server | ≥ 2 | You might run a single NATS instance if you lack the resources to deploy two stable NATS servers. Components using NATS are resilient to message failures and the BOSH resurrector recovers the NATS VM quickly if it becomes non-responsive. NATS includes metrics as well as route registration and deregistration messages. <%= vars.recommended_by %> recommends scaling NATS VMs to 2 or more CPU. |
| Cloud Controller API | ≥ 2 | Scale the Cloud Controller to accommodate the number of requests to the API and the number of apps in the system. |
| Cloud Controller Worker | ≥ 2 | Scale the Cloud Controller to accommodate the number of asynchronous requests to the API and background jobs. |
| Router | ≥ 2 | Scale the router to accommodate the number of incoming requests. Additional instances increase available bandwidth. In general, this load is much less than the load on host VMs. |
| UAA | ≥ 2 | |
| Doppler Server | ≥ 2 | Deploying additional Doppler servers splits traffic across them. For high availability, use at least two per Availability Zone (AZ). |
| Loggregator TC | ≥ 2 | Deploying additional Loggregator Traffic Controllers allows you to direct traffic to them in a round-robin manner. For high availability, use at least two per AZ. |
| Log Cache | ≥ 1 | Deploying additional Log Cache instances increases the total storage, sharding data by app ID. If app logs and metrics are sharded to an unavailable instance, they are unavailable when the designated instance is unavailable regardless of the number of instances or AZs. |
<col /> closed and the class added<table class="table">
<col width="25%" />
<col width="25%" />
<col width="50%" />
<thead>
<tr>
<th>Component</th>
<th>Total Instances</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td>Diego Cell</td>
<td>≥ 2</td>
<td>The optimal balance between CPU/memory sizing and instance count depends on the performance characteristics of the apps that run on Diego cells. Scaling vertically with larger Diego cells makes for larger points of failure, and more apps go down when a cell fails. On the other hand, scaling horizontally decreases the speed at which the system rebalances apps. Rebalancing 100 cells takes longer and demands more processing overhead than rebalancing 20 cells.</td>
</tr>
<tr>
<td>Diego Brain</td>
<td>≥ 2</td>
<td>One per AZ, or two if only one AZ.</td>
</tr>
<tr>
<td>Diego BBS</td>
<td>≥ 2</td>
<td>One per AZ, or two if only one AZ.</td>
</tr>
<tr>
<td>PostgreSQL Server</td>
<td>0 or 1</td>
<td><code>0</code> if Postgres database is external.</td>
</tr>
<tr>
<td>MySQL Proxy</td>
<td>≥ 2</td>
<td></td>
</tr>
<tr>
<td>NATS Server</td>
<td>≥ 2</td>
<td>You might run a single NATS instance if you lack the resources to deploy two stable NATS servers. Components using NATS are resilient to message failures and the BOSH resurrector recovers the NATS VM quickly if it becomes non-responsive. NATS includes metrics as well as route registration and deregistration messages. <%= vars.recommended_by %> recommends scaling NATS VMs to 2 or more CPU.</td>
</tr>
<tr>
<td>Cloud Controller API</td>
<td>≥ 2</td>
<td>Scale the Cloud Controller to accommodate the number of requests to the API and the number of apps in the system.</td>
</tr>
<tr>
<td>Cloud Controller Worker</td>
<td>≥ 2</td>
<td>Scale the Cloud Controller to accommodate the number of asynchronous requests to the API and background jobs.</td>
</tr>
<tr>
<td>Router</td>
<td>≥ 2</td>
<td>Scale the router to accommodate the number of incoming requests. Additional instances increase available bandwidth. In general, this load is much less than the load on host VMs.</td>
</tr>
<tr>
<td>UAA</td>
<td>≥ 2</td>
<td></td>
</tr>
<tr>
<td>Doppler Server</td>
<td>≥ 2</td>
<td>Deploying additional Doppler servers splits traffic across them. For high availability, use at least two per Availability Zone (AZ).</td>
</tr>
<tr>
<td>Loggregator TC</td>
<td>≥ 2</td>
<td>Deploying additional Loggregator Traffic Controllers allows you to direct traffic to them in a round-robin manner. For high availability, use at least two per AZ.</td>
</tr>
<tr>
<td>Log Cache</td>
<td>≥ 1</td>
<td>Deploying additional Log Cache instances increases the total storage, sharding data by app ID. If app logs and metrics are sharded to an unavailable instance, they are unavailable when the designated instance is unavailable regardless of the number of instances or AZs.</td>
</tr>
</tbody>
</table>
The variable keeps its ERB form, <%= vars.recommended_by %>, in every
mode.
Files: native, native-plain, passthrough, passthrough as written, extension; host page.
Native and passthrough output (the two screenshots differ only by image-compression noise):

Differences seen:
<col>
elements is the intent file’s cleanup, not something Zensical forces.table.table the theme’s
table look (Zensical finding 1),
so the two modes look the same.Extension mode. A /// list-table block, read by a Python-Markdown
extension added to the site,
list_table.py, with
hints.css.
/// list-table
widths: 25 25 50
header-rows: 1
stub-columns: 1
roles: key value prose
- - Component
- Total Instances
- Notes
- - Diego Cell
- ≥ 2
- The optimal balance between CPU/memory sizing and instance count depends on the performance characteristics of the apps that run on Diego cells. Scaling vertically with larger Diego cells makes for larger points of failure, and more apps go down when a cell fails. On the other hand, scaling horizontally decreases the speed at which the system rebalances apps. Rebalancing 100 cells takes longer and demands more processing overhead than rebalancing 20 cells.
- - Diego Brain
- ≥ 2
- One per AZ, or two if only one AZ.
- - Diego BBS
- ≥ 2
- One per AZ, or two if only one AZ.
- - PostgreSQL Server
- 0 or 1
- `0` if Postgres database is external.
- - MySQL Proxy
- ≥ 2
- <!-- -->
- - NATS Server
- ≥ 2
- You might run a single NATS instance if you lack the resources to deploy two stable NATS servers. Components using NATS are resilient to message failures and the BOSH resurrector recovers the NATS VM quickly if it becomes non-responsive. NATS includes metrics as well as route registration and deregistration messages. <%= vars.recommended_by %> recommends scaling NATS VMs to 2 or more CPU.
- - Cloud Controller API
- ≥ 2
- Scale the Cloud Controller to accommodate the number of requests to the API and the number of apps in the system.
- - Cloud Controller Worker
- ≥ 2
- Scale the Cloud Controller to accommodate the number of asynchronous requests to the API and background jobs.
- - Router
- ≥ 2
- Scale the router to accommodate the number of incoming requests. Additional instances increase available bandwidth. In general, this load is much less than the load on host VMs.
- - UAA
- ≥ 2
- <!-- -->
- - Doppler Server
- ≥ 2
- Deploying additional Doppler servers splits traffic across them. For high availability, use at least two per Availability Zone (AZ).
- - Loggregator TC
- ≥ 2
- Deploying additional Loggregator Traffic Controllers allows you to direct traffic to them in a round-robin manner. For high availability, use at least two per AZ.
- - Log Cache
- ≥ 1
- Deploying additional Log Cache instances increases the total storage, sharding data by app ID. If app logs and metrics are sharded to an unavailable instance, they are unavailable when the designated instance is unavailable regardless of the number of instances or AZs.
///
The options mean the same as in the Docusaurus directive. An empty cell is
written - <!-- -->: a bare - under a line turns that line into a
heading, so the row loses a cell and the build reports nothing
(Zensical finding 5).
Extension output:

Differences seen, against native and passthrough:
Starlight is a documentation theme for the Astro site builder
(depends on astro).
These pages
are Markdoc, Markdown with {% %} tags, with HTML allowed (see the
glossary). Markdoc’s {% table %} tag writes each
cell as a list item and each row break as ---. A partial is a file whose
name starts with _; the host includes it with Markdoc’s partial tag,
and Markdoc wraps it in its own <article>
(conventions,
“Partials”).
---
title: Scale table host
---
Host page for the `_oss_scale_table` partial, standing in for
`high-availability.html.md.erb`, which includes it with
an ERB `partial 'oss_scale_table'` call.
{% partial file="./_oss_scale_table.mdoc" /%}
The host page is the same in every mode.
{% table %}
* Component {% width="25%" %}
* Total Instances {% width="25%" %}
* Notes {% width="50%" %}
---
* Diego Cell
* ≥ 2
* The optimal balance between CPU/memory sizing and instance count depends on the performance characteristics of the apps that run on Diego cells. Scaling vertically with larger Diego cells makes for larger points of failure, and more apps go down when a cell fails. On the other hand, scaling horizontally decreases the speed at which the system rebalances apps. Rebalancing 100 cells takes longer and demands more processing overhead than rebalancing 20 cells.
---
* Diego Brain
* ≥ 2
* One per AZ, or two if only one AZ.
---
* Diego BBS
* ≥ 2
* One per AZ, or two if only one AZ.
---
* PostgreSQL Server
* 0 or 1
* `0` if Postgres database is external.
---
* MySQL Proxy
* ≥ 2
* <!-- -->
---
* NATS Server
* ≥ 2
* You might run a single NATS instance if you lack the resources to deploy two stable NATS servers. Components using NATS are resilient to message failures and the BOSH resurrector recovers the NATS VM quickly if it becomes non-responsive. NATS includes metrics as well as route registration and deregistration messages. {% $vars.recommended_by %} recommends scaling NATS VMs to 2 or more CPU.
---
* Cloud Controller API
* ≥ 2
* Scale the Cloud Controller to accommodate the number of requests to the API and the number of apps in the system.
---
* Cloud Controller Worker
* ≥ 2
* Scale the Cloud Controller to accommodate the number of asynchronous requests to the API and background jobs.
---
* Router
* ≥ 2
* Scale the router to accommodate the number of incoming requests. Additional instances increase available bandwidth. In general, this load is much less than the load on host VMs.
---
* UAA
* ≥ 2
* <!-- -->
---
* Doppler Server
* ≥ 2
* Deploying additional Doppler servers splits traffic across them. For high availability, use at least two per Availability Zone (AZ).
---
* Loggregator TC
* ≥ 2
* Deploying additional Loggregator Traffic Controllers allows you to direct traffic to them in a round-robin manner. For high availability, use at least two per AZ.
---
* Log Cache
* ≥ 1
* Deploying additional Log Cache instances increases the total storage, sharding data by app ID. If app logs and metrics are sharded to an unavailable instance, they are unavailable when the designated instance is unavailable regardless of the number of instances or AZs.
{% /table %}
The two empty Notes cells are written * <!-- -->.
<col /> closed and the class added<table class="table">
<col width="25%" />
<col width="25%" />
<col width="50%" />
<thead>
<tr>
<th>Component</th>
<th>Total Instances</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td>Diego Cell</td>
<td>≥ 2</td>
<td>The optimal balance between CPU/memory sizing and instance count depends on the performance characteristics of the apps that run on Diego cells. Scaling vertically with larger Diego cells makes for larger points of failure, and more apps go down when a cell fails. On the other hand, scaling horizontally decreases the speed at which the system rebalances apps. Rebalancing 100 cells takes longer and demands more processing overhead than rebalancing 20 cells.</td>
</tr>
<tr>
<td>Diego Brain</td>
<td>≥ 2</td>
<td>One per AZ, or two if only one AZ.</td>
</tr>
<tr>
<td>Diego BBS</td>
<td>≥ 2</td>
<td>One per AZ, or two if only one AZ.</td>
</tr>
<tr>
<td>PostgreSQL Server</td>
<td>0 or 1</td>
<td><code>0</code> if Postgres database is external.</td>
</tr>
<tr>
<td>MySQL Proxy</td>
<td>≥ 2</td>
<td></td>
</tr>
<tr>
<td>NATS Server</td>
<td>≥ 2</td>
<td>You might run a single NATS instance if you lack the resources to deploy two stable NATS servers. Components using NATS are resilient to message failures and the BOSH resurrector recovers the NATS VM quickly if it becomes non-responsive. NATS includes metrics as well as route registration and deregistration messages. {% $vars.recommended_by %} recommends scaling NATS VMs to 2 or more CPU.</td>
</tr>
<tr>
<td>Cloud Controller API</td>
<td>≥ 2</td>
<td>Scale the Cloud Controller to accommodate the number of requests to the API and the number of apps in the system.</td>
</tr>
<tr>
<td>Cloud Controller Worker</td>
<td>≥ 2</td>
<td>Scale the Cloud Controller to accommodate the number of asynchronous requests to the API and background jobs.</td>
</tr>
<tr>
<td>Router</td>
<td>≥ 2</td>
<td>Scale the router to accommodate the number of incoming requests. Additional instances increase available bandwidth. In general, this load is much less than the load on host VMs.</td>
</tr>
<tr>
<td>UAA</td>
<td>≥ 2</td>
<td></td>
</tr>
<tr>
<td>Doppler Server</td>
<td>≥ 2</td>
<td>Deploying additional Doppler servers splits traffic across them. For high availability, use at least two per Availability Zone (AZ).</td>
</tr>
<tr>
<td>Loggregator TC</td>
<td>≥ 2</td>
<td>Deploying additional Loggregator Traffic Controllers allows you to direct traffic to them in a round-robin manner. For high availability, use at least two per AZ.</td>
</tr>
<tr>
<td>Log Cache</td>
<td>≥ 1</td>
<td>Deploying additional Log Cache instances increases the total storage, sharding data by app ID. If app logs and metrics are sharded to an unavailable instance, they are unavailable when the designated instance is unavailable regardless of the number of instances or AZs.</td>
</tr>
</tbody>
</table>
The variable is written {% $vars.recommended_by %} in every mode.
Files: native, native-plain, passthrough, passthrough as written, extension; host page.
Native output:

Passthrough output:

Differences seen:
width
on the header cells. Without them (native-plain, a pipe table), the
columns are 18/17/65.Extension mode. Markdoc’s own {% table %} tag with extra attributes,
declared for the site in
list-table.mjs, with
hints.css.
{% table widths="25 25 50" header-rows=1 stub-columns=1 roles="key value prose" %}
* Component
* Total Instances
* Notes
---
* Diego Cell
* ≥ 2
* The optimal balance between CPU/memory sizing and instance count depends on the performance characteristics of the apps that run on Diego cells. Scaling vertically with larger Diego cells makes for larger points of failure, and more apps go down when a cell fails. On the other hand, scaling horizontally decreases the speed at which the system rebalances apps. Rebalancing 100 cells takes longer and demands more processing overhead than rebalancing 20 cells.
---
* Diego Brain
* ≥ 2
* One per AZ, or two if only one AZ.
---
* Diego BBS
* ≥ 2
* One per AZ, or two if only one AZ.
---
* PostgreSQL Server
* 0 or 1
* `0` if Postgres database is external.
---
* MySQL Proxy
* ≥ 2
* <!-- -->
---
* NATS Server
* ≥ 2
* You might run a single NATS instance if you lack the resources to deploy two stable NATS servers. Components using NATS are resilient to message failures and the BOSH resurrector recovers the NATS VM quickly if it becomes non-responsive. NATS includes metrics as well as route registration and deregistration messages. {% $vars.recommended_by %} recommends scaling NATS VMs to 2 or more CPU.
---
* Cloud Controller API
* ≥ 2
* Scale the Cloud Controller to accommodate the number of requests to the API and the number of apps in the system.
---
* Cloud Controller Worker
* ≥ 2
* Scale the Cloud Controller to accommodate the number of asynchronous requests to the API and background jobs.
---
* Router
* ≥ 2
* Scale the router to accommodate the number of incoming requests. Additional instances increase available bandwidth. In general, this load is much less than the load on host VMs.
---
* UAA
* ≥ 2
* <!-- -->
---
* Doppler Server
* ≥ 2
* Deploying additional Doppler servers splits traffic across them. For high availability, use at least two per Availability Zone (AZ).
---
* Loggregator TC
* ≥ 2
* Deploying additional Loggregator Traffic Controllers allows you to direct traffic to them in a round-robin manner. For high availability, use at least two per AZ.
---
* Log Cache
* ≥ 1
* Deploying additional Log Cache instances increases the total storage, sharding data by app ID. If app logs and metrics are sharded to an unavailable instance, they are unavailable when the designated instance is unavailable regardless of the number of instances or AZs.
{% /table %}
The attributes mean the same as in the Docusaurus directive.
Extension output:

Differences seen, against native and passthrough:
Antora builds sites from AsciiDoc, a plain-text markup with its own table
syntax (see the glossary). The whole page is
rewritten from Markdown to AsciiDoc in every mode, including passthrough. In
passthrough the HTML sits inside a passthrough block (++++), which
AsciiDoc hands to the browser without reading it. The partial lives in
modules/ROOT/partials/, and the host page includes it with include::;
its attributes (AsciiDoc’s variables) render
(conventions, “Partials”).
On this host page there is no table of contents beside the article, so
tables are 792 pixels wide, against 686 on the other pages
(Antora).
= Scale table host
Host page for the `+_oss_scale_table+` partial, standing in for
`high-availability.html.md.erb`, which includes it with
an ERB `partial 'oss_scale_table'` call.
include::partial$_oss_scale_table.adoc[]
The host page is the same in every mode.
[%header,cols=".<25%h,.<25%,.<50%"]
|===
|Component |Total Instances |Notes
|Diego Cell
|≥ 2
|The optimal balance between CPU/memory sizing and instance count depends on the performance characteristics of the apps that run on Diego cells. Scaling vertically with larger Diego cells makes for larger points of failure, and more apps go down when a cell fails. On the other hand, scaling horizontally decreases the speed at which the system rebalances apps. Rebalancing 100 cells takes longer and demands more processing overhead than rebalancing 20 cells.
|Diego Brain
|≥ 2
|One per AZ, or two if only one AZ.
|Diego BBS
|≥ 2
|One per AZ, or two if only one AZ.
|PostgreSQL Server
|0 or 1
|`0` if Postgres database is external.
|MySQL Proxy
|≥ 2
|
|NATS Server
|≥ 2
|You might run a single NATS instance if you lack the resources to deploy two stable NATS servers. Components using NATS are resilient to message failures and the BOSH resurrector recovers the NATS VM quickly if it becomes non-responsive. NATS includes metrics as well as route registration and deregistration messages. {recommended_by} recommends scaling NATS VMs to 2 or more CPU.
|Cloud Controller API
|≥ 2
|Scale the Cloud Controller to accommodate the number of requests to the API and the number of apps in the system.
|Cloud Controller Worker
|≥ 2
|Scale the Cloud Controller to accommodate the number of asynchronous requests to the API and background jobs.
|Router
|≥ 2
|Scale the router to accommodate the number of incoming requests. Additional instances increase available bandwidth. In general, this load is much less than the load on host VMs.
|UAA
|≥ 2
|
|Doppler Server
|≥ 2
|Deploying additional Doppler servers splits traffic across them. For high availability, use at least two per Availability Zone (AZ).
|Loggregator TC
|≥ 2
|Deploying additional Loggregator Traffic Controllers allows you to direct traffic to them in a round-robin manner. For high availability, use at least two per AZ.
|Log Cache
|≥ 1
|Deploying additional Log Cache instances increases the total storage, sharding data by app ID. If app logs and metrics are sharded to an unavailable instance, they are unavailable when the designated instance is unavailable regardless of the number of instances or AZs.
|===
%header makes the first row the header row. In cols, .< aligns a
column to the top, the percentage is its width, and h styles column 1’s
cells as headers (row headers). The variable is the attribute {recommended_by}.
[subs=attributes+]
++++
<table class="table">
<col width="25%" />
<col width="25%" />
<col width="50%" />
<thead>
<tr>
<th>Component</th>
<th>Total Instances</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td>Diego Cell</td>
<td>≥ 2</td>
<td>The optimal balance between CPU/memory sizing and instance count depends on the performance characteristics of the apps that run on Diego cells. Scaling vertically with larger Diego cells makes for larger points of failure, and more apps go down when a cell fails. On the other hand, scaling horizontally decreases the speed at which the system rebalances apps. Rebalancing 100 cells takes longer and demands more processing overhead than rebalancing 20 cells.</td>
</tr>
<tr>
<td>Diego Brain</td>
<td>≥ 2</td>
<td>One per AZ, or two if only one AZ.</td>
</tr>
<tr>
<td>Diego BBS</td>
<td>≥ 2</td>
<td>One per AZ, or two if only one AZ.</td>
</tr>
<tr>
<td>PostgreSQL Server</td>
<td>0 or 1</td>
<td><code>0</code> if Postgres database is external.</td>
</tr>
<tr>
<td>MySQL Proxy</td>
<td>≥ 2</td>
<td></td>
</tr>
<tr>
<td>NATS Server</td>
<td>≥ 2</td>
<td>You might run a single NATS instance if you lack the resources to deploy two stable NATS servers. Components using NATS are resilient to message failures and the BOSH resurrector recovers the NATS VM quickly if it becomes non-responsive. NATS includes metrics as well as route registration and deregistration messages. {recommended_by} recommends scaling NATS VMs to 2 or more CPU.</td>
</tr>
<tr>
<td>Cloud Controller API</td>
<td>≥ 2</td>
<td>Scale the Cloud Controller to accommodate the number of requests to the API and the number of apps in the system.</td>
</tr>
<tr>
<td>Cloud Controller Worker</td>
<td>≥ 2</td>
<td>Scale the Cloud Controller to accommodate the number of asynchronous requests to the API and background jobs.</td>
</tr>
<tr>
<td>Router</td>
<td>≥ 2</td>
<td>Scale the router to accommodate the number of incoming requests. Additional instances increase available bandwidth. In general, this load is much less than the load on host VMs.</td>
</tr>
<tr>
<td>UAA</td>
<td>≥ 2</td>
<td></td>
</tr>
<tr>
<td>Doppler Server</td>
<td>≥ 2</td>
<td>Deploying additional Doppler servers splits traffic across them. For high availability, use at least two per Availability Zone (AZ).</td>
</tr>
<tr>
<td>Loggregator TC</td>
<td>≥ 2</td>
<td>Deploying additional Loggregator Traffic Controllers allows you to direct traffic to them in a round-robin manner. For high availability, use at least two per AZ.</td>
</tr>
<tr>
<td>Log Cache</td>
<td>≥ 1</td>
<td>Deploying additional Log Cache instances increases the total storage, sharding data by app ID. If app logs and metrics are sharded to an unavailable instance, they are unavailable when the designated instance is unavailable regardless of the number of instances or AZs.</td>
</tr>
</tbody>
</table>
++++
[subs=attributes+] lets the attribute {recommended_by} render inside the
block, which otherwise gets no substitutions
(Asciidoctor).
It is the only addition the HTML needed.
Files: native, native-plain, passthrough, passthrough as written, extension; host page.
Native output:

Passthrough output:

Differences seen:
cols.
An AsciiDoc table with no cols (native-plain) splits the columns
equally, 33/33/33
(screenshot).h in cols. Passthrough keeps them ordinary cells..< specs); passthrough
centers them vertically, as on the published page.credential-types, the site’s stylesheet gives
table.table the look of the native table
(R-09 table styles by class).Extension mode. The native AsciiDoc table with roles (AsciiDoc’s
names for classes, written [.name]) added before it. No code: the roles
get their meaning from the site’s stylesheet,
hints.css.
[.hinted.col1-key.col2-value.col3-prose.col1-nowrap%header,cols=".<25%h,.<25%,.<50%"]
|===
|Component |Total Instances |Notes
|Diego Cell
|≥ 2
|The optimal balance between CPU/memory sizing and instance count depends on the performance characteristics of the apps that run on Diego cells. Scaling vertically with larger Diego cells makes for larger points of failure, and more apps go down when a cell fails. On the other hand, scaling horizontally decreases the speed at which the system rebalances apps. Rebalancing 100 cells takes longer and demands more processing overhead than rebalancing 20 cells.
|Diego Brain
|≥ 2
|One per AZ, or two if only one AZ.
|Diego BBS
|≥ 2
|One per AZ, or two if only one AZ.
|PostgreSQL Server
|0 or 1
|`0` if Postgres database is external.
|MySQL Proxy
|≥ 2
|
|NATS Server
|≥ 2
|You might run a single NATS instance if you lack the resources to deploy two stable NATS servers. Components using NATS are resilient to message failures and the BOSH resurrector recovers the NATS VM quickly if it becomes non-responsive. NATS includes metrics as well as route registration and deregistration messages. {recommended_by} recommends scaling NATS VMs to 2 or more CPU.
|Cloud Controller API
|≥ 2
|Scale the Cloud Controller to accommodate the number of requests to the API and the number of apps in the system.
|Cloud Controller Worker
|≥ 2
|Scale the Cloud Controller to accommodate the number of asynchronous requests to the API and background jobs.
|Router
|≥ 2
|Scale the router to accommodate the number of incoming requests. Additional instances increase available bandwidth. In general, this load is much less than the load on host VMs.
|UAA
|≥ 2
|
|Doppler Server
|≥ 2
|Deploying additional Doppler servers splits traffic across them. For high availability, use at least two per Availability Zone (AZ).
|Loggregator TC
|≥ 2
|Deploying additional Loggregator Traffic Controllers allows you to direct traffic to them in a round-robin manner. For high availability, use at least two per AZ.
|Log Cache
|≥ 1
|Deploying additional Log Cache instances increases the total storage, sharding data by app ID. If app logs and metrics are sharded to an unavailable instance, they are unavailable when the designated instance is unavailable regardless of the number of instances or AZs.
|===
.hinted marks the table as carrying hints; .col1-key, .col2-value and
.col3-prose name the column roles; .col1-nowrap keeps column 1 on one
line, up to a cap. The rest is the native table.
Extension output (the same as native; the two screenshots differ only by a one-pixel shift in where the table sits on the page):

Differences seen:
credential-typescredential-types.html.md.erb in cloudfoundry/docs-credhub, commit e074f74From docs-credhub, one table: Type / Description, seven rows, one per CredHub credential type (intent).
What the table asks for (R-02 rich tables):
<th style="width:20%">.class=“table”.
Browsers read that as a class named “table”, quotes included (a
typographic quote is not an attribute quote, so the value is an
unquoted attribute value),
so the published page never applied the table class. Every conversion makes the
quotes straight first (R-24 markup cleanup before conversion), so
class="table" names the standard table style (R-09 table styles by
class).At a glance, from the screenshots below. Column 1 widths are the measured values in results.md, percent of the table:
| Output | Column 1 width | Header cells | Body cells, vertically | Type cells as row headers | Rule between the columns |
|---|---|---|---|---|---|
| Published | 20% | left | centered | no | yes |
| Docusaurus native | 18%, sized by content | centered | centered | no | yes |
| Docusaurus passthrough | 20% | centered | centered | no | yes |
| Zensical native and passthrough | 20% | left | top | no | no |
| Starlight native and passthrough | 20% | left | top | no | no |
| Antora native | 20% | left | top | yes (bold) | yes |
| Antora passthrough | 20% | left | centered | no | yes |
| Docusaurus extension | 20% | “Type” left, “Description” centered | top | yes (bold) | yes |
| Zensical extension | 20% | left | top | yes (bold) | no |
| Starlight extension | 20% | left | top | yes (bold) | no |
| Antora extension | 20% | left | top | yes (bold) | yes |
All seven rows and both columns are present in every output, and every type name renders as code: the spot checks (per-table checks listed in the intent file and run on every build) pass in every mode of every tool.

Column 1 is 20% of the table. Header cells are on the left. A type name sits in the vertical middle of its row when the description takes two or three lines. Every cell has a border.
<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>
ERB (Embedded Ruby, <%= … %> tags in a page; see the
glossary) is how today’s pages insert variables and
partials. This table uses neither.
Pages are MDX: Markdown that also accepts JSX, the HTML-like syntax of React components (see the glossary). MDX parses HTML as JSX, which is stricter than a browser (the MDX project’s own documentation).
| 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. |
<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>
Files: native, passthrough, passthrough as written, extension. Docusaurus has no native-plain page: its native page already has no width settings.
Native output:

Passthrough output:

Differences seen:
“ before the class value. Passthrough also needed style written as a
JSX object (style={{width: '20%'}}) and the rows wrapped in <tbody>
(R-24 markup cleanup before conversion;
raw passthrough errors).| between cells; see the glossary) carries
no widths, so column 1 is sized by its content, 18% here. Passthrough keeps
the 20%. Without the 20%, passthrough and extension also size column 1
by its content, to the same 18%
(checked after review).| :--- | :--- |) align a pipe table’s
columns, and one rule in the site’s stylesheet aligns every table
(checked after review).json, password, rsa), in both
modes. The published table has no shading.Both modes use no plugin: native is MDX’s own pipe table, passthrough is HTML written as JSX inside MDX.
Extension mode. A :::list-table block, read by a remark plugin
(remark is the Markdown parser under MDX:
@mdx-js/mdx dependencies) added to the site:
plugins/list-table.js,
with hints.css.
:::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.
:::
widths sets column 1 to 20% and sizes column 2 by its content,
header-rows="1" makes the first row the header, stub-columns="1" makes
column 1 row headers, and roles names column 1 a key column and column 2
prose.
Extension output:

Differences seen, against the published page and the other two modes:
Pages are Markdown read by Python-Markdown, which passes HTML blocks through
unchanged (see the glossary;
HTML block stash
in Python-Markdown’s source). An
attribute list, {: … } after a cell’s text, sets HTML attributes on that
cell
(attr_list.py).
| 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. |
<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>
Files: native, native-plain, passthrough, passthrough as written, extension.
Native and passthrough output (the two screenshots are the same image, byte for byte):

Differences seen:
table.table the theme’s table look
(Zensical finding 1); that is
why the two modes look the same.Extension mode. A /// list-table block, read by a Python-Markdown
extension added to the site,
list_table.py, with
hints.css.
/// 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.
///
The options mean the same as in the Docusaurus directive: column 1 at 20%, a header row, column 1 as row headers, and the column roles.
Extension output:

Differences seen, against native and passthrough:
Starlight is a documentation theme for the Astro site builder
(depends on astro).
These pages are Markdoc, Markdown with {% %} tags, with HTML allowed (see the
glossary). Markdoc’s {% table %} tag writes each
cell as a list item and each row break as ---
(table transform).
{% 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 %}
<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>
Files: native, native-plain, passthrough, passthrough as written, extension.
Native and passthrough output (the two screenshots are the same image, byte for byte):

Differences seen:
width on the
header cell. Without it (native-plain, a pipe table), column 1 is 18%.Extension mode. Markdoc’s own {% table %} tag with extra attributes,
declared for the site in
list-table.mjs, with
hints.css.
{% 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.
{% /table %}
The attributes mean the same as in the Docusaurus directive: column 1 at 20%, a header row, column 1 as row headers, and the column roles.
Extension output:

Differences seen, against native and passthrough:
Antora builds sites from AsciiDoc, a plain-text markup with its own table
syntax (see the glossary). The whole page is
rewritten from Markdown to AsciiDoc in every mode, including passthrough. In
passthrough the HTML sits unchanged inside a passthrough block (++++),
which AsciiDoc hands to the browser without reading it (Asciidoctor:
raw block,
no substitutions).
[%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.
|===
%header makes the first row the header row. In cols, each column gets a
spec: .< aligns it to the top, 20% is the width, h styles its cells as
headers (row headers), and ~ sizes the second column by its content
(Asciidoctor:
cols parsing,
< and h).
++++
<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>
++++
Files: native, native-plain, passthrough, passthrough as written, extension.
Native output:

Passthrough output:

Differences seen:
cols. An AsciiDoc
table with no cols (native-plain) splits the columns equally, 50/50
(assign_column_widths;
screenshot).h
in cols. It is the only native syntax here that does so without an
extension. Passthrough keeps them ordinary cells..< specs); passthrough
centers them vertically, as on the published page.table.table the same look as the native
table (R-09 table styles by class).Extension mode. The native AsciiDoc table with roles (AsciiDoc’s
names for classes, written [.name];
shorthand parsing)
added before it. No code: the roles
get their meaning from the site’s stylesheet,
hints.css.
[.hinted.col1-key.col2-prose.col1-nowrap%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.
|===
.hinted marks the table as carrying hints; .col1-key and .col2-prose
name the column roles; .col1-nowrap keeps column 1 on one line, up to a
cap. The rest is the native table.
Extension output:

Differences seen:
cols.metadatametadata.html.md.erb in cloudfoundry/docs-cf-admin, commit 19b0c9cFrom docs-cf-admin, three tables: label requirements and annotation
requirements (HTML, with a title row spanning all four columns and lists
inside cells), and a selector reference that is already a Markdown table.
The published page shows stray backslashes in \[a-z0-9A-Z\]; every
conversion removes them (a decided fix). Every converted mode except
passthrough shows the title as a bold line above the table.
What the tables ask for (R-02 rich tables):
<tr> after </thead>.0-253, which should not break at the hyphen. Columns
3 and 4 are prose, and hold lists.<td> is
never closed. Browsers close it when the next <td> opens, so the
published page is correct; strict parsers fail or nest the cell. The
column headers move into <thead>. The backslashes in
\[a-z0-9A-Z\] are Markdown escapes, but Markdown is not processed
inside this HTML, so the published page shows them; every conversion
removes them (a decided fix).| between cells): column 1 a
key, column 2 a value in code, column 3 prose. Code in column 2 should not
break inside KEY in (VALUE1,VALUE2...) if avoidable. No cleanup.At a glance, from the screenshots below, for tables 1 and 2. Key column widths are the measured values in results.md, percent of table 1, first body row; a dash means not measured:
| Output | Title | Key column width | Header cells | Body cells, vertically | Key cells as row headers | “(Optional) Key Prefix” on one line | Rule between the columns |
|---|---|---|---|---|---|---|---|
| Published | spanning row, centered | — | left | centered | no | no | yes |
| Docusaurus native | bold line above | — | centered | centered | no | no | yes |
| Docusaurus passthrough | spanning row, centered | — | centered | centered | no | no | yes |
| Zensical native | bold line above | 18% | left | top | no | no | no |
| Zensical passthrough | spanning row, centered | 16% | left | top | no | no | no |
| Starlight native | bold line above | 16% | left | top | no | no | no |
| Starlight passthrough | spanning row, centered | 16% | left | top | no | no | no |
| Antora native | bold line above | 17% | left | top | yes (bold) | no | yes |
| Antora passthrough | spanning row, centered | 16% | left | centered | no | no | yes |
| Docusaurus extension | bold line above | 26% | “Part of …” left, the rest centered | top | yes (bold) | yes | yes |
| Zensical extension | bold line above | 23% | left | top | yes (bold) | yes | no |
| Starlight extension | bold line above | 27% | left | top | yes (bold) | yes | no |
| Antora extension | bold line above | 23% | left | top | yes (bold) | yes | yes |
Table 3 follows the same pattern, with two exceptions in Antora: native makes the requirement names row headers too, and passthrough draws the table as AsciiDoc, with its cells aligned to the top.
Every row, cell and list item is present in every output, the
one-character code spans (-, ., _, /) render as code, and the
backslashes are gone in every converted mode: the table spot checks (listed
in the intent file and run on every build) pass in every mode of every tool.
In Docusaurus the page’s description check fails, in every mode: the
description is taken from the first paragraph, which holds a variable
(Docusaurus finding 7).
Table 1, label requirements:

The title row spans the four columns, centered, above the column headers;
both rows share the shaded header band. Column headers are on the left.
Body cells sit in the vertical middle of their rows. Every cell has a
border. The bracket text shows its backslashes, ( \[a-z0-9A-Z\] ), and
breaks after [a-.
<thead>, and the backslashes)<table class="table">
<thead>
<tr>
<th colspan="4" style="text-align: center">Label requirements</th>
</tr>
</thead>
<tr>
<th>Part of Label</th>
<th>Length in characters</th>
<th>Allowed characters</th>
<th>Other Requirements</th>
</tr>
<tr>
<td>(Optional) Key Prefix</td>
<td>0-253</td>
<td>
<ul>
<li>Alphanumeric ( \[a-z0-9A-Z\] )</li>
<li><code>-</code></li>
<li><code>.</code></li>
</ul>
<td>
<ul>
<li>DNS subdomain format, with at least one <code>.</code></li>
<li>Must end with <code>/</code></li>
</ul>
</td>
</tr>
<tr>
<td>Key Name</td>
<td>1-63</td>
<td>
<ul>
<li>Alphanumeric ( \[a-z0-9A-Z\] )</li>
<li><code>-</code></li>
<li><code>_</code></li>
<li><code>.</code></li>
</ul>
</td>
<td>Must begin and end with an alphanumeric character</td>
</tr>
<tr>
<td>Value</td>
<td>0-63</td>
<td>
<ul>
<li>Alphanumeric</li>
<li><code>-</code></li>
<li><code>_</code></li>
<li><code>.</code></li>
</ul>
</td>
<td>
<ul>
<li>Must begin and end with an alphanumeric character</li>
<li>Empty values allowed</li>
</ul>
</td>
</tr>
</table>
Table 2, annotation requirements:

The same layout as table 1. Row 3 is plain text in every cell.
<table class="table">
<thead>
<tr>
<th colspan="4" style="text-align: center">Annotation Requirements</th>
</tr>
</thead>
<tr>
<th>Part of Annotation</th>
<th>Length in characters</th>
<th>Allowed characters</th>
<th>Other Requirements</th>
</tr>
<tr>
<td>(Optional) Key Prefix</td>
<td>0-253</td>
<td>
<ul>
<li>Alphanumeric ( \[a-z0-9A-Z\] )</li>
<li><code>-</code></li>
<li><code>.</code></li>
</ul>
<td>
<ul>
<li>DNS subdomain format, with at least one <code>.</code></li>
<li>Must end with <code>/</code></li>
</ul>
</td>
</tr>
<tr>
<td>Key Name</td>
<td>1-63</td>
<td>
<ul>
<li>Alphanumeric ( \[a-z0-9A-Z\] )</li>
<li><code>-</code></li>
<li><code>_</code></li>
<li><code>.</code></li>
</ul>
</td>
<td>Must begin and end with an alphanumeric character</td>
</tr>
<tr>
<td>Value</td>
<td>0-5000</td>
<td>Any unicode character</td>
<td>n/a</td>
</tr>
</table>
Table 3, selector requirement reference:

Header cells are on the left and body cells are vertically centered. Code
in the Format column wraps: KEY in (VALUE1,VALUE2...) breaks after in,
and KEY==VALUE or KEY=VALUE takes two lines.
| Requirement | Format | Description |
| ----------- | ------ | ----------- |
| existence | `KEY` | Returns all resources labeled with the given key |
| inexistence | `!KEY` | Returns all resources not labeled with the given key |
| equality | `KEY==VALUE` or `KEY=VALUE` | Returns all resources labeled with the given key and value |
| inequality | `KEY!=VALUE` | Returns all resources not labeled with the given key and value |
| set inclusion | `KEY in (VALUE1,VALUE2...)` | Returns all resources labeled with the given key and one of the specified values |
| set exclusion | `KEY notin (VALUE1,VALUE2...)` | Returns all resources not labeled with the given key and one of the specified values |
ERB (Embedded Ruby, <%= … %> tags in a page; see the
glossary) is how today’s pages insert variables and
partials. These tables use neither. The page’s prose uses variables,
including vars.metadata_ref, which the book does not define, so the
published page renders it as empty text
(SOURCES.md).
Pages are MDX, as for credential-types. A pipe table
cell can hold an inline HTML list, <ul><li>…</li></ul> on one line
(conventions).
Table 1:
**Label requirements**
| Part of Label | Length in characters | Allowed characters | Other Requirements |
| --- | --- | --- | --- |
| (Optional) Key Prefix | 0-253 | <ul><li>Alphanumeric ( [a-z0-9A-Z] )</li><li>`-`</li><li>`.`</li></ul> | <ul><li>DNS subdomain format, with at least one `.`</li><li>Must end with `/`</li></ul> |
| Key Name | 1-63 | <ul><li>Alphanumeric ( [a-z0-9A-Z] )</li><li>`-`</li><li>`_`</li><li>`.`</li></ul> | Must begin and end with an alphanumeric character |
| Value | 0-63 | <ul><li>Alphanumeric</li><li>`-`</li><li>`_`</li><li>`.`</li></ul> | <ul><li>Must begin and end with an alphanumeric character</li><li>Empty values allowed</li></ul> |
Table 2:
**Annotation Requirements**
| Part of Annotation | Length in characters | Allowed characters | Other Requirements |
| --- | --- | --- | --- |
| (Optional) Key Prefix | 0-253 | <ul><li>Alphanumeric ( [a-z0-9A-Z] )</li><li>`-`</li><li>`.`</li></ul> | <ul><li>DNS subdomain format, with at least one `.`</li><li>Must end with `/`</li></ul> |
| Key Name | 1-63 | <ul><li>Alphanumeric ( [a-z0-9A-Z] )</li><li>`-`</li><li>`_`</li><li>`.`</li></ul> | Must begin and end with an alphanumeric character |
| Value | 0-5000 | Any unicode character | n/a |
Table 3, the source’s pipe table unchanged:
| Requirement | Format | Description |
| ----------- | ------ | ----------- |
| existence | `KEY` | Returns all resources labeled with the given key |
| inexistence | `!KEY` | Returns all resources not labeled with the given key |
| equality | `KEY==VALUE` or `KEY=VALUE` | Returns all resources labeled with the given key and value |
| inequality | `KEY!=VALUE` | Returns all resources not labeled with the given key and value |
| set inclusion | `KEY in (VALUE1,VALUE2...)` | Returns all resources labeled with the given key and one of the specified values |
| set exclusion | `KEY notin (VALUE1,VALUE2...)` | Returns all resources not labeled with the given key and one of the specified values |
Table 1:
<table class="table">
<thead>
<tr>
<th colspan="4" style={{textAlign: 'center'}}>Label requirements</th>
</tr>
<tr>
<th>Part of Label</th>
<th>Length in characters</th>
<th>Allowed characters</th>
<th>Other Requirements</th>
</tr>
</thead>
<tbody>
<tr>
<td>(Optional) Key Prefix</td>
<td>0-253</td>
<td>
<ul>
<li>Alphanumeric ( [a-z0-9A-Z] )</li>
<li><code>-</code></li>
<li><code>.</code></li>
</ul>
</td>
<td>
<ul>
<li>DNS subdomain format, with at least one <code>.</code></li>
<li>Must end with <code>/</code></li>
</ul>
</td>
</tr>
<tr>
<td>Key Name</td>
<td>1-63</td>
<td>
<ul>
<li>Alphanumeric ( [a-z0-9A-Z] )</li>
<li><code>-</code></li>
<li><code>_</code></li>
<li><code>.</code></li>
</ul>
</td>
<td>Must begin and end with an alphanumeric character</td>
</tr>
<tr>
<td>Value</td>
<td>0-63</td>
<td>
<ul>
<li>Alphanumeric</li>
<li><code>-</code></li>
<li><code>_</code></li>
<li><code>.</code></li>
</ul>
</td>
<td>
<ul>
<li>Must begin and end with an alphanumeric character</li>
<li>Empty values allowed</li>
</ul>
</td>
</tr>
</tbody>
</table>
Table 2:
<table class="table">
<thead>
<tr>
<th colspan="4" style={{textAlign: 'center'}}>Annotation Requirements</th>
</tr>
<tr>
<th>Part of Annotation</th>
<th>Length in characters</th>
<th>Allowed characters</th>
<th>Other Requirements</th>
</tr>
</thead>
<tbody>
<tr>
<td>(Optional) Key Prefix</td>
<td>0-253</td>
<td>
<ul>
<li>Alphanumeric ( [a-z0-9A-Z] )</li>
<li><code>-</code></li>
<li><code>.</code></li>
</ul>
</td>
<td>
<ul>
<li>DNS subdomain format, with at least one <code>.</code></li>
<li>Must end with <code>/</code></li>
</ul>
</td>
</tr>
<tr>
<td>Key Name</td>
<td>1-63</td>
<td>
<ul>
<li>Alphanumeric ( [a-z0-9A-Z] )</li>
<li><code>-</code></li>
<li><code>_</code></li>
<li><code>.</code></li>
</ul>
</td>
<td>Must begin and end with an alphanumeric character</td>
</tr>
<tr>
<td>Value</td>
<td>0-5000</td>
<td>Any unicode character</td>
<td>n/a</td>
</tr>
</tbody>
</table>
Table 3, the source’s pipe table unchanged, as in native:
| Requirement | Format | Description |
| ----------- | ------ | ----------- |
| existence | `KEY` | Returns all resources labeled with the given key |
| inexistence | `!KEY` | Returns all resources not labeled with the given key |
| equality | `KEY==VALUE` or `KEY=VALUE` | Returns all resources labeled with the given key and value |
| inequality | `KEY!=VALUE` | Returns all resources not labeled with the given key and value |
| set inclusion | `KEY in (VALUE1,VALUE2...)` | Returns all resources labeled with the given key and one of the specified values |
| set exclusion | `KEY notin (VALUE1,VALUE2...)` | Returns all resources not labeled with the given key and one of the specified values |
Files: native, passthrough, passthrough as written, extension. Docusaurus has no native-plain page: its native page already has no width settings.
Table 1, native output:

Table 1, passthrough output:

Table 2, native output:

Table 2, passthrough output:

Table 3, native and passthrough output (the two screenshots differ only by image-compression noise):

Differences seen:
{ of JSON inside a <pre>
block as an expression
(raw passthrough errors).
For the tables, passthrough needed the intent file’s cleanup (the two
unclosed <td> closed, the column headers moved into <thead>), style
written as a JSX object (style={{textAlign: 'center'}}) and the rows
wrapped in <tbody> (R-24 markup
cleanup before conversion).credential-types:
the theme sets no alignment, so the browser’s default shows
(checked after review).[a-z0-9A-Z] still breaks after [a-.KEY==VALUE or
KEY=VALUE fits on one line; KEY in (VALUE1,VALUE2...) still breaks
after in.Extension mode. A :::list-table block, as in credential-types, read
by plugins/list-table.js,
with hints.css.
Table 1:
**Label requirements**
:::list-table{header-rows="1" stub-columns="1" roles="key value prose prose"}
- - Part of Label
- Length in characters
- Allowed characters
- Other Requirements
- - (Optional) Key Prefix
- 0-253
- - Alphanumeric ( [a-z0-9A-Z] )
- `-`
- `.`
- - DNS subdomain format, with at least one `.`
- Must end with `/`
- - Key Name
- 1-63
- - Alphanumeric ( [a-z0-9A-Z] )
- `-`
- `_`
- `.`
- Must begin and end with an alphanumeric character
- - Value
- 0-63
- - Alphanumeric
- `-`
- `_`
- `.`
- - Must begin and end with an alphanumeric character
- Empty values allowed
:::
Table 2:
**Annotation Requirements**
:::list-table{header-rows="1" stub-columns="1" roles="key value prose prose"}
- - Part of Annotation
- Length in characters
- Allowed characters
- Other Requirements
- - (Optional) Key Prefix
- 0-253
- - Alphanumeric ( [a-z0-9A-Z] )
- `-`
- `.`
- - DNS subdomain format, with at least one `.`
- Must end with `/`
- - Key Name
- 1-63
- - Alphanumeric ( [a-z0-9A-Z] )
- `-`
- `_`
- `.`
- Must begin and end with an alphanumeric character
- - Value
- 0-5000
- Any unicode character
- n/a
:::
Table 3:
:::list-table{header-rows="1" stub-columns="1" roles="key value prose"}
- - Requirement
- Format
- Description
- - existence
- `KEY`
- Returns all resources labeled with the given key
- - inexistence
- `!KEY`
- Returns all resources not labeled with the given key
- - equality
- `KEY==VALUE` or `KEY=VALUE`
- Returns all resources labeled with the given key and value
- - inequality
- `KEY!=VALUE`
- Returns all resources not labeled with the given key and value
- - set inclusion
- `KEY in (VALUE1,VALUE2...)`
- Returns all resources labeled with the given key and one of the specified values
- - set exclusion
- `KEY notin (VALUE1,VALUE2...)`
- Returns all resources not labeled with the given key and one of the specified values
:::
header-rows="1" makes the first row the header, stub-columns="1" makes
column 1 row headers, and roles names the columns key, value and prose.
There is no widths: the source sets none. A key column stays on one
line up to a cap; the wrap option would do the same for another column
(conventions), and
these tables do not use it.
Table 1, extension output:

Table 2, extension output:

Table 3, extension output:

Differences seen, against the published page and the other two modes:
credential-types.Pages are Markdown read by Python-Markdown, which passes HTML blocks through
unchanged, as for credential-types. The source sets
no widths, so native needs no attribute lists: its pipe tables are the same
as Docusaurus native, byte for byte, and native-plain is the same file as
native.
Table 1:
**Label requirements**
| Part of Label | Length in characters | Allowed characters | Other Requirements |
| --- | --- | --- | --- |
| (Optional) Key Prefix | 0-253 | <ul><li>Alphanumeric ( [a-z0-9A-Z] )</li><li>`-`</li><li>`.`</li></ul> | <ul><li>DNS subdomain format, with at least one `.`</li><li>Must end with `/`</li></ul> |
| Key Name | 1-63 | <ul><li>Alphanumeric ( [a-z0-9A-Z] )</li><li>`-`</li><li>`_`</li><li>`.`</li></ul> | Must begin and end with an alphanumeric character |
| Value | 0-63 | <ul><li>Alphanumeric</li><li>`-`</li><li>`_`</li><li>`.`</li></ul> | <ul><li>Must begin and end with an alphanumeric character</li><li>Empty values allowed</li></ul> |
Table 2:
**Annotation Requirements**
| Part of Annotation | Length in characters | Allowed characters | Other Requirements |
| --- | --- | --- | --- |
| (Optional) Key Prefix | 0-253 | <ul><li>Alphanumeric ( [a-z0-9A-Z] )</li><li>`-`</li><li>`.`</li></ul> | <ul><li>DNS subdomain format, with at least one `.`</li><li>Must end with `/`</li></ul> |
| Key Name | 1-63 | <ul><li>Alphanumeric ( [a-z0-9A-Z] )</li><li>`-`</li><li>`_`</li><li>`.`</li></ul> | Must begin and end with an alphanumeric character |
| Value | 0-5000 | Any unicode character | n/a |
Table 3, the source’s pipe table unchanged:
| Requirement | Format | Description |
| ----------- | ------ | ----------- |
| existence | `KEY` | Returns all resources labeled with the given key |
| inexistence | `!KEY` | Returns all resources not labeled with the given key |
| equality | `KEY==VALUE` or `KEY=VALUE` | Returns all resources labeled with the given key and value |
| inequality | `KEY!=VALUE` | Returns all resources not labeled with the given key and value |
| set inclusion | `KEY in (VALUE1,VALUE2...)` | Returns all resources labeled with the given key and one of the specified values |
| set exclusion | `KEY notin (VALUE1,VALUE2...)` | Returns all resources not labeled with the given key and one of the specified values |
Table 1:
<table class="table">
<thead>
<tr>
<th colspan="4" style="text-align: center">Label requirements</th>
</tr>
<tr>
<th>Part of Label</th>
<th>Length in characters</th>
<th>Allowed characters</th>
<th>Other Requirements</th>
</tr>
</thead>
<tr>
<td>(Optional) Key Prefix</td>
<td>0-253</td>
<td>
<ul>
<li>Alphanumeric ( [a-z0-9A-Z] )</li>
<li><code>-</code></li>
<li><code>.</code></li>
</ul>
</td>
<td>
<ul>
<li>DNS subdomain format, with at least one <code>.</code></li>
<li>Must end with <code>/</code></li>
</ul>
</td>
</tr>
<tr>
<td>Key Name</td>
<td>1-63</td>
<td>
<ul>
<li>Alphanumeric ( [a-z0-9A-Z] )</li>
<li><code>-</code></li>
<li><code>_</code></li>
<li><code>.</code></li>
</ul>
</td>
<td>Must begin and end with an alphanumeric character</td>
</tr>
<tr>
<td>Value</td>
<td>0-63</td>
<td>
<ul>
<li>Alphanumeric</li>
<li><code>-</code></li>
<li><code>_</code></li>
<li><code>.</code></li>
</ul>
</td>
<td>
<ul>
<li>Must begin and end with an alphanumeric character</li>
<li>Empty values allowed</li>
</ul>
</td>
</tr>
</table>
Table 2:
<table class="table">
<thead>
<tr>
<th colspan="4" style="text-align: center">Annotation Requirements</th>
</tr>
<tr>
<th>Part of Annotation</th>
<th>Length in characters</th>
<th>Allowed characters</th>
<th>Other Requirements</th>
</tr>
</thead>
<tr>
<td>(Optional) Key Prefix</td>
<td>0-253</td>
<td>
<ul>
<li>Alphanumeric ( [a-z0-9A-Z] )</li>
<li><code>-</code></li>
<li><code>.</code></li>
</ul>
</td>
<td>
<ul>
<li>DNS subdomain format, with at least one <code>.</code></li>
<li>Must end with <code>/</code></li>
</ul>
</td>
</tr>
<tr>
<td>Key Name</td>
<td>1-63</td>
<td>
<ul>
<li>Alphanumeric ( [a-z0-9A-Z] )</li>
<li><code>-</code></li>
<li><code>_</code></li>
<li><code>.</code></li>
</ul>
</td>
<td>Must begin and end with an alphanumeric character</td>
</tr>
<tr>
<td>Value</td>
<td>0-5000</td>
<td>Any unicode character</td>
<td>n/a</td>
</tr>
</table>
Table 3, the source’s pipe table unchanged, as in native:
| Requirement | Format | Description |
| ----------- | ------ | ----------- |
| existence | `KEY` | Returns all resources labeled with the given key |
| inexistence | `!KEY` | Returns all resources not labeled with the given key |
| equality | `KEY==VALUE` or `KEY=VALUE` | Returns all resources labeled with the given key and value |
| inequality | `KEY!=VALUE` | Returns all resources not labeled with the given key and value |
| set inclusion | `KEY in (VALUE1,VALUE2...)` | Returns all resources labeled with the given key and one of the specified values |
| set exclusion | `KEY notin (VALUE1,VALUE2...)` | Returns all resources not labeled with the given key and one of the specified values |
Files: native, native-plain, passthrough, passthrough as written, extension.
Table 1, native output:

Table 1, passthrough output:

Table 2, native output:

Table 2, passthrough output:

Table 3, native output (passthrough is the same pipe table and looks the same):

Differences seen:
table.table the theme’s table look. The default theme styles only
tables without a class, so these two tables first rendered with no
borders and headers in normal weight
(Zensical finding 1;
screenshot).
Decided: keep the class and style it
(R-09 table styles by class).Extension mode. A /// list-table block, as in credential-types,
read by list_table.py,
with hints.css.
Table 1:
**Label requirements**
/// list-table
header-rows: 1
stub-columns: 1
roles: key value prose prose
- - Part of Label
- Length in characters
- Allowed characters
- Other Requirements
- - (Optional) Key Prefix
- 0-253
- - Alphanumeric ( [a-z0-9A-Z] )
- `-`
- `.`
- - DNS subdomain format, with at least one `.`
- Must end with `/`
- - Key Name
- 1-63
- - Alphanumeric ( [a-z0-9A-Z] )
- `-`
- `_`
- `.`
- Must begin and end with an alphanumeric character
- - Value
- 0-63
- - Alphanumeric
- `-`
- `_`
- `.`
- - Must begin and end with an alphanumeric character
- Empty values allowed
///
Table 2:
**Annotation Requirements**
/// list-table
header-rows: 1
stub-columns: 1
roles: key value prose prose
- - Part of Annotation
- Length in characters
- Allowed characters
- Other Requirements
- - (Optional) Key Prefix
- 0-253
- - Alphanumeric ( [a-z0-9A-Z] )
- `-`
- `.`
- - DNS subdomain format, with at least one `.`
- Must end with `/`
- - Key Name
- 1-63
- - Alphanumeric ( [a-z0-9A-Z] )
- `-`
- `_`
- `.`
- Must begin and end with an alphanumeric character
- - Value
- 0-5000
- Any unicode character
- n/a
///
Table 3:
/// list-table
header-rows: 1
stub-columns: 1
roles: key value prose
- - Requirement
- Format
- Description
- - existence
- `KEY`
- Returns all resources labeled with the given key
- - inexistence
- `!KEY`
- Returns all resources not labeled with the given key
- - equality
- `KEY==VALUE` or `KEY=VALUE`
- Returns all resources labeled with the given key and value
- - inequality
- `KEY!=VALUE`
- Returns all resources not labeled with the given key and value
- - set inclusion
- `KEY in (VALUE1,VALUE2...)`
- Returns all resources labeled with the given key and one of the specified values
- - set exclusion
- `KEY notin (VALUE1,VALUE2...)`
- Returns all resources not labeled with the given key and one of the specified values
///
The options mean the same as in the Docusaurus directive. Rows need a blank line between them, and nesting needs four-space indents (Zensical finding 5).
Table 1, extension output:

Table 2, extension output:

Table 3, extension output:

Differences seen, against native and passthrough:
Pages are Markdoc, as for credential-types.
Markdoc’s own {% table %} tag holds lists in cells without any HTML, so
native writes the lists as Markdown lists
(Starlight summary).
Table 1:
**Label requirements**
{% table %}
* Part of Label
* Length in characters
* Allowed characters
* Other Requirements
---
* (Optional) Key Prefix
* 0-253
* - Alphanumeric ( [a-z0-9A-Z] )
- `-`
- `.`
* - DNS subdomain format, with at least one `.`
- Must end with `/`
---
* Key Name
* 1-63
* - Alphanumeric ( [a-z0-9A-Z] )
- `-`
- `_`
- `.`
* Must begin and end with an alphanumeric character
---
* Value
* 0-63
* - Alphanumeric
- `-`
- `_`
- `.`
* - Must begin and end with an alphanumeric character
- Empty values allowed
{% /table %}
Table 2:
**Annotation Requirements**
{% table %}
* Part of Annotation
* Length in characters
* Allowed characters
* Other Requirements
---
* (Optional) Key Prefix
* 0-253
* - Alphanumeric ( [a-z0-9A-Z] )
- `-`
- `.`
* - DNS subdomain format, with at least one `.`
- Must end with `/`
---
* Key Name
* 1-63
* - Alphanumeric ( [a-z0-9A-Z] )
- `-`
- `_`
- `.`
* Must begin and end with an alphanumeric character
---
* Value
* 0-5000
* Any unicode character
* n/a
{% /table %}
Table 3:
{% table %}
* Requirement
* Format
* Description
---
* existence
* `KEY`
* Returns all resources labeled with the given key
---
* inexistence
* `!KEY`
* Returns all resources not labeled with the given key
---
* equality
* `KEY==VALUE` or `KEY=VALUE`
* Returns all resources labeled with the given key and value
---
* inequality
* `KEY!=VALUE`
* Returns all resources not labeled with the given key and value
---
* set inclusion
* `KEY in (VALUE1,VALUE2...)`
* Returns all resources labeled with the given key and one of the specified values
---
* set exclusion
* `KEY notin (VALUE1,VALUE2...)`
* Returns all resources not labeled with the given key and one of the specified values
{% /table %}
- for the lone dashes and each list cell on one lineTable 1:
<table class="table">
<thead>
<tr>
<th colspan="4" style="text-align: center">Label requirements</th>
</tr>
<tr>
<th>Part of Label</th>
<th>Length in characters</th>
<th>Allowed characters</th>
<th>Other Requirements</th>
</tr>
</thead>
<tr>
<td>(Optional) Key Prefix</td>
<td>0-253</td>
<td> <ul> <li>Alphanumeric ( [a-z0-9A-Z] )</li> <li><code>-</code></li> <li><code>.</code></li> </ul> </td>
<td> <ul> <li>DNS subdomain format, with at least one <code>.</code></li> <li>Must end with <code>/</code></li> </ul> </td>
</tr>
<tr>
<td>Key Name</td>
<td>1-63</td>
<td> <ul> <li>Alphanumeric ( [a-z0-9A-Z] )</li> <li><code>-</code></li> <li><code>_</code></li> <li><code>.</code></li> </ul> </td>
<td>Must begin and end with an alphanumeric character</td>
</tr>
<tr>
<td>Value</td>
<td>0-63</td>
<td> <ul> <li>Alphanumeric</li> <li><code>-</code></li> <li><code>_</code></li> <li><code>.</code></li> </ul> </td>
<td> <ul> <li>Must begin and end with an alphanumeric character</li> <li>Empty values allowed</li> </ul> </td>
</tr>
</table>
Table 2:
<table class="table">
<thead>
<tr>
<th colspan="4" style="text-align: center">Annotation Requirements</th>
</tr>
<tr>
<th>Part of Annotation</th>
<th>Length in characters</th>
<th>Allowed characters</th>
<th>Other Requirements</th>
</tr>
</thead>
<tr>
<td>(Optional) Key Prefix</td>
<td>0-253</td>
<td> <ul> <li>Alphanumeric ( [a-z0-9A-Z] )</li> <li><code>-</code></li> <li><code>.</code></li> </ul> </td>
<td> <ul> <li>DNS subdomain format, with at least one <code>.</code></li> <li>Must end with <code>/</code></li> </ul> </td>
</tr>
<tr>
<td>Key Name</td>
<td>1-63</td>
<td> <ul> <li>Alphanumeric ( [a-z0-9A-Z] )</li> <li><code>-</code></li> <li><code>_</code></li> <li><code>.</code></li> </ul> </td>
<td>Must begin and end with an alphanumeric character</td>
</tr>
<tr>
<td>Value</td>
<td>0-5000</td>
<td>Any unicode character</td>
<td>n/a</td>
</tr>
</table>
Table 3, the source’s pipe table unchanged:
| Requirement | Format | Description |
| ----------- | ------ | ----------- |
| existence | `KEY` | Returns all resources labeled with the given key |
| inexistence | `!KEY` | Returns all resources not labeled with the given key |
| equality | `KEY==VALUE` or `KEY=VALUE` | Returns all resources labeled with the given key and value |
| inequality | `KEY!=VALUE` | Returns all resources not labeled with the given key and value |
| set inclusion | `KEY in (VALUE1,VALUE2...)` | Returns all resources labeled with the given key and one of the specified values |
| set exclusion | `KEY notin (VALUE1,VALUE2...)` | Returns all resources not labeled with the given key and one of the specified values |
Files: native, native-plain, passthrough, passthrough as written, extension.
Table 1, native output:

Table 1, passthrough output:

Table 2, native output:

Table 2, passthrough output:

Table 3, native and passthrough output (the two screenshots differ only by image-compression noise):

Differences seen:
<li><code>-</code></li> becomes a code span holding an
empty bulleted list, and the dash is gone. No error is reported
(Starlight finding 1;
screenshot).
Passthrough writes the five lone dashes as - and joins each list
cell onto one line: Markdoc cannot take the HTML as is.<ul> lists;
results.md rates that source “hard to edit” and native’s Markdoc table
with nested lists readable
(R-11 readable source).Extension mode. Markdoc’s own {% table %} tag with extra attributes,
as in credential-types, declared in
list-table.mjs, with
hints.css.
Table 1:
**Label requirements**
{% table header-rows=1 stub-columns=1 roles="key value prose prose" %}
* Part of Label
* Length in characters
* Allowed characters
* Other Requirements
---
* (Optional) Key Prefix
* 0-253
* - Alphanumeric ( [a-z0-9A-Z] )
- `-`
- `.`
* - DNS subdomain format, with at least one `.`
- Must end with `/`
---
* Key Name
* 1-63
* - Alphanumeric ( [a-z0-9A-Z] )
- `-`
- `_`
- `.`
* Must begin and end with an alphanumeric character
---
* Value
* 0-63
* - Alphanumeric
- `-`
- `_`
- `.`
* - Must begin and end with an alphanumeric character
- Empty values allowed
{% /table %}
Table 2:
**Annotation Requirements**
{% table header-rows=1 stub-columns=1 roles="key value prose prose" %}
* Part of Annotation
* Length in characters
* Allowed characters
* Other Requirements
---
* (Optional) Key Prefix
* 0-253
* - Alphanumeric ( [a-z0-9A-Z] )
- `-`
- `.`
* - DNS subdomain format, with at least one `.`
- Must end with `/`
---
* Key Name
* 1-63
* - Alphanumeric ( [a-z0-9A-Z] )
- `-`
- `_`
- `.`
* Must begin and end with an alphanumeric character
---
* Value
* 0-5000
* Any unicode character
* n/a
{% /table %}
Table 3:
{% table header-rows=1 stub-columns=1 roles="key value prose" %}
* Requirement
* Format
* Description
---
* existence
* `KEY`
* Returns all resources labeled with the given key
---
* inexistence
* `!KEY`
* Returns all resources not labeled with the given key
---
* equality
* `KEY==VALUE` or `KEY=VALUE`
* Returns all resources labeled with the given key and value
---
* inequality
* `KEY!=VALUE`
* Returns all resources not labeled with the given key and value
---
* set inclusion
* `KEY in (VALUE1,VALUE2...)`
* Returns all resources labeled with the given key and one of the specified values
---
* set exclusion
* `KEY notin (VALUE1,VALUE2...)`
* Returns all resources not labeled with the given key and one of the specified values
{% /table %}
The attributes mean the same as in the Docusaurus directive.
Table 1, extension output:

Table 2, extension output:

Table 3, extension output:

Differences seen, against native and passthrough:
( [a-z0-9A-Z] ) lands on its own line, and table 1 is
728 pixels tall in the screenshot against 620 in native.The whole page is AsciiDoc in every mode, as for
credential-types. An a| cell is an AsciiDoc cell,
which holds lists and paragraphs
(conventions). Table 3 is
a Markdown table in the source, so it is an AsciiDoc table in every mode,
passthrough included.
a| cellsTable 1:
*Label requirements*
[%header,cols=".<~h,.<~,.<~,.<~"]
|===
|Part of Label |Length in characters |Allowed characters |Other Requirements
|(Optional) Key Prefix
|0-253
a|* Alphanumeric ( [a-z0-9A-Z] )
* `-`
* `.`
a|* DNS subdomain format, with at least one `.`
* Must end with `/`
|Key Name
|1-63
a|* Alphanumeric ( [a-z0-9A-Z] )
* `-`
* `+_+`
* `.`
|Must begin and end with an alphanumeric character
|Value
|0-63
a|* Alphanumeric
* `-`
* `+_+`
* `.`
a|* Must begin and end with an alphanumeric character
* Empty values allowed
|===
Table 2:
*Annotation Requirements*
[%header,cols=".<~h,.<~,.<~,.<~"]
|===
|Part of Annotation |Length in characters |Allowed characters |Other Requirements
|(Optional) Key Prefix
|0-253
a|* Alphanumeric ( [a-z0-9A-Z] )
* `-`
* `.`
a|* DNS subdomain format, with at least one `.`
* Must end with `/`
|Key Name
|1-63
a|* Alphanumeric ( [a-z0-9A-Z] )
* `-`
* `+_+`
* `.`
|Must begin and end with an alphanumeric character
|Value
|0-5000
|Any unicode character
|n/a
|===
Table 3:
[%header,cols=".<~h,.<~,.<~"]
|===
|Requirement |Format |Description
|existence
|`KEY`
|Returns all resources labeled with the given key
|inexistence
|`!KEY`
|Returns all resources not labeled with the given key
|equality
|`KEY==VALUE` or `KEY=VALUE`
|Returns all resources labeled with the given key and value
|inequality
|`KEY!=VALUE`
|Returns all resources not labeled with the given key and value
|set inclusion
|`+KEY in (VALUE1,VALUE2...)+`
|Returns all resources labeled with the given key and one of the specified values
|set exclusion
|`+KEY notin (VALUE1,VALUE2...)+`
|Returns all resources not labeled with the given key and one of the specified values
|===
In cols, h styles column 1’s cells as row headers, .< aligns every
column to the top, and ~ sizes each column by its content. Code spans
that hold _ or ... are written as literal monospace, `+…+`:
plain backticks turned ... into …
(Antora finding 7).
Table 1:
++++
<table class="table">
<thead>
<tr>
<th colspan="4" style="text-align: center">Label requirements</th>
</tr>
<tr>
<th>Part of Label</th>
<th>Length in characters</th>
<th>Allowed characters</th>
<th>Other Requirements</th>
</tr>
</thead>
<tr>
<td>(Optional) Key Prefix</td>
<td>0-253</td>
<td>
<ul>
<li>Alphanumeric ( [a-z0-9A-Z] )</li>
<li><code>-</code></li>
<li><code>.</code></li>
</ul>
</td>
<td>
<ul>
<li>DNS subdomain format, with at least one <code>.</code></li>
<li>Must end with <code>/</code></li>
</ul>
</td>
</tr>
<tr>
<td>Key Name</td>
<td>1-63</td>
<td>
<ul>
<li>Alphanumeric ( [a-z0-9A-Z] )</li>
<li><code>-</code></li>
<li><code>_</code></li>
<li><code>.</code></li>
</ul>
</td>
<td>Must begin and end with an alphanumeric character</td>
</tr>
<tr>
<td>Value</td>
<td>0-63</td>
<td>
<ul>
<li>Alphanumeric</li>
<li><code>-</code></li>
<li><code>_</code></li>
<li><code>.</code></li>
</ul>
</td>
<td>
<ul>
<li>Must begin and end with an alphanumeric character</li>
<li>Empty values allowed</li>
</ul>
</td>
</tr>
</table>
++++
Table 2:
++++
<table class="table">
<thead>
<tr>
<th colspan="4" style="text-align: center">Annotation Requirements</th>
</tr>
<tr>
<th>Part of Annotation</th>
<th>Length in characters</th>
<th>Allowed characters</th>
<th>Other Requirements</th>
</tr>
</thead>
<tr>
<td>(Optional) Key Prefix</td>
<td>0-253</td>
<td>
<ul>
<li>Alphanumeric ( [a-z0-9A-Z] )</li>
<li><code>-</code></li>
<li><code>.</code></li>
</ul>
</td>
<td>
<ul>
<li>DNS subdomain format, with at least one <code>.</code></li>
<li>Must end with <code>/</code></li>
</ul>
</td>
</tr>
<tr>
<td>Key Name</td>
<td>1-63</td>
<td>
<ul>
<li>Alphanumeric ( [a-z0-9A-Z] )</li>
<li><code>-</code></li>
<li><code>_</code></li>
<li><code>.</code></li>
</ul>
</td>
<td>Must begin and end with an alphanumeric character</td>
</tr>
<tr>
<td>Value</td>
<td>0-5000</td>
<td>Any unicode character</td>
<td>n/a</td>
</tr>
</table>
++++
Table 3:
[%header,cols=".<~,.<~,.<~"]
|===
|Requirement |Format |Description
|existence
|`KEY`
|Returns all resources labeled with the given key
|inexistence
|`!KEY`
|Returns all resources not labeled with the given key
|equality
|`KEY==VALUE` or `KEY=VALUE`
|Returns all resources labeled with the given key and value
|inequality
|`KEY!=VALUE`
|Returns all resources not labeled with the given key and value
|set inclusion
|`+KEY in (VALUE1,VALUE2...)+`
|Returns all resources labeled with the given key and one of the specified values
|set exclusion
|`+KEY notin (VALUE1,VALUE2...)+`
|Returns all resources not labeled with the given key and one of the specified values
|===
Files: native, native-plain, passthrough, passthrough as written, extension.
Table 1, native output:

Table 1, passthrough output:

Table 2, native output:

Table 2, passthrough output:

Table 3, native output:

Table 3, passthrough output:

Differences seen:
*Label
requirements*) and the source’s spanning row in passthrough.h in cols. Passthrough keeps ordinary cells, in table 3 too,
whose specs have no h..< specs). Passthrough
centers tables 1 and 2 vertically, as on the published page; its table 3
is top-aligned.table.table the same look (every HTML table names its style with a
class, decided; Antora finding 3).cols splits the width
evenly (Antora finding 6).Extension mode. The native AsciiDoc tables with roles added before
them, as in credential-types. No code: the roles get their meaning from
the site’s stylesheet,
hints.css.
Table 1:
*Label requirements*
[.hinted.col1-key.col2-value.col3-prose.col4-prose.col1-nowrap%header,cols=".<~h,.<~,.<~,.<~"]
|===
|Part of Label |Length in characters |Allowed characters |Other Requirements
|(Optional) Key Prefix
|0-253
a|* Alphanumeric ( [a-z0-9A-Z] )
* `-`
* `.`
a|* DNS subdomain format, with at least one `.`
* Must end with `/`
|Key Name
|1-63
a|* Alphanumeric ( [a-z0-9A-Z] )
* `-`
* `+_+`
* `.`
|Must begin and end with an alphanumeric character
|Value
|0-63
a|* Alphanumeric
* `-`
* `+_+`
* `.`
a|* Must begin and end with an alphanumeric character
* Empty values allowed
|===
Table 2:
*Annotation Requirements*
[.hinted.col1-key.col2-value.col3-prose.col4-prose.col1-nowrap%header,cols=".<~h,.<~,.<~,.<~"]
|===
|Part of Annotation |Length in characters |Allowed characters |Other Requirements
|(Optional) Key Prefix
|0-253
a|* Alphanumeric ( [a-z0-9A-Z] )
* `-`
* `.`
a|* DNS subdomain format, with at least one `.`
* Must end with `/`
|Key Name
|1-63
a|* Alphanumeric ( [a-z0-9A-Z] )
* `-`
* `+_+`
* `.`
|Must begin and end with an alphanumeric character
|Value
|0-5000
|Any unicode character
|n/a
|===
Table 3:
[.hinted.col1-key.col2-value.col3-prose.col1-nowrap%header,cols=".<~h,.<~,.<~"]
|===
|Requirement |Format |Description
|existence
|`KEY`
|Returns all resources labeled with the given key
|inexistence
|`!KEY`
|Returns all resources not labeled with the given key
|equality
|`KEY==VALUE` or `KEY=VALUE`
|Returns all resources labeled with the given key and value
|inequality
|`KEY!=VALUE`
|Returns all resources not labeled with the given key and value
|set inclusion
|`+KEY in (VALUE1,VALUE2...)+`
|Returns all resources labeled with the given key and one of the specified values
|set exclusion
|`+KEY notin (VALUE1,VALUE2...)+`
|Returns all resources not labeled with the given key and one of the specified values
|===
.hinted marks the table as carrying hints; .col1-key, .col2-value,
.col3-prose and .col4-prose name the column roles; .col1-nowrap
keeps column 1 on one line, up to a cap. The rest is the native table.
Table 1, extension output:

Table 2, extension output:

Table 3, extension output:

Differences seen, against native:
credential-types, these are default themes; a site’s or a page’s theme
can set table font size, padding and alignment
(font size).a| cells
hold lists in the tool’s own syntax, and results.md rates both readable.
Docusaurus and Zensical native, pipe tables, hold them only as inline
HTML, which results.md rates hard to edit. Every extension writes them as
lists in the tool’s own syntax (R-11 readable source).0-253 never break in any output. No extension
page asks it for column 2, though each extension could (the wrap
option; a col2-nowrap role in Antora), and KEY in (VALUE1,VALUE2...)
breaks after in in every output, as on the published page
(R-03 column widths as hints).- for the lone dashes
(R-24 markup cleanup before
conversion).troubleshooting_slow_requeststroubleshooting_slow_requests.html.md.erb in cloudfoundry/docs-cf-admin, commit 19b0c9cFrom docs-cf-admin, six tables with the same shape: Result / Explanation / Action, one per experiment. Table 2 sits inside a numbered list step, so it is narrower. Passthrough keeps the widths as written; every other mode sets no widths and lets the column roles decide (variant C, decided).
What the tables ask for (R-02 rich tables):
width="25%" on a column 1 cell, and tables 5 and 6 set it on columns 1
and 2. Each width sits on one body cell and applies to the whole column
only because browsers size a column from its widest request
(R-03 column widths as hints).stub-columns, no h in Antora’s cols).<table> with
no <tbody>; browsers insert one.<%= vars.app_runtime_abbr %>, which
the published page renders as “Cloud Foundry”.At a glance, from the screenshots below. Widths are the measured values in results.md, percent of the table, first body row:
| Output | Table 1 widths | Table 2 widths | Header cells | Body cells, vertically | Rule between the columns |
|---|---|---|---|---|---|
| Published | not measured | not measured | left | centered | yes |
| Docusaurus native | 33/25/42 | 28/35/37 | centered | centered | yes |
| Docusaurus passthrough | 33/25/42 | 25/36/39 | centered | centered | yes |
| Docusaurus extension | 33/25/42 | 28/35/37 | centered | top | yes |
| Zensical native, native-plain and extension | 28/25/46 | 23/37/40 | left | top | no |
| Zensical passthrough | same image as native | 25/36/39 | left | top | no |
| Starlight native, native-plain and extension | 32/27/41 | 31/35/34 | left | top | no |
| Starlight passthrough | 32/27/41 | 25/38/37 | left | top | no |
| Antora native and extension | 34/23/43 | 28/34/37 | left | top | yes |
| Antora passthrough | 34/23/43 | 25/36/39 | left | centered | yes |
No output has row headers. All six tables keep every row and column in every output, and every spot check of the tables passes in every mode of every tool (the two Docusaurus misses in results.md are page descriptions, not tables).
Table 1, Experiment 1:

Table 2, Experiment 2, inside step 4 of the list:

Table 3, Experiment 3:

Table 4, Experiment 4:

Table 5, Experiment 5:

Table 6, Experiment 6:

Header cells are on the left. Body cells sit in the vertical middle of their rows, and every cell has a border. Code has a shaded background. Table 2 is narrower than the others (634 pixels in the screenshot, against 656) because it sits in a list step. Tables 5 and 6 link to headings on the same page.
Table 1 (lines 69–100):
<table class="table">
<thead>
<tr>
<th>Result</th>
<th>Explanation</th>
<th>Action</th>
</tr>
</thead>
<tr>
<td>The output shows latency.</td>
<td>A component of your app request flow is causing a delay.</td>
<td>Continue with the rest of the experiments to try to narrow down which component is causing
latency.</td>
</tr>
<tr>
<td>The output does not show latency.</td>
<td>Your app experiences inconsistent delays.</td>
<td>Try to find an endpoint that is consistently experiencing latency. If that is not possible,
then continue with the following experiments, running each of them multiple times.</td>
</tr>
<tr>
<td>The output shows the error: <code>Could not resolve host: NONEXISTENT.com</code></td>
<td>DNS failed to resolve.</td>
<td>Troubleshoot your DNS configuration.</td>
</tr>
<tr>
<td>The output of <code>curl</code> returns normally, but there is no value for
<code>X-Vcap-Request-Id</code>.</td>
<td>The request from the load balancer did not reach <%= vars.app_runtime_abbr %>.</td>
<td>Troubleshoot your load balancer configuration.</td>
</tr>
</table>
Table 2, with the last lines of step 4 before it (lines 147–183):
To narrow down the cause of latency, see the following table for information about the output
that you see after running `cf logs APP-NAME`:
<table class="table">
<thead>
<tr>
<th>Result</th>
<th>Explanation</th>
<th>Action</th>
</tr>
</thead>
<tr>
<td width="25%">The output shows latency within <code>gorouter_time</code>.</td>
<td>Gorouter</td>
<td>Investigate gorouter logs as to why the latency is high. Investigate gorouter capacity metrics + possibly scale up</td>
</tr>
<tr>
<td width="25%">The output shows latency within <code>response_time</code> but not in
<code>gorouter_time</code>.</td>
<td>The network between Gorouter and the app, or the app itself, is causing latency. If the requests are uploading data
to the app, latency between the client and gorouter may appear here as well
</td>
<td>If the issue is not related to uploads, jump to experiment 5, and continue with the rest of the experiments to try to narrow
down which component is causing latency. Otherwise continue with experiment 3.</td>
</tr>
<tr>
<td>The output does not show latency within <code>response_time</code>.</td>
<td>A component before Gorouter is causing latency to the request before it reaches Gorouter.</td>
<td>Continue with the rest of the experiments to try to narrow down which component is
causing latency.</td>
</tr>
<tr>
<td>The output does not show a log line.</td>
<td>Every incoming request should generate an access log message. If a request does not
generate an access log message, it means Gorouter did not receive the request.</td>
<td>Troubleshoot your Gorouter configuration.</td>
</tr>
</table>
Table 3 (lines 210–229):
<table class="table">
<thead>
<tr>
<th>Result</th>
<th>Explanation</th>
<th>Action</th>
</tr>
</thead>
<tr>
<td width="25%">The output shows latency.</td>
<td>One of the components in the app request path is causing latency.</td>
<td>Continue with the rest of the experiments, using the test app, to try to narrow down which
component is causing latency.</td>
</tr>
<tr>
<td>The output does not show latency.</td>
<td>Something in your app configuration is causing latency.</td>
<td>Evaluate your app for recent changes.</td>
</tr>
</table>
Table 4 (lines 275–296):
<table class="table">
<thead>
<tr>
<th>Result</th>
<th>Explanation</th>
<th>Action</th>
</tr>
</thead>
<tr>
<td width="25%">The output shows latency.</td>
<td>The load balancer is not causing latency.</td>
<td>Continue with the rest of the experiments, using the test app, to try to narrow down which
component is causing latency.</td>
</tr>
<tr>
<td>The output does not show latency.</td>
<td>A component before Gorouter is causing latency.</td>
<td>Look at your load balancer logs and logs for any other components that exist between the
end client and Gorouter. Additionally, run these experiments with clients in different networks
to help isolate where issues occur.</td>
</tr>
</table>
Table 5 (lines 330–350):
<table class="table">
<thead>
<tr>
<th>Result</th>
<th>Explanation</th>
<th>Action</th>
</tr>
</thead>
<tr>
<td width="25%">The output shows latency.</td>
<td width="25%">Gorouter is not causing latency.</td>
<td>Continue with the rest of the experiments, using the test app, to try to narrow down which
component is causing latency.</td>
</tr>
<tr>
<td>The output does not show latency.</td>
<td>Gorouter is causing latency.</td>
<td>See <a href="#gorouter-latency">Causes for Gorouter Latency</a> and
<a href="#ops-recommendations">Operations Recommendations</a>.</td>
</tr>
</table>
Table 6 (lines 395–415; the last cell’s third line starts with a tab):
<table class="table">
<thead>
<tr>
<th>Result</th>
<th>Explanation</th>
<th>Action</th>
</tr>
</thead>
<tr>
<td width="25%">The output shows latency.</td>
<td width="25%">Your network is causing latency.</td>
<td>Troubleshoot your network configuration.</td>
</tr>
<tr>
<td>The output does not show latency.</td>
<td>A component in your app request path is causing latency.</td>
<td>Repeat the diagnostic experiments to narrow down which component is causing latency. Follow
the steps in <a href="#total-latency">Experiment 1: Measure Total Round-Trip App Requests</a>
and ensure that you are consistently experiencing latency.</td>
</tr>
</table>
ERB (see the glossary) inserts the one variable in
the tables, vars.app_runtime_abbr in table 1, row 4. Each tool writes it
its own way: {vars.app_runtime_abbr} in Docusaurus, unchanged in
Zensical, {% $vars.app_runtime_abbr %} in Starlight and
{app_runtime_abbr} in Antora. Every output shows “Cloud Foundry”.
The sections below show tables 1 and 2 for each tool and mode. All six tables, in every mode, are side by side on the comparison page.
Pages are MDX, as in credential-types: MDX parses
HTML as JSX, which is stricter than a browser. Variables need one import
per page.
Table 1:
| Result | Explanation | Action |
| --- | --- | --- |
| The output shows latency. | A component of your app request flow is causing a delay. | Continue with the rest of the experiments to try to narrow down which component is causing latency. |
| The output does not show latency. | Your app experiences inconsistent delays. | Try to find an endpoint that is consistently experiencing latency. If that is not possible, then continue with the following experiments, running each of them multiple times. |
| The output shows the error: `Could not resolve host: NONEXISTENT.com` | DNS failed to resolve. | Troubleshoot your DNS configuration. |
| The output of `curl` returns normally, but there is no value for `X-Vcap-Request-Id`. | The request from the load balancer did not reach {vars.app_runtime_abbr}. | Troubleshoot your load balancer configuration. |
Table 2, after the last lines of step 4:
To narrow down the cause of latency, see the following table for information about the output
that you see after running `cf logs APP-NAME`:
| Result | Explanation | Action |
| --- | --- | --- |
| The output shows latency within `gorouter_time`. | Gorouter | Investigate gorouter logs as to why the latency is high. Investigate gorouter capacity metrics + possibly scale up |
| The output shows latency within `response_time` but not in `gorouter_time`. | The network between Gorouter and the app, or the app itself, is causing latency. If the requests are uploading data to the app, latency between the client and gorouter may appear here as well | If the issue is not related to uploads, jump to experiment 5, and continue with the rest of the experiments to try to narrow down which component is causing latency. Otherwise continue with experiment 3. |
| The output does not show latency within `response_time`. | A component before Gorouter is causing latency to the request before it reaches Gorouter. | Continue with the rest of the experiments to try to narrow down which component is causing latency. |
| The output does not show a log line. | Every incoming request should generate an access log message. If a request does not generate an access log message, it means Gorouter did not receive the request. | Troubleshoot your Gorouter configuration. |
tbody added; table 2 indented under step 4Table 1:
<table class="table">
<thead>
<tr>
<th>Result</th>
<th>Explanation</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<tr>
<td>The output shows latency.</td>
<td>A component of your app request flow is causing a delay.</td>
<td>Continue with the rest of the experiments to try to narrow down which component is causing
latency.</td>
</tr>
<tr>
<td>The output does not show latency.</td>
<td>Your app experiences inconsistent delays.</td>
<td>Try to find an endpoint that is consistently experiencing latency. If that is not possible,
then continue with the following experiments, running each of them multiple times.</td>
</tr>
<tr>
<td>The output shows the error: <code>Could not resolve host: NONEXISTENT.com</code></td>
<td>DNS failed to resolve.</td>
<td>Troubleshoot your DNS configuration.</td>
</tr>
<tr>
<td>The output of <code>curl</code> returns normally, but there is no value for
<code>X-Vcap-Request-Id</code>.</td>
<td>The request from the load balancer did not reach {vars.app_runtime_abbr}.</td>
<td>Troubleshoot your load balancer configuration.</td>
</tr>
</tbody>
</table>
Table 2, after the last lines of step 4:
To narrow down the cause of latency, see the following table for information about the output
that you see after running `cf logs APP-NAME`:
<table class="table">
<thead>
<tr>
<th>Result</th>
<th>Explanation</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<tr>
<td width="25%">The output shows latency within <code>gorouter_time</code>.</td>
<td>Gorouter</td>
<td>Investigate gorouter logs as to why the latency is high. Investigate gorouter capacity metrics + possibly scale up</td>
</tr>
<tr>
<td width="25%">The output shows latency within <code>response_time</code> but not in
<code>gorouter_time</code>.</td>
<td>The network between Gorouter and the app, or the app itself, is causing latency. If the requests are uploading data
to the app, latency between the client and gorouter may appear here as well</td>
<td>If the issue is not related to uploads, jump to experiment 5, and continue with the rest of the experiments to try to narrow
down which component is causing latency. Otherwise continue with experiment 3.</td>
</tr>
<tr>
<td>The output does not show latency within <code>response_time</code>.</td>
<td>A component before Gorouter is causing latency to the request before it reaches Gorouter.</td>
<td>Continue with the rest of the experiments to try to narrow down which component is
causing latency.</td>
</tr>
<tr>
<td>The output does not show a log line.</td>
<td>Every incoming request should generate an access log message. If a request does not
generate an access log message, it means Gorouter did not receive the request.</td>
<td>Troubleshoot your Gorouter configuration.</td>
</tr>
</tbody>
</table>
Files: native, passthrough, passthrough as written, extension. Docusaurus has no native-plain page: its native page already has no width settings.
Table 1, native and passthrough output (the two screenshots are the same image, byte for byte):

Table 2, native output:

Table 2, passthrough output:

Differences seen:
<br> outside the tables
(raw passthrough errors).
The tables needed <tbody> and one cell’s closing </td> moved off the
start of its line, the Explanation cell of row 2 in table 2. The width="25%"
attributes stay as written
(R-24 markup cleanup before conversion).credential-types:
the theme sets no alignment, so the browser’s default shows
(checked after review).X-Vcap-Request-Id breaks after its last hyphen (“X-Vcap-Request-“ /
“Id”) in table 1, row 4, in every mode; the published page keeps it
whole. The text itself is unchanged.Both modes use no plugin: native is MDX’s own pipe table, passthrough is HTML written as JSX inside MDX.
Extension mode. A :::list-table block, read by the remark plugin
added to the site,
plugins/list-table.js,
with hints.css.
:::list-table{header-rows="1" roles="key prose prose" wrap="normal"}
- - Result
- Explanation
- Action
- - The output shows latency.
- A component of your app request flow is causing a delay.
- Continue with the rest of the experiments to try to narrow down which component is causing latency.
- - The output does not show latency.
- Your app experiences inconsistent delays.
- Try to find an endpoint that is consistently experiencing latency. If that is not possible, then continue with the following experiments, running each of them multiple times.
- - The output shows the error: `Could not resolve host: NONEXISTENT.com`
- DNS failed to resolve.
- Troubleshoot your DNS configuration.
- - The output of `curl` returns normally, but there is no value for `X-Vcap-Request-Id`.
- The request from the load balancer did not reach {vars.app_runtime_abbr}.
- Troubleshoot your load balancer configuration.
:::
header-rows="1" makes the first row the header, roles names column 1 a
key column and columns 2 and 3 prose, and wrap="normal" lets column 1
wrap; a key column otherwise avoids wrapping. There is no widths
(variant C) and no stub-columns, so no row headers. Table 2 is written
the same way, indented under step 4.
Table 1, extension output:

Table 2, extension output:

Differences seen, against native:
Pages are Markdown read by Python-Markdown, which passes HTML blocks
through unchanged, as in credential-types. Variables
keep their ERB form.
Table 1:
| Result | Explanation | Action |
| --- | --- | --- |
| The output shows latency. | A component of your app request flow is causing a delay. | Continue with the rest of the experiments to try to narrow down which component is causing latency. |
| The output does not show latency. | Your app experiences inconsistent delays. | Try to find an endpoint that is consistently experiencing latency. If that is not possible, then continue with the following experiments, running each of them multiple times. |
| The output shows the error: `Could not resolve host: NONEXISTENT.com` | DNS failed to resolve. | Troubleshoot your DNS configuration. |
| The output of `curl` returns normally, but there is no value for `X-Vcap-Request-Id`. | The request from the load balancer did not reach <%= vars.app_runtime_abbr %>. | Troubleshoot your load balancer configuration. |
Table 2, after the last lines of step 4:
To narrow down the cause of latency, see the following table for information about the output
that you see after running `cf logs APP-NAME`:
| Result | Explanation | Action |
| --- | --- | --- |
| The output shows latency within `gorouter_time`. | Gorouter | Investigate gorouter logs as to why the latency is high. Investigate gorouter capacity metrics + possibly scale up |
| The output shows latency within `response_time` but not in `gorouter_time`. | The network between Gorouter and the app, or the app itself, is causing latency. If the requests are uploading data to the app, latency between the client and gorouter may appear here as well | If the issue is not related to uploads, jump to experiment 5, and continue with the rest of the experiments to try to narrow down which component is causing latency. Otherwise continue with experiment 3. |
| The output does not show latency within `response_time`. | A component before Gorouter is causing latency to the request before it reaches Gorouter. | Continue with the rest of the experiments to try to narrow down which component is causing latency. |
| The output does not show a log line. | Every incoming request should generate an access log message. If a request does not generate an access log message, it means Gorouter did not receive the request. | Troubleshoot your Gorouter configuration. |
Table 1, the same as the source:
<table class="table">
<thead>
<tr>
<th>Result</th>
<th>Explanation</th>
<th>Action</th>
</tr>
</thead>
<tr>
<td>The output shows latency.</td>
<td>A component of your app request flow is causing a delay.</td>
<td>Continue with the rest of the experiments to try to narrow down which component is causing
latency.</td>
</tr>
<tr>
<td>The output does not show latency.</td>
<td>Your app experiences inconsistent delays.</td>
<td>Try to find an endpoint that is consistently experiencing latency. If that is not possible,
then continue with the following experiments, running each of them multiple times.</td>
</tr>
<tr>
<td>The output shows the error: <code>Could not resolve host: NONEXISTENT.com</code></td>
<td>DNS failed to resolve.</td>
<td>Troubleshoot your DNS configuration.</td>
</tr>
<tr>
<td>The output of <code>curl</code> returns normally, but there is no value for
<code>X-Vcap-Request-Id</code>.</td>
<td>The request from the load balancer did not reach <%= vars.app_runtime_abbr %>.</td>
<td>Troubleshoot your load balancer configuration.</td>
</tr>
</table>
Table 2, after the last lines of step 4:
To narrow down the cause of latency, see the following table for information about the output
that you see after running `cf logs APP-NAME`:
<table class="table">
<thead>
<tr>
<th>Result</th>
<th>Explanation</th>
<th>Action</th>
</tr>
</thead>
<tr>
<td width="25%">The output shows latency within <code>gorouter_time</code>.</td>
<td>Gorouter</td>
<td>Investigate gorouter logs as to why the latency is high. Investigate gorouter capacity metrics + possibly scale up</td>
</tr>
<tr>
<td width="25%">The output shows latency within <code>response_time</code> but not in
<code>gorouter_time</code>.</td>
<td>The network between Gorouter and the app, or the app itself, is causing latency. If the requests are uploading data
to the app, latency between the client and gorouter may appear here as well
</td>
<td>If the issue is not related to uploads, jump to experiment 5, and continue with the rest of the experiments to try to narrow
down which component is causing latency. Otherwise continue with experiment 3.</td>
</tr>
<tr>
<td>The output does not show latency within <code>response_time</code>.</td>
<td>A component before Gorouter is causing latency to the request before it reaches Gorouter.</td>
<td>Continue with the rest of the experiments to try to narrow down which component is
causing latency.</td>
</tr>
<tr>
<td>The output does not show a log line.</td>
<td>Every incoming request should generate an access log message. If a request does not
generate an access log message, it means Gorouter did not receive the request.</td>
<td>Troubleshoot your Gorouter configuration.</td>
</tr>
</table>
Files: native, native-plain, passthrough, passthrough as written, extension. Native and native-plain are the same file: with no widths, native has no attribute to leave out.
Table 1, every mode (the native, native-plain, passthrough and extension screenshots are the same image, byte for byte):

Table 2, native, native-plain and extension output (the three screenshots are the same image, byte for byte):

Table 2, passthrough output:

Differences seen:
credential-types. The site’s stylesheet
gives table.table the theme’s table look
(Zensical finding 1), so
passthrough looks like native.X-Vcap-Request-Id breaks after its first hyphen (“X-Vcap-“ /
“Request-Id”) in table 1, row 4. The text itself is unchanged.Extension mode. A /// list-table block, read by the Python-Markdown
extension added to the site,
list_table.py, with
hints.css.
/// list-table
header-rows: 1
roles: key prose prose
wrap: normal
- - Result
- Explanation
- Action
- - The output shows latency.
- A component of your app request flow is causing a delay.
- Continue with the rest of the experiments to try to narrow down which component is causing latency.
- - The output does not show latency.
- Your app experiences inconsistent delays.
- Try to find an endpoint that is consistently experiencing latency. If that is not possible, then continue with the following experiments, running each of them multiple times.
- - The output shows the error: `Could not resolve host: NONEXISTENT.com`
- DNS failed to resolve.
- Troubleshoot your DNS configuration.
- - The output of `curl` returns normally, but there is no value for `X-Vcap-Request-Id`.
- The request from the load balancer did not reach <%= vars.app_runtime_abbr %>.
- Troubleshoot your load balancer configuration.
///
The options mean the same as in the Docusaurus directive: a header row, the column roles, and column 1 allowed to wrap. Table 2 is written the same way, indented under step 4.
Extension output: the same images as native, for all six tables.
Differences seen:
These pages are Markdoc, as in credential-types:
Markdown with {% %} tags, with HTML allowed. Markdoc’s {% table %} tag
writes each cell as a list item and each row break as ---.
Table 1:
{% table %}
* Result
* Explanation
* Action
---
* The output shows latency.
* A component of your app request flow is causing a delay.
* Continue with the rest of the experiments to try to narrow down which component is causing latency.
---
* The output does not show latency.
* Your app experiences inconsistent delays.
* Try to find an endpoint that is consistently experiencing latency. If that is not possible, then continue with the following experiments, running each of them multiple times.
---
* The output shows the error: `Could not resolve host: NONEXISTENT.com`
* DNS failed to resolve.
* Troubleshoot your DNS configuration.
---
* The output of `curl` returns normally, but there is no value for `X-Vcap-Request-Id`.
* The request from the load balancer did not reach {% $vars.app_runtime_abbr %}.
* Troubleshoot your load balancer configuration.
{% /table %}
Table 2, after the last lines of step 4:
To narrow down the cause of latency, see the following table for information about the output
that you see after running `cf logs APP-NAME`:
{% table %}
* Result
* Explanation
* Action
---
* The output shows latency within `gorouter_time`.
* Gorouter
* Investigate gorouter logs as to why the latency is high. Investigate gorouter capacity metrics + possibly scale up
---
* The output shows latency within `response_time` but not in `gorouter_time`.
* The network between Gorouter and the app, or the app itself, is causing latency. If the requests are uploading data to the app, latency between the client and gorouter may appear here as well
* If the issue is not related to uploads, jump to experiment 5, and continue with the rest of the experiments to try to narrow down which component is causing latency. Otherwise continue with experiment 3.
---
* The output does not show latency within `response_time`.
* A component before Gorouter is causing latency to the request before it reaches Gorouter.
* Continue with the rest of the experiments to try to narrow down which component is causing latency.
---
* The output does not show a log line.
* Every incoming request should generate an access log message. If a request does not generate an access log message, it means Gorouter did not receive the request.
* Troubleshoot your Gorouter configuration.
{% /table %}
Table 1:
<table class="table">
<thead>
<tr>
<th>Result</th>
<th>Explanation</th>
<th>Action</th>
</tr>
</thead>
<tr>
<td>The output shows latency.</td>
<td>A component of your app request flow is causing a delay.</td>
<td>Continue with the rest of the experiments to try to narrow down which component is causing latency.</td>
</tr>
<tr>
<td>The output does not show latency.</td>
<td>Your app experiences inconsistent delays.</td>
<td>Try to find an endpoint that is consistently experiencing latency. If that is not possible, then continue with the following experiments, running each of them multiple times.</td>
</tr>
<tr>
<td>The output shows the error: <code>Could not resolve host: NONEXISTENT.com</code></td>
<td>DNS failed to resolve.</td>
<td>Troubleshoot your DNS configuration.</td>
</tr>
<tr>
<td>The output of <code>curl</code> returns normally, but there is no value for <code>X-Vcap-Request-Id</code>.</td>
<td>The request from the load balancer did not reach {% $vars.app_runtime_abbr %}.</td>
<td>Troubleshoot your load balancer configuration.</td>
</tr>
</table>
Table 2, after the last lines of step 4:
To narrow down the cause of latency, see the following table for information about the output
that you see after running `cf logs APP-NAME`:
<table class="table">
<thead>
<tr>
<th>Result</th>
<th>Explanation</th>
<th>Action</th>
</tr>
</thead>
<tr>
<td width="25%">The output shows latency within <code>gorouter_time</code>.</td>
<td>Gorouter</td>
<td>Investigate gorouter logs as to why the latency is high. Investigate gorouter capacity metrics + possibly scale up</td>
</tr>
<tr>
<td width="25%">The output shows latency within <code>response_time</code> but not in <code>gorouter_time</code>.</td>
<td>The network between Gorouter and the app, or the app itself, is causing latency. If the requests are uploading data to the app, latency between the client and gorouter may appear here as well </td>
<td>If the issue is not related to uploads, jump to experiment 5, and continue with the rest of the experiments to try to narrow down which component is causing latency. Otherwise continue with experiment 3.</td>
</tr>
<tr>
<td>The output does not show latency within <code>response_time</code>.</td>
<td>A component before Gorouter is causing latency to the request before it reaches Gorouter.</td>
<td>Continue with the rest of the experiments to try to narrow down which component is causing latency.</td>
</tr>
<tr>
<td>The output does not show a log line.</td>
<td>Every incoming request should generate an access log message. If a request does not generate an access log message, it means Gorouter did not receive the request.</td>
<td>Troubleshoot your Gorouter configuration.</td>
</tr>
</table>
Files: native, native-plain, passthrough, passthrough as written, extension. Native-plain writes the same tables as pipe tables.
Table 1, every mode (the native, native-plain, passthrough and extension screenshots are the same image, byte for byte):

Table 2, native, native-plain and extension output (the three screenshots are the same image, byte for byte):

Table 2, passthrough output:

Differences seen:
(Starlight finding 3).credential-types.X-Vcap-Request-Id breaks after its first hyphen (“X-“ /
“Vcap-Request-Id”) in table 1, row 4. The text itself is unchanged.Accept: */* in a terminal block shows as
Accept: / in every mode, as in Docusaurus. Code blocks are their own
concept.Extension mode. Markdoc’s own {% table %} tag with extra attributes,
declared for the site in
list-table.mjs, with
hints.css.
{% table header-rows=1 roles="key prose prose" wrap="normal" %}
* Result
* Explanation
* Action
---
* The output shows latency.
* A component of your app request flow is causing a delay.
* Continue with the rest of the experiments to try to narrow down which component is causing latency.
---
* The output does not show latency.
* Your app experiences inconsistent delays.
* Try to find an endpoint that is consistently experiencing latency. If that is not possible, then continue with the following experiments, running each of them multiple times.
---
* The output shows the error: `Could not resolve host: NONEXISTENT.com`
* DNS failed to resolve.
* Troubleshoot your DNS configuration.
---
* The output of `curl` returns normally, but there is no value for `X-Vcap-Request-Id`.
* The request from the load balancer did not reach {% $vars.app_runtime_abbr %}.
* Troubleshoot your load balancer configuration.
{% /table %}
The attributes mean the same as in the Docusaurus directive. Only the opening tag differs from native; table 2 is written the same way, indented under step 4.
Extension output: the same images as native, for all six tables.
Differences seen:
Antora builds sites from AsciiDoc, as in
credential-types. The whole page is rewritten from
Markdown to AsciiDoc in every mode; in passthrough the HTML sits unchanged
inside a passthrough block (++++).
Table 1:
[%header,cols=".<~,.<~,.<~"]
|===
|Result |Explanation |Action
|The output shows latency.
|A component of your app request flow is causing a delay.
|Continue with the rest of the experiments to try to narrow down which component is causing latency.
|The output does not show latency.
|Your app experiences inconsistent delays.
|Try to find an endpoint that is consistently experiencing latency. If that is not possible, then continue with the following experiments, running each of them multiple times.
|The output shows the error: `Could not resolve host: NONEXISTENT.com`
|DNS failed to resolve.
|Troubleshoot your DNS configuration.
|The output of `curl` returns normally, but there is no value for `X-Vcap-Request-Id`.
|The request from the load balancer did not reach {app_runtime_abbr}.
|Troubleshoot your load balancer configuration.
|===
Table 2, after the last lines of step 4; the -- below it closes the block
that holds the step’s content:
To narrow down the cause of latency, see the following table for information about the output
that you see after running `cf logs APP-NAME`:
[%header,cols=".<~,.<~,.<~"]
|===
|Result |Explanation |Action
|The output shows latency within `+gorouter_time+`.
|Gorouter
|Investigate gorouter logs as to why the latency is high. Investigate gorouter capacity metrics + possibly scale up
|The output shows latency within `+response_time+` but not in `+gorouter_time+`.
|The network between Gorouter and the app, or the app itself, is causing latency. If the requests are uploading data to the app, latency between the client and gorouter may appear here as well
|If the issue is not related to uploads, jump to experiment 5, and continue with the rest of the experiments to try to narrow down which component is causing latency. Otherwise continue with experiment 3.
|The output does not show latency within `+response_time+`.
|A component before Gorouter is causing latency to the request before it reaches Gorouter.
|Continue with the rest of the experiments to try to narrow down which component is causing latency.
|The output does not show a log line.
|Every incoming request should generate an access log message. If a request does not generate an access log message, it means Gorouter did not receive the request.
|Troubleshoot your Gorouter configuration.
|===
--
In cols, .< aligns each column to the top and ~ sizes it by its
content, so no column gets a width (variant C; Asciidoctor:
cols parsing).
Step 4’s content sits in a block opened with -- after the + that
attaches it to the step, so the table belongs to the step. Code that holds
_ is written `+…+` (Antora finding 7).
Table 1:
[subs=attributes+]
++++
<table class="table">
<thead>
<tr>
<th>Result</th>
<th>Explanation</th>
<th>Action</th>
</tr>
</thead>
<tr>
<td>The output shows latency.</td>
<td>A component of your app request flow is causing a delay.</td>
<td>Continue with the rest of the experiments to try to narrow down which component is causing
latency.</td>
</tr>
<tr>
<td>The output does not show latency.</td>
<td>Your app experiences inconsistent delays.</td>
<td>Try to find an endpoint that is consistently experiencing latency. If that is not possible,
then continue with the following experiments, running each of them multiple times.</td>
</tr>
<tr>
<td>The output shows the error: <code>Could not resolve host: NONEXISTENT.com</code></td>
<td>DNS failed to resolve.</td>
<td>Troubleshoot your DNS configuration.</td>
</tr>
<tr>
<td>The output of <code>curl</code> returns normally, but there is no value for
<code>X-Vcap-Request-Id</code>.</td>
<td>The request from the load balancer did not reach {app_runtime_abbr}.</td>
<td>Troubleshoot your load balancer configuration.</td>
</tr>
</table>
++++
Table 2, after the last lines of step 4:
To narrow down the cause of latency, see the following table for information about the output
that you see after running `cf logs APP-NAME`:
++++
<table class="table">
<thead>
<tr>
<th>Result</th>
<th>Explanation</th>
<th>Action</th>
</tr>
</thead>
<tr>
<td width="25%">The output shows latency within <code>gorouter_time</code>.</td>
<td>Gorouter</td>
<td>Investigate gorouter logs as to why the latency is high. Investigate gorouter capacity metrics + possibly scale up</td>
</tr>
<tr>
<td width="25%">The output shows latency within <code>response_time</code> but not in
<code>gorouter_time</code>.</td>
<td>The network between Gorouter and the app, or the app itself, is causing latency. If the requests are uploading data
to the app, latency between the client and gorouter may appear here as well
</td>
<td>If the issue is not related to uploads, jump to experiment 5, and continue with the rest of the experiments to try to narrow
down which component is causing latency. Otherwise continue with experiment 3.</td>
</tr>
<tr>
<td>The output does not show latency within <code>response_time</code>.</td>
<td>A component before Gorouter is causing latency to the request before it reaches Gorouter.</td>
<td>Continue with the rest of the experiments to try to narrow down which component is
causing latency.</td>
</tr>
<tr>
<td>The output does not show a log line.</td>
<td>Every incoming request should generate an access log message. If a request does not
generate an access log message, it means Gorouter did not receive the request.</td>
<td>Troubleshoot your Gorouter configuration.</td>
</tr>
</table>
++++
--
[subs=attributes+] lets the block replace {app_runtime_abbr}; it is
the only addition to table 1.
Files: native, native-plain, passthrough, passthrough as written, extension.
Table 1, native output:

Table 1, passthrough output:

Table 2, native output:

Table 2, passthrough output:

Differences seen:
.< specs); passthrough
centers them vertically, as on the published page.table.table the look of AsciiDoc’s tables
(Antora finding 3;
R-09 table styles by class).X-Vcap-Request-Id stays whole, as on the published page. The
default UI hyphenates words in cells; the site turns that off in every
mode (Antora finding 5;
screenshot of table 2).cols splits the width equally
(Antora finding 6).Extension mode. The native AsciiDoc table with roles added before it. No code: the roles get their meaning from the site’s stylesheet, hints.css.
[.hinted.col1-key.col2-prose.col3-prose%header,cols=".<~,.<~,.<~"]
|===
|Result |Explanation |Action
|The output shows latency.
|A component of your app request flow is causing a delay.
|Continue with the rest of the experiments to try to narrow down which component is causing latency.
|The output does not show latency.
|Your app experiences inconsistent delays.
|Try to find an endpoint that is consistently experiencing latency. If that is not possible, then continue with the following experiments, running each of them multiple times.
|The output shows the error: `Could not resolve host: NONEXISTENT.com`
|DNS failed to resolve.
|Troubleshoot your DNS configuration.
|The output of `curl` returns normally, but there is no value for `X-Vcap-Request-Id`.
|The request from the load balancer did not reach {app_runtime_abbr}.
|Troubleshoot your load balancer configuration.
|===
.hinted marks the table as carrying hints; .col1-key, .col2-prose
and .col3-prose name the column roles. There is no .col1-nowrap, so
column 1 wraps. The rest is the native table. Table 2 is written the same
way, inside step 4.
Extension output: the same images as native, for all six tables.
Differences seen:
credential-types).X-Vcap-Request-Id breaks at a hyphen in Docusaurus, Zensical and
Starlight, at a different hyphen in each. Antora and the published page
keep it whole.uaa-conceptsuaa-concepts.html.md.erb in cloudfoundry/docs-uaa, commit 0f43fb9From docs-uaa, two tables: Grant type / User / Details, and Key / Value. The
implicit row ends with </td> instead of </tr> (fixed in every mode).
In the Key / Value table, <br/><br/> in a cell is a paragraph break
(decided): two paragraphs in extension and in Starlight and Antora native.
<br/><br/>
and as two paragraphs
(Docusaurus), the
lost spaces
(Starlight, HTML as written)What the tables ask for (R-02 rich tables):
<th width="30%">. Column 1 names the grant type, so it is a key column
and could be row headers. Its identifiers, such as client_credentials,
should not break at the _. Columns 2 and 3 are prose.<th width="25%">), a key column that could be row
headers. Column 2 is prose.</td>. The implicit row ends with </td> where </tr>
belongs. Browsers ignore the stray end tag and close the row at the next
<tr>; strict parsers fail. Every conversion fixes it
(R-24 markup cleanup before conversion).allowed providers row, <br/><br/>
separates two paragraphs; the line breaks stand in for a paragraph break.
The cell holds two paragraphs (decided) wherever the tool’s table syntax
can hold them. Passthrough keeps <br/><br/>, and pipe tables, which
cannot hold paragraphs, keep <br /><br />. The intent file records the
change as a deviation (R-01 content and
outline survive).<%= vars.platform_name %> renders as
“Cloud Foundry” (R-04 variables
everywhere).class="table", the standard style
(R-09 table styles by class).At a glance, from the screenshots below. Widths are the measured values in results.md, percent of the table, table 1 then table 2; a cell is empty where results.md has no measurement (the published page, and Docusaurus extension, where results.md records only that the widths are honored):
| Output | Column widths | Header cells | Body cells, vertically | Key cells as row headers | Rule between the columns | allowed providers cell |
|---|---|---|---|---|---|---|
| Published | left | centered | no | yes | <br/><br/> |
|
| Docusaurus native | 27/30/43 and 25/74, sized by content | centered | centered | no | yes | <br /><br /> |
| Docusaurus passthrough | 30% and 25% | centered | centered | no | yes | <br/><br/> |
| Zensical native | 30/26/43 and 25/75 | left | top | no | no | <br /><br /> |
| Zensical passthrough | 30/26/43 and 25/75 | left | top | no | no | <br/><br/> |
| Starlight native | 30/31/39 and 25/75 | left | top | no | no | two paragraphs |
| Starlight passthrough | 30/31/39 and 25/75 | left | top | no | no | <br/><br/> |
| Antora native | 30/29/41 and 25/75 | left | top | yes (bold) | yes | two paragraphs |
| Antora passthrough | 30/29/41 and 26/74 | left | centered | no | yes | <br/><br/> |
| Docusaurus extension | column 1 left, the others centered | top | yes (bold) | yes | two paragraphs | |
| Zensical extension | 30/26/43 and 25/75 | left | top | yes (bold) | no | two paragraphs |
| Starlight extension | 30/31/39 and 25/75 | left | top | yes (bold) | no | two paragraphs |
| Antora extension | 30/29/41 and 25/75 | left | top | yes (bold) | yes | two paragraphs |
All five rows of both tables are present in every output: the spot checks
(per-table checks listed in the intent file and run on every build) pass in
every mode of every tool. Among them: every code span in table 1 renders as
code, the second paragraph of the allowed providers cell is set off by a
visible gap, and the name row’s link goes to #clientid.
Table 1:

Table 2:

Header cells are on the left on a gray background, and every cell has a
border. A grant type or key sits in the vertical middle of its row. In
table 2 the double break leaves a blank line between the two paragraphs of
the allowed providers cell. The published build makes apostrophes
typographic (organization’s).
</td> that ends the implicit row)Table 1:
<table>
<thead>
<tr>
<th width="30%">Grant type</th>
<th>User</th>
<th>Details</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>authorization_code</code></td>
<td>Developers building web apps</td>
<td>In the authorization code grant flow, the user is directed to a UAA page where they grant approvals to the
client. After the user approves the requested scopes, they are redirected back to the client app with an
authorization code in the URL parameters. The client app may then exchange the authorization code with UAA to
obtain an access token.</td>
</tr>
<tr>
<td><code>password</code></td>
<td>Developers building native desktop or mobile apps</td>
<td>The name <code>password</code> refers to the resource owner password grant type. The user provides their
username and password to the client app, which may then use them to obtain an <code>access_token</code>.</td>
</tr>
<tr>
<td><code>implicit</code></td>
<td>Developers building a single page web app with no server back end</td>
<td>The user is taken to a page on UAA where they are asked to grant approvals to the client. After doing so, they
are redirected to the <code>redirect_uri</code> with the access token in the URI fragment.</td>
</td>
<tr>
<td><code>client_credentials</code></td>
<td>Developers when the client app needs to perform actions in UAA on its own behalf</td>
<td>Actions where a <code>client_credentials</code> grant type might be appropriate include creating or destroying
user groups, managing user group membership, or creating or destroying other clients. The
<code>client_credentials</code> grant can be likened to service accounts in legacy app ecosystems.</td>
</tr>
<tr>
<td><code>refresh_token</code></td>
<td>Developers must use the <code>refresh_token</code> grant type with either the <code>authorization_code</code>
or <code>password</code> grant type. <code>refresh_token</code> cannot be used by itself.</td>
<td>Clients typically use the <code>refresh_token</code> to obtain a new access token without the need for the user
to authenticate again. They do this by calling <code>/oauth/token</code> with
<code>grant_type=refresh_token</code>. A refresh token is only issued to clients that have
<code>refresh_token</code> in their list of <code>authorized_grant_types</code>.</td>
</tr>
</tbody>
</table>
Table 2:
<table>
<thead>
<tr>
<th width="25%">Key</th>
<th>Value</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>allowed providers</code></td>
<td>You can limit which users can use which apps. For example, in a <%= vars.platform_name %> deployment, you may
have set up multiple IDPs. Or, you could be using Facebook and your organization's LDAP system.<br/><br/>
You can limit UAA to only issue an app tokens if the users are from a certain provider. To do this, configure the
app's client with <code>allowed providers="ldap"</code>. The value is a comma-separated string of
<code>Identity Provider.origin</code> values.</td>
</tr>
<tr>
<td><code>created with</code></td>
<td>UAA stores the scope <code>zones.write</code> in this field if the client was created using the
<code>/identity-zones</code> endpoint. UAA uses this field to allow clients to be deleted by the same endpoint.
This is not a configurable field.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>Various tooling in the <%= vars.platform_name %> ecosystem creates clients with generated
<code>Client.client_id</code> values. These tools often store a human-readable name in this field. For more
information, see <a href="#clientid">client.client_id</a>.</td>
</tr>
<tr>
<td><code>approvals_deleted</code></td>
<td>Contains a boolean value if performing an operation on the client resulted in all the client's user approvals
were deleted. For example, changing the <code>client.client_secret</code> value causes UAA to delete all the
approvals. UAA then stores a value of <code>true</code> in this field.</td>
</tr>
<tr>
<td><code>token_salt</code></td>
<td>Tokens, even stateless JWT, can be revoked. Revoked tokens do not pass a UAA token validation when the token is
passed to the <code>/introspect</code> endpoint. UAA revokes a token if the client's secret has changed. There
may be occasions to revoke all tokens for a certain client without having to change the client secret. You can do
this by changing the <code>token_salt</code>. <code>token_salt</code> is an arbitrary string value that is used
to generate a hash.</td>
</tr>
</tbody>
</table>
ERB (Embedded Ruby, <%= … %> tags in a page; see the
glossary) is how today’s pages insert variables and
partials. Table 2 uses one variable, vars.platform_name, in two cells
(see the glossary).
Pages are MDX, which parses HTML as JSX (see
credential-types and the
glossary). A variable is an MDX expression,
{vars.platform_name}, after one import at the top of the page.
Table 1:
| Grant type | User | Details |
| --- | --- | --- |
| `authorization_code` | Developers building web apps | In the authorization code grant flow, the user is directed to a UAA page where they grant approvals to the client. After the user approves the requested scopes, they are redirected back to the client app with an authorization code in the URL parameters. The client app may then exchange the authorization code with UAA to obtain an access token. |
| `password` | Developers building native desktop or mobile apps | The name `password` refers to the resource owner password grant type. The user provides their username and password to the client app, which may then use them to obtain an `access_token`. |
| `implicit` | Developers building a single page web app with no server back end | The user is taken to a page on UAA where they are asked to grant approvals to the client. After doing so, they are redirected to the `redirect_uri` with the access token in the URI fragment. |
| `client_credentials` | Developers when the client app needs to perform actions in UAA on its own behalf | Actions where a `client_credentials` grant type might be appropriate include creating or destroying user groups, managing user group membership, or creating or destroying other clients. The `client_credentials` grant can be likened to service accounts in legacy app ecosystems. |
| `refresh_token` | Developers must use the `refresh_token` grant type with either the `authorization_code` or `password` grant type. `refresh_token` cannot be used by itself. | Clients typically use the `refresh_token` to obtain a new access token without the need for the user to authenticate again. They do this by calling `/oauth/token` with `grant_type=refresh_token`. A refresh token is only issued to clients that have `refresh_token` in their list of `authorized_grant_types`. |
Table 2:
| Key | Value |
| --- | --- |
| `allowed providers` | You can limit which users can use which apps. For example, in a {vars.platform_name} deployment, you may have set up multiple IDPs. Or, you could be using Facebook and your organization's LDAP system. <br /><br /> You can limit UAA to only issue an app tokens if the users are from a certain provider. To do this, configure the app's client with `allowed providers="ldap"`. The value is a comma-separated string of `Identity Provider.origin` values. |
| `created with` | UAA stores the scope `zones.write` in this field if the client was created using the `/identity-zones` endpoint. UAA uses this field to allow clients to be deleted by the same endpoint. This is not a configurable field. |
| `name` | Various tooling in the {vars.platform_name} ecosystem creates clients with generated `Client.client_id` values. These tools often store a human-readable name in this field. For more information, see [client.client_id](#clientid). |
| `approvals_deleted` | Contains a boolean value if performing an operation on the client resulted in all the client's user approvals were deleted. For example, changing the `client.client_secret` value causes UAA to delete all the approvals. UAA then stores a value of `true` in this field. |
| `token_salt` | Tokens, even stateless JWT, can be revoked. Revoked tokens do not pass a UAA token validation when the token is passed to the `/introspect` endpoint. UAA revokes a token if the client's secret has changed. There may be occasions to revoke all tokens for a certain client without having to change the client secret. You can do this by changing the `token_salt`. `token_salt` is an arbitrary string value that is used to generate a hash. |
</tr> fixed and the variable as an MDX expressionTable 1:
<table class="table">
<thead>
<tr>
<th width="30%">Grant type</th>
<th>User</th>
<th>Details</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>authorization_code</code></td>
<td>Developers building web apps</td>
<td>In the authorization code grant flow, the user is directed to a UAA page where they grant approvals to the
client. After the user approves the requested scopes, they are redirected back to the client app with an
authorization code in the URL parameters. The client app may then exchange the authorization code with UAA to
obtain an access token.</td>
</tr>
<tr>
<td><code>password</code></td>
<td>Developers building native desktop or mobile apps</td>
<td>The name <code>password</code> refers to the resource owner password grant type. The user provides their
username and password to the client app, which may then use them to obtain an <code>access_token</code>.</td>
</tr>
<tr>
<td><code>implicit</code></td>
<td>Developers building a single page web app with no server back end</td>
<td>The user is taken to a page on UAA where they are asked to grant approvals to the client. After doing so, they
are redirected to the <code>redirect_uri</code> with the access token in the URI fragment.</td>
</tr>
<tr>
<td><code>client_credentials</code></td>
<td>Developers when the client app needs to perform actions in UAA on its own behalf</td>
<td>Actions where a <code>client_credentials</code> grant type might be appropriate include creating or destroying
user groups, managing user group membership, or creating or destroying other clients. The
<code>client_credentials</code> grant can be likened to service accounts in legacy app ecosystems.</td>
</tr>
<tr>
<td><code>refresh_token</code></td>
<td>Developers must use the <code>refresh_token</code> grant type with either the <code>authorization_code</code>
or <code>password</code> grant type. <code>refresh_token</code> cannot be used by itself.</td>
<td>Clients typically use the <code>refresh_token</code> to obtain a new access token without the need for the user
to authenticate again. They do this by calling <code>/oauth/token</code> with
<code>grant_type=refresh_token</code>. A refresh token is only issued to clients that have
<code>refresh_token</code> in their list of <code>authorized_grant_types</code>.</td>
</tr>
</tbody>
</table>
Table 2:
<table class="table">
<thead>
<tr>
<th width="25%">Key</th>
<th>Value</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>allowed providers</code></td>
<td>You can limit which users can use which apps. For example, in a {vars.platform_name} deployment, you may
have set up multiple IDPs. Or, you could be using Facebook and your organization's LDAP system.<br/><br/>
You can limit UAA to only issue an app tokens if the users are from a certain provider. To do this, configure the
app's client with <code>allowed providers="ldap"</code>. The value is a comma-separated string of
<code>Identity Provider.origin</code> values.</td>
</tr>
<tr>
<td><code>created with</code></td>
<td>UAA stores the scope <code>zones.write</code> in this field if the client was created using the
<code>/identity-zones</code> endpoint. UAA uses this field to allow clients to be deleted by the same endpoint.
This is not a configurable field.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>Various tooling in the {vars.platform_name} ecosystem creates clients with generated
<code>Client.client_id</code> values. These tools often store a human-readable name in this field. For more
information, see <a href="#clientid">client.client_id</a>.</td>
</tr>
<tr>
<td><code>approvals_deleted</code></td>
<td>Contains a boolean value if performing an operation on the client resulted in all the client's user approvals
were deleted. For example, changing the <code>client.client_secret</code> value causes UAA to delete all the
approvals. UAA then stores a value of <code>true</code> in this field.</td>
</tr>
<tr>
<td><code>token_salt</code></td>
<td>Tokens, even stateless JWT, can be revoked. Revoked tokens do not pass a UAA token validation when the token is
passed to the <code>/introspect</code> endpoint. UAA revokes a token if the client's secret has changed. There
may be occasions to revoke all tokens for a certain client without having to change the client secret. You can do
this by changing the <code>token_salt</code>. <code>token_salt</code> is an arbitrary string value that is used
to generate a hash.</td>
</tr>
</tbody>
</table>
Files: native, passthrough, passthrough as written, extension. Docusaurus has no native-plain page: its native page already has no width settings.
Native output:


Passthrough output:


Differences seen:
{OIDC provider alias} in a list, which it
reads as an expression; passthrough writes it \{OIDC provider alias\}
(raw passthrough errors).
The tables need only the </tr> fix and the variable: the source already
has <tbody> and sets widths with width, not style.<br /><br />, and both modes show a blank line
between the two paragraphs, as the published page does.allowed providers="ldap" breaks at its space, in both modes
(“allowed” / providers="ldap"). The published page keeps it on one
line. The text itself is unchanged.Extension mode. A :::list-table block, read by a remark plugin added
to the site, as in credential-types:
plugins/list-table.js,
with hints.css.
Table 1:
:::list-table{widths="30 auto auto" header-rows="1" stub-columns="1" roles="key prose prose"}
- - Grant type
- User
- Details
- - `authorization_code`
- Developers building web apps
- In the authorization code grant flow, the user is directed to a UAA page where they grant approvals to the client. After the user approves the requested scopes, they are redirected back to the client app with an authorization code in the URL parameters. The client app may then exchange the authorization code with UAA to obtain an access token.
- - `password`
- Developers building native desktop or mobile apps
- The name `password` refers to the resource owner password grant type. The user provides their username and password to the client app, which may then use them to obtain an `access_token`.
- - `implicit`
- Developers building a single page web app with no server back end
- The user is taken to a page on UAA where they are asked to grant approvals to the client. After doing so, they are redirected to the `redirect_uri` with the access token in the URI fragment.
- - `client_credentials`
- Developers when the client app needs to perform actions in UAA on its own behalf
- Actions where a `client_credentials` grant type might be appropriate include creating or destroying user groups, managing user group membership, or creating or destroying other clients. The `client_credentials` grant can be likened to service accounts in legacy app ecosystems.
- - `refresh_token`
- Developers must use the `refresh_token` grant type with either the `authorization_code` or `password` grant type. `refresh_token` cannot be used by itself.
- Clients typically use the `refresh_token` to obtain a new access token without the need for the user to authenticate again. They do this by calling `/oauth/token` with `grant_type=refresh_token`. A refresh token is only issued to clients that have `refresh_token` in their list of `authorized_grant_types`.
:::
Table 2:
:::list-table{widths="25 auto" header-rows="1" stub-columns="1" roles="key prose"}
- - Key
- Value
- - `allowed providers`
- You can limit which users can use which apps. For example, in a {vars.platform_name} deployment, you may have set up multiple IDPs. Or, you could be using Facebook and your organization's LDAP system.
You can limit UAA to only issue an app tokens if the users are from a certain provider. To do this, configure the app's client with `allowed providers="ldap"`. The value is a comma-separated string of `Identity Provider.origin` values.
- - `created with`
- UAA stores the scope `zones.write` in this field if the client was created using the `/identity-zones` endpoint. UAA uses this field to allow clients to be deleted by the same endpoint. This is not a configurable field.
- - `name`
- Various tooling in the {vars.platform_name} ecosystem creates clients with generated `Client.client_id` values. These tools often store a human-readable name in this field. For more information, see [client.client_id](#clientid).
- - `approvals_deleted`
- Contains a boolean value if performing an operation on the client resulted in all the client's user approvals were deleted. For example, changing the `client.client_secret` value causes UAA to delete all the approvals. UAA then stores a value of `true` in this field.
- - `token_salt`
- Tokens, even stateless JWT, can be revoked. Revoked tokens do not pass a UAA token validation when the token is passed to the `/introspect` endpoint. UAA revokes a token if the client's secret has changed. There may be occasions to revoke all tokens for a certain client without having to change the client secret. You can do this by changing the `token_salt`. `token_salt` is an arbitrary string value that is used to generate a hash.
:::
widths sets column 1 to 30% (25% in table 2) and sizes the other columns
by their content, header-rows="1" makes the first row the header,
stub-columns="1" makes column 1 row headers, and roles names column 1 a
key column and the others prose. In table 2 the allowed providers cell
holds two paragraphs, written as in Markdown: a blank line, then the second
paragraph indented under its list item.
Extension output:


Differences seen, against the published page and the other two modes:
allowed providers cell holds two paragraphs. The gap between
them is a paragraph margin, a little smaller than the blank line the
double break leaves. The site removes the margin after a cell’s last
paragraph (Docusaurus finding 9).credential-types.allowed providers="ldap" still
breaks at its space, as in the other two modes.Pages are Markdown read by Python-Markdown, which passes HTML blocks through
unchanged, and an attribute list, {: … } after a cell’s text, sets HTML
attributes on that cell (see credential-types and the
glossary). Variables keep their ERB form.
Table 1:
| Grant type {: style="width:30%" } | User | Details |
| --- | --- | --- |
| `authorization_code` | Developers building web apps | In the authorization code grant flow, the user is directed to a UAA page where they grant approvals to the client. After the user approves the requested scopes, they are redirected back to the client app with an authorization code in the URL parameters. The client app may then exchange the authorization code with UAA to obtain an access token. |
| `password` | Developers building native desktop or mobile apps | The name `password` refers to the resource owner password grant type. The user provides their username and password to the client app, which may then use them to obtain an `access_token`. |
| `implicit` | Developers building a single page web app with no server back end | The user is taken to a page on UAA where they are asked to grant approvals to the client. After doing so, they are redirected to the `redirect_uri` with the access token in the URI fragment. |
| `client_credentials` | Developers when the client app needs to perform actions in UAA on its own behalf | Actions where a `client_credentials` grant type might be appropriate include creating or destroying user groups, managing user group membership, or creating or destroying other clients. The `client_credentials` grant can be likened to service accounts in legacy app ecosystems. |
| `refresh_token` | Developers must use the `refresh_token` grant type with either the `authorization_code` or `password` grant type. `refresh_token` cannot be used by itself. | Clients typically use the `refresh_token` to obtain a new access token without the need for the user to authenticate again. They do this by calling `/oauth/token` with `grant_type=refresh_token`. A refresh token is only issued to clients that have `refresh_token` in their list of `authorized_grant_types`. |
Table 2:
| Key {: style="width:25%" } | Value |
| --- | --- |
| `allowed providers` | You can limit which users can use which apps. For example, in a <%= vars.platform_name %> deployment, you may have set up multiple IDPs. Or, you could be using Facebook and your organization's LDAP system. <br /><br /> You can limit UAA to only issue an app tokens if the users are from a certain provider. To do this, configure the app's client with `allowed providers="ldap"`. The value is a comma-separated string of `Identity Provider.origin` values. |
| `created with` | UAA stores the scope `zones.write` in this field if the client was created using the `/identity-zones` endpoint. UAA uses this field to allow clients to be deleted by the same endpoint. This is not a configurable field. |
| `name` | Various tooling in the <%= vars.platform_name %> ecosystem creates clients with generated `Client.client_id` values. These tools often store a human-readable name in this field. For more information, see [client.client_id](#clientid). |
| `approvals_deleted` | Contains a boolean value if performing an operation on the client resulted in all the client's user approvals were deleted. For example, changing the `client.client_secret` value causes UAA to delete all the approvals. UAA then stores a value of `true` in this field. |
| `token_salt` | Tokens, even stateless JWT, can be revoked. Revoked tokens do not pass a UAA token validation when the token is passed to the `/introspect` endpoint. UAA revokes a token if the client's secret has changed. There may be occasions to revoke all tokens for a certain client without having to change the client secret. You can do this by changing the `token_salt`. `token_salt` is an arbitrary string value that is used to generate a hash. |
</tr> fixedTable 1:
<table class="table">
<thead>
<tr>
<th width="30%">Grant type</th>
<th>User</th>
<th>Details</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>authorization_code</code></td>
<td>Developers building web apps</td>
<td>In the authorization code grant flow, the user is directed to a UAA page where they grant approvals to the
client. After the user approves the requested scopes, they are redirected back to the client app with an
authorization code in the URL parameters. The client app may then exchange the authorization code with UAA to
obtain an access token.</td>
</tr>
<tr>
<td><code>password</code></td>
<td>Developers building native desktop or mobile apps</td>
<td>The name <code>password</code> refers to the resource owner password grant type. The user provides their
username and password to the client app, which may then use them to obtain an <code>access_token</code>.</td>
</tr>
<tr>
<td><code>implicit</code></td>
<td>Developers building a single page web app with no server back end</td>
<td>The user is taken to a page on UAA where they are asked to grant approvals to the client. After doing so, they
are redirected to the <code>redirect_uri</code> with the access token in the URI fragment.</td>
</tr>
<tr>
<td><code>client_credentials</code></td>
<td>Developers when the client app needs to perform actions in UAA on its own behalf</td>
<td>Actions where a <code>client_credentials</code> grant type might be appropriate include creating or destroying
user groups, managing user group membership, or creating or destroying other clients. The
<code>client_credentials</code> grant can be likened to service accounts in legacy app ecosystems.</td>
</tr>
<tr>
<td><code>refresh_token</code></td>
<td>Developers must use the <code>refresh_token</code> grant type with either the <code>authorization_code</code>
or <code>password</code> grant type. <code>refresh_token</code> cannot be used by itself.</td>
<td>Clients typically use the <code>refresh_token</code> to obtain a new access token without the need for the user
to authenticate again. They do this by calling <code>/oauth/token</code> with
<code>grant_type=refresh_token</code>. A refresh token is only issued to clients that have
<code>refresh_token</code> in their list of <code>authorized_grant_types</code>.</td>
</tr>
</tbody>
</table>
Table 2:
<table class="table">
<thead>
<tr>
<th width="25%">Key</th>
<th>Value</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>allowed providers</code></td>
<td>You can limit which users can use which apps. For example, in a <%= vars.platform_name %> deployment, you may
have set up multiple IDPs. Or, you could be using Facebook and your organization's LDAP system.<br/><br/>
You can limit UAA to only issue an app tokens if the users are from a certain provider. To do this, configure the
app's client with <code>allowed providers="ldap"</code>. The value is a comma-separated string of
<code>Identity Provider.origin</code> values.</td>
</tr>
<tr>
<td><code>created with</code></td>
<td>UAA stores the scope <code>zones.write</code> in this field if the client was created using the
<code>/identity-zones</code> endpoint. UAA uses this field to allow clients to be deleted by the same endpoint.
This is not a configurable field.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>Various tooling in the <%= vars.platform_name %> ecosystem creates clients with generated
<code>Client.client_id</code> values. These tools often store a human-readable name in this field. For more
information, see <a href="#clientid">client.client_id</a>.</td>
</tr>
<tr>
<td><code>approvals_deleted</code></td>
<td>Contains a boolean value if performing an operation on the client resulted in all the client's user approvals
were deleted. For example, changing the <code>client.client_secret</code> value causes UAA to delete all the
approvals. UAA then stores a value of <code>true</code> in this field.</td>
</tr>
<tr>
<td><code>token_salt</code></td>
<td>Tokens, even stateless JWT, can be revoked. Revoked tokens do not pass a UAA token validation when the token is
passed to the <code>/introspect</code> endpoint. UAA revokes a token if the client's secret has changed. There
may be occasions to revoke all tokens for a certain client without having to change the client secret. You can do
this by changing the <code>token_salt</code>. <code>token_salt</code> is an arbitrary string value that is used
to generate a hash.</td>
</tr>
</tbody>
</table>
Files: native, native-plain, passthrough, passthrough as written, extension.
Native and passthrough output, table 1 (the two screenshots differ only by image-compression noise):

Native output, table 2:

Passthrough output, table 2 (it looks the same as native, but the two screenshots are not the same image):

Differences seen:
</td> builds
and renders as on the published page, because the browser repairs it; the
only table change is the </tr> fix from the intent file
(Zensical, raw passthrough).credential-types
(font size).table.table the theme’s
table look (Zensical finding 1),
which is why the two modes look the same.Extension mode. A /// list-table block, read by a Python-Markdown
extension added to the site, as in credential-types:
list_table.py, with
hints.css.
Table 1:
/// list-table
widths: 30 auto auto
header-rows: 1
stub-columns: 1
roles: key prose prose
- - Grant type
- User
- Details
- - `authorization_code`
- Developers building web apps
- In the authorization code grant flow, the user is directed to a UAA page where they grant approvals to the client. After the user approves the requested scopes, they are redirected back to the client app with an authorization code in the URL parameters. The client app may then exchange the authorization code with UAA to obtain an access token.
- - `password`
- Developers building native desktop or mobile apps
- The name `password` refers to the resource owner password grant type. The user provides their username and password to the client app, which may then use them to obtain an `access_token`.
- - `implicit`
- Developers building a single page web app with no server back end
- The user is taken to a page on UAA where they are asked to grant approvals to the client. After doing so, they are redirected to the `redirect_uri` with the access token in the URI fragment.
- - `client_credentials`
- Developers when the client app needs to perform actions in UAA on its own behalf
- Actions where a `client_credentials` grant type might be appropriate include creating or destroying user groups, managing user group membership, or creating or destroying other clients. The `client_credentials` grant can be likened to service accounts in legacy app ecosystems.
- - `refresh_token`
- Developers must use the `refresh_token` grant type with either the `authorization_code` or `password` grant type. `refresh_token` cannot be used by itself.
- Clients typically use the `refresh_token` to obtain a new access token without the need for the user to authenticate again. They do this by calling `/oauth/token` with `grant_type=refresh_token`. A refresh token is only issued to clients that have `refresh_token` in their list of `authorized_grant_types`.
///
Table 2:
/// list-table
widths: 25 auto
header-rows: 1
stub-columns: 1
roles: key prose
- - Key
- Value
- - `allowed providers`
- You can limit which users can use which apps. For example, in a <%= vars.platform_name %> deployment, you may have set up multiple IDPs. Or, you could be using Facebook and your organization's LDAP system.
You can limit UAA to only issue an app tokens if the users are from a certain provider. To do this, configure the app's client with `allowed providers="ldap"`. The value is a comma-separated string of `Identity Provider.origin` values.
- - `created with`
- UAA stores the scope `zones.write` in this field if the client was created using the `/identity-zones` endpoint. UAA uses this field to allow clients to be deleted by the same endpoint. This is not a configurable field.
- - `name`
- Various tooling in the <%= vars.platform_name %> ecosystem creates clients with generated `Client.client_id` values. These tools often store a human-readable name in this field. For more information, see [client.client_id](#clientid).
- - `approvals_deleted`
- Contains a boolean value if performing an operation on the client resulted in all the client's user approvals were deleted. For example, changing the `client.client_secret` value causes UAA to delete all the approvals. UAA then stores a value of `true` in this field.
- - `token_salt`
- Tokens, even stateless JWT, can be revoked. Revoked tokens do not pass a UAA token validation when the token is passed to the `/introspect` endpoint. UAA revokes a token if the client's secret has changed. There may be occasions to revoke all tokens for a certain client without having to change the client secret. You can do this by changing the `token_salt`. `token_salt` is an arbitrary string value that is used to generate a hash.
///
The options mean the same as in the Docusaurus directive: column 1 at 30%
(25% in table 2), a header row, column 1 as row headers, and the column
roles. The two paragraphs of the allowed providers cell are written as in
Markdown, the second indented under its list item.
Extension output:


Differences seen, against native and passthrough:
allowed providers cell holds two paragraphs. The gap between
them is a paragraph margin, a little smaller than the blank line of the
other two modes, so table 2 is 10 pixels shorter (701 against 711).Starlight pages are Markdoc, Markdown with {% %} tags, with HTML allowed.
Markdoc’s {% table %} tag writes each cell as a list item and each row
break as --- (see credential-types and the
glossary). Its cells hold paragraphs. A variable
is written {% $vars.platform_name %}.
Table 1:
{% table %}
* Grant type {% width="30%" %}
* User
* Details
---
* `authorization_code`
* Developers building web apps
* In the authorization code grant flow, the user is directed to a UAA page where they grant approvals to the client. After the user approves the requested scopes, they are redirected back to the client app with an authorization code in the URL parameters. The client app may then exchange the authorization code with UAA to obtain an access token.
---
* `password`
* Developers building native desktop or mobile apps
* The name `password` refers to the resource owner password grant type. The user provides their username and password to the client app, which may then use them to obtain an `access_token`.
---
* `implicit`
* Developers building a single page web app with no server back end
* The user is taken to a page on UAA where they are asked to grant approvals to the client. After doing so, they are redirected to the `redirect_uri` with the access token in the URI fragment.
---
* `client_credentials`
* Developers when the client app needs to perform actions in UAA on its own behalf
* Actions where a `client_credentials` grant type might be appropriate include creating or destroying user groups, managing user group membership, or creating or destroying other clients. The `client_credentials` grant can be likened to service accounts in legacy app ecosystems.
---
* `refresh_token`
* Developers must use the `refresh_token` grant type with either the `authorization_code` or `password` grant type. `refresh_token` cannot be used by itself.
* Clients typically use the `refresh_token` to obtain a new access token without the need for the user to authenticate again. They do this by calling `/oauth/token` with `grant_type=refresh_token`. A refresh token is only issued to clients that have `refresh_token` in their list of `authorized_grant_types`.
{% /table %}
Table 2:
{% table %}
* Key {% width="25%" %}
* Value
---
* `allowed providers`
* You can limit which users can use which apps. For example, in a {% $vars.platform_name %} deployment, you may have set up multiple IDPs. Or, you could be using Facebook and your organization's LDAP system.
You can limit UAA to only issue an app tokens if the users are from a certain provider. To do this, configure the app's client with `allowed providers="ldap"`. The value is a comma-separated string of `Identity Provider.origin` values.
---
* `created with`
* UAA stores the scope `zones.write` in this field if the client was created using the `/identity-zones` endpoint. UAA uses this field to allow clients to be deleted by the same endpoint. This is not a configurable field.
---
* `name`
* Various tooling in the {% $vars.platform_name %} ecosystem creates clients with generated `Client.client_id` values. These tools often store a human-readable name in this field. For more information, see [client.client_id](#clientid).
---
* `approvals_deleted`
* Contains a boolean value if performing an operation on the client resulted in all the client's user approvals were deleted. For example, changing the `client.client_secret` value causes UAA to delete all the approvals. UAA then stores a value of `true` in this field.
---
* `token_salt`
* Tokens, even stateless JWT, can be revoked. Revoked tokens do not pass a UAA token validation when the token is passed to the `/introspect` endpoint. UAA revokes a token if the client's secret has changed. There may be occasions to revoke all tokens for a certain client without having to change the client secret. You can do this by changing the `token_salt`. `token_salt` is an arbitrary string value that is used to generate a hash.
{% /table %}
In table 2 the allowed providers cell holds two paragraphs: a blank line,
then the second paragraph indented under its list item.
</tr> fixed, each cell on one line, and one space written  Table 1:
<table class="table">
<thead>
<tr>
<th width="30%">Grant type</th>
<th>User</th>
<th>Details</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>authorization_code</code></td>
<td>Developers building web apps</td>
<td>In the authorization code grant flow, the user is directed to a UAA page where they grant approvals to the client. After the user approves the requested scopes, they are redirected back to the client app with an authorization code in the URL parameters. The client app may then exchange the authorization code with UAA to obtain an access token.</td>
</tr>
<tr>
<td><code>password</code></td>
<td>Developers building native desktop or mobile apps</td>
<td>The name <code>password</code> refers to the resource owner password grant type. The user provides their username and password to the client app, which may then use them to obtain an <code>access_token</code>.</td>
</tr>
<tr>
<td><code>implicit</code></td>
<td>Developers building a single page web app with no server back end</td>
<td>The user is taken to a page on UAA where they are asked to grant approvals to the client. After doing so, they are redirected to the <code>redirect_uri</code> with the access token in the URI fragment.</td>
</tr>
<tr>
<td><code>client_credentials</code></td>
<td>Developers when the client app needs to perform actions in UAA on its own behalf</td>
<td>Actions where a <code>client_credentials</code> grant type might be appropriate include creating or destroying user groups, managing user group membership, or creating or destroying other clients. The <code>client_credentials</code> grant can be likened to service accounts in legacy app ecosystems.</td>
</tr>
<tr>
<td><code>refresh_token</code></td>
<td>Developers must use the <code>refresh_token</code> grant type with either the <code>authorization_code</code> or <code>password</code> grant type. <code>refresh_token</code> cannot be used by itself.</td>
<td>Clients typically use the <code>refresh_token</code> to obtain a new access token without the need for the user to authenticate again. They do this by calling <code>/oauth/token</code> with <code>grant_type=refresh_token</code>. A refresh token is only issued to clients that have <code>refresh_token</code> in their list of <code>authorized_grant_types</code>.</td>
</tr>
</tbody>
</table>
Table 2:
<table class="table">
<thead>
<tr>
<th width="25%">Key</th>
<th>Value</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>allowed providers</code></td>
<td>You can limit which users can use which apps. For example, in a {% $vars.platform_name %} deployment, you may have set up multiple IDPs. Or, you could be using Facebook and your organization's LDAP system.<br/><br/> You can limit UAA to only issue an app tokens if the users are from a certain provider. To do this, configure the app's client with <code>allowed providers="ldap"</code>. The value is a comma-separated string of <code>Identity Provider.origin</code> values.</td>
</tr>
<tr>
<td><code>created with</code></td>
<td>UAA stores the scope <code>zones.write</code> in this field if the client was created using the <code>/identity-zones</code> endpoint. UAA uses this field to allow clients to be deleted by the same endpoint. This is not a configurable field.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>Various tooling in the {% $vars.platform_name %} ecosystem creates clients with generated <code>Client.client_id</code> values. These tools often store a human-readable name in this field. For more information, see <a href="#clientid">client.client_id</a>.</td>
</tr>
<tr>
<td><code>approvals_deleted</code></td>
<td>Contains a boolean value if performing an operation on the client resulted in all the client's user approvals were deleted. For example, changing the <code>client.client_secret</code> value causes UAA to delete all the approvals. UAA then stores a value of <code>true</code> in this field.</td>
</tr>
<tr>
<td><code>token_salt</code></td>
<td>Tokens, even stateless JWT, can be revoked. Revoked tokens do not pass a UAA token validation when the token is passed to the <code>/introspect</code> endpoint. UAA revokes a token if the client's secret has changed. There may be occasions to revoke all tokens for a certain client without having to change the client secret. You can do this by changing the <code>token_salt</code>. <code>token_salt</code> is an arbitrary string value that is used to generate a hash.</td>
</tr>
</tbody>
</table>
Files: native, native-plain, passthrough, passthrough as written, extension.
Native and passthrough output, table 1 (the two screenshots are the same image, byte for byte):

Native output, table 2:

Passthrough output, table 2:

Differences seen:
<code>password</code> refers
renders as “passwordrefers”, in 19 places on this page, all inside table
cells, and the build reports nothing
(screenshot;
Starlight finding 2).
Passthrough puts each cell on one line and writes the space after the
variable in the name row as  . Joining cells is not adopted as a
conversion rule: it makes the source harder to read.width on the
first header cell. Without it (native-plain, a pipe table), the columns
are 27/32/41 and 25/75.allowed providers cell, from
Markdoc’s own table tag; passthrough keeps <br/><br/>, and its blank
line makes table 2 12 pixels taller (978 against 966).Extension mode. Markdoc’s own {% table %} tag with extra attributes,
declared for the site in
list-table.mjs, with
hints.css, as in
credential-types.
Table 1:
{% table widths="30 auto auto" header-rows=1 stub-columns=1 roles="key prose prose" %}
* Grant type
* User
* Details
---
* `authorization_code`
* Developers building web apps
* In the authorization code grant flow, the user is directed to a UAA page where they grant approvals to the client. After the user approves the requested scopes, they are redirected back to the client app with an authorization code in the URL parameters. The client app may then exchange the authorization code with UAA to obtain an access token.
---
* `password`
* Developers building native desktop or mobile apps
* The name `password` refers to the resource owner password grant type. The user provides their username and password to the client app, which may then use them to obtain an `access_token`.
---
* `implicit`
* Developers building a single page web app with no server back end
* The user is taken to a page on UAA where they are asked to grant approvals to the client. After doing so, they are redirected to the `redirect_uri` with the access token in the URI fragment.
---
* `client_credentials`
* Developers when the client app needs to perform actions in UAA on its own behalf
* Actions where a `client_credentials` grant type might be appropriate include creating or destroying user groups, managing user group membership, or creating or destroying other clients. The `client_credentials` grant can be likened to service accounts in legacy app ecosystems.
---
* `refresh_token`
* Developers must use the `refresh_token` grant type with either the `authorization_code` or `password` grant type. `refresh_token` cannot be used by itself.
* Clients typically use the `refresh_token` to obtain a new access token without the need for the user to authenticate again. They do this by calling `/oauth/token` with `grant_type=refresh_token`. A refresh token is only issued to clients that have `refresh_token` in their list of `authorized_grant_types`.
{% /table %}
Table 2:
{% table widths="25 auto" header-rows=1 stub-columns=1 roles="key prose" %}
* Key
* Value
---
* `allowed providers`
* You can limit which users can use which apps. For example, in a {% $vars.platform_name %} deployment, you may have set up multiple IDPs. Or, you could be using Facebook and your organization's LDAP system.
You can limit UAA to only issue an app tokens if the users are from a certain provider. To do this, configure the app's client with `allowed providers="ldap"`. The value is a comma-separated string of `Identity Provider.origin` values.
---
* `created with`
* UAA stores the scope `zones.write` in this field if the client was created using the `/identity-zones` endpoint. UAA uses this field to allow clients to be deleted by the same endpoint. This is not a configurable field.
---
* `name`
* Various tooling in the {% $vars.platform_name %} ecosystem creates clients with generated `Client.client_id` values. These tools often store a human-readable name in this field. For more information, see [client.client_id](#clientid).
---
* `approvals_deleted`
* Contains a boolean value if performing an operation on the client resulted in all the client's user approvals were deleted. For example, changing the `client.client_secret` value causes UAA to delete all the approvals. UAA then stores a value of `true` in this field.
---
* `token_salt`
* Tokens, even stateless JWT, can be revoked. Revoked tokens do not pass a UAA token validation when the token is passed to the `/introspect` endpoint. UAA revokes a token if the client's secret has changed. There may be occasions to revoke all tokens for a certain client without having to change the client secret. You can do this by changing the `token_salt`. `token_salt` is an arbitrary string value that is used to generate a hash.
{% /table %}
The attributes mean the same as in the Docusaurus directive: column 1 at 30% (25% in table 2), a header row, column 1 as row headers, and the column roles. The cells are written as in native.
Extension output:


Differences seen, against native:
Antora builds sites from AsciiDoc, and the whole page is rewritten from
Markdown to AsciiDoc in every mode, including passthrough, where the HTML
sits unchanged inside a passthrough block (++++) (see
credential-types and the
glossary). A variable is an AsciiDoc attribute,
{platform_name}.
Table 1:
[%header,cols=".<30%h,.<~,.<~"]
|===
|Grant type |User |Details
|`+authorization_code+`
|Developers building web apps
|In the authorization code grant flow, the user is directed to a UAA page where they grant approvals to the client. After the user approves the requested scopes, they are redirected back to the client app with an authorization code in the URL parameters. The client app may then exchange the authorization code with UAA to obtain an access token.
|`password`
|Developers building native desktop or mobile apps
|The name `password` refers to the resource owner password grant type. The user provides their username and password to the client app, which may then use them to obtain an `+access_token+`.
|`implicit`
|Developers building a single page web app with no server back end
|The user is taken to a page on UAA where they are asked to grant approvals to the client. After doing so, they are redirected to the `+redirect_uri+` with the access token in the URI fragment.
|`+client_credentials+`
|Developers when the client app needs to perform actions in UAA on its own behalf
|Actions where a `+client_credentials+` grant type might be appropriate include creating or destroying user groups, managing user group membership, or creating or destroying other clients. The `+client_credentials+` grant can be likened to service accounts in legacy app ecosystems.
|`+refresh_token+`
|Developers must use the `+refresh_token+` grant type with either the `+authorization_code+` or `password` grant type. `+refresh_token+` cannot be used by itself.
|Clients typically use the `+refresh_token+` to obtain a new access token without the need for the user to authenticate again. They do this by calling `/oauth/token` with `+grant_type=refresh_token+`. A refresh token is only issued to clients that have `+refresh_token+` in their list of `+authorized_grant_types+`.
|===
Table 2:
[%header,cols=".<25%h,.<~"]
|===
|Key |Value
|`allowed providers`
a|You can limit which users can use which apps. For example, in a {platform_name} deployment, you may have set up multiple IDPs. Or, you could be using Facebook and your organization's LDAP system.
You can limit UAA to only issue an app tokens if the users are from a certain provider. To do this, configure the app's client with `allowed providers="ldap"`. The value is a comma-separated string of `Identity Provider.origin` values.
|`created with`
|UAA stores the scope `zones.write` in this field if the client was created using the `/identity-zones` endpoint. UAA uses this field to allow clients to be deleted by the same endpoint. This is not a configurable field.
|`name`
|Various tooling in the {platform_name} ecosystem creates clients with generated `+Client.client_id+` values. These tools often store a human-readable name in this field. For more information, see <<clientid,client.client_id>>.
|`+approvals_deleted+`
|Contains a boolean value if performing an operation on the client resulted in all the client's user approvals were deleted. For example, changing the `+client.client_secret+` value causes UAA to delete all the approvals. UAA then stores a value of `true` in this field.
|`+token_salt+`
|Tokens, even stateless JWT, can be revoked. Revoked tokens do not pass a UAA token validation when the token is passed to the `/introspect` endpoint. UAA revokes a token if the client's secret has changed. There may be occasions to revoke all tokens for a certain client without having to change the client secret. You can do this by changing the `+token_salt+`. `+token_salt+` is an arbitrary string value that is used to generate a hash.
|===
In cols, .< aligns a column to the top, 30% and 25% are widths, h
makes column 1 row headers, and ~ sizes a column by its content, as in
credential-types. a| before the allowed providers
value makes that one cell an AsciiDoc cell, which can hold paragraphs
(Asciidoctor:
cell styles).
Code that holds _ is written in the literal form, `+…+`
(Antora finding 7).
</tr> fixedTable 1:
++++
<table class="table">
<thead>
<tr>
<th width="30%">Grant type</th>
<th>User</th>
<th>Details</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>authorization_code</code></td>
<td>Developers building web apps</td>
<td>In the authorization code grant flow, the user is directed to a UAA page where they grant approvals to the
client. After the user approves the requested scopes, they are redirected back to the client app with an
authorization code in the URL parameters. The client app may then exchange the authorization code with UAA to
obtain an access token.</td>
</tr>
<tr>
<td><code>password</code></td>
<td>Developers building native desktop or mobile apps</td>
<td>The name <code>password</code> refers to the resource owner password grant type. The user provides their
username and password to the client app, which may then use them to obtain an <code>access_token</code>.</td>
</tr>
<tr>
<td><code>implicit</code></td>
<td>Developers building a single page web app with no server back end</td>
<td>The user is taken to a page on UAA where they are asked to grant approvals to the client. After doing so, they
are redirected to the <code>redirect_uri</code> with the access token in the URI fragment.</td>
</tr>
<tr>
<td><code>client_credentials</code></td>
<td>Developers when the client app needs to perform actions in UAA on its own behalf</td>
<td>Actions where a <code>client_credentials</code> grant type might be appropriate include creating or destroying
user groups, managing user group membership, or creating or destroying other clients. The
<code>client_credentials</code> grant can be likened to service accounts in legacy app ecosystems.</td>
</tr>
<tr>
<td><code>refresh_token</code></td>
<td>Developers must use the <code>refresh_token</code> grant type with either the <code>authorization_code</code>
or <code>password</code> grant type. <code>refresh_token</code> cannot be used by itself.</td>
<td>Clients typically use the <code>refresh_token</code> to obtain a new access token without the need for the user
to authenticate again. They do this by calling <code>/oauth/token</code> with
<code>grant_type=refresh_token</code>. A refresh token is only issued to clients that have
<code>refresh_token</code> in their list of <code>authorized_grant_types</code>.</td>
</tr>
</tbody>
</table>
++++
Table 2:
[subs=attributes+]
++++
<table class="table">
<thead>
<tr>
<th width="25%">Key</th>
<th>Value</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>allowed providers</code></td>
<td>You can limit which users can use which apps. For example, in a {platform_name} deployment, you may
have set up multiple IDPs. Or, you could be using Facebook and your organization's LDAP system.<br/><br/>
You can limit UAA to only issue an app tokens if the users are from a certain provider. To do this, configure the
app's client with <code>allowed providers="ldap"</code>. The value is a comma-separated string of
<code>Identity Provider.origin</code> values.</td>
</tr>
<tr>
<td><code>created with</code></td>
<td>UAA stores the scope <code>zones.write</code> in this field if the client was created using the
<code>/identity-zones</code> endpoint. UAA uses this field to allow clients to be deleted by the same endpoint.
This is not a configurable field.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>Various tooling in the {platform_name} ecosystem creates clients with generated
<code>Client.client_id</code> values. These tools often store a human-readable name in this field. For more
information, see <a href="#clientid">client.client_id</a>.</td>
</tr>
<tr>
<td><code>approvals_deleted</code></td>
<td>Contains a boolean value if performing an operation on the client resulted in all the client's user approvals
were deleted. For example, changing the <code>client.client_secret</code> value causes UAA to delete all the
approvals. UAA then stores a value of <code>true</code> in this field.</td>
</tr>
<tr>
<td><code>token_salt</code></td>
<td>Tokens, even stateless JWT, can be revoked. Revoked tokens do not pass a UAA token validation when the token is
passed to the <code>/introspect</code> endpoint. UAA revokes a token if the client's secret has changed. There
may be occasions to revoke all tokens for a certain client without having to change the client secret. You can do
this by changing the <code>token_salt</code>. <code>token_salt</code> is an arbitrary string value that is used
to generate a hash.</td>
</tr>
</tbody>
</table>
++++
[subs=attributes+] lets the attribute {platform_name} work inside
table 2’s passthrough block; it is the only addition to the HTML besides the
intent file’s fixes.
Files: native, native-plain, passthrough, passthrough as written, extension.
Native output:


Passthrough output:


Differences seen:
cols. An
AsciiDoc table with no cols (native-plain) splits the columns equally,
33/33/34 and 50/50.h in cols. Passthrough keeps them ordinary cells.allowed providers cell, from
a|; passthrough keeps <br/><br/>. Native-plain holds two paragraphs
too..< specs); passthrough
centers them vertically, as on the published page.organization’s),
as on the published page; the HTML in passthrough keeps them straight
(Antora finding 9).allowed providers="ldap" breaks at its space and “human-readable”
breaks after its hyphen, in both modes. The published page keeps both
whole. The text itself is unchanged.table.table the look of the native table
(R-09 table styles by class).Extension mode. The native AsciiDoc tables with roles added before
them, as in credential-types. No code: the roles get their
meaning from the site’s stylesheet,
hints.css.
Table 1:
[.hinted.col1-key.col2-prose.col3-prose.col1-nowrap%header,cols=".<30%h,.<~,.<~"]
|===
|Grant type |User |Details
|`+authorization_code+`
|Developers building web apps
|In the authorization code grant flow, the user is directed to a UAA page where they grant approvals to the client. After the user approves the requested scopes, they are redirected back to the client app with an authorization code in the URL parameters. The client app may then exchange the authorization code with UAA to obtain an access token.
|`password`
|Developers building native desktop or mobile apps
|The name `password` refers to the resource owner password grant type. The user provides their username and password to the client app, which may then use them to obtain an `+access_token+`.
|`implicit`
|Developers building a single page web app with no server back end
|The user is taken to a page on UAA where they are asked to grant approvals to the client. After doing so, they are redirected to the `+redirect_uri+` with the access token in the URI fragment.
|`+client_credentials+`
|Developers when the client app needs to perform actions in UAA on its own behalf
|Actions where a `+client_credentials+` grant type might be appropriate include creating or destroying user groups, managing user group membership, or creating or destroying other clients. The `+client_credentials+` grant can be likened to service accounts in legacy app ecosystems.
|`+refresh_token+`
|Developers must use the `+refresh_token+` grant type with either the `+authorization_code+` or `password` grant type. `+refresh_token+` cannot be used by itself.
|Clients typically use the `+refresh_token+` to obtain a new access token without the need for the user to authenticate again. They do this by calling `/oauth/token` with `+grant_type=refresh_token+`. A refresh token is only issued to clients that have `+refresh_token+` in their list of `+authorized_grant_types+`.
|===
Table 2:
[.hinted.col1-key.col2-prose.col1-nowrap%header,cols=".<25%h,.<~"]
|===
|Key |Value
|`allowed providers`
a|You can limit which users can use which apps. For example, in a {platform_name} deployment, you may have set up multiple IDPs. Or, you could be using Facebook and your organization's LDAP system.
You can limit UAA to only issue an app tokens if the users are from a certain provider. To do this, configure the app's client with `allowed providers="ldap"`. The value is a comma-separated string of `Identity Provider.origin` values.
|`created with`
|UAA stores the scope `zones.write` in this field if the client was created using the `/identity-zones` endpoint. UAA uses this field to allow clients to be deleted by the same endpoint. This is not a configurable field.
|`name`
|Various tooling in the {platform_name} ecosystem creates clients with generated `+Client.client_id+` values. These tools often store a human-readable name in this field. For more information, see <<clientid,client.client_id>>.
|`+approvals_deleted+`
|Contains a boolean value if performing an operation on the client resulted in all the client's user approvals were deleted. For example, changing the `+client.client_secret+` value causes UAA to delete all the approvals. UAA then stores a value of `true` in this field.
|`+token_salt+`
|Tokens, even stateless JWT, can be revoked. Revoked tokens do not pass a UAA token validation when the token is passed to the `/introspect` endpoint. UAA revokes a token if the client's secret has changed. There may be occasions to revoke all tokens for a certain client without having to change the client secret. You can do this by changing the `+token_salt+`. `+token_salt+` is an arbitrary string value that is used to generate a hash.
|===
.hinted marks the table as carrying hints; .col1-key, .col2-prose and
.col3-prose name the column roles; .col1-nowrap keeps column 1 on one
line, up to a cap. The rest is the native table.
Extension output: the same images as native, byte for byte, for both tables.
Differences seen:
credential-types, Zensical’s table 1 is shorter than
the published one. Each theme’s cell padding, line height and font size
set that; they belong to the template, not to the table
(font size).<br /><br />, and passthrough keeps <br/><br/>. Both forms read as two
paragraphs; the paragraph gap is a little smaller than the blank line.uaa-performanceuaa-performance.html.md.erb in cloudfoundry/docs-running-cf, commit 956acc8From docs-running-cf, the first section only, added after the round: one
table of charts (Instances / Threads / Throughput). It is the example of a
second table style, table-media: no cell borders, a rule under the header,
centered cells, images filling their cells.
CONVENTIONS.md, section “Adding a style”
(Docusaurus,
Zensical,
Starlight,
Antora)What the table asks for (R-02 rich tables):
table-media style, the example of a second style: no cell
borders, a rule under the header row and a thin line between body rows,
no header shading, cells centered both ways, and each image filling the
width of its cell, so the image columns share the width equally. The
class carries the style; a native Markdown table cannot carry a class,
so it gets the standard style
(R-09 table styles by class).###, which
CommonMark does not read as a heading
(R-24 markup cleanup before conversion).
The other changes are recorded as deviations: <strong> in the header
cells and the lightbox are left out
(R-01 content and outline survive).At a glance, from the screenshots below. results.md records no column widths for this page, so none are given; a cell is left empty where the screenshots do not settle it:
| Output | Style | Borders and rules | Header cells | Instance counts | Charts fill their cells |
|---|---|---|---|---|---|
| Published | table (the source’s class) |
every cell | left, bold | left, vertically centered | |
| Docusaurus native | standard | every cell; header row and the row for 2 shaded | centered | left, vertically centered | |
| Docusaurus passthrough and extension | table-media |
rule under the header, lines between rows | centered | centered | yes |
| Zensical native and native-plain | standard | rules between rows, thin outer frame | left | top left | |
| Zensical passthrough and extension | table-media |
rule under the header, lines between rows | centered | centered | yes |
| Starlight native and native-plain | standard | horizontal rules only | left | bottom left | |
| Starlight passthrough and extension | table-media |
rule under the header, lines between rows | centered | centered | yes |
| Antora native and native-plain | standard, three equal columns | every cell | left | top left | |
| Antora passthrough | table-media |
rule under the header, lines between rows | centered | centered | yes |
| Antora extension | table-media |
rule under the header, lines between rows | centered | centered | yes |
All three rows and all six charts, with their alt text and their links, are
present in every output, and the heading keeps its anchor
client-credentials. Passthrough and extension carry the table-media
style; native does not. The spot checks (per-table checks listed in the
intent file and run on every build) pass in every mode of every tool
(progress).

Column 1 is narrow; the two chart columns share the rest. Header cells are on the left, in bold. Every cell has a border. An instance count sits on the left, in the vertical middle of its row.
###<a id='client-credentials'></a> Client credentials grant type
**Endpoint**: /oauth/token?grant_type=client_credentials
<table class="table">
<thead><tr>
<th><strong>Instances</strong></th>
<th><strong>Threads</strong></th>
<th><strong>Throughput</strong></th>
</tr></thead>
<tr>
<td>1</td>
<td><a data-fancybox="gallery" href="images/client-creds-threads-1.png"><img src="images/client-creds-threads-1.png" alt="Threads Level 1"></a></td>
<td><a data-fancybox="gallery" href="images/client-creds-throughput-1.png"><img src="images/client-creds-throughput-1.png" alt="Throughput Level 1"></a></td>
</tr>
<tr>
<td>2</td>
<td><a data-fancybox="gallery" href="images/client-creds-threads-2.png"><img src="images/client-creds-threads-2.png" alt="Threads Level 2"></a></td>
<td><a data-fancybox="gallery" href="images/client-creds-throughput-2.png"><img src="images/client-creds-throughput-2.png" alt="Throughput Level 2"></a></td>
</tr>
<tr>
<td>4</td>
<td><a data-fancybox="gallery" href="images/client-creds-threads-4.png"><img src="images/client-creds-threads-4.png" alt="Threads Level 4"></a></td>
<td><a data-fancybox="gallery" href="images/client-creds-throughput-4.png"><img src="images/client-creds-throughput-4.png" alt="Throughput Level 4"></a></td>
</tr>
</table>
The page loads jQuery and a lightbox script (fancybox) at its top, and
data-fancybox="gallery" on each link opens the chart in that lightbox.
The six charts are copied into this repo
(SOURCES.md).
What the intent file changes:
###<a id=…> as a heading; CommonMark does not, so the Markdown pages add
a space after ###
(R-24 markup cleanup before conversion).
Antora writes the anchor as [[client-credentials]] above the heading.
The anchor client-credentials is kept in every mode.table to table-media in passthrough and
extension; that is the point of the page
(R-09 table styles by class). A native
table keeps the standard style (decided).<strong> in the header cells is dropped: bold header cells are a
convention the template provides
(Template conventions).data-fancybox="gallery".
A chart’s link opens the image itself. Scripts on a page belong to
another concept.Pages are MDX, as in credential-types. A pipe table
has no place for a class, so naming a style takes the extension.
| Instances | Threads | Throughput |
| --- | --- | --- |
| 1 | [](./images/client-creds-threads-1.png) | [](./images/client-creds-throughput-1.png) |
| 2 | [](./images/client-creds-threads-2.png) | [](./images/client-creds-throughput-2.png) |
| 4 | [](./images/client-creds-threads-4.png) | [](./images/client-creds-throughput-4.png) |
<table class="table-media">
<thead><tr>
<th>Instances</th>
<th>Threads</th>
<th>Throughput</th>
</tr></thead>
<tbody>
<tr>
<td>1</td>
<td><a href={require('./images/client-creds-threads-1.png').default}><img src={require('./images/client-creds-threads-1.png').default} alt="Threads Level 1" /></a></td>
<td><a href={require('./images/client-creds-throughput-1.png').default}><img src={require('./images/client-creds-throughput-1.png').default} alt="Throughput Level 1" /></a></td>
</tr>
<tr>
<td>2</td>
<td><a href={require('./images/client-creds-threads-2.png').default}><img src={require('./images/client-creds-threads-2.png').default} alt="Threads Level 2" /></a></td>
<td><a href={require('./images/client-creds-throughput-2.png').default}><img src={require('./images/client-creds-throughput-2.png').default} alt="Throughput Level 2" /></a></td>
</tr>
<tr>
<td>4</td>
<td><a href={require('./images/client-creds-threads-4.png').default}><img src={require('./images/client-creds-threads-4.png').default} alt="Threads Level 4" /></a></td>
<td><a href={require('./images/client-creds-throughput-4.png').default}><img src={require('./images/client-creds-throughput-4.png').default} alt="Throughput Level 4" /></a></td>
</tr>
</tbody>
</table>
Files: native, passthrough, passthrough as written, extension. Docusaurus has no native-plain page: its native page already has no width settings.
Native output:

Passthrough output:

Differences seen:
<img> is closed
and its path goes through require(…), and the rows are wrapped in
<tbody> (the site’s
passthrough rules).credential-types. Instance counts sit on the left, in the vertical
middle of their rows.table-media style. No cell borders, a rule
under the header, a thin line between rows, no header shading and no
shaded rows. Instance counts and charts are centered.Extension mode. The :::list-table directive, read by the remark
plugin plugins/list-table.js,
with the style’s rules in
hints.css.
:::list-table{.table-media header-rows="1"}
- - Instances
- Threads
- Throughput
- - 1
- [](./images/client-creds-threads-1.png)
- [](./images/client-creds-throughput-1.png)
- - 2
- [](./images/client-creds-threads-2.png)
- [](./images/client-creds-throughput-2.png)
- - 4
- [](./images/client-creds-threads-4.png)
- [](./images/client-creds-throughput-4.png)
:::
.table-media is the class shorthand: it names the style.
header-rows="1" makes the first row the header. No widths, row headers
or roles.
Extension output: the same image as passthrough, byte for byte.
Differences seen:
require.Pages are Markdown read by Python-Markdown, as in
credential-types. The theme styles only tables
without a class, so table-media gets its whole look from the site’s
stylesheet, not only the parts that differ
(Adding a style).
| Instances | Threads | Throughput |
| --- | --- | --- |
| 1 | [](images/client-creds-threads-1.png) | [](images/client-creds-throughput-1.png) |
| 2 | [](images/client-creds-threads-2.png) | [](images/client-creds-throughput-2.png) |
| 4 | [](images/client-creds-threads-4.png) | [](images/client-creds-throughput-4.png) |
<table class="table-media">
<thead><tr>
<th>Instances</th>
<th>Threads</th>
<th>Throughput</th>
</tr></thead>
<tr>
<td>1</td>
<td><a href="images/client-creds-threads-1.png"><img src="images/client-creds-threads-1.png" alt="Threads Level 1"></a></td>
<td><a href="images/client-creds-throughput-1.png"><img src="images/client-creds-throughput-1.png" alt="Throughput Level 1"></a></td>
</tr>
<tr>
<td>2</td>
<td><a href="images/client-creds-threads-2.png"><img src="images/client-creds-threads-2.png" alt="Threads Level 2"></a></td>
<td><a href="images/client-creds-throughput-2.png"><img src="images/client-creds-throughput-2.png" alt="Throughput Level 2"></a></td>
</tr>
<tr>
<td>4</td>
<td><a href="images/client-creds-threads-4.png"><img src="images/client-creds-threads-4.png" alt="Threads Level 4"></a></td>
<td><a href="images/client-creds-throughput-4.png"><img src="images/client-creds-throughput-4.png" alt="Throughput Level 4"></a></td>
</tr>
</table>
Files: native, native-plain, passthrough, passthrough as written, extension. The source sets no widths, so native and native-plain are the same file, and their screenshots the same image.
Native output:

Passthrough output:

Differences seen:
table-media style. No frame and no cell
borders, a heavier rule under the header, thin lines between rows, cells
centered both ways.Extension mode. The /// list-table block, read by the
Python-Markdown extension
list_table.py, with the
style’s rules in
hints.css.
/// list-table
header-rows: 1
roles: value
style: table-media
- - Instances
- Threads
- Throughput
- - 1
- [](images/client-creds-threads-1.png)
- [](images/client-creds-throughput-1.png)
- - 2
- [](images/client-creds-threads-2.png)
- [](images/client-creds-throughput-2.png)
- - 4
- [](images/client-creds-threads-4.png)
- [](images/client-creds-throughput-4.png)
///
style becomes the table’s class. header-rows: 1 makes the first row the
header. roles: value names column 1 a value column, as the intent file
lists; the other three tools’ extension pages name no roles.
Extension output: the same image as passthrough, byte for byte.
Differences seen:
Pages are Markdoc, as in credential-types. The
charts sit in public/images/ and are written with an absolute path,
/images/…, so the site serves them as they are: an image that a link
opens at full size, or that sits in an HTML table, goes there instead of
being optimized and renamed (site conventions).
{% table %}
* Instances
* Threads
* Throughput
---
* 1
* [](/images/client-creds-threads-1.png)
* [](/images/client-creds-throughput-1.png)
---
* 2
* [](/images/client-creds-threads-2.png)
* [](/images/client-creds-throughput-2.png)
---
* 4
* [](/images/client-creds-threads-4.png)
* [](/images/client-creds-throughput-4.png)
{% /table %}
<table class="table-media">
<thead><tr>
<th>Instances</th>
<th>Threads</th>
<th>Throughput</th>
</tr></thead>
<tr>
<td>1</td>
<td><a href="/images/client-creds-threads-1.png"><img src="/images/client-creds-threads-1.png" alt="Threads Level 1"></a></td>
<td><a href="/images/client-creds-throughput-1.png"><img src="/images/client-creds-throughput-1.png" alt="Throughput Level 1"></a></td>
</tr>
<tr>
<td>2</td>
<td><a href="/images/client-creds-threads-2.png"><img src="/images/client-creds-threads-2.png" alt="Threads Level 2"></a></td>
<td><a href="/images/client-creds-throughput-2.png"><img src="/images/client-creds-throughput-2.png" alt="Throughput Level 2"></a></td>
</tr>
<tr>
<td>4</td>
<td><a href="/images/client-creds-threads-4.png"><img src="/images/client-creds-threads-4.png" alt="Threads Level 4"></a></td>
<td><a href="/images/client-creds-throughput-4.png"><img src="/images/client-creds-throughput-4.png" alt="Throughput Level 4"></a></td>
</tr>
</table>
Files: native, native-plain, passthrough, passthrough as written, extension. Native-plain is a pipe table; its screenshot is the same image as native’s, byte for byte.
Native output:

Passthrough output:

Differences seen:
table-media style. A heavier rule under the
header, thin lines between rows, cells centered both ways.Extension mode. Markdoc’s own {% table %} tag with the class
shorthand. list-table.mjs
passes the class to the table, with or without hints; the style’s rules
are in hints.css.
{% table .table-media %}
* Instances
* Threads
* Throughput
---
* 1
* [](/images/client-creds-threads-1.png)
* [](/images/client-creds-throughput-1.png)
---
* 2
* [](/images/client-creds-threads-2.png)
* [](/images/client-creds-throughput-2.png)
---
* 4
* [](/images/client-creds-threads-4.png)
* [](/images/client-creds-throughput-4.png)
{% /table %}
.table-media names the style. The rest is the native table.
Extension output: the same image as passthrough, byte for byte.
Differences seen:
Pages are AsciiDoc, as in credential-types; the
whole page is rewritten in every mode, including passthrough. An image
macro with link=self links a chart to itself. Antora publishes module
images to _images/, so the passthrough page links them as
../_images/<file>
(Adding a style).
[%header]
|===
|Instances |Threads |Throughput
|1
|image:client-creds-threads-1.png["Threads Level 1",link=self]
|image:client-creds-throughput-1.png["Throughput Level 1",link=self]
|2
|image:client-creds-threads-2.png["Threads Level 2",link=self]
|image:client-creds-throughput-2.png["Throughput Level 2",link=self]
|4
|image:client-creds-threads-4.png["Threads Level 4",link=self]
|image:client-creds-throughput-4.png["Throughput Level 4",link=self]
|===
%header makes the first row the header row. There is no cols.
++++
<table class="table-media">
<thead><tr>
<th>Instances</th>
<th>Threads</th>
<th>Throughput</th>
</tr></thead>
<tr>
<td>1</td>
<td><a href="../_images/client-creds-threads-1.png"><img src="../_images/client-creds-threads-1.png" alt="Threads Level 1"></a></td>
<td><a href="../_images/client-creds-throughput-1.png"><img src="../_images/client-creds-throughput-1.png" alt="Throughput Level 1"></a></td>
</tr>
<tr>
<td>2</td>
<td><a href="../_images/client-creds-threads-2.png"><img src="../_images/client-creds-threads-2.png" alt="Threads Level 2"></a></td>
<td><a href="../_images/client-creds-throughput-2.png"><img src="../_images/client-creds-throughput-2.png" alt="Throughput Level 2"></a></td>
</tr>
<tr>
<td>4</td>
<td><a href="../_images/client-creds-threads-4.png"><img src="../_images/client-creds-threads-4.png" alt="Threads Level 4"></a></td>
<td><a href="../_images/client-creds-throughput-4.png"><img src="../_images/client-creds-throughput-4.png" alt="Throughput Level 4"></a></td>
</tr>
</table>
++++
Files: native,
native-plain,
passthrough,
passthrough as written,
extension.
Native sets no cols, so native and native-plain are the same file, and
their screenshots the same image.
Native output:

Passthrough output:

Differences seen:
cols gets equal widths
(assign_column_widths).
Column 1 takes as much room as a chart column, so the charts are the
smallest of any output.table-media style. No cell borders, a heavier
rule under the header, thin lines between rows, cells centered both
ways. Its rules replace the standard look, so they set the borders,
padding and alignment themselves.Extension mode. The native AsciiDoc table with the role
.table-media added. No code: the role gets its meaning from the site’s
stylesheet,
hints.css.
[.table-media%header%autowidth]
|===
|Instances |Threads |Throughput
|1
|image:client-creds-threads-1.png["Threads Level 1",link=self]
|image:client-creds-throughput-1.png["Throughput Level 1",link=self]
|2
|image:client-creds-threads-2.png["Threads Level 2",link=self]
|image:client-creds-throughput-2.png["Throughput Level 2",link=self]
|4
|image:client-creds-threads-4.png["Threads Level 4",link=self]
|image:client-creds-throughput-4.png["Throughput Level 4",link=self]
|===
.table-media names the style; Asciidoctor adds it to the table’s
classes. %autowidth leaves out the equal column widths Asciidoctor
writes by default, so the images share the full width.
Extension output:

Differences seen:
style option in Zensical, Markdoc’s class shorthand
in Starlight, a role in Antora
(summary).credential-types. Starlight’s and Antora’s own
table syntax could name the style; a pipe table in Docusaurus and
Zensical cannot, so there the style takes the extension
(R-13 no per-WG extensions). In Antora
the extension is a role and CSS, with no code.table-media the charts fill their cells, so the
grid’s height follows its column widths.table-media grid does not scroll sideways, unlike a wide table in
the standard style (R-02 rich tables):
its rules make it a full-width table, so it shrinks its images to fit
the column (summary).hints.css holds the style’s few
rules; in Docusaurus, Zensical and Starlight they use the theme’s own
color variables. A further style is one more class and a few rules
(R-09 table styles by class)._oss_roles_table_oss_scale_table, it is a
partial, included by the roles page,
https://docs.cloudfoundry.org/concepts/roles.html
(include line in the host page’s source).
The table on the page: Roles and permissions for active orgs_oss_roles_table.html.md.erb in cloudfoundry/docs-cloudfoundry-concepts, commit 97e0d0bThe seventh test page, added on 2026-10-12 as a real wide table. The
partial, from docs-cloudfoundry-concepts, holds one table of 12 columns and
42 rows: Activity, then one column per role, from Admin to Space Supporter.
Each row is an activity. Its cells hold Yes, Org, Space or nothing,
some with a note marker: a superscript number that points to one of nine
notes below the table. The source sets no widths.
What the table asks for (R-02 rich tables):
<sup><strong>N</strong></sup>, numbers 1 to 9: 36 in the table and 9 in
front of the notes.<sup><strong></strong></sup>,
which shows nothing. The intent file lists them as cleanup, and every
converted input leaves the two cells empty
(R-24 markup cleanup before conversion).class="table", the standard style, as every HTML table names its style
(R-09 table styles by class).oss-roles-permissions, is kept where the tool’s
syntax can carry one. The published page uses the same id on a second
table, the one for suspended orgs, so #oss-roles-permissions reaches
only the first. That is listed for cleanup in the
broken links list.roles-table-host, instead of copying all of roles. The host page
also carries the sentence before the table, with its variable,
vars.app_runtime_abbr (R-04 variables everywhere;
R-05 partials and reuse;
SOURCES.md).At a glance, from the screenshots below. Column widths are the measured values in results.md, percent of the table, first body row; results.md has no column-width figures for Docusaurus or the published page, so those cells are empty. Table and box widths are results.md’s, in pixels:
| Output | Column widths | Table in its box | Header cells | Body cells, vertically | Activity cells as row headers | Rule between the columns |
|---|---|---|---|---|---|---|
| Published | 874 in a 720 column, no box | left | centered | no | yes | |
| Docusaurus native and passthrough | 1053 in 703 | centered | centered | no | yes | |
| Docusaurus extension | 1060 in 703 | centered | top | yes (bold, centered) | yes | |
| Zensical native, native-plain and passthrough | 8 × 12 (100 pixels each) | 1202 in 688 | left | top | no | no |
| Zensical extension | 8 × 12 | 1202 in 688 | left | top | yes (bold) | no |
| Starlight native, native-plain and passthrough | 9/7/7/8/9/8/9/6/9/10/8/9 | 1087 in 632 | left | top | no | no |
| Starlight extension | 9/7/7/8/9/8/9/6/9/10/8/9 | 1092 in 632 | left | top | yes (bold) | no |
| Antora native and extension | 11/7/7/8/9/8/9/6/9/10/8/10 | 882 in 792 | left | top | yes (bold) | yes |
| Antora native-plain | 11/7/7/8/9/8/9/6/9/10/8/10 | 882 in 792 | left | top | no | yes |
| Antora passthrough | 11/7/7/8/9/8/9/6/9/10/8/10 | 882 in 792 | left | centered | no | yes |
All 42 rows and 12 columns are present in every output. Yes appears 160
times, the 45 note markers and the nine notes are there with their three
links, no empty marker is left, and the table renders inside its host
page: the spot checks (listed in the intent file and run on every build)
pass in every mode of every tool. The proof of concept’s
summary counts seven pages and 51 checks;
Docusaurus misses two in every mode, as before this page was added, and
both are page descriptions on other pages. At 1280 and 390 pixels the table
scrolls in its own box in every tool and every converted mode, as decided,
and the page does not scroll sideways
(Summary).
How the screenshots are shown. The tables are 4,200 to 5,500 pixels tall, because the activity column wraps on almost every row. Each tool below shows its passthrough output twice: as seen, the box a reader sees, with the rest of the table hidden past its right edge, and the full table, the whole table with nothing cut off. The other modes are shown only where they look clearly different, and linked otherwise. The two-pane page shows any two outputs side by side, full or as seen (its “Full table” button, the default, and “As seen”), and the comparison page shows them all.
No scrollbar shows in the “as seen” images. The scrollbars are overlay scrollbars, which appear only while the reader scrolls. Only Docusaurus cuts a column through its text at the box’s edge; in the other tools the box ends between columns, so nothing in view shows that more follow (Summary); see each tool.

The page draws no box around the table, so this one image is the whole table. It runs past the 720-pixel column into the right margin. Header cells are bold and on the left. Cells sit in the vertical middle of their row, and every cell has a border. The activity column is narrow, so most activities wrap: “Create, delete, and list container-to-container networking policies” takes eight lines. “Admin Read-Only” breaks after its hyphen.
Lines 1–46: the table’s opening, the header row and the first two body rows.
<table id='oss-roles-permissions'>
<thead>
<tr>
<th>Activity</th>
<th>Admin</th>
<th>Admin Read-Only</th>
<th>Global Auditor</th>
<th>Org Manager</th>
<th>Org Auditor</th>
<th>Org Billing Manager</th>
<th>Org User</th>
<th>Space Manager</th>
<th>Space Developer</th>
<th>Space Auditor</th>
<th>Space Supporter</th>
</tr>
</thead>
<tbody>
<tr>
<td>Scope of operation</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Space</td>
<td>Space</td>
<td>Space</td>
<td>Space</td>
</tr>
<tr>
<td>Assign user roles</td>
<td>Yes</td>
<td></td>
<td></td>
<td>Yes</td>
<td></td>
<td></td>
<td></td>
<td>Yes</td>
<td></td>
<td></td>
<td></td>
</tr>
Lines 89–102: the “Create orgs” row.
<tr>
<td>Create orgs</td>
<td>Yes</td>
<td><sup><strong></strong></sup></td>
<td><sup><strong></strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
</tr>
Lines 610–612: the first two notes, after the table.
<sup><strong>1</strong></sup>Not by default, unless feature flag `user_org_creation` is set to `true`.
<sup><strong>2</strong></sup>Admin, admin read-only, and global auditor roles do not need to be added as members of orgs or spaces to view resources.
The whole file: source/_oss_roles_table.html.md.erb.
ERB (Embedded Ruby, <%= … %> tags in a page; see the
glossary) is how today’s pages insert variables and
partials. This partial uses neither; the notes are Markdown, with three
links and two italic titles. The roles page includes it with
<%= partial 'oss_roles_table' %>
(SOURCES.md).
Pages are MDX: Markdown that also accepts JSX, the HTML-like syntax of
React components (see the glossary). As for the scale
table, the partial is an MDX file whose name starts with _; the host page
imports it and uses it as a component. Here the host page also imports the
variables, for its own sentence before the table.
---
title: Roles table host
---
import vars from '@site/vars.json';
import OssRolesTable from './_oss_roles_table.mdx';
Host page for the `_oss_roles_table` partial, standing in for `roles.html.md.erb`, which includes it with an ERB `partial 'oss_roles_table'` call.
The following table describes the default permissions for various {vars.app_runtime_abbr} roles in active orgs.
<OssRolesTable />
The host page is the same in every mode.
Lines 1–4: the header row, the delimiter row and the first two body rows.
| Activity | Admin | Admin Read-Only | Global Auditor | Org Manager | Org Auditor | Org Billing Manager | Org User | Space Manager | Space Developer | Space Auditor | Space Supporter |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Scope of operation | Org | Org | Org | Org | Org | Org | Org | Space | Space | Space | Space |
| Assign user roles | Yes | | | Yes | | | | Yes | | | |
Line 8: the “Create orgs” row.
| Create orgs | Yes | | | <sup><strong>1</strong></sup> | <sup><strong>1</strong></sup> | <sup><strong>1</strong></sup> | <sup><strong>1</strong></sup> | <sup><strong>1</strong></sup> | <sup><strong>1</strong></sup> | <sup><strong>1</strong></sup> | <sup><strong>1</strong></sup> |
Lines 46–48: the first two notes.
<sup><strong>1</strong></sup>Not by default, unless feature flag `user_org_creation` is set to `true`.
<sup><strong>2</strong></sup>Admin, admin read-only, and global auditor roles do not need to be added as members of orgs or spaces to view resources.
The whole file: native/_oss_roles_table.mdx.
The note markers stay inline HTML. A pipe table cannot carry an id, so
oss-roles-permissions is gone.
Lines 1–46: the table’s opening, the header row and the first two body rows.
<table id='oss-roles-permissions' class="table">
<thead>
<tr>
<th>Activity</th>
<th>Admin</th>
<th>Admin Read-Only</th>
<th>Global Auditor</th>
<th>Org Manager</th>
<th>Org Auditor</th>
<th>Org Billing Manager</th>
<th>Org User</th>
<th>Space Manager</th>
<th>Space Developer</th>
<th>Space Auditor</th>
<th>Space Supporter</th>
</tr>
</thead>
<tbody>
<tr>
<td>Scope of operation</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Space</td>
<td>Space</td>
<td>Space</td>
<td>Space</td>
</tr>
<tr>
<td>Assign user roles</td>
<td>Yes</td>
<td></td>
<td></td>
<td>Yes</td>
<td></td>
<td></td>
<td></td>
<td>Yes</td>
<td></td>
<td></td>
<td></td>
</tr>
Lines 89–102: the “Create orgs” row.
<tr>
<td>Create orgs</td>
<td>Yes</td>
<td></td>
<td></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
</tr>
Lines 610–612: the first two notes.
<sup><strong>1</strong></sup>Not by default, unless feature flag `user_org_creation` is set to `true`.
<sup><strong>2</strong></sup>Admin, admin read-only, and global auditor roles do not need to be added as members of orgs or spaces to view resources.
The whole file: passthrough/_oss_roles_table.mdx. Line 1 and lines 92–93 are the only lines that differ from the source.
Files: native, passthrough, passthrough as written, extension; host page. Docusaurus has no native-plain page: its native page already has no width settings.
Passthrough output, as seen:

Passthrough output, full table:

Native looks the same: its screenshots are the passthrough ones, byte for byte (as seen, full table).
Differences seen:
display: block; overflow-x: auto), so a table
wider than the column is drawn at its min-content width: every column as
narrow as its longest word. The table is 1053 by 5518 pixels in a
703-pixel box; at its natural width it would be 2087 by 2237. The
activity column, 106 pixels, wraps on all 42 rows
(Docusaurus finding 10).oss-roles-permissions. Its rows run up to 377
characters (Docusaurus grid).Extension mode. A :::list-table block, read by the remark plugin
added to the site:
plugins/list-table.js,
with hints.css.
For this table the plugin was changed to pass an id, written {#name},
on to the table
(conventions;
Docusaurus finding 10).
Lines 1–37: the directive’s opening, the header row and the first two body rows.
:::list-table{#oss-roles-permissions header-rows="1" stub-columns="1" roles="prose value value value value value value value value value value value"}
- - Activity
- Admin
- Admin Read-Only
- Global Auditor
- Org Manager
- Org Auditor
- Org Billing Manager
- Org User
- Space Manager
- Space Developer
- Space Auditor
- Space Supporter
- - Scope of operation
- Org
- Org
- Org
- Org
- Org
- Org
- Org
- Space
- Space
- Space
- Space
- - Assign user roles
- Yes
-
-
- Yes
-
-
-
- Yes
-
-
-
Lines 74–85: the “Create orgs” row.
- - Create orgs
- Yes
-
-
- <sup><strong>1</strong></sup>
- <sup><strong>1</strong></sup>
- <sup><strong>1</strong></sup>
- <sup><strong>1</strong></sup>
- <sup><strong>1</strong></sup>
- <sup><strong>1</strong></sup>
- <sup><strong>1</strong></sup>
- <sup><strong>1</strong></sup>
Lines 520–522: the first two notes, after the block.
<sup><strong>1</strong></sup>Not by default, unless feature flag `user_org_creation` is set to `true`.
<sup><strong>2</strong></sup>Admin, admin read-only, and global auditor roles do not need to be added as members of orgs or spaces to view resources.
The whole file: extension/_oss_roles_table.mdx.
{#oss-roles-permissions} is the table’s id, header-rows="1" makes the
first row the header, stub-columns="1" makes column 1 row headers, and
roles names column 1 prose and the other eleven value columns. There are
no widths. An empty cell is a bare -. The notes are the native file’s.
Extension output, as seen (the full table is linked):

Differences seen, against passthrough:
Pages are Markdown read by Python-Markdown, which passes HTML blocks through
unchanged (see the glossary). As for the
scale table, the partial lives in partials/<mode>/, outside docs/, and
the host page includes it with the template engine’s include. The host’s
sentence before the table keeps the variable’s ERB form,
<%= vars.app_runtime_abbr %>.
---
title: Roles table host
---
Host page for the `_oss_roles_table` partial, standing in for
`roles.html.md.erb`, which includes it with
an ERB `partial 'oss_roles_table'` call.
The following table describes the default permissions for various <%= vars.app_runtime_abbr %> roles in active orgs.
<% include "native/_oss_roles_table.md" %>
Each mode’s host page includes that mode’s partial.
^N^ markers (excerpt: lines 1–4, 8 and 46–48 of 62)Lines 1–4: the header row, the delimiter row and the first two body rows.
| Activity | Admin | Admin Read-Only | Global Auditor | Org Manager | Org Auditor | Org Billing Manager | Org User | Space Manager | Space Developer | Space Auditor | Space Supporter |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Scope of operation | Org | Org | Org | Org | Org | Org | Org | Space | Space | Space | Space |
| Assign user roles | Yes | | | Yes | | | | Yes | | | |
Line 8: the “Create orgs” row.
| Create orgs | Yes | | | ^1^ | ^1^ | ^1^ | ^1^ | ^1^ | ^1^ | ^1^ | ^1^ |
Lines 46–48: the first two notes.
^1^Not by default, unless feature flag `user_org_creation` is set to `true`.
^2^Admin, admin read-only, and global auditor roles do not need to be added as members of orgs or spaces to view resources.
The whole file: native/_oss_roles_table.md.
^1^ is a superscript, written with the pymdownx.caret extension. The
native-plain file is the same, byte for byte: the source sets no widths,
so there is nothing to leave out.
Lines 1–46: the table’s opening, the header row and the first two body rows.
<table id='oss-roles-permissions' class="table">
<thead>
<tr>
<th>Activity</th>
<th>Admin</th>
<th>Admin Read-Only</th>
<th>Global Auditor</th>
<th>Org Manager</th>
<th>Org Auditor</th>
<th>Org Billing Manager</th>
<th>Org User</th>
<th>Space Manager</th>
<th>Space Developer</th>
<th>Space Auditor</th>
<th>Space Supporter</th>
</tr>
</thead>
<tbody>
<tr>
<td>Scope of operation</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Space</td>
<td>Space</td>
<td>Space</td>
<td>Space</td>
</tr>
<tr>
<td>Assign user roles</td>
<td>Yes</td>
<td></td>
<td></td>
<td>Yes</td>
<td></td>
<td></td>
<td></td>
<td>Yes</td>
<td></td>
<td></td>
<td></td>
</tr>
Lines 89–102: the “Create orgs” row.
<tr>
<td>Create orgs</td>
<td>Yes</td>
<td></td>
<td></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
</tr>
Lines 610–612: the first two notes.
<sup><strong>1</strong></sup>Not by default, unless feature flag `user_org_creation` is set to `true`.
<sup><strong>2</strong></sup>Admin, admin read-only, and global auditor roles do not need to be added as members of orgs or spaces to view resources.
The whole file: passthrough/_oss_roles_table.md. Line 1 and lines 92–93 are the only lines that differ from the source.
Files: native, native-plain, passthrough, passthrough as written, extension; host page.
Passthrough output, as seen:

Passthrough output, full table:

Native and native-plain look like passthrough. Their screenshots are the same as each other, byte for byte, but not as passthrough’s (as seen, full table): in the theme’s wrapper the table sits a little further right, its note markers are not bold, and its frame has no right edge.
Differences seen:
min-width: 5rem.
Twelve of them do not fit the 688-pixel column, so every column is 100
pixels and the table is 1202 pixels wide. The activity column wraps onto
up to eight lines
(Zensical finding 9).table.table itself in passthrough and in the theme’s wrapper in the
other modes (Zensical grid).^N^.
^**N**^ next to text stays literal, because the delimiter follows
CommonMark’s flanking rules (Zensical finding 9).Extension mode. A /// list-table block, read by a Python-Markdown
extension added to the site,
list_table.py, with
hints.css.
Lines 1–44: the block’s opening, the header row and the first two body rows.
/// list-table
header-rows: 1
stub-columns: 1
roles: prose value value value value value value value value value value value
attrs: {id: oss-roles-permissions}
- - Activity
- Admin
- Admin Read-Only
- Global Auditor
- Org Manager
- Org Auditor
- Org Billing Manager
- Org User
- Space Manager
- Space Developer
- Space Auditor
- Space Supporter
- - Scope of operation
- Org
- Org
- Org
- Org
- Org
- Org
- Org
- Space
- Space
- Space
- Space
- - Assign user roles
- Yes
- <!-- -->
- <!-- -->
- Yes
- <!-- -->
- <!-- -->
- <!-- -->
- Yes
- <!-- -->
- <!-- -->
- <!-- -->
Lines 85–96: the “Create orgs” row.
- - Create orgs
- Yes
- <!-- -->
- <!-- -->
- ^1^
- ^1^
- ^1^
- ^1^
- ^1^
- ^1^
- ^1^
- ^1^
Lines 567–569: the first two notes, after the block.
^1^Not by default, unless feature flag `user_org_creation` is set to `true`.
^2^Admin, admin read-only, and global auditor roles do not need to be added as members of orgs or spaces to view resources.
The whole file: extension/_oss_roles_table.md.
The options mean the same as in the Docusaurus directive. attrs sets the
id, but on the div around the table, not on the table (Zensical finding
9). An empty cell is written - <!-- -->. The notes are the native file’s.
Extension output, as seen (the full table is linked):

Differences seen, against native:
Starlight is a documentation theme for the Astro site builder
(depends on astro).
These pages are Markdoc, Markdown with {% %} tags, with HTML allowed (see
the glossary). As for the scale table, the host
includes the partial with Markdoc’s partial tag. Markdoc has no
superscript syntax; inline <sup><strong> works in table-tag cells, pipe
cells and paragraphs
(Starlight finding 10).
---
title: Roles table host
---
Host page for the `_oss_roles_table` partial, standing in for
`roles.html.md.erb`, which includes it with
an ERB `partial 'oss_roles_table'` call.
The following table describes the default permissions for various {% $vars.app_runtime_abbr %} roles in active orgs.
{% partial file="./_oss_roles_table.mdoc" /%}
The host page is the same in every mode.
Lines 1–39: the tag’s opening, the header row and the first two body rows.
{% table #oss-roles-permissions %}
* Activity
* Admin
* Admin Read-Only
* Global Auditor
* Org Manager
* Org Auditor
* Org Billing Manager
* Org User
* Space Manager
* Space Developer
* Space Auditor
* Space Supporter
---
* Scope of operation
* Org
* Org
* Org
* Org
* Org
* Org
* Org
* Space
* Space
* Space
* Space
---
* Assign user roles
* Yes
* <!-- -->
* <!-- -->
* Yes
* <!-- -->
* <!-- -->
* <!-- -->
* Yes
* <!-- -->
* <!-- -->
* <!-- -->
Lines 80–91: the “Create orgs” row.
* Create orgs
* Yes
* <!-- -->
* <!-- -->
* <sup><strong>1</strong></sup>
* <sup><strong>1</strong></sup>
* <sup><strong>1</strong></sup>
* <sup><strong>1</strong></sup>
* <sup><strong>1</strong></sup>
* <sup><strong>1</strong></sup>
* <sup><strong>1</strong></sup>
* <sup><strong>1</strong></sup>
Lines 562–564: the first two notes, after the table.
<sup><strong>1</strong></sup>Not by default, unless feature flag `user_org_creation` is set to `true`.
<sup><strong>2</strong></sup>Admin, admin read-only, and global auditor roles do not need to be added as members of orgs or spaces to view resources.
The whole file: native/_oss_roles_table.mdoc.
#oss-roles-permissions is Markdoc’s id shorthand. Empty cells are
written * <!-- -->. Native-plain is a pipe table, one line per row, and
drops the id.
Lines 1–46: the table’s opening, the header row and the first two body rows.
<table id='oss-roles-permissions' class="table">
<thead>
<tr>
<th>Activity</th>
<th>Admin</th>
<th>Admin Read-Only</th>
<th>Global Auditor</th>
<th>Org Manager</th>
<th>Org Auditor</th>
<th>Org Billing Manager</th>
<th>Org User</th>
<th>Space Manager</th>
<th>Space Developer</th>
<th>Space Auditor</th>
<th>Space Supporter</th>
</tr>
</thead>
<tbody>
<tr>
<td>Scope of operation</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Space</td>
<td>Space</td>
<td>Space</td>
<td>Space</td>
</tr>
<tr>
<td>Assign user roles</td>
<td>Yes</td>
<td></td>
<td></td>
<td>Yes</td>
<td></td>
<td></td>
<td></td>
<td>Yes</td>
<td></td>
<td></td>
<td></td>
</tr>
Lines 89–102: the “Create orgs” row.
<tr>
<td>Create orgs</td>
<td>Yes</td>
<td></td>
<td></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
</tr>
Lines 610–612: the first two notes.
<sup><strong>1</strong></sup>Not by default, unless feature flag `user_org_creation` is set to `true`.
<sup><strong>2</strong></sup>Admin, admin read-only, and global auditor roles do not need to be added as members of orgs or spaces to view resources.
The whole file: passthrough/_oss_roles_table.mdoc. Line 1 and lines 92–93 are the only lines that differ from the source.
Files: native, native-plain, passthrough, passthrough as written, extension; host page.
Passthrough output, as seen:

Passthrough output, full table:

Native and native-plain look the same: all three modes’ screenshots are the same, byte for byte (native as seen, native full table; native-plain as seen, native-plain full table).
Differences seen:
Extension mode. Markdoc’s own {% table %} tag with extra attributes,
declared for the site in
list-table.mjs, with
hints.css. For
this table list-table.mjs was changed to keep the id; it grew from 83 to
85 lines (Starlight finding 10;
Summary).
{% table #oss-roles-permissions header-rows=1 stub-columns=1 roles="prose value value value value value value value value value value value" %}
Line 1 is the only line that differs from the native file. The attributes mean the same as in the Docusaurus directive. The whole file: extension/_oss_roles_table.mdoc.
Extension output, as seen (the full table is linked):

Differences seen, against native:
Antora builds sites from AsciiDoc, a plain-text markup with its own table
syntax (see the glossary). The whole page is
rewritten from Markdown to AsciiDoc in every mode, including passthrough. In
passthrough the HTML sits inside a passthrough block (++++), which
AsciiDoc hands to the browser without reading it. As for the scale table,
the partial lives in modules/ROOT/partials/ and the host page includes
it with include::. The site’s script puts each table in a box that
scrolls, 792 pixels wide on this host page
(Antora finding 11).
= Roles table host
Host page for the `+_oss_roles_table+` partial, standing in for
`roles.html.md.erb`, which includes it with
an ERB `partial 'oss_roles_table'` call.
The following table describes the default permissions for various {app_runtime_abbr} roles in active orgs.
include::partial$_oss_roles_table.adoc[]
The host page is the same in every mode.
Lines 1–29: the table’s opening, the header row and the first two body rows.
[#oss-roles-permissions%header,cols=".<~h,11*.<~"]
|===
|Activity |Admin |Admin Read-Only |Global Auditor |Org Manager |Org Auditor |Org Billing Manager |Org User |Space Manager |Space Developer |Space Auditor |Space Supporter
|Scope of operation
|Org
|Org
|Org
|Org
|Org
|Org
|Org
|Space
|Space
|Space
|Space
|Assign user roles
|Yes
|
|
|Yes
|
|
|
|Yes
|
|
|
Lines 70–81: the “Create orgs” row.
|Create orgs
|Yes
|
|
|^1^
|^1^
|^1^
|^1^
|^1^
|^1^
|^1^
|^1^
Lines 552–554: the first two notes, after the table.
^1^Not by default, unless feature flag `+user_org_creation+` is set to `true`.
^2^Admin, admin read-only, and global auditor roles do not need to be added as members of orgs or spaces to view resources.
The whole file: native/…/_oss_roles_table.adoc.
#oss-roles-permissions sets the id and %header makes the first row the
header row. In cols, .<~h aligns column 1 to the top (.<), sizes it
by its content (~) and styles its cells as headers (h), and 11*.<~
gives the other eleven columns the same spec without h (Asciidoctor:
cols parsing).
The markers are ^N^. Native-plain is the same file with line 1 cut to
[#oss-roles-permissions%header].
Lines 1–47: the block’s opening, the table’s opening, the header row and the first two body rows.
++++
<table id='oss-roles-permissions' class="table">
<thead>
<tr>
<th>Activity</th>
<th>Admin</th>
<th>Admin Read-Only</th>
<th>Global Auditor</th>
<th>Org Manager</th>
<th>Org Auditor</th>
<th>Org Billing Manager</th>
<th>Org User</th>
<th>Space Manager</th>
<th>Space Developer</th>
<th>Space Auditor</th>
<th>Space Supporter</th>
</tr>
</thead>
<tbody>
<tr>
<td>Scope of operation</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Org</td>
<td>Space</td>
<td>Space</td>
<td>Space</td>
<td>Space</td>
</tr>
<tr>
<td>Assign user roles</td>
<td>Yes</td>
<td></td>
<td></td>
<td>Yes</td>
<td></td>
<td></td>
<td></td>
<td>Yes</td>
<td></td>
<td></td>
<td></td>
</tr>
Lines 90–103: the “Create orgs” row.
<tr>
<td>Create orgs</td>
<td>Yes</td>
<td></td>
<td></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
<td><sup><strong>1</strong></sup></td>
</tr>
Lines 612–614: the first two notes, after the block, in AsciiDoc.
^*1*^Not by default, unless feature flag `+user_org_creation+` is set to `true`.
^*2*^Admin, admin read-only, and global auditor roles do not need to be added as members of orgs or spaces to view resources.
The whole file: passthrough/…/_oss_roles_table.adoc.
The partial has no variable, so the block needs no [subs=attributes+],
unlike the scale table’s. The notes are rewritten as AsciiDoc, with bold
markers, ^*N*^, and AsciiDoc links.
Files: native, native-plain, passthrough, passthrough as written, extension; host page.
Passthrough output, as seen:

Passthrough output, full table:

Native output, as seen (the same as extension, byte for byte; the full table is linked):

Native-plain is linked (as seen, full table): it has the native layout without row headers.
Differences seen:
h in cols. Passthrough and native-plain keep them ordinary cells.^N^). Passthrough
keeps <sup><strong> in the table.Extension mode. The native AsciiDoc table with roles (AsciiDoc’s
names for classes, written [.name]) added before it. No code: the roles
get their meaning from the site’s stylesheet,
hints.css.
[#oss-roles-permissions.hinted.col1-prose.col2-value.col3-value.col4-value.col5-value.col6-value.col7-value.col8-value.col9-value.col10-value.col11-value.col12-value%header,cols=".<~h,11*.<~"]
Line 1 is the only line that differs from the native file. .hinted
marks the table as carrying hints, and .col1-prose to .col12-value name
the column roles.
The whole file: extension/…/_oss_roles_table.adoc.
Differences seen:
{% table #… %}) and Antora’s AsciiDoc
([#…]) carry it too. Pipe tables drop it: Docusaurus native, Zensical
native and native-plain, Starlight native-plain. The Docusaurus and
Starlight extensions needed a small code change to keep it; Zensical’s
extension puts it on the div around the table. The published page has
the same id twice, listed for cleanup
(R-24 markup cleanup before conversion;
broken links list).<sup><strong> as
inline HTML in every mode, so the markers stay bold. Zensical and
Antora write them in their own syntax, ^N^, outside passthrough, and
there they are not bold. The two empty markers are removed in every
mode, as the intent file asks.* lines per
row in Starlight; Antora’s AsciiDoc table is one cell per line.
Passthrough is HTML in every tool, 608 lines of it in Antora’s
passthrough block.