Quarto项目中Typst字体权重命名不兼容问题解析

在Quarto项目的最新版本中，用户在使用Typst格式输出时可能会遇到一个关于字体权重命名的兼容性问题。这个问题表现为在YAML前端配置中使用特定字体权重名称时，Quarto验证与Typst编译阶段对同一名称的不同处理方式导致的冲突。

问题现象

当用户在brands.yml配置文件中为字体指定权重时，如果使用"semibold"作为值，Quarto前端会报错提示该值无效，并建议使用"semi-bold"替代。然而，当用户按照建议修改为"semi-bold"后，Typst编译器又会报错，指出该值不符合预期格式。

这种不一致性源于两个系统对字体权重命名的不同规范：

• Quarto前端验证接受带连字符的格式（如"semi-bold"）
• Typst编译器则要求使用无连字符的格式（如"semibold"）

技术背景

字体权重（font weight）是描述字体粗细程度的属性，在CSS规范中通常使用数值（100-900）或预定义名称表示。不同系统和工具链对预定义名称的处理存在差异：

1. Quarto验证规则：遵循更传统的CSS命名约定，使用带连字符的形式（如"extra-light"、"semi-bold"）
2. Typst编译器：采用了更简化的命名方案，去除了连字符（如"extralight"、"semibold"）

解决方案

目前推荐的临时解决方案是直接使用数值表示法（如600代替"semibold"或"semi-bold"），这在不同系统中都具有良好的兼容性。

从技术实现角度看，Quarto项目需要在_quarto.modules.typst.css模块中添加专门的权重转换函数，将前端配置中的权重名称转换为Typst兼容的格式。这种转换应包括：

1. 去除连字符
2. 处理可能的同义词映射（如将"demi-bold"转换为"semibold"）

最佳实践建议

对于需要在Quarto中使用Typst输出的开发者，建议：

1. 优先使用数值形式的字体权重（100-900），这是最可靠的跨平台方案
2. 如果必须使用名称形式，暂时采用Typst兼容的无连字符格式，并注意Quarto前端的验证警告
3. 关注Quarto项目的更新，该问题已被标记为需要向后移植修复的重要问题

这个问题虽然表面上是简单的命名差异，但反映了不同排版引擎在设计理念和规范实现上的细微差别，值得开发者在使用混合技术栈时特别注意。