Migration from LaTeX

Guide for migrating from Documenter's LaTeX backend to DocumenterTypst.

Quick Migration

Step 1: Update Dependencies

docs/Project.toml - Add DocumenterTypst:

[deps]
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
DocumenterTypst = "d7fd56dd-41bc-4b2d-b658-79a5840b2e09"  # Add this

[compat]
Documenter = "1"
DocumenterTypst = "0.1"  # Add this

Step 2: Update make.jl

Before:

using Documenter, MyPackage

makedocs(
    sitename = "MyPackage",
    format = Documenter.LaTeX(platform = "native"),
    ...
)

After:

using Documenter, DocumenterTypst, MyPackage

makedocs(
    sitename = "MyPackage",
    format = DocumenterTypst.Typst(),  # Change this line
    ...
)

Step 3: Test

julia --project=docs -e '
  using Pkg
  Pkg.instantiate()
  include("docs/make.jl")
'

That's it! Your markdown files need no changes.

Feature Mapping

Platform Options

Math Syntax

LaTeX math just works - no changes needed!

# Works in both backends

`\\alpha + \\beta = \\gamma`

```math
\sum_{i=1}^n i = \frac{n(n+1)}{2}
```

Custom Styling

What Stays the Same

✅ Markdown files - No changes needed ✅ Math equations - LaTeX syntax supported via mitex ✅ Code blocks - Same syntax highlighting ✅ Cross-references - @ref works identically ✅ Doctests - Full support ✅ Images - Same relative paths ✅ Tables - Same markdown tables ✅ Admonitions - Same !!! note syntax

What's Different

Faster Compilation

LaTeX: Several minutes for large docs Typst: < 60 seconds

Better Error Messages

LaTeX:

! Undefined control sequence.
l.42 \mysterycommand

Typst:

error: unknown variable: mysterycommand
  ┌─ document.typ:42:2
  │
42│ #mysterycommand
  │  ^^^^^^^^^^^^^

No LaTeX Distribution Required

LaTeX: Install TeXLive/MiKTeX (GB of downloads) Typst: Automatic via Typst_jll (MB of downloads)

Breaking Changes

None for Standard Usage

If you're using standard Documenter features, migration is seamless.

Rare Cases

Custom LaTeX packages: Not supported. Use Typst equivalents in custom.typ.

Example:

% LaTeX (old)
\usepackage{tikz}
\begin{tikzpicture}
  ...
\end{tikzpicture}

// Typst (new)
#import "@preview/cetz:0.1.0": *

#canvas({
  ...
})

Migration Checklist

• [ ] Add DocumenterTypst to docs/Project.toml
• [ ] Update makedocs() format argument
• [ ] Test build locally
• [ ] Update CI configuration
• [ ] Remove LaTeX-specific dependencies
• [ ] (Optional) Convert custom.tex to custom.typ
• [ ] (Optional) Update documentation to mention new backend

Gradual Migration

You can support both formats temporarily:

# docs/make_latex.jl
using Documenter, MyPackage
makedocs(format = Documenter.LaTeX(), ...)

# docs/make_typst.jl
using Documenter, DocumenterTypst, MyPackage
makedocs(format = DocumenterTypst.Typst(), ...)

Compare outputs before fully switching.

CI Migration

GitHub Actions

Before:

- name: Install LaTeX
  run: sudo apt-get install texlive-full

- name: Build docs
  run: julia docs/make.jl

After:

# No LaTeX installation needed!

- name: Build docs
  run: julia docs/make.jl

Simpler and faster!

Troubleshooting Migration

Issue: Fonts Look Different

Solution: Typst uses different default fonts. Customize in custom.typ:

#let config = (
  text-font: ("Times New Roman", "Liberation Serif"),  // LaTeX-like
)

Issue: Spacing Changed

Solution: Fine-tune in custom.typ:

#let config = (
  text-size: 11pt,  // Match LaTeX default
)

Issue: Custom LaTeX Macros Missing

Solution: Rewrite as Typst functions:

// LaTeX: \newcommand{\R}{\mathbb{R}}
// Typst equivalent ($ is math delimiter in Typst):
#let R = [ℝ]

// Usage in markdown:
// @raw typst
// The set #R represents real numbers.

Getting Help

• Check Troubleshooting Guide
• See Advanced Features
• Ask in GitHub Discussions

Success Stories

"Migration took 5 minutes, builds are 10x faster!" - User A "Finally, no more LaTeX installation issues in CI" - User B "The error messages actually make sense now" - User C

Next Steps

After migration:

1. Customize styling
2. Explore Typst math
3. Optimize CI builds