tinymist/docs/for-llm/vscode-ui.md

VS Code Extension Specification

This document describes the software specification of the VS Code extension for Tinymist.

Overview

There are following user interfaces for Tinymist:

• In the activity bar, there is a Tinymist icon that show up the Tinymist Views.
• In the status bar, there is a Document Status Indicator and a general Problem Indicator.
• You can press Ctrl+Shift+P to open the command palette and type Typst to see all Typst-Related Commands.
• You can also perform some contextual actions in the editor, such as Drag and Drop a file to the editor, or Right Click in the editor to see the Context Menu.
• There are tools in the Tool View that you can use to automate typst tasks.
• You can interacts with the Tinymist LSP under the state model Entry File, Focus State, Pin State, and Preview State.
• You can configure the extension and the language server by the Typst-Specific VS Code Configurations.

Tinymist Views

There are following views in the Tinymist Views:

• Symbol View
• Tool View
• Package View
• Content View
• Label View
• Outline View

Symbol View

There are following actions that you can perform in the Symbol View:

• Search Symbol by Names: You can search for a symbol by its name. The search is case-insensitive and supports partial matching.
• Search Symbol by Handwritten Strokes: You can draw a symbol and search for it. The symbol will be highlighted.
• Click to paste: You can click on a symbol to paste it to the editor.

Tool View

There are following tools that you can use in the Tool View:

• Template Gallery: You can use this tool to show the template gallery.
• Document Summary: You can use this tool to show the document summary.
• Symbol View: You can open the Symbol View to the side.
• Font View: You can use this tool to show the font view.
• Profiling: You can use this tool to profile the current file.
• Profiling Server: You can use this tool to profile the language server.

Package View

There are following actions that you can perform in the Package View:

• Create a new local package: You can create a new local package by clicking the Create Local Package button in the commands group.
• Open a local package: You can open a local package by clicking the Open Local Package button in the commands group.
• Get a tree view of the package: You can view packages in @preview and @local namespaces in tree.
• Check documentation of a package: You can check the documentation of a package by clicking the Documentation button associated with the package in the tree view.
• Open a package in the editor: You can open a package in the editor by clicking the Open button associated with the package in the tree view.
• Open a package in the file explorer: You can open a package in the file explorer by clicking the Reveal in File Explorer button associated with the package in the tree view.
• Check exported symbols of a package: You can check the exported symbols of a package by expanding the symbols node in the tree view.

Content View

You can get a thumbnail of the current document in the Content View if Preview State is enabled.

Label View

You can find all syntatical labels in the workspaces in the Label View. The labels are grouped by prefix.

Outline View

You can get the document outline in the Outline View if Preview State is enabled. The outline is strictly same as the outline that will show up in the PDF document. This is different from the LSP’s syntax outline which shows language syntax structure in the current opened document.

Tools

Template Gallery

The Template Gallery connects to the typst universe and shows the templates that are available in the universe.

• You can search for a template by its name.
• You can filter templates by their categories.
• You can create a project from a template by clicking the Creates Project (+) button.
• You can favorite a template by clicking the Favorite (♥) button. The favorite templates will show up when you initializes a template by command tinymist in place in to the current opened text document.

Document Summary

The Document Summary shows the summary of the current document. It includes:

• The fonts and related information used by the document. The related information includes:

  • The font family, size, and style.
  • The occurrences of the glyphs (informally characters) in the document.

• The arguments used to compile the document.

• The resources used by the document.

Font View

The Font View shows all of the fonts and related information recognized by the LSP server. The related information includes:

• The font family, size, and style.
• The font file name and path.

There are following actions that you can perform in the Font View:

• Click Show Number: You can click the Show Number button to show or hide accurate number of font weights.
• Click Copy: You can click the Copy button to copy the typst family name of the font to the clipboard.
• Click Paste String: You can click the Paste String button to paste the typst family name of the font directly to the editor.
• Click #set: You can click the #set button to generate and paste a set rule to the editor.

Profiling

The Profiling tool allows you to profile the current file. It shows the time taken to compile the document by flame graph.

Profiling Server

The Profiling Server tool allows you to profile the language server. When you click the Profiling Server button in the tool view, the server will start profiling and you can see the profiling results in the Profiling tool. You can stop profiling by clicking the Stop Profiling button.

