typsphinx

Sphinx extension for Typst output format support.

📖 Documentation | 🐛 Issue Tracker | 📦 PyPI

Overview

typsphinx is a Sphinx extension that enables generating Typst documents from reStructuredText sources. Typst is a modern typesetting system designed as an alternative to LaTeX, offering faster compilation and a more intuitive syntax.

Features

• Convert Sphinx documentation to Typst format: Seamlessly transform your reStructuredText/Markdown documents
• Standard docutils nodes: Full support for paragraphs, sections, lists, tables, admonitions, and more
• Mathematical expressions:
  • LaTeX syntax via mitex (@preview/mitex:0.2.7)
  • Native Typst math syntax
• Code blocks with syntax highlighting: Using codly package (@preview/codly:1.3.0)
  • Automatic line numbering
  • Syntax highlighting for multiple languages
  • Highlight specific lines
• Images and figures: Embed images with captions and references
• Cross-references: Maintain document structure with internal links
• Customizable templates: Use default or custom Typst templates
• Direct PDF generation: Self-contained PDF generation via typst-py (no external Typst CLI required)
• Multi-document support: Generate multiple Typst files with toctree integration using #include()

Requirements

• Python 3.12 or higher
• Sphinx 9.1 or higher
• typst-py 0.15.0 or higher

Installation

From PyPI

pip install typsphinx

Using uv (recommended for development)

# Clone the repository
git clone https://github.com/YuSabo90002/typsphinx.git
cd typsphinx

# Install dependencies with uv
uv sync

# For development dependencies
uv sync --extra dev

Quick Start

Basic Configuration

Configure Typst output in your conf.py:

# conf.py

# Note: typsphinx is auto-discovered via entry points.
# Adding to extensions list is optional but recommended for clarity.
# extensions = ['typsphinx']

# Optional: Configure Typst builder
typst_use_mitex = True  # Use mitex for LaTeX math (default: True)

typst_documents

typst_documents is the list of master documents to build. Each entry is a tuple (source, target, title, author, documentclass), and each entry produces a wrapper .typ file at the entry's target and, under the typstpdf builder, one compiled .pdf from that wrapper; the entry's source document is additionally emitted as its own .typ file holding the document body, as is every other document in the project. See docs/source/user_guide/output_layout.rst for the full contract and which file to compile.

You never need to set it for a single-master project — leaving it unset is supported, and that's exactly what this Quick Start does. When unset, typsphinx derives a single entry from root_doc, project, and author: the target stem is project run through the same filename helper Sphinx's own LaTeX builder uses, so project = "My Project" yields myproject.typ and, under typstpdf, myproject.pdf. This is more than a rename — the derived entry makes the root document a master, so its emitted .typ gains the full template wrapper it would not otherwise receive.

An explicit typst_documents value — including an explicit empty list [] — always overrides the derived default: Sphinx resolves your raw config value before falling back to the callable default.

Only the documents named in typst_documents (or the single derived entry) become PDFs. A document reached only through a toctree is not a separate PDF — it is emitted as its own .typ file and pulled into its master through Typst's #include().

Build Typst Output

# Generate Typst files
sphinx-build -b typst source build/typst

# Generate PDF directly
sphinx-build -b typstpdf source build/pdf

Example Document

Create a simple reStructuredText document:

==============
My Document
==============

This is a paragraph with **bold** and *italic* text.

Math Example
============

Inline math: :math:`E = mc^2`

Block math:

.. math::

   \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}

Code Example
============

.. code-block:: python

   def hello_world():
       print("Hello, Typst!")

This will generate a Typst file with:

• Proper heading hierarchy
• Formatted text with emphasis
• LaTeX math via mitex (or native Typst math)
• Syntax-highlighted code blocks with codly

Advanced Usage

Custom Templates

Create a custom Typst template:

# conf.py
typst_template = '_typst/custom.typ'

Template Parameter Mapping

Map Sphinx metadata to template parameters:

# conf.py
typst_template_mapping = {
    'project': 'doc_title',
    'author': 'doc_authors',
    'release': 'version',
}

Keys are Sphinx metadata names; values are the template parameter names they map to.

Multi-Document Projects

Use toctree to combine multiple documents:

.. toctree::
   :maxdepth: 2
   :numbered:

   intro
   chapter1
   chapter2

