Convert Typst to JSON

Why Convert Typst to JSON?

Converting Typst documents to JSON transforms modern typeset content into a structured data format that integrates seamlessly with contemporary software systems. JSON is the standard data interchange format for web APIs, databases, and applications. By converting your Typst documents to JSON, you make their content, metadata, and structure programmatically accessible to any software system, from web applications to machine learning pipelines.

Typst's clean markup and scripting language make it an excellent source for structured data extraction. Unlike LaTeX with its complex macro system, Typst's consistent syntax allows for more predictable parsing of document structure. Headings defined with = signs, content blocks, tables created with #table(), and metadata set with #set rules can all be mapped cleanly to JSON objects and arrays, producing well-organized output suitable for downstream processing.

For developers building content management systems, educational platforms, or document processing pipelines, JSON output from Typst provides the ideal data format. A learning management system can import course materials as JSON objects, an academic portfolio website can render publication data from JSON, and a search engine can index document content stored in JSON. The hierarchical structure of JSON maps naturally to Typst's document organization, preserving relationships between sections, figures, tables, and references.

As Typst grows in adoption for academic and technical writing, the need to integrate Typst content with existing data infrastructure becomes increasingly important. Converting to JSON allows researchers to feed their documents into citation analysis tools, text mining frameworks, and automated publishing workflows that expect structured input rather than typesetting markup.

Key Benefits of Converting Typst to JSON:

• API Integration: Feed document data directly into REST APIs and web services
• Database Storage: Store structured document content in MongoDB, PostgreSQL, or Elasticsearch
• Programmatic Access: Parse and process document structure in any programming language
• Text Mining: Enable NLP and computational analysis of academic content
• Web Applications: Display document data in React, Vue, or Angular frontends
• Metadata Indexing: Power search and discovery systems for document content
• Schema Validation: Verify document structure against JSON Schema definitions

Practical Examples

Example 1: Research Document for Academic Database

Input Typst file (paper.typ):

#set document(
  title: "Neural Network Optimization",
  author: "Dr. Sarah Chen",
)

= Neural Network Optimization
== Abstract
We propose a novel approach to
*gradient descent* optimization using
_adaptive learning rates_.

== Methods
$ L(theta) = -1/n sum_(i=1)^n
  y_i log(hat(y)_i) $

#table(
  columns: 3,
  [Model], [Accuracy], [Speed],
  [ResNet], [95.2%], [1.2s],
  [ViT], [97.1%], [2.8s],
)

Output JSON file (paper.json):

{
  "metadata": {
    "title": "Neural Network Optimization",
    "author": "Dr. Sarah Chen"
  },
  "sections": [
    {
      "title": "Neural Network Optimization",
      "subsections": [
        {
          "title": "Abstract",
          "content": "We propose a novel approach..."
        },
        {
          "title": "Methods",
          "equations": ["L(theta) = -1/n sum..."],
          "tables": [{
            "columns": ["Model", "Accuracy", "Speed"],
            "rows": [
              ["ResNet", "95.2%", "1.2s"],
              ["ViT", "97.1%", "2.8s"]
            ]
          }]
        }
      ]
    }
  ]
}

Example 2: Course Notes for Learning Platform

Input Typst file (notes.typ):

= Module 5: Linear Algebra
== Vector Spaces
A *vector space* $V$ over a field $F$
is a set with two operations.

=== Properties
- Closure under addition
- Closure under scalar multiplication
- Existence of zero vector
- Existence of additive inverses

== Eigenvalues
#let eigen = $lambda$
The eigenvalue equation:
$ A v = eigen v $

Output JSON file (notes.json):

{
  "module": {
    "title": "Module 5: Linear Algebra",
    "sections": [{
      "title": "Vector Spaces",
      "content": "A vector space V over...",
      "subsections": [{
        "title": "Properties",
        "items": [
          "Closure under addition",
          "Closure under scalar multiplication",
          "Existence of zero vector",
          "Existence of additive inverses"
        ]
      }]
    }, {
      "title": "Eigenvalues",
      "equations": ["A v = lambda v"]
    }]
  }
}

