In version 1.1.6, Typsite introduced a series of major updates, inevitably including some breaking-changes. This document aims to help users migrate to the new version smoothly.

1 Typsite Packages

Parts of the Typst library that are closely related to Typsite have been extracted into separate Typst packages. You can find them under typsite/packages. Typsite bundles these packages into the binary and automatically installs them to the @local @local directory during each typsite compile typsite compile .

To facilitate debugging and using packages, Typsite also supports local package auto-installation. Just specify the --packages --packages flag when running typsite compile typsite compile .

In watch-mode watch-mode , Typsite will also automatically update these local packages and recompile the site.

So now, the Typsite Typst libraries are split into two parts:

@local/typsite:0.1.0 @local/typsite:0.1.0 : Contains core functionality of Typsite, provides basic functions, and acts as an interface between Typsite and site libraries.
- Thanks to this layer, it is unlikely for future updates to introduce more breaking-changes.
root/lib/ root/lib/ : The site library of each Typsite site. Users are free to customize anything here.

2 Migration

If you're relying on site libraries from before version 1.1.6, you'll need to make the following replacements when migrating:

import "lib.typ" import "lib.typ" |-> import "/lib/lib.typ" import "/lib/lib.typ"
html-text html-text |-> html.text html.text
text-align text-align |-> html.align html.align
- (Make sure not- to replace text-align text-align inside /lib/site.typ /lib/site.typ )

It's recommended to import lib.typ lib.typ using an absolute path. If you're using tinymist as your LSP, you'll need to specify the Typst root-path root-path for better experience:

In VSCode, you can add the following to .vscode/settings.json .vscode/settings.json in your site directory:

"tinymist.rootPath": "absolute path of your site/root"

"tinymist.rootPath": "absolute path of your site/root"

For any breaking-changes not anticipated here, you can easily detect them by launching watch-mode watch-mode with typsite compile --port 8000 typsite compile --port 8000 . Typsite will provide helpful error messages whenever you modify a file, allowing you to fix issues quickly.

3 Other Updates

Added support for converting Typst math to MathML.
- This improves the rendering of math formulas, and the MathML conversion will detect Typst math fonts in-place for compatibility.
inline inline function has a new fit-font fit-font parameter, which can adapt to Typst's context text.size context text.size .
For pages containing backlinks and references, duplicate tags in the <head> <head> section are now removed, resulting in a much cleaner structure.
In the default site library, show-rules show-rules have been modularized. You can easily add/remove/modify show-rule show-rule items in /lib/lib.typ /lib/lib.typ .
In the default site configuration, link titles have been optimized. You can now preview links as Link Title [Link URL] Link Title [Link URL] .

Backlinks

Typsite Documentation [index]

Glomzzz
2025-04-12 02:08

Migrating to Typsite 1.1.6

1 Introduction

Typsite is a tool for building static websites. It uses pure Typst to write content and processes it through Typsite to generate a fully functional static site.

2 Features

Standard Typst expressions
Framework support: hierarchical headings, section templates, sidebar, footer
Rich text: paragraphs, sections, quotes, code blocks, math formulas, footnotes, page embedding
Typst math -> Mathml （auto detected math-font)
Supports modern web standards such as HTML5, CSS3, and JavaScript (ES6+)
Incremental compilation and real-time preview

3 Introduction to Typst [typst]

2025-04-27 18:39
Glomzzz

Typst is a modern typesetting system, similar to LaTeX, but designed to be more concise and easier to learn. It is primarily used to create beautifully typeset documents such as academic papers, books, and reports.