Typst-Specific VS Code Configurations

tinymist.compileStatus

In VSCode, enable compile status meaning that the extension will show the compilation status in the status bar. Since Neovim and Helix don’t have a such feature, it is disabled by default at the language server label.

• Type: string
• Valid Values:
  • "enable"
  • "disable"
• Default: "enable"

tinymist.completion.postfix

Whether to enable postfix code completion. For example, [A].box| will be completed to box[A]|. Hint: Restarting the editor is required to change this setting.

• Type: boolean
• Default: true

tinymist.completion.postfixUfcs

Whether to enable UFCS-style completion. For example, [A].box| will be completed to box[A]|. Hint: Restarting the editor is required to change this setting.

• Type: boolean
• Default: true

tinymist.completion.postfixUfcsLeft

Whether to enable left-variant UFCS-style completion. For example, [A].table| will be completed to table(|)[A]. Hint: Restarting the editor is required to change this setting.

• Type: boolean
• Default: true

tinymist.completion.postfixUfcsRight

Whether to enable right-variant UFCS-style completion. For example, [A].table| will be completed to table([A], |). Hint: Restarting the editor is required to change this setting.

• Type: boolean
• Default: true

tinymist.completion.symbol

Whether to make symbol completion stepless. For example, $ar|$ will be completed to $arrow.r$. Hint: Restarting the editor is required to change this setting.

• Type: string
• Valid Values:
  • "step" : Complete symbols step by step
  • "stepless" : Complete symbols steplessly
• Default: "step"

tinymist.completion.triggerOnSnippetPlaceholders

Whether to trigger completions on arguments (placeholders) of snippets. For example, box will be completed to box(|), and server will request the editor (lsp client) to request completion after moving cursor to the placeholder in the snippet. Note: this has no effect if the editor doesn’t support editor.action.triggerSuggest or tinymist.triggerSuggestAndParameterHints command. Hint: Restarting the editor is required to change this setting.

• Type: boolean
• Default: false

tinymist.configureDefaultWordSeparator

Whether to configure default word separators on startup

• Type: string
• Valid Values:
  • "enable" : Override the default word separators on startup
  • "disable" : Do not override the default word separators on startup
• Default: "disable"

tinymist.copyAndPaste

Whether to handle paste of resources into the editing typst document. Note: restarting the editor is required to change this setting.

• Type: string
• Valid Values:
  • "enable" : Enable copy-and-paste.
  • "disable" : Disable copy-and-paste.
• Default: "enable"

tinymist.dragAndDrop

Whether to handle drag-and-drop of resources into the editing typst document. Note: restarting the editor is required to change this setting.

• Type: string
• Valid Values:
  • "enable" : Enable drag-and-drop.
  • "disable" : Disable drag-and-drop.
• Default: "enable"

tinymist.exportPdf

The extension can export PDFs of your Typst files. This setting controls whether this feature is enabled and how often it runs.

• Type: string
• Valid Values:
  • "never" : Never export PDFs, you will manually run typst.
  • "onSave" : Export PDFs when you save a file.
  • "onType" : Export PDFs as you type in a file.
  • "onDocumentHasTitle" : (Deprecated) Export PDFs when a document has a title (and save a file), which is useful to filter out template files.
• Default: "never"

tinymist.exportTarget

The target to export the document to. Defaults to paged. Note: you can still export PDF when it is set to html. This configuration only affects how the language server completes your code.

• Type: string
• Valid Values:
  • "paged" : The current export target is for PDF, PNG, and SVG export.
  • "html" : The current export target is for HTML export.
• Default: "paged"

tinymist.fontPaths

A list of file or directory path to fonts. Note: The configuration source in higher priority will override the configuration source in lower priority. The order of precedence is: Configuration tinymist.fontPaths > Configuration tinymist.typstExtraArgs.fontPaths > LSP’s CLI Argument --font-path > The environment variable TYPST_FONT_PATHS (a path list separated by ; (on Windows) or : (Otherwise)). Note: If the path to fonts is a relative path, it will be resolved based on the root directory. Note: In VSCode, you can use VSCode variables in the path, e.g. ${workspaceFolder}/fonts.

• Type: array | null

tinymist.formatterIndentSize

Sets the indent size (using space) for the formatter.

• Type: number
• Default: 2

