ADOC vs TYPST

Two formats for technical writing, different generations

AsciiDoc (2002, Stuart Rackham) and Typst (2023, Typst GmbH) are both modern alternatives to LaTeX for technical writing, but they target different priorities. AsciiDoc is a mature plain-text markup format with 20+ years of adoption in technical documentation, particularly in the open-source software world. Typst is a brand-new (2023) typesetting system designed from scratch as a modern LaTeX alternative with cleaner syntax and faster compilation.

The comparison is interesting because both formats target similar audiences (technical writers, academics, documentation engineers) but make very different tradeoffs.

What AsciiDoc is

AsciiDoc is a lightweight markup language designed to be readable as plain text and convertible to multiple output formats (HTML, PDF, EPUB, DocBook, man pages). Syntax example:

= My Document Title
Author Name <email@example.com>
v1.0, 2026-04-30

== Section Heading

This is a paragraph with *bold* and _italic_ text.

* Bullet point 1
* Bullet point 2
** Nested point

[source,python]
----
def hello():
    print("Hello, world!")
----

[NOTE]
====
This is an admonition box.
====

Key AsciiDoc strengths:

1. Extreme readability: AsciiDoc files are pleasant to read as plain text without rendering. Unlike LaTeX or HTML, the markup doesn't dominate the content.

2. Mature ecosystem: 20+ years of tools, IDE support, build pipelines. Asciidoctor is the modern Ruby-based processor with excellent quality.

3. Multi-format output: same source generates HTML, PDF, EPUB, DocBook, man pages, slides, and more.

4. Used in massive projects: Linux kernel documentation, Spring Framework docs, GitLab docs, Pro Git book, many O'Reilly books — all written in AsciiDoc.

5. Built-in technical features: code blocks with syntax highlighting, admonition boxes (NOTE, TIP, WARNING), cross-references, footnotes, tables, callouts pointing to lines of code, math equations.

6. GitHub native rendering: GitHub renders .adoc files inline like Markdown. Documentation lives next to code.

7. Plain text source: works perfectly with Git version control, diff/merge tools, programmatic generation.

What Typst is

Typst is a typesetting system (like LaTeX) designed for high-quality print output, particularly academic papers, technical books, and complex documents with mathematical content. Syntax example:

#set page(paper: "a4")
#set text(font: "Linux Libertine", size: 11pt)

= Introduction

This is a paragraph with *bold* and _italic_ text.

+ Numbered list item
+ Another item
  - Nested bullet

```python
def hello():
    print("Hello, world!")

#figure( image("plot.svg", width: 80%), caption: [Sample plot.], )

$ E = m c^2 $

Key Typst strengths:

1. **Modern syntax**: cleaner and more intuitive than LaTeX, easier to learn for newcomers

2. **Fast compilation**: incremental compilation in milliseconds vs LaTeX's seconds-to-minutes for large documents

3. **Beautiful default output**: well-designed defaults produce publication-quality PDFs without configuration

4. **Integrated math**: first-class mathematical typesetting with LaTeX-compatible syntax

5. **Programming model**: powerful scripting capabilities for generating content programmatically

6. **Live preview**: web-based editor with real-time preview as you type

7. **Modern tooling**: VS Code extension, language server, package manager — built with modern developer expectations in mind

### When to choose AsciiDoc

1. **Technical documentation for software projects**: AsciiDoc is the de facto standard for serious software documentation outside Markdown. Use it when documentation lives next to code in version control.

2. **Multi-output requirements**: when you need HTML for web docs, PDF for downloads, EPUB for ebooks, all from the same source.

3. **Existing AsciiDoc ecosystem integration**: contributing to projects that use AsciiDoc (Linux kernel, Spring, Asciidoctor itself, many books).

4. **Long-term maintenance**: AsciiDoc has 20+ years of stability. Tools, processors, and skills are widely available. Files written in 2005 still convert correctly today.

5. **GitHub-rendered documentation**: GitHub renders .adoc inline like Markdown. Pages, READMEs, contributing guides all work natively.

6. **Books with code-heavy content**: O'Reilly, Pragmatic Bookshelf, and similar publishers commonly use AsciiDoc for technical books because of its excellent code block features (callouts, syntax highlighting, includes from external files).

7. **Migration from existing markup**: AsciiDoc is similar to but more powerful than Markdown, easier to migrate from than LaTeX.

### When to choose Typst

1. **Academic papers and research**: Typst's typographical quality and math support make it ideal for papers, theses, and academic writing where appearance matters.

2. **Replacing LaTeX**: if you've used LaTeX and found it painful (slow, complex syntax, fragile builds), Typst delivers similar output quality with vastly better developer experience.

3. **Books with complex layouts**: Typst's programmatic capabilities enable sophisticated typography (multi-column layouts, complex tables, custom themes) more easily than other formats.

4. **Fast iteration on complex documents**: Typst compiles in milliseconds even for large documents. LaTeX users accustomed to multi-second builds will find this transformative.

5. **Mathematical content**: Typst's math typesetting is first-class and uses familiar syntax (similar to LaTeX) but compiles much faster.

6. **New projects without legacy constraints**: starting fresh in 2026, Typst offers a better developer experience than AsciiDoc or LaTeX for typesetting-focused work.

7. **Teams with developer backgrounds**: Typst's programming model resonates with developers who appreciate well-designed APIs.

### When to choose neither

- **Simple documentation**: if your needs are basic, **Markdown** is simpler than AsciiDoc and has even broader tool support.
- **Word processor users**: **Microsoft Word** or **Google Docs** suit users who prefer WYSIWYG editing over markup.
- **Quick one-off PDFs**: **direct HTML → PDF** conversion (with KaijuConverter) is faster for simple documents than learning either format.

### Conversion mechanics

**AsciiDoc → PDF**: KaijuConverter uses Asciidoctor PDF (Ruby-based, mature, well-maintained) for conversion. Supports all AsciiDoc features including admonitions, callouts, tables, code blocks with syntax highlighting, math equations (via Asciidoctor Mathematical), and custom themes.

**AsciiDoc → HTML**: Asciidoctor produces clean, semantic HTML5 with optional theme styling. The HTML is suitable for static site generators (Hugo, Jekyll) or direct web publishing.

**Typst → PDF**: KaijuConverter uses the Typst CLI compiler (Rust-based, fast) for conversion. Output PDFs are publication-quality with embedded fonts, proper kerning, and ligatures. Single-pass compilation is typically under 100ms even for hundreds of pages.

**Typst → other formats**: Typst is primarily designed for PDF output. HTML and other format support is community-driven and less mature than AsciiDoc's multi-format ecosystem.

### The future of these formats

AsciiDoc has 20+ years of stability and a deep ecosystem. It will continue to dominate technical documentation in software projects for the foreseeable future. **Choose AsciiDoc if you need stability, multi-format output, and broad tool support**.

Typst is new but gaining momentum quickly. Its developer experience advantages over LaTeX are dramatic, and academic adoption is growing. **Choose Typst if you're starting fresh, need fast compilation, or want LaTeX-quality output without LaTeX's pain points**.

For different use cases, these are complementary tools rather than competitors. Many technical writers use both: AsciiDoc for software documentation that needs HTML/PDF/EPUB outputs, Typst for high-quality PDF documents like papers, books, and reports.