AsciiDoc format (.adoc, .asciidoc, .adfm, .asc)
The AsciiDoc format reads .adoc / .asciidoc documents — the
lightweight prose markup language used widely for technical documentation.
The reader extracts the logical, translatable content and preserves
everything else byte-for-byte.
Headings (the document title = and section headings ==…======),
paragraphs, list items (ordered and unordered, with nesting), block titles
(.Title), admonition text (NOTE:, TIP:, WARNING:, …), and table cells
each become blocks carrying a normalized structural role (heading, paragraph,
list-item, caption, table-cell) — tables are reconstructed as table / table-row
groups so cell geometry stays intact. Inline markup is linearized into
canonical inline-code runs: *bold*, _italic_, `mono`, ^super^ /
~sub~, URL and link: macros, attribute references {name}, and cross
references <<id,text>>. The visible text stays translatable; the markup never
leaks into it.
Verbatim blocks (listing/literal/source/passthrough), comments, attribute entries, and the document header are non-translatable and round-trip as skeleton — an untouched document is reproduced byte-for-byte; only changed values are spliced back in.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
extractBlockTitles | boolean | true | Emit AsciiDoc block titles (`.Title`) as translatable blocks. When false they are preserved verbatim as skeleton. |
extractTableCells | boolean | true | Emit `|===` table cells as translatable blocks grouped into table / table-row groups. When false the table is preserved verbatim. |
Configure these parameters interactively and copy the YAML on the Format Reference.
Examples
Keep block titles untranslated
Treat .Title lines as skeleton rather than translatable captions.
extractBlockTitles: false
Preserve tables verbatim
Do not extract table cells; round-trip the whole table unchanged.
extractTableCells: false
Processing notes
Headings carry their level on Properties["level"] (the count of
=), so the structure survives translation and cross-format export.Tables are reconstructed as table / table-row groups; header cells carry the table-header role, body cells the table-cell role.
Inline markup (bold/italic/mono/super/sub, links, attribute references, cross references) is protected as inline-code runs and must not be translated.
Output is byte-faithful: an unchanged document round-trips exactly; only modified block values are rewritten. Verbatim blocks, comments, attribute entries, and the document header are preserved as skeleton.
← Back to the Format Reference