tinymist.formatterMode

The extension can format Typst files using typstfmt or typstyle.

• Type: string
• Valid Values:
  • "disable" : Formatter is not activated.
  • "typstyle" : Use typstyle formatter.
  • "typstfmt" : Use typstfmt formatter.
• Default: "typstyle"

tinymist.formatterPrintWidth

Sets the print width for the formatter, which is a soft limit of characters per line. See the definition of Print Width. Note: this has lower priority than the formatter’s specific configurations.

• Type: number
• Default: 120

tinymist.formatterProseWrap

Controls how the formatter handles prose line wrapping. If enabled, the formatter will insert hard line breaks at the specified print width. If disabled, the formatter keeps the original line breaks and spaces.

• Type: boolean
• Default: false

tinymist.lint.enabled

Enable or disable lint checks. Note: restarting the editor is required to change this setting.

• Type: boolean
• Default: false

tinymist.lint.when

Configure when to perform lint checks. Note: restarting the editor is required to change this setting.

• Type: string
• Valid Values:
  • "onSave" : Perform lint checks on save
  • "onType" : Perform lint checks on type
• Default: "onSave"

tinymist.onEnterEvent

Enable or disable experimental/onEnter (LSP onEnter feature) to allow automatic insertion of characters on enter, such as /// for comments. Note: restarting the editor is required to change this setting.

• Type: boolean
• Default: true

tinymist.onPaste

The script to be executed when pasting resources into the editing typst document. If the script code starts with { and ends with }, it will be evaluated as a typst code expression, e.g. $root/x/$dir/$name evaluated as /path/to/root/x/dir/main, otherwise it will be evaluated as a path pattern, e.g. { join(root, "x", dir, if name.ends-with(".png") ("imgs"), name) } evaluated as /path/to/root/x/dir/imgs/main. The extra valid definitions are root, dir, name, and join. To learn more about the paste script, please visit Script Hooks. Hint: you could import @local packages in the paste script. Note: restarting the editor is required to change this setting.

• Type: string
• Default: "$root/assets"

tinymist.outputPath

The path pattern to store Typst artifacts, you can use $root or $dir or $name to do magic configuration, e.g. $dir/$name (default) and $root/target/$dir/$name.

• Type: string
• Default: ""

tinymist.preview.background.args

The arguments that the background preview server used for. It is only used when `tinymist.preview.background` is enabled. Check `tinymist preview` to see the allowed arguments.

• Type: array
• Properties:
  • "type":
    • Type: string
• Default: [ "--data-plane-host=127.0.0.1:23635", "--invert-colors=auto" ]

tinymist.preview.background.enabled

This configuration is only used for the editors that doesn't support lsp well, e.g. helix and zed. When it is enabled, the preview server listens a specific tcp port in the background. You can discover the background previewers in the preview panel.

• Type: boolean
• Default: false

tinymist.preview.browsing.args

The arguments used by `tinymist.startDefaultPreview` command. Check `tinymist preview` to see the allowed arguments.

• Type: array
• Properties:
  • "type":
    • Type: string
• Default: [ "--data-plane-host=127.0.0.1:0", "--invert-colors=auto", "--open" ]

tinymist.preview.cursorIndicator

(Experimental) Show typst cursor indicator in preview.

• Type: boolean
• Default: false

tinymist.preview.invertColors

Invert colors of the preview (useful for dark themes without cost). Please note you could see the origin colors when you hover elements in the preview. It is also possible to specify strategy to each element kind by an object map in JSON format.

This configuration item can be one of following types:

• Invert colors of the preview.
  • Type: string
  • Valid Values:
    • "never" : Never
    • "auto" : Inferring from the browser settings
    • "always" : Always
• Invert colors of the preview in a more fine-grained way.
  • Type: object
  • Properties:
    • "rest": Invert colors of the rest of the elements.
      • Type: string
      • Valid Values:
        • "never" : Never
        • "auto" : Inferring from the browser settings
        • "always" : Always
      • Default: "never"
    • "image": Invert colors of the images.
      • Type: string
      • Valid Values:
        • "never" : Never
        • "auto" : Inferring from the browser settings
        • "always" : Always
      • Default: "never"
• Default: "never"

tinymist.preview.partialRendering

Only render visible part of the document. This can improve performance but still being experimental.

