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

1 0.1.6 Migration

Make sure you’ve done： Migrating to Typsite 0.1.6

2 .typsite Configuration Migration

In version 0.1.7, the following new components and rewrites were added to the .typsite directory:

.typsite/components/anchor_def_svg.html .typsite/components/anchor_def_svg.html : SVG anchor definition component
.typsite/components/anchor_goto_svg.html .typsite/components/anchor_goto_svg.html : SVG anchor goto component
.typsite/rewrite/footnote-ref-svg.html .typsite/rewrite/footnote-ref-svg.html : Footnote reference rewrite for SVG

If you’re upgrading from an older version, make sure to copy these new files to your site’s .typsite directory.

3 /root/lib Library Migration

3.1 inline Function Signature Change

The fit-font fit-font parameter semantics of the inline inline function have changed:

Before 0.1.7: fit-font fit-font was a bool bool type
After 0.1.7: fit-font fit-font is a 1em 1em type (can be true true , false false , or values like 1em 1em , 2em 2em )

Migration:

inline(content, fit-font: true) inline(content, fit-font: true) |-> inline(content, fit-font: 1em) inline(content, fit-font: 1em)
inline(content, fit-font: false) inline(content, fit-font: false) |-> inline(content) inline(content) or inline(content, fit-font: false) inline(content, fit-font: false)

3.2 Library Import Changes

If you’ve customized the inline inline function in your site library, you need to update the call signature:

// Old version
#import "@local/typsite:0.1.0": inline

// New version
#let footnotes = state("footnotes", ())
#let inline(..args) = context {
  import "@local/typsite:0.1.0": inline
  inline(..args, footnotes: footnotes.get())
}

// Old version
#import "@local/typsite:0.1.0": inline

// New version
#let footnotes = state("footnotes", ())
#let inline(..args) = context {
  import "@local/typsite:0.1.0": inline
  inline(..args, footnotes: footnotes.get())
}

3.3 rule Function Signature Changes

The following functions in rule.typ rule.typ now need to receive the footnotes footnotes parameter:

rule-ref(footnotes) rule-ref(footnotes) instead of the old rule-ref rule-ref
rule-footnote(footnotes) rule-footnote(footnotes) instead of the old rule-footnote rule-footnote

In the schema schema function, you need to fetch footnotes first and then pass them to the rules:

let _footnotes = query(footnote).map(it => it.at("label", default: none)).filter(it => it != none)
show: rule-footnote(_footnotes)
show: rule-ref(_footnotes)

let _footnotes = query(footnote).map(it => it.at("label", default: none)).filter(it => it != none)
show: rule-footnote(_footnotes)
show: rule-ref(_footnotes)

4 /packages Package Migration

4.1 inline Function New footnotes Parameter

The inline inline function in @local/typsite:0.1.0 @local/typsite:0.1.0 now requires a footnotes footnotes parameter:

// Old version
inline(content, fit-font: true, scale: 100%)

// New version
inline(content, fit-font: 1em, scale: 100%, footnotes: ())

// Old version
inline(content, fit-font: true, scale: 100%)

// New version
inline(content, fit-font: 1em, scale: 100%, footnotes: ())

4.2 auto-sized-svg New fit-font Parameter

The auto-sized-svg auto-sized-svg function now has a fit-font fit-font parameter with more flexible font size control:

true true : Use CSS font-size inheritance
false false : Use fixed font-size: 1rem
1em 1em : Use relative em value

5 Zed Editor Compatibility

5.1 Zed LSP Configuration

If you’re using Zed as your editor, you can add the following configuration for a better Typst development experience:

Add to .zed/settings.json .zed/settings.json :

{
  "lsp": {
    "tinymist": {
      "initialization_options": {
        "exportPdf": "never",
        "rootPath": "your/site/root/path",
      },
    },
  },
}

{
  "lsp": {
    "tinymist": {
      "initialization_options": {
        "exportPdf": "never",
        "rootPath": "your/site/root/path",
      },
    },
  },
}

5.2 VSCode Settings Migration

If you were previously using VSCode with tinymist configured, you need to update rootPath rootPath to an absolute path:

In .vscode/settings.json .vscode/settings.json :

{
  "tinymist.rootPath": "/absolute/path/to/your/site/root"
}

{
  "tinymist.rootPath": "/absolute/path/to/your/site/root"
}

6 0.1.6 Migration Link

If you’re migrating from version 0.1.6, make sure you’ve also completed the 0.1.6 migration steps:

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

7 Other Updates

Added SVG anchor support, allowing creation of jumpable anchors in Typst content
Footnote references now support SVG inline rendering
Improved the font size adaptation mechanism for the inline inline function
Added support for more flexible fit-font fit-font parameter, allowing specific em values

Backlinks

Typsite Documentation [index]

Glomzzz
2025-04-12 02:08

Migrating to Typsite 0.1.7

Migrating to Typsite 0.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?