Typstyle：打造优雅 Typst 代码的终极格式化工具

Typstyle：打造优雅 Typst 代码的终极格式化工具

【免费下载链接】typstyleBeautiful and reliable typst code formatter项目地址: https://gitcode.com/gh_mirrors/ty/typstyle

Typstyle 是一款为 Typst 语言打造的优雅且可靠的代码格式化工具，它能帮助开发者自动整理代码结构，提升代码可读性与一致性。无论是处理小型文档还是大型项目，Typstyle 都能让你的 Typst 代码保持整洁专业的外观，是 Typst 开发者不可或缺的效率工具。

为什么选择 Typstyle？四大核心优势

Typstyle 采用了业界领先的 Wadler 漂亮打印算法（与 Prettier 格式化工具同源），确保在任何宽度限制下都能生成美观一致的代码。与其他格式化工具相比，它具有四大独特优势：

✅ 专注代码格式化，内容保持原样

Typstyle 严格遵循"只格式化代码，不修改内容"的设计理念。它智能识别 Typst 代码结构，仅调整缩进、换行和空格等格式元素，确保格式化前后的文档渲染效果完全一致。这意味着你的公式、图表和排版样式不会受到任何影响。

✅ 高度一致性，杜绝二次格式化差异

"收敛性"是 Typstyle 的核心特性之一。无论你运行多少次格式化命令，结果始终保持一致，不会出现"格式化后再格式化又变化"的尴尬情况。这种稳定性让团队协作更加顺畅，避免因格式反复变化导致的版本控制冲突。

✅ 全面测试保障，确保格式化正确性

Typstyle 拥有业界领先的测试体系，包括：

• 收敛性测试：确保格式化结果稳定一致
• 快照测试：存储预期格式化结果并进行对比验证
• 正确性测试：比较格式化前后的文档渲染效果
• 端到端测试：在真实项目（如 tablex、cetz、fletcher 等）上验证格式化效果

这些测试确保了 Typstyle 在各种场景下都能提供可靠的格式化结果。

✅ 极致性能，闪电般的格式化速度

Typstyle 针对性能进行了深度优化，通常能在 5 毫秒内完成对包含 3000 行代码的大型文档的格式化。项目还提供了持续基准测试，你可以在 性能报告 中查看详细的性能数据。

快速上手：三种简单安装方式

Typstyle 提供了多种安装选项，满足不同用户的需求：

📦 方法一：使用 Cargo 安装

如果你熟悉 Rust 生态，可以直接通过 Cargo 安装：

cargo install typstyle --locked

📥 方法二：下载预编译二进制

从项目的 发布页面 下载适合你操作系统的预编译二进制文件，解压后将可执行文件添加到系统 PATH 即可。

📋 方法三：使用包管理器

Typstyle 已被多个 Linux 发行版的包管理器收录，例如在 Arch Linux CN 仓库中可以直接安装：

sudo pacman -S typstyle

更多包管理器支持情况可查看 安装文档。

简单实用：Typstyle 基础使用指南

🌐 在线试用（无需安装）

如果你想先体验 Typstyle 的效果，可以访问项目的 Web playground（位于/playground/目录），在线测试格式化效果。这个 playground 集成了最新版本的 Typstyle，支持实时格式化预览，非常适合测试不同代码风格的格式化效果。

💻 命令行使用示例

Typstyle 提供了简洁直观的命令行接口，以下是一些常用示例：

• 格式化单个文件并输出到标准输出：

typstyle file.typ

• 原地格式化文件（直接修改原文件）：

typstyle -i file.typ

• 格式化多个文件和目录：

typstyle -i file1.typ file2.typ src/

• 检查文件是否已格式化：

typstyle --check file.typ

• 自定义行宽和缩进：

typstyle -i --line-width 100 --indent-width 4 file.typ

完整的命令行选项可以通过typstyle --help查看，或参考 CLI 使用文档。

📝 配置选项

虽然 Typstyle 设计为" opinionated "（ opinionated ）工具，但仍提供了一些实用的配置选项：

• --line-width：设置最大行宽（默认 80）
• --indent-width：设置缩进空格数（默认 2）
• --no-reorder-import-items：禁用导入项的字母排序
• --wrap-text：自动换行标记文本以适应行宽

你可以在 配置文档 中了解更多细节。

高级应用：集成到开发流程

🔧 编辑器集成

Typstyle 已集成到 tinymist 插件中，支持多种编辑器。只需安装 tinymist 插件并将tinymist.formatterMode设置为typstyle，即可在保存文件时自动格式化 Typst 代码。

🖥️ Typst.app 集成

通过 typstyle-tampermonkey 用户脚本，你可以将 Typstyle 集成到在线的 typst.app 编辑器中，享受云端格式化体验。

🤖 CI/CD 集成

Typstyle 提供了 GitHub Action 支持，你可以通过 typstyle-action 在 CI 流程中自动检查代码格式，确保提交的代码符合项目风格要求。

🐙 Git 钩子集成

通过 pre-commit 钩子，你可以在提交代码前自动运行 Typstyle：

- repo: https://link.gitcode.com/i/35521a0ea6a773c52884e3e661164bb4/pre-commit-typstyle rev: '' # 使用最新版本 hooks: - id: typstyle

应对特殊情况：格式化"逃生舱"

有时你可能需要暂时禁用格式化，Typstyle 提供了灵活的"逃生舱"机制：

• 使用// @typstyle off或/* @typstyle off */注释可以禁用下一个代码节点的格式化
• 如果代码包含语法错误或不支持的语法，Typstyle 会自动放弃该部分的格式化，保持原样输出

如果你发现格式化结果不符合预期，请在 GitHub 仓库 提交 issue，帮助改进 Typstyle。

技术内幕：Typstyle 的工作原理

Typstyle 的核心架构分为三个主要模块：

1. 解析器：将 Typst 代码解析为抽象语法树（AST）
2. 格式化器：基于 AST 生成格式化后的代码，使用 Wadler 漂亮打印算法
3. 输出器：将格式化结果写入文件或标准输出

核心格式化逻辑位于 crates/typstyle-core/src/pretty/ 目录，包含了对各种 Typst 语法结构的格式化规则。

开始使用 Typstyle

无论你是 Typst 新手还是资深用户，Typstyle 都能帮助你保持代码整洁有序。现在就通过以下命令安装体验：

cargo install typstyle --locked

或者克隆仓库进行本地构建：

git clone https://link.gitcode.com/i/35521a0ea6a773c52884e3e661164bb4 cd typstyle cargo build --release

Typstyle 是一个开源项目，欢迎在 GitHub 仓库 贡献代码、报告问题或提出建议。让我们一起打造更优雅的 Typst 代码世界！

【免费下载链接】typstyleBeautiful and reliable typst code formatter项目地址: https://gitcode.com/gh_mirrors/ty/typstyle