• Type: boolean
• Default: true

tinymist.preview.refresh

Refresh preview when the document is saved or when the document is changed

• Type: string
• Valid Values:
  • "onSave" : Refresh preview on save
  • "onType" : Refresh preview on type
• Default: "onType"

tinymist.preview.scrollSync

Configure scroll sync mode.

• Type: string
• Valid Values:
  • "never" : Disable automatic scroll sync
  • "onSelectionChangeByMouse" : Scroll preview to current cursor position when selection changes by mouse
  • "onSelectionChange" : Scroll preview to current cursor position when selection changes by mouse or keyboard (any source)
• Default: "onSelectionChangeByMouse"

tinymist.previewFeature

Enable or disable preview features of Typst. Note: restarting the editor is required to change this setting.

• Type: string
• Valid Values:
  • "enable" : Enable preview features.
  • "disable" : Disable preview features.
• Default: "enable"

tinymist.projectResolution

This configuration specifies the way to resolved projects.

• Type: string
• Valid Values:
  • "singleFile" : Manage typst documents like what we did in Markdown. Each single file is an individual document and no project resolution is needed.
  • "lockDatabase" : Manage typst documents like what we did in Rust. For each workspace, tinymist tracks your preview and compilation history, and stores the information in a lock file. Tinymist will automatically selects the main file to use according to the lock file. This also allows other tools push preview and export tasks to language server by updating the lock file.
• Default: "singleFile"

tinymist.renderDocs

(Experimental) Whether to render typst elements in (hover) docs. In VS Code, when this feature is enabled, tinymist will store rendered results in the filesystem’s temporary storage to show them in the hover content. Note: Please disable this feature if the editor doesn’t support/handle image previewing in docs.

• Type: string
• Valid Values:
  • "enable" : Enable render docs.
  • "disable" : Disable render docs.
• Default: "enable"

tinymist.rootPath

Configure the root for absolute paths in typst. Note: for Neovim users, if it complains root not found, you must set require("lspconfig")["tinymist"].setup { root_dir } as well, see tinymist#528.

• Type: string | null

tinymist.semanticTokens

Enable or disable semantic tokens (LSP syntax highlighting)

• Type: string
• Valid Values:
  • "enable" : Use semantic tokens for syntax highlighting
  • "disable" : Do not use semantic tokens for syntax highlighting
• Default: "enable"

tinymist.serverPath

The extension can use a local tinymist executable instead of the one bundled with the extension. This setting controls the path to the executable. The string “tinymist” means look up Tinymist in PATH.

• Type: string | null

tinymist.showExportFileIn

Configures way of opening exported files, e.g. inside of editor tabs or using system application.

This configuration item can be one of following types:

• Configures way of opening exported files, e.g. inside of editor tabs or using system application.
  • Type: string
  • Valid Values:
    • "editorTab" : Show the exported files in editor tabs.
    • "systemDefault" : Show the exported files by system default application.
  • Default: "editorTab"

tinymist.statusBarFormat

Set format string of the server status. For example, {compileStatusIcon}{wordCount} [{fileName}] will format the status as $(check) 123 words [main]. Valid placeholders are:

• {compileStatusIcon}: Icon indicating the compile status
• {wordCount}: Number of words in the document
• {fileName}: Name of the file being compiled

Note: The status bar will be hidden if the format string is empty.

• Type: string
• Default: "{compileStatusIcon} {wordCount} [{fileName}]"

tinymist.systemFonts

A flag that determines whether to load system fonts for Typst compiler, which is useful for ensuring reproducible compilation. If set to null or not set, the extension will use the default behavior of the Typst compiler. Note: You need to restart LSP to change this options.

• Type: boolean
• Default: true

tinymist.trace.server

Traces the communication between VS Code and the language server.

• Type: string
• Valid Values:
  • "off"
  • "messages"
  • "verbose"
• Default: "off"

tinymist.typingContinueCommentsOnNewline

Whether to prefix newlines after comments with the corresponding comment prefix.

• Type: boolean
• Default: true

tinymist.typstExtraArgs

You can pass any arguments as you like, and we will try to follow behaviors of the same version of typst-cli. Note: the arguments may be overridden by other settings. For example, --font-path will be overridden by tinymist.fontPaths.

• Type: array
• Default: []