How to Use the Command 'typst' (with Examples)

The typst command-line tool is a powerful utility designed to compile Typst files into PDFs. Typst is a markup-based language similar in spirit to LaTeX, designed for creating high-quality documents. The simplicity of Typst’s syntax, along with the power and flexibility of its command-line tool, provides users with a streamlined way to manage document generation efficiently. The following examples illustrate various use cases of the typst command, showcasing its abilities to initialize projects, compile documents, watch files, and list fonts.

Use Case 1: Initialize a New Typst Project

Code:

typst init "template" path/to/directory

Motivation:

When starting a new document project, especially one that follows a specific style or format, initializing a project using a predefined template can save time. This command creates the necessary file structure and includes starter files that can be customized, ensuring consistency and helping the user get started quickly without setting up from scratch.

Explanation:

• init: This tells the typst tool to initialize a new project.
• "template": This specifies the template to use, such as @preview/charged-ieee. Templates often contain predefined settings and elements tailored for specific types of documents or organizations.
• path/to/directory: The destination path where the initialized project will be created. The directory will contain the template structure and files necessary for your project.

Example Output:

Executing this command in a terminal with the template set to @preview/charged-ieee and the directory set to ~/Documents/MyProject will result in:

Initializing new Typst project using template '@preview/charged-ieee'.
Project files created successfully at '~/Documents/MyProject'.

Use Case 2: Compile a Typst File

Code:

typst compile path/to/source.typ path/to/output.pdf

Motivation:

The core function of the typst tool is to compile Typst source files into PDFs. This is essential for users who have completed drafting their document and need a finalized version in PDF format for distribution, printing, or review. The compilation process transforms the markup in the source file into a professionally formatted document.

Explanation:

• compile: Instructs typst to compile a document.
• path/to/source.typ: The source Typst file that contains the document’s text and markup.
• path/to/output.pdf: The desired output location and filename for the compiled PDF. If omitted, the PDF will be created in the same directory as the source file with the same base name.

Example Output:

Running the command with a source file located at ~/Documents/MyProject/document.typ and an output path of ~/Documents/MyProject/final-document.pdf will produce:

Compiling '~/Documents/MyProject/document.typ' to '~/Documents/MyProject/final-document.pdf'.
Compilation successful.

Use Case 3: Watch a Typst File and Recompile on Changes

Code:

typst watch path/to/source.typ path/to/output.pdf

Motivation:

During document editing, especially when changes need frequent review, it’s efficient to have a tool that automatically recompiles the document upon every save. This feature saves time and manual effort by constantly keeping the PDF output up-to-date with the latest modifications in the source file.

Explanation:

• watch: Initiates a mode where typst continuously monitors the specified Typst file for any changes.
• path/to/source.typ: The source file to be watched.
• path/to/output.pdf: The destination for the compiled PDF, updated whenever the source file changes.

Example Output:

Executing this command on a source file at ~/Documents/MyProject/document.typ and outputting to ~/Documents/MyProject/live-document.pdf will prompt:

Watching '~/Documents/MyProject/document.typ' for changes.
Changes detected, recompiling...
Recompilation successful. Output updated at '~/Documents/MyProject/live-document.pdf'.

Use Case 4: List All Discoverable Fonts

Code:

typst --font-path path/to/fonts_directory fonts

Motivation:

Fonts significantly affect a document’s appearance and readability. Listing all available fonts, especially those in custom directories, helps users select the ideal typefaces for their documents. This is particularly useful when specific typography is required by a project’s style guidelines.

Explanation:

• --font-path path/to/fonts_directory: This option allows the user to specify a font directory that typst should include when listing fonts, in addition to the system-wide fonts.
• fonts: The command that tells typst to list all discoverable fonts.

Example Output:

Running this command with a custom font directory at ~/Documents/MyProject/fonts might produce:

System fonts:
  - Arial
  - Times New Roman
  - Courier New

Custom fonts in '~/Documents/MyProject/fonts':
  - Open Sans
  - Lato

Conclusion

The typst command-line tool offers a variety of functionalities that enhance document preparation and management. Whether you’re setting up new projects, compiling documents, keeping your work updated in real-time, or managing fonts, typst provides robust solutions for all your document production needs. Each use case showcases its practicality and ease of use, making it an invaluable tool for users engaged in document creation and distribution.