Convert Typst to ADOC

Why Convert Typst to ADOC?

Converting Typst documents to AsciiDoc bridges the gap between modern typesetting and established technical documentation workflows. While Typst excels at producing beautifully typeset PDFs with its intuitive markup, AsciiDoc is the preferred format for software documentation platforms like Antora, GitHub, and GitLab, where technical content needs to be rendered as web pages.

AsciiDoc offers a mature ecosystem for documentation publishing that complements Typst's strengths in typesetting. By converting your Typst documents to ADOC, you gain access to Asciidoctor's multi-format output pipeline, enabling you to produce HTML documentation sites, PDF manuals, EPUB ebooks, and DocBook XML from a single source. This is particularly valuable for organizations that maintain both printed and online documentation.

The conversion preserves headings, text formatting, code blocks, and document structure from your Typst source. While Typst's scripting features (#let, #set) and math expressions may need manual refinement in AsciiDoc, the core textual content transfers cleanly, providing a solid foundation for further documentation work.

Key Benefits of Converting Typst to ADOC:

• Documentation Platforms: Publish on Antora, GitHub, and GitLab documentation sites
• Multi-Format Output: Generate HTML, PDF, EPUB, and DocBook from AsciiDoc
• Version Control: AsciiDoc files produce clean, meaningful diffs in Git
• Modular Documentation: Use include directives to compose larger documents
• Mature Tooling: Leverage Asciidoctor's extensive processing pipeline
• Cross-References: Add navigation links, footnotes, and table of contents
• Industry Adoption: AsciiDoc is widely used in enterprise documentation

Practical Examples

Example 1: Technical Document with Headings and Formatting

Input Typst file (document.typ):

= API Reference Guide

== Authentication
All API calls require *Bearer token* authentication.
Use the `Authorization` header with your token.

=== Token Format
The token is a _JSON Web Token_ (JWT) containing:
- User ID
- Expiration timestamp
- Access scope

#set text(font: "Inter")
`GET /api/v1/users`

Output ADOC file (document.adoc):

= API Reference Guide

== Authentication
All API calls require *Bearer token* authentication.
Use the `Authorization` header with your token.

=== Token Format
The token is a _JSON Web Token_ (JWT) containing:
* User ID
* Expiration timestamp
* Access scope

`GET /api/v1/users`

Example 2: Document with Tables and Code

Input Typst file (specs.typ):

= System Requirements

#table(
  columns: 3,
  [Component], [Minimum], [Recommended],
  [CPU], [2 cores], [4 cores],
  [RAM], [4 GB], [8 GB],
  [Storage], [20 GB], [50 GB],
)

== Installation
```bash
curl -sSL https://install.example.com | sh
```

Output ADOC file (specs.adoc):

= System Requirements

[cols="1,1,1"]
|===
|Component |Minimum |Recommended
|CPU |2 cores |4 cores
|RAM |4 GB |8 GB
|Storage |20 GB |50 GB
|===

== Installation
[source,bash]
----
curl -sSL https://install.example.com | sh
----

Example 3: Academic Content with Math and References

Input Typst file (paper.typ):

= Quadratic Formula

The solutions to $ a x^2 + b x + c = 0 $ are:

$ x = (-b plus.minus sqrt(b^2 - 4 a c)) / (2 a) $

#figure(
  caption: [Parabola plot],
  image("parabola.png")
)

See @fig:parabola for the graph.

Output ADOC file (paper.adoc):

= Quadratic Formula

The solutions to ax^2 + bx + c = 0 are:

x = (-b +/- sqrt(b^2 - 4ac)) / (2a)

.Parabola plot
image::parabola.png[]

See <<fig:parabola>> for the graph.

Frequently Asked Questions (FAQ)

Q: How are Typst headings converted to AsciiDoc?

A: Typst headings using the = syntax map directly to AsciiDoc headings with the same = syntax. For example, = Title becomes a level-1 heading and == Section becomes a level-2 heading in AsciiDoc, preserving the document hierarchy.

Q: Are Typst tables preserved in the ADOC output?

A: Yes. Typst tables defined with #table() are converted to AsciiDoc table syntax using pipe-delimited rows enclosed in |=== delimiters. Column counts and cell content are preserved, though complex table styling may need manual adjustment.

Q: What happens to Typst math expressions?

A: Typst math expressions enclosed in $ delimiters are converted to their textual representation in AsciiDoc. For advanced math rendering, you can use the asciidoctor-mathematical extension or STEM blocks in AsciiDoc to render equations in the final output.

Q: How are Typst scripting features handled?

A: Typst scripting constructs like #let, #set, and #import are evaluated during conversion. Variable values are resolved to their final text content in the AsciiDoc output. The scripting logic itself does not transfer, as AsciiDoc is a static markup language.

Q: Can I use the converted ADOC file with Asciidoctor?

A: Yes. The output is valid AsciiDoc that can be processed immediately by Asciidoctor to generate HTML, PDF, or other formats. You can also include the file in larger documentation projects using the include::[] directive.

Q: Are Typst code blocks preserved?

A: Yes. Typst code blocks using backtick syntax are converted to AsciiDoc source blocks with proper delimiters. Language annotations are preserved where specified, enabling syntax highlighting in the AsciiDoc output.

Q: How are Typst figures and images handled?

A: Typst figures created with #figure() are converted to AsciiDoc image macros with captions. The image file references are preserved, so you need to ensure the image files are available alongside the converted ADOC file.

Q: What is the maximum Typst file size supported?

A: Our converter handles Typst files of typical sizes used in documentation and academic writing. Very large documents with extensive scripting or numerous imported packages may take longer to process. For best results, ensure your .typ file compiles successfully with the Typst compiler before converting.