Example 3: Technical Report for API Integration

Input Typst file (report.typ):

#set document(
  title: "Q4 Performance Report",
  author: "Analytics Team",
)

= Quarterly Performance Report
== Key Metrics
#table(
  columns: 3,
  [Metric], [Q3], [Q4],
  [Revenue], [$2.1M], [$2.8M],
  [Users], [45K], [62K],
  [Uptime], [99.7%], [99.9%],
)

== Summary
Growth of *33%* in revenue and
_38%_ in active users.

Output JSON file (report.json):

{
  "metadata": {
    "title": "Q4 Performance Report",
    "author": "Analytics Team"
  },
  "sections": [{
    "title": "Key Metrics",
    "tables": [{
      "columns": ["Metric", "Q3", "Q4"],
      "rows": [
        ["Revenue", "$2.1M", "$2.8M"],
        ["Users", "45K", "62K"],
        ["Uptime", "99.7%", "99.9%"]
      ]
    }]
  }, {
    "title": "Summary",
    "content": "Growth of 33% in revenue..."
  }]
}

Frequently Asked Questions (FAQ)

Q: What parts of a Typst document are captured in JSON?

A: The JSON output captures document metadata (title, author, date), the full heading hierarchy with content, lists and enumerated items, tables created with #table(), and mathematical expressions. Typst's #set rules and styling information are preserved as metadata properties. The clean structure of Typst markup allows for more predictable JSON output compared to other typesetting formats.

Q: How are Typst math equations stored in JSON?

A: Typst math expressions (written between $ signs) are stored as string values in the JSON output. For example, $ E = m c^2 $ becomes a JSON string that can be rendered by MathJax or KaTeX in web applications. Typst's math syntax is slightly different from LaTeX but equally expressive, and the stored strings preserve the original notation.

Q: Can I use the JSON output with MongoDB or Elasticsearch?

A: Yes, the JSON output is directly importable into document-oriented databases. MongoDB accepts JSON documents natively, allowing you to build searchable collections of your Typst documents. Elasticsearch can index the JSON for full-text search across content and metadata. PostgreSQL's JSONB column type also supports storing and querying the converted documents.

Q: Is the JSON output valid according to RFC 8259?

A: Yes, the converter produces strictly valid JSON conforming to RFC 8259. All strings are properly escaped, Unicode characters use correct encoding, and the structure uses standard JSON objects and arrays. You can validate the output with any JSON validator like JSONLint or use JSON Schema for structural validation.

Q: How does the converter handle Typst scripting constructs?

A: Typst scripting constructs like #let variable definitions, #if conditions, and #for loops are evaluated during conversion, so the JSON output contains the resulting content rather than the unexpanded scripting code. For example, if you define #let name = "Alice", the JSON will contain the resolved value. Complex computed content is included in its final rendered form.

Q: Can I process the JSON output with Python or JavaScript?

A: Absolutely. Python's built-in json module reads the output directly into dictionaries and lists. JavaScript can parse it with JSON.parse() for use in web applications. Any programming language with JSON support can process the data, making it straightforward to build analysis scripts or data pipelines that work with Typst document content programmatically.

Q: What is Typst and how does it differ from LaTeX?

A: Typst is a modern typesetting system created in 2023 as an alternative to LaTeX. It features a cleaner syntax (= for headings, *bold*, _italic_), fast Rust-based compilation, built-in scripting, and helpful error messages. While LaTeX has a vast ecosystem and is the academic standard, Typst offers a gentler learning curve and faster compilation times, making it attractive for new users and rapid document creation.

Q: How large is the JSON output compared to the Typst source?

A: The JSON output is typically similar in size to the Typst source or slightly larger due to JSON's structural overhead (braces, brackets, quotes, key names). A 50KB Typst file might produce a 60-80KB JSON file. However, JSON compresses very well with gzip (typically 70-80% reduction), so storage and transmission overhead is minimal.