adoctra writes Word documents into a template. The template, not the converter, decides how things look: every element gets a named style that the template defines.

adoctra --to docx report.adoc                           # built-in template
adoctra --to docx -a docx-template=corp.dotx report.adoc # your template
adoctra --to docx -d book manual.adoc                   # built-in book template

Built-in templates

Without a template, one is chosen by doctype:

article

title, subtitle, authors and the revision line at the start of the body, then the document.

book

a cover page in its own section; the document follows with page numbers from 1, parts and chapters start a new page, and the page header shows the current chapter.

Their look follows the HTML stylesheet (Noto Serif, Open Sans, Asciidoctor’s colors). To start your own template from them, export them as Word files:

cargo run -p adoctra-docx --example export_templates -- templates/

Your own template

Pass a .docx or .dotx with -a docx-template=PATH (or book/article for a built-in one). The path is read relative to the document’s base directory, within the safe-mode jail. An unreadable or invalid template gives a warning and the built-in one is used.

The template stays an opaque package: theme, fonts, headers and footers, custom XML and all other parts are copied as they are. Only the body, the markers and the styles change.

Markers

Markers are Word content controls tagged adoctra:<name>:

adoctra:body

where the document body goes. Without it, the template’s sample paragraphs are removed and the document is inserted at the end.

adoctra:title, adoctra:subtitle, adoctra:author, adoctra:email, adoctra:revnumber, adoctra:revdate, adoctra:revremark, adoctra:revision

cover fields, also inside headers and footers. A field without a value removes its control.

adoctra:chapter

in a book’s page header: the current part or chapter.

Sample paragraphs inside adoctra:body are fine — keep them as a style showcase for the designer.

Styles

Styles are looked up by name, then by alias, then by id, ignoring ASCII case. A missing built-in Word style (heading 4, toc 3, …) is added with Word’s defaults; a missing custom style gives a warning and the element keeps the base formatting.

Paragraph styles

Normal, Title, Subtitle, Document Details, Part Title, Heading 1–6, Appendix Heading 1–6, Floating Title 1–6, Lead, Abstract, List Paragraph, Term, Description, Question, Answer, Code, Literal, Horizontal Rule, Block Title, Caption, Quote, Quote Attribution, Verse, Verse Attribution, Sidebar Title, Admonition Label, Footnote Text, TOC Heading, TOC 1–6.

Character styles

Strong, Emphasis, Monospace, Mark, Hyperlink, Xref, Keyboard, Button, Menu, Callout, Line Number, Footnote Reference, and the optional Chapter Title for the running chapter header.

Table styles

Table, Code Table, Literal Table, Admonition Table, Admonition Note|Tip|Important|Warning|Caution Table, Example Table, Sidebar Table, Quote Table, Verse Table.

Roles become styles too: a block role that matches a template style (by name, alias or id) uses it, and a phrase role (text) uses a character style. A role without a matching style changes nothing.

What is rendered

Sections and numbering, paragraphs and inline formatting, links and cross references (as Word hyperlinks and bookmarks), all list types and callouts, tables including AsciiDoc cells, block frames, images (including SVG), Word footnotes, the table of contents, index fields, highlighted source listings with line numbers, page orientation changes (page-layout on a page break, %rotate on a table) and document properties (title, authors, description, keywords, dates).

Output is deterministic: the same input gives the same bytes.