Convert Typst to AsciiDoc

Why Convert Typst to AsciiDoc?

Converting Typst to AsciiDoc enables you to leverage the strengths of both formats. Typst provides an excellent authoring experience with its clean syntax and instant preview, while AsciiDoc offers a battle-tested publishing pipeline through Asciidoctor. By writing in Typst and converting to AsciiDoc, you can publish your content across multiple platforms and output formats.

AsciiDoc has deep integration with software documentation platforms like Antora, Spring REST Docs, and various static site generators. If your organization uses these tools for documentation hosting, converting from Typst gives you access to these established workflows without abandoning Typst's modern authoring experience.

The conversion is particularly useful for teams transitioning between tools or maintaining content in multiple formats. AsciiDoc's plain text nature makes it ideal for version control with Git, and its rendering support on GitHub and GitLab means your documentation is viewable directly in repository browsers without any build step.

Key Benefits of Converting Typst to AsciiDoc:

• Platform Integration: Publish on Antora, GitHub, GitLab, and Spring documentation sites
• Multi-Format Publishing: Generate HTML5, PDF, EPUB3, and DocBook from one source
• Mature Ecosystem: Access Asciidoctor extensions and processing features
• Version Control: Clean text diffs in Git for collaborative documentation
• Modular Composition: Build large documentation sets with include directives
• Admonition Blocks: Use NOTE, TIP, WARNING, and CAUTION callouts
• Industry Standard: AsciiDoc is trusted for enterprise and open-source documentation

Practical Examples

Example 1: Software Installation Guide

Input Typst file (install.typ):

= Installation Guide

== Prerequisites
Before installing, ensure you have:
- Python 3.10 or later
- pip package manager
- Git version control

== Quick Start
```bash
pip install myproject
myproject init
```

#table(
  columns: 2,
  [Platform], [Command],
  [Linux], [`apt install myproject`],
  [macOS], [`brew install myproject`],
)

Output AsciiDoc file (install.adoc):

= Installation Guide

== Prerequisites
Before installing, ensure you have:
* Python 3.10 or later
* pip package manager
* Git version control

== Quick Start
[source,bash]
----
pip install myproject
myproject init
----

[cols="1,1"]
|===
|Platform |Command
|Linux |`apt install myproject`
|macOS |`brew install myproject`
|===

Example 2: API Documentation with Variables

Input Typst file (api.typ):

#let api_version = "v3"
#let base_url = "https://api.example.com"

= API Reference (#api_version)

== Base URL
All endpoints use: `#base_url/#api_version`

== Endpoints
=== Get Users
*Method:* `GET`
*Path:* `/#api_version/users`

Returns a _paginated_ list of users.

Output AsciiDoc file (api.adoc):

= API Reference (v3)

== Base URL
All endpoints use: `https://api.example.com/v3`

== Endpoints
=== Get Users
*Method:* `GET`
*Path:* `/v3/users`

Returns a _paginated_ list of users.

Example 3: Document with Figures and Cross-References

Input Typst file (report.typ):

= Architecture Overview

#figure(
  image("diagram.png", width: 80%),
  caption: [System architecture diagram],
) 

As shown in @arch-diagram, the system
consists of three microservices.

== Performance
The response time is $ O(log n) $ for
search operations.

Output AsciiDoc file (report.adoc):

= Architecture Overview

[[arch-diagram]]
.System architecture diagram
image::diagram.png[width=80%]

As shown in <<arch-diagram>>, the system
consists of three microservices.

== Performance
The response time is O(log n) for
search operations.

Frequently Asked Questions (FAQ)

Q: What is the difference between ADOC and AsciiDoc?

A: They refer to the same format. AsciiDoc is the markup language name, while .adoc is the standard file extension. Both terms are used interchangeably in practice. Asciidoctor is the primary processor for both.

Q: How are Typst variables and scripting converted?

A: Typst scripting features like #let variables and #set rules are evaluated during conversion. The resolved values appear as static text in the AsciiDoc output. AsciiDoc has its own attribute system (:attribute:) for simple variable substitution, but it does not support the full programming capabilities of Typst.

Q: Are Typst math expressions supported in AsciiDoc?

A: Typst math expressions are converted to their textual representation. For proper math rendering in AsciiDoc output, you can use the STEM (Science, Technology, Engineering, Math) blocks with the :stem: document attribute and asciidoctor-mathematical extension.

Q: Can I render the AsciiDoc file on GitHub?

A: Yes. GitHub natively renders .adoc files in repositories, showing formatted headings, tables, code blocks, and other markup elements. This makes AsciiDoc an excellent choice for project documentation stored alongside code.

Q: How are Typst cross-references converted?

A: Typst label references using @label syntax are converted to AsciiDoc cross-references using <<label>> syntax. Figure and section labels are preserved, enabling navigation within the converted document.

Q: What happens to Typst #import statements?

A: Typst import statements pull in external packages and modules. During conversion, the imported functionality is resolved and the resulting content appears in the AsciiDoc output. Package-specific formatting may need manual adjustment.

Q: Can I convert AsciiDoc back to Typst?

A: While tools like Pandoc can convert AsciiDoc to various formats, direct AsciiDoc-to-Typst conversion tools are limited given Typst's relative newness. It is recommended to keep your original Typst source files for future editing.

Q: How does the converter handle Typst page layout settings?

A: Typst page layout settings like #set page() and #set text() control visual presentation, which does not have a direct equivalent in AsciiDoc markup. These settings are not transferred, as AsciiDoc presentation is controlled by the output processor (Asciidoctor) and its themes or stylesheets.