Build and export

Native builds

archledger build --format markdown
archledger build --format asciidoc

[build].default_output_dir is relative to the directory containing archledger.toml or .archledger.toml. New projects default to build/ under the workspace root, and projects may override this path.

Converter-backed exports

  • Markdown source uses pandoc for HTML, DOCX, RST, Textile, PDF, and AsciiDoc.

  • AsciiDoc source uses asciidoctor for HTML.

  • AsciiDoc source uses asciidoctor-pdf for PDF.

  • AsciiDoc source uses Asciidoctor DocBook plus pandoc for DOCX, Markdown, RST, and Textile.

These export paths are supported when the external tools are installed and the corresponding integration checks pass. Native Markdown and AsciiDoc assembly remain the lowest-friction path because they do not depend on external converters.

Diagram records

Diagram records are plain text by default. Dense architecture diagrams should use diagram_type = "text" or "unicode" so they remain readable in source, Git diffs, terminal output, and native Markdown/AsciiDoc builds. Mermaid remains available for compact sequence or flow diagrams, but it is not the default.

Supported diagram_type values: text (default), ascii, unicode, svgbob, mermaid.

Native builds preserve text diagram blocks as readable fenced code blocks or literal blocks — no external tool is required.

Optional materialization for converter-backed outputs can be enabled with:

[diagrams]
enabled = true
renderer = "mermaid-cli"
default_type = "text"
output_dir = "diagrams"
image_format = "svg"
kroki_url = ""

Notes:

  • renderer = "pass-through" keeps diagram blocks unchanged (default).

  • renderer = "mermaid-cli" requires mmdc on PATH and only processes Mermaid blocks.

  • renderer = "asciidoctor-diagram" is intended for direct Asciidoctor flows.

  • Kroki is not currently supported by config validation.

Source migration

source convert migrates Markdown-source projects to AsciiDoc-source projects. Write mode is strict by default and requires pandoc:

archledger source convert --to asciidoc --apply

For an explicit temporary mixed-body migration:

archledger source convert --to asciidoc --apply --allow-mixed-body-format