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, inline image: macros, attribute references {name}, and cross references <<id,text>>. The visible text, an image's alt text included, stays translatable; the markup never leaks into it. A block macro such as image:: or include:: stays in the skeleton, and a block image's alt text becomes a block of its own. An alt text an edit or a translation changed is written for the macro's attribute list: in double quotes when it holds a comma or an =, with a quote inside the quotes written \" and, in an inline image: macro, a ] written \]. An alt text holding a line break is refused, since it would end the macro.

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, and only changed values are spliced back in.

IDasciidoc

SourceBuilt-in

Extensions.adoc, .asciidoc, .adfm, .asc

MIME Typestext/asciidoc

CapabilitiesRead + Write

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 it live

Configuration

Loading form…

Configuration output

vs defaultsno changes

apiVersion: neokapi/v1
kind: AsciidocFormatConfig
metadata:
  name: asciidoc
spec:
  # (default configuration)

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, inline images, attribute references, cross references) is protected as inline-code runs and must not be translated.

• Block macros (image::, include::, …) are skeleton; the alt text of a block image is extracted as its own block.

• A changed image alt text is quoted and escaped for the macro's attribute list, so a comma in a translation never splits it into attributes.

• 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