Convert Typst to DocBook

Why Convert Typst to DocBook?

Converting Typst to DocBook bridges the gap between modern document authoring and enterprise technical publishing workflows. DocBook XML is the industry standard for structured technical documentation, used by organizations like O'Reilly Media, Red Hat, and the Linux Documentation Project. By converting your Typst documents to DocBook, you integrate with these established publishing pipelines.

DocBook's semantic XML structure provides rich metadata about your document's content that goes beyond visual formatting. Each element carries meaning -- a <warning> is different from a <note>, and a <function> is different from a <parameter>. This semantic richness enables sophisticated processing, searching, and indexing that is not possible with plain text markup formats.

The conversion is particularly valuable for technical writers who author content quickly in Typst's intuitive syntax but need to deliver in DocBook for their organization's documentation system. DocBook's XSLT-based processing can then generate multiple output formats from the single XML source, including HTML documentation sites, PDF manuals, EPUB ebooks, and Unix man pages.

Key Benefits of Converting Typst to DocBook:

• Enterprise Publishing: Integrate with DocBook-based documentation systems
• Semantic Markup: Rich XML elements capture document meaning
• Multi-Format Output: Generate HTML, PDF, EPUB, and man pages via XSLT
• Schema Validation: Ensure document structure correctness
• Industry Standard: Used by major technical publishers
• Content Reuse: Modular XML allows content sharing across documents
• Longevity: XML-based format ensures long-term accessibility

Practical Examples

Example 1: Technical Article

Input Typst file (article.typ):

= Getting Started with Docker

== Prerequisites
Before installing Docker, ensure you have:
- A 64-bit operating system
- Linux kernel 3.10 or higher

== Installation
Run the following command:
```bash
curl -fsSL https://get.docker.com | sh
```

Verify the installation with `docker --version`.

Output DocBook file (article.xml):

<article xmlns="http://docbook.org/ns/docbook"
         version="5.1">
  <title>Getting Started with Docker</title>
  <section>
    <title>Prerequisites</title>
    <para>Before installing Docker:</para>
    <itemizedlist>
      <listitem><para>A 64-bit OS</para></listitem>
      <listitem><para>Kernel 3.10+</para></listitem>
    </itemizedlist>
  </section>
  <section>
    <title>Installation</title>
    <programlisting language="bash">
curl -fsSL https://get.docker.com | sh
    </programlisting>
  </section>
</article>

Example 2: Book Chapter with Table

Input Typst file (chapter.typ):

= Chapter 3: Configuration

== Environment Variables

#table(
  columns: 3,
  [Variable], [Default], [Description],
  [PORT], [8080], [Server listen port],
  [LOG_LEVEL], [info], [Logging verbosity],
  [DB_HOST], [localhost], [Database hostname],
)

See the _configuration guide_ for more details.

Output DocBook file (chapter.xml):

<chapter>
  <title>Chapter 3: Configuration</title>
  <section>
    <title>Environment Variables</title>
    <table>
      <title>Environment Variables</title>
      <thead><tr>
        <th>Variable</th>
        <th>Default</th>
        <th>Description</th>
      </tr></thead>
      <tbody>
        <tr><td>PORT</td>
          <td>8080</td>
          <td>Server listen port</td></tr>
        ...
      </tbody>
    </table>
  </section>
</chapter>

Example 3: API Reference Documentation

Input Typst file (api-ref.typ):

= API Reference

== Authentication
Use *Bearer tokens* for all API requests.

=== Request Headers
```
Authorization: Bearer <token>
Content-Type: application/json
```

=== Response Codes
- *200* -- Success
- *401* -- Unauthorized
- *404* -- Not Found

Output DocBook file (api-ref.xml):

<article>
  <title>API Reference</title>
  <section>
    <title>Authentication</title>
    <para>Use <emphasis role="bold">
    Bearer tokens</emphasis> for all
    API requests.</para>
    <section>
      <title>Request Headers</title>
      <programlisting>
Authorization: Bearer &lt;token&gt;
Content-Type: application/json
      </programlisting>
    </section>
    <section>
      <title>Response Codes</title>
      <itemizedlist>...</itemizedlist>
    </section>
  </section>
</article>

Frequently Asked Questions (FAQ)

Q: What version of DocBook is generated?

A: The converter produces DocBook 5.1 XML, which is the current OASIS standard. DocBook 5 uses XML namespaces and RELAX NG schema validation. The output is well-formed XML that can be validated against the official DocBook schema.

Q: How are Typst headings mapped to DocBook elements?

A: Typst headings are mapped to DocBook section hierarchy. Level-1 headings (=) become <article> or <chapter> titles, level-2 headings (==) become <section> titles, and level-3 headings (===) become nested <section> titles. The nesting structure is maintained in the XML output.

Q: Can I process the DocBook output with XSLT?

A: Yes. The output is standard DocBook XML compatible with the official DocBook XSL Stylesheets. You can use Saxon, xsltproc, or other XSLT processors to transform the DocBook into HTML, PDF (via XSL-FO), EPUB, or man pages.

Q: How are Typst code blocks converted?

A: Typst code blocks become DocBook <programlisting> elements with optional language attributes. Inline code uses <code> or <literal> elements. This preserves syntax information for downstream processing and syntax highlighting.

Q: Are Typst tables supported in DocBook?

A: Yes. Typst tables are converted to DocBook <table> or <informaltable> elements following the HTML table model or CALS table model. Rows, columns, headers, and cell content are preserved in the XML structure.

Q: What happens to Typst math expressions?

A: Typst math is converted to DocBook <equation> or <inlineequation> elements. Where possible, MathML markup is used for the mathematical content. Simple expressions may be represented as text within <mathphrase> elements.

Q: Can I use the DocBook output with O'Reilly's publishing system?

A: Yes. O'Reilly Media uses DocBook as one of their accepted manuscript formats. The converted DocBook XML can be submitted to their publishing pipeline. You may need to adjust the document structure to match O'Reilly's specific DTD requirements.

Q: How are Typst figures converted?

A: Typst figures become DocBook <figure> elements containing <mediaobject> and <imageobject> children. Figure captions are converted to <title> elements within the figure. Image file references are preserved as fileref attributes.