Typst LSP

Typst 的语言服务器。

功能

• 语法高亮、错误报告、代码补全和函数签名帮助
• 保存时编译为 PDF（可配置为边输入边编译，或可禁用）
• 使用 typstfmt 进行实验性格式化

此存储库包含

• 一个用 Rust 编写的 LSP 服务器
• 相应的 VS Code(ium) 扩展。该扩展可在 VS Code 市场place 和 OpenVSX 上找到。

近期目标

• 改进预览（例如，内置 PDF 查看器，快速渲染为图像）
• 支持更多编辑器

从源代码构建

先决条件

安装 Rust，它包含 cargo。其中之一，cargo 是用于 Rust 项目的构建工具。

构建

cargo build --release

Cargo 会根据需要下载和编译 Rust 依赖项。使用 --release 标志将生成优化的二进制文件。生成的可执行文件将在 target/release/typst-lsp（在 Windows 上带有 .exe 扩展名）。

Cargo 功能

Cargo 功能允许您通过在编译时启用代码块来自定义构建。

我们需要一个 HTTP 客户端来下载 Typst 包。客户端需要一个 TLS 实现；默认情况下，使用 Rustls。如果您想禁用或更改此设置，以下 Cargo 功能可用：

• remote-packages（默认值）：使用 HTTP 客户端下载 Typst 包
• rustls-tls（默认值）：使用 Rustls 进行 TLS
• native-tls：使用您平台上的 TLS 实现

例如，以下命令将使用 native-tls 构建：

cargo build --release --no-default-features --features remote-packages,fontconfig,native-tls

对于 Linux，native-tls 表示 OpenSSL。您需要安装其头文件才能使用 native-tls 进行编译。

此外，使用 fontconfig 功能以启用对 fontconfig 的最小支持。这对于 LSP 在某些 Linux 发行版（如 NixOS）中检测字体是必要的，因此默认启用。如果这会导致您的发行版出现问题，您可以通过不启用该功能来禁用对 fontconfig 的支持，例如，通过使用带有标志 --no-default-features --features remote-packages,rustls-tls 进行编译。

注意：如果 LSP 无法通过 fontconfig 找到您的字体，请在运行 LSP 时尝试设置环境变量 FONTCONFIG_FILE 为指定所需字体路径的 fontconfig 配置文件的绝对路径。在使用 VSCode 通过 Flatpak 在 NixOS 等发行版上时可能会发生这种情况，并且在编译您的 Typst 文档时可能会导致某些字体未检测到。要使用 Flatpak 设置环境变量，您可以使用 Flatseal 或运行以下命令（假设是 --user 安装） - 确保用您系统上的适当路径替换 FONTCONFIG_FILE 后面的路径。

# For VSCode:
flatpak override --user --env=FONTCONFIG_FILE=$HOME/.config/fontconfig/conf.d/configfilenamehere.conf com.visualstudio.code

# For VSCodium:
flatpak override --user --env=FONTCONFIG_FILE=$HOME/.config/fontconfig/conf.d/configfilenamehere.conf com.vscodium.codium

升级 Typst 版本

警告：在编写本文时，Typst API 在每个版本中都发生了变化。在语言稳定之前，您可能需要 Rust 知识来处理 Typst 的变化，以成功编译到新的 Typst 版本。

您需要修改 Cargo.toml 中的 Typst 依赖项。这些位于 [dependencies] 部分的顶部，名称以 typst 开头，并引用 git = "https://github.com/typst/typst.git"。

如果您想针对 Typst 的版本化版本进行编译，请将 tag 更改为您所需的版本的标签。通常，标签的命名方式为 vX.X.X。

如果您想针对尚未发布的提交进行编译，请将 tag 替换为 rev，并设置它们的值为 Git 提交哈希。提交哈希是十六进制字符串，具有长版本和短版本，都命名了提交。提交哈希可以在该提交的 GitHub URL 的末尾找到。

开发指南

先决条件

安装

• Rust 用于 LSP 本身
• Rust Analyzer 是 VS Code 上 Rust LSP 的扩展
• node 用于 VS Code 扩展；它可能最容易通过 fnm 安装

首次设置

1. 在本地上克隆此存储库
2. 在 VS Code 中打开它；这是运行扩展所需的
3. 在 editors/vscode 子目录中
   1. 运行 npm install 以安装扩展依赖项
   2. 运行 npm run compile 以构建扩展
4. 完成一次开发周期以初始化和测试一切
5. （可选：安装扩展的开发版本）：按 Ctrl+Shift+P，然后选择 Developer: Install Extension from Location... 并选择扩展的目录，editors/vscode/。将没有消息，但可以在扩展的 @installed 列表中找到扩展。

开发周期

1. 进行任何更改
2. 运行 cargo install --path .；目前，VS Code 扩展仅调用 typst-lsp 命令以启动 LSP，此命令将编译并替换为最新版本
   • 修改扩展时，保持 npm run watch 运行，或者在更改后运行 npm run compile
3. 按 Ctrl+F5 启动“扩展开发主机”；如果它已经运行，则从扩展开发主机的命令面板调用“开发者：重新加载窗口”
   • 如果提示，请选择“运行扩展”
4. 在扩展开发主机中，扩展将处于活动状态并准备好测试

使用 Jaeger 跟踪

Jaeger 是一个可视化跟踪数据的工具。它显示跨度（例如，每个文件打开对应一个跨度，每次我们计算语义令牌时对应一个跨度等）以及关联数据（例如，打开的文件 URL），提供了定时和调试数据。

默认情况下，LSP 不会向 Jaeger 发送数据。要启用它

1. 启动 Jaeger 服务器。建议使用 opentelemetry_jaeger crate

   $ docker run -d -p6831:6831/udp -p6832:6832/udp -p16686:16686 -p14268:14268 jaegertracing/all-in-one:latest
   

2. 使用 jaeger 特性编译 LSP。在终端中运行

   $ cargo build --features jaeger
   

   在 VS Code 中，您可以使用“运行扩展 [Jaeger]”任务以 Jaeger 支持启动扩展。
3. 运行 LSP，然后最终关闭它。
4. 从 Jaeger 中搜索跟踪。可能最好将搜索限制在最小长度为 2 秒的跟踪中，以隐藏来自向 Jaeger 发送数据的任务的较小跟踪。

安装指南

Visual Studio Code

• 从 Marketplace 安装。

Neovim

基本设置

先决条件：mason-lspconfig.nvim、mason.nvim 和 nvim-lspconfig（对于高级用户是可选的，但对于本指南是必需的）。

1. 运行 MasonInstall typst-lsp。
2. 编辑您的 init.lua 设置（有关更多详细信息，您可能需要查阅 server_configurations.md#typst_lsp）

require'lspconfig'.typst_lsp.setup{
	settings = {
		exportPdf = "onType" -- Choose onType, onSave or never.
        -- serverPath = "" -- Normally, there is no need to uncomment it.
	}
}

3. 您还可以安装 typst.vim 以在 nvim 中获得更多功能。

针对 coc.nvim 用户的额外步骤

运行 CocConfig 来编辑设置，以便 coc.nvim 可以提供自动完成等功能

{
"languageserver": {
    "typst": {
        "command": "typst-lsp",
        "filetypes": ["typst"]
        }
    }
}

Sublime Text

遵循 LSP 插件的 配置说明。