You can find the official English documentation here: Typst Document
For a Chinese tutorial on Typst, I highly recommend: The Typst Blue Book
[Oh my, the author is clearly aware that they're explaining an ontology!].

Typst

🔥has risen!🔥

🚀Did the TeX folks miss the memo?🚀

The rest of this section will introduce Typst & HTML → Typsite

3.1 Typst’s HTML Export Feature

In version 0.13 0.13 , Typst added HTML export capabilities, including an html-export mode and two core functions: html.elem html.elem and html.frame html.frame — using these, we can write Typst documents targeting HTML+CSS output.

3.2 Typsite: A Static Site Generator Based on Typst

Inspired by this, I developed a static site generator in Rust called Typsite.

Currently, Typst’s HTML export:

Has good support for basic rich text
Requires users to manually write complex styles using the html.elem html.elem function
Cannot automatically convert all Typst ecosystem content into HTML
For content with complex Typst styles, html.frame html.frame can be used to convert them into SVG and embed them into HTML
Only supports single-file HTML output per compilation

For details on supported features and the roadmap, follow this issue: HTML export #5512

Although the official team plans to support automatic typst style → HTML+CSS in the future, this won’t conflict with Typsite. On the contrary, Typst’s development will make Typsite even more useful, because Typsite’s main role is to coordinate interaction between articles and ultimately build a fully functional static website.

4 Installation

Download the binary from the release
- Make sure you have Typst 0.13+ installed
Build via Nix & Flakes
- Ensure you’ve enabled experimental-features = nix-command flakes experimental-features = nix-command flakes

git clone https://github.com/Glomzzz/typsite.git

cd typsite
nix build .

git clone https://github.com/Glomzzz/typsite.git

cd typsite
nix build .

5 Initialization

Run typsite init typsite init to initialize a Typsite project in the current directory.

.
├── root         ---  Typst root directory
│   ├── index.typ    --- Main article
│   └── lib.typ      --- Typsite library file
├── .typsite     ---  Typsite configuration directory
│   ├── assets       ---  Resources (synced to output directory)
│   ├── components   ---  Component templates
│   ├── themes       ---  Code highlighting themes
│   ├── rewrite      ---  Rewrite templates
│   ├── schemas      ---  Page templates
│   └── options.toml ---  Project configuration
├── .cache       ---  Cache directory
└── publish      ---  Output directory

.
├── root         ---  Typst root directory
│   ├── index.typ    --- Main article
│   └── lib.typ      --- Typsite library file
├── .typsite     ---  Typsite configuration directory
│   ├── assets       ---  Resources (synced to output directory)
│   ├── components   ---  Component templates
│   ├── themes       ---  Code highlighting themes
│   ├── rewrite      ---  Rewrite templates
│   ├── schemas      ---  Page templates
│   └── options.toml ---  Project configuration
├── .cache       ---  Cache directory
└── publish      ---  Output directory

6 Writing

Typsite is compatible with most native Typst syntax:

¹For align align , please use the html.align html.align function from the library

²For complex styled elements, use the inline inline function for SVG embedding

7 CLI (Command Line Interface)

Usage: typsite <COMMAND>

Commands:
  init     Initialize a new Typsite project in the specified directory
  compile  Compile or watch a project; specify input/output [alias: c]
  clean    Clear cache and output directories
  syntect  Check the list of supported syntax and code highlighting
  help     Print this message or help info for a subcommand

Options:
  -h, --help     Print help
  -V, --version  Print version info

Usage: typsite <COMMAND>

Commands:
  init     Initialize a new Typsite project in the specified directory
  compile  Compile or watch a project; specify input/output [alias: c]
  clean    Clear cache and output directories
  syntect  Check the list of supported syntax and code highlighting
  help     Print this message or help info for a subcommand

Options:
  -h, --help     Print help
  -V, --version  Print version info

7.1 init

Initialize a new Typsite project in the specified directory

Usage: typsite init [OPTIONS]

Options:
  -d, --dir <DIR>  Project root directory [default: ./]
  -h, --help       Print help

Initialize a new Typsite project in the specified directory

Usage: typsite init [OPTIONS]

Options:
  -d, --dir <DIR>  Project root directory [default: ./]
  -h, --help       Print help

7.2 compile

Compile or watch the project with specified input and output directories

Usage: typsite compile [OPTIONS]

Options:
      --host <HOST>          Serve host [default: localhost]
      --port <PORT>          Serve port, must be specified to watch mode [default: 0]
      --config <CONFIG>      Project config [default: ./.typsite]
      --cache <CACHE>        Cache dir [default: ./.cache]
  -i, --input <INPUT>        Typst root dir, where your typst files are stored [default: ./root] [aliases: --i]
  -o, --output <OUTPUT>      Output dir [default: ./publish] [aliases: --o]
  -p, --packages <PACKAGES>  Packages dir, will be installed to @local and will be synced to @local in watch mode, skip if empty or not found [default: ] [aliases: --p]
      --no-pretty-url
      --no-short-slug
  -h, --help                 Print help

Compile or watch the project with specified input and output directories

Usage: typsite compile [OPTIONS]

Options:
      --host <HOST>          Serve host [default: localhost]
      --port <PORT>          Serve port, must be specified to watch mode [default: 0]
      --config <CONFIG>      Project config [default: ./.typsite]
      --cache <CACHE>        Cache dir [default: ./.cache]
  -i, --input <INPUT>        Typst root dir, where your typst files are stored [default: ./root] [aliases: --i]
  -o, --output <OUTPUT>      Output dir [default: ./publish] [aliases: --o]
  -p, --packages <PACKAGES>  Packages dir, will be installed to @local and will be synced to @local in watch mode, skip if empty or not found [default: ] [aliases: --p]
      --no-pretty-url
      --no-short-slug
  -h, --help                 Print help

7.3 clean

Clear cache and output directories

Usage: typsite clean [OPTIONS]

Options:
  -o, --output <OUTPUT>  Output directory [default: ./publish]
  -c, --cache <CACHE>    Cache directory for typst_html_export content [default: ./.cache]
  -h, --help             Print help

Clear cache and output directories

Usage: typsite clean [OPTIONS]

Options:
  -o, --output <OUTPUT>  Output directory [default: ./publish]
  -c, --cache <CACHE>    Cache directory for typst_html_export content [default: ./.cache]
  -h, --help             Print help

7.4 syntect

View the list of syntax highlighting and supported languages  
Usage: typsite syntect [OPTIONS]

Options:
      --config <CONFIG>  Config path [default: ./.typsite]
  -h, --help             Print help

View the list of syntax highlighting and supported languages  
Usage: typsite syntect [OPTIONS]

Options:
      --config <CONFIG>  Config path [default: ./.typsite]
  -h, --help             Print help

8 Architecture & Flow

9 Configuration

You can view all default configurations here:

Based on these, you can fully customize your entire site.

schema: Page templates, handling page structure
components / rewrites: Components/Rewriters, build up the page content
assets: Resource files, automatically synced during compilation
themes: Code highlighting files
syntaxes: Code syntaxes files

10 Article [article]

2025-05-30 22:51
Glomzzz

TODO….

10.1 Metadata

10.1.1 Page Settings

10.1.2 Meta Content

10.1.3 Article Relations

10.2 Sidebar

10.3 Main Content

10.3.1 Headings

10.3.2 Paragraphs

10.3.3 Breadcrumbs

10.3.4 Embeds

10.3.5 Footnotes

10.3.6 Links

10.3.7 Formulas

10.3.8 Inline Content

10.3.9 Code

10.3.9.1 Theme

10.3.9.2 Syntax

10.3.10 Styles

10.3.10.1 Alignment

10.3.10.2 Highlight

10.3.10.3 Colored Text

10.3.10.4 Bold

10.3.10.5 Italic

10.4 Footer

10.4.1 Backlinks

10.4.2 References

Why not take a look at Content Example first?