Configuration¶

This page documents all configuration options available for typsphinx.

Basic Configuration¶

Add these settings to your conf.py file:

Project Information¶

project = "My Project"
copyright = "2025, Author Name"
author = "Author Name"
release = "1.0.0"

These are standard Sphinx settings that typsphinx uses for document metadata.

Typst Documents¶

Define which documents to build:

typst_documents = [
    ("index", "output", "Title", "Author", "typst"),
]

Each tuple contains:

Source file (without .rst extension)
Output filename (without extension)
Document title
Author
Document class (usually “typst”)

Template Configuration¶

Template Function¶

Specify the Typst template function:

# Simple string format
typst_template_function = "project"

# Dictionary format with parameters
typst_template_function = {
    "name": "ieee",
    "params": {
        "abstract": "This paper presents...",
        "index-terms": ["AI", "ML"],
    }
}

Custom Template File¶

Use a custom Typst template file:

typst_template = "_templates/custom.typ"

The template file should define a project function (or the function specified in typst_template_function).

Typst Package¶

Use external Typst packages from Typst Universe:

typst_package = "@preview/charged-ieee:0.1.4"

Math Rendering¶

mitex Support¶

Enable LaTeX math rendering with mitex:

typst_use_mitex = True  # Default

When enabled, LaTeX math expressions are converted to Typst using the mitex package. When disabled, math is passed directly as Typst math syntax.

Code Highlighting¶

Codly Configuration¶

Enable code highlighting with codly:

typst_use_codly = True  # Default

Customize line numbering:

typst_code_line_numbers = True  # Show line numbers

Author Information¶

Simple Format¶

typst_author = ("John Doe", "Jane Smith")

Detailed Format¶

Include detailed author information:

typst_authors = {
    "John Doe": {
        "department": "Computer Science",
        "organization": "MIT",
        "email": "john@mit.edu"
    },
    "Jane Smith": {
        "department": "Engineering",
        "organization": "Stanford",
        "email": "jane@stanford.edu"
    }
}

Paper Size and Format¶

typst_papersize = "a4"  # Default: "a4"
# Options: "a4", "us-letter", "a5", etc.

typst_fontsize = "11pt"  # Default: "11pt"

Complete Example¶

Here’s a complete conf.py example:

# Project information
project = "My Documentation"
copyright = "2025, My Name"
author = "My Name"
release = "1.0.0"

# General configuration
extensions = ["typsphinx"]

# Typst documents
typst_documents = [
    ("index", "mydoc", project, author, "typst"),
]

# Template configuration
typst_package = "@preview/charged-ieee:0.1.4"
typst_template_function = {
    "name": "ieee",
    "params": {
        "abstract": "This document demonstrates...",
        "index-terms": ["Documentation", "Typst"],
        "paper-size": "us-letter",
    }
}

# Author details
typst_authors = {
    "My Name": {
        "department": "Engineering",
        "organization": "My Organization",
        "email": "me@example.com"
    }
}

# Math and code
typst_use_mitex = True
typst_use_codly = True
typst_code_line_numbers = True