This generates #include() directives in Typst with proper heading level adjustments.

Working with Third-Party Extensions

typsphinx integrates with Sphinx's standard extension mechanism. For custom nodes from third-party extensions (e.g., sphinxcontrib-mermaid), you can register Typst handlers in your conf.py:

# conf.py
def setup(app):
    # Example: Support sphinxcontrib-mermaid diagrams
    if 'sphinxcontrib.mermaid' in app.config.extensions:
        from sphinxcontrib.mermaid import mermaid
        from docutils import nodes

        def typst_visit_mermaid(self, node):
            """Render Mermaid diagram as image in Typst output"""
            # Export diagram as SVG and include in Typst
            diagram_path = f"diagrams/{node['name']}.svg"
            self.add_text(f'#image("{diagram_path}")\n\n')
            raise nodes.SkipNode

        # Register with Sphinx's standard API
        app.add_node(mermaid, typst=(typst_visit_mermaid, None))

How it works:

• typsphinx uses Sphinx's standard app.add_node() API (no custom registry needed)
• Unknown nodes trigger unknown_visit() which logs a warning and extracts text content
• Users can add Typst support for any extension by registering handlers in conf.py

For more details, see the Sphinx Extension API documentation.

Configuration Options

Below are the main configuration options. This is not the complete set — see docs/source/user_guide/configuration.rst for the full reference:

• typst_documents: Master documents to build, as [(source, target, title, author, documentclass), ...] — optional; when unset, typsphinx derives a single master from root_doc/project/author (target <project>.typ), and an explicit value always overrides that derived default. The target names the entry's wrapper file.
• typst_use_mitex: Enable/disable mitex for LaTeX math
• typst_template: Custom template path
• typst_elements: Template parameters (paper size, fonts, etc.)
• typst_template_mapping: Sphinx metadata to template parameter mapping

Development

This project uses uv for fast package management and follows TDD (Test-Driven Development) practices.

Setup Development Environment

# Install with development dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Run tests with coverage report
uv run pytest --cov=typsphinx --cov-report=html

# Run tests across multiple Python versions
uv run tox

# Run specific tox environments
uv run tox -e lint          # Run linters (black, ruff)
uv run tox -e type          # Run type checking (mypy)
uv run tox -e py312         # Run tests on Python 3.12
uv run tox -e docs-html     # Build HTML documentation
uv run tox -e docs-pdf      # Build PDF documentation
uv run tox -e docs          # Build both HTML and PDF docs

Testing Strategy

• Unit tests: Cover all major components
• Integration tests: Full build process validation
• Example projects: examples/basic/ and examples/advanced/

Project Structure

typsphinx/
├── typsphinx/              # Main package
│   ├── builder.py          # Typst builder
│   ├── writer.py           # Doctree writer
│   ├── translator.py       # Node translator
│   ├── template_engine.py  # Template processor
│   ├── pdf.py              # PDF generation
│   └── templates/          # Default templates
├── tests/                  # Test suite
├── docs/                   # Documentation
├── examples/               # Example projects
└── pyproject.toml          # Project configuration

Known Limitations

• Bibliography: BibTeX integration not yet supported
• Citations: reStructuredText citation directives are not yet supported

Documentation

📖 Full documentation is available at typsphinx.readthedocs.io

日本語ドキュメントは typsphinx.readthedocs.io/ja/latest/ にあります。

Quick links:

• Installation Guide
• Quick Start
• User Guide
• Configuration Reference
• Output Layout
• Examples
• API Reference
• Contributing Guide

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Write tests for new features
4. Ensure all tests pass: uv run pytest
5. Submit a pull request

Development Guidelines

• Follow TDD (Test-Driven Development)
• Use black for code formatting
• Follow Sphinx extension conventions
• Add tests for all new features

License

MIT License - see LICENSE file for details.

Acknowledgments

• Built on top of Sphinx
• Uses Typst for typesetting
• Integrates mitex for LaTeX math
• Uses codly for code highlighting
• Uses gentle-clues for admonitions
• Developed with Claude Code and GSD (spec-driven development for AI coding agents)

Version History

See CHANGELOG.md for detailed version history.

Status: Stable (v0.9.2) - Production ready Python: 3.12+ | Sphinx: 9.1+ | Typst: 0.15+