Typst-codelst 包使用指南：优雅排版代码的技术实践

前言

在技术文档编写过程中，代码展示是不可或缺的重要元素。typst-codelst 包正是为解决 Typst 文档中的代码排版问题而生，它提供了丰富的代码展示功能，让技术文档编写变得更加专业和高效。

安装与导入

作为包使用（Typst 0.9.0及以上版本）

对于较新的 Typst 版本，可以直接从预览仓库导入：

#import "@preview/codelst:2.0.2": sourcecode

作为模块使用

将 codelst.typ 文件放入项目目录后，可以直接导入：

#import "codelst.typ": sourcecode

核心功能详解

基础代码展示

sourcecode 命令是 typst-codelst 的核心功能，它包装了 Typst 的 raw 块，为其添加了丰富的格式化选项：

#sourcecode[```typ
  #show "ArtosFlow": name => box[
    #box(image(
      "logo.svg",
      height: 0.7em,
    ))
    #name
  ]
```]

行号定制

typst-codelst 提供了灵活的行号显示方式：

#sourcecode(
    numbers-side: right,
    numbering: "I",          // 使用罗马数字
    numbers-start: 10,       // 起始行号
    numbers-step: 4,         // 行号步长
    numbers-style: (i) => align(right, text(fill:blue, emph(i))),
    frame: none
)[```typ
// 你的代码
```]

代码框架样式

默认情况下，代码块会显示在浅灰色背景的块元素中。可以通过 frame 参数完全自定义：

#let myframe = block.with(
  fill: fuchsia.lighten(96%),
  stroke: 1pt + fuchsia,
  radius: 2pt,
  inset: (x: 10pt, y: 5pt)
)

#sourcecode(frame: myframe)[```typ
// 你的代码
```]

外部文件导入

sourcefile 命令可以直接展示外部文件内容：

#sourcefile(read("example.py"), file:"example.py")

为简化使用，可以创建别名：

#let sourcefile(filename, ..args) = codelst.sourcefile(read(filename), file:filename, ..args)

行引用功能

typst-codelst 支持代码行标记和引用：

// 在代码中添加标记
public static void main(String[] args) { // <main-entry>
    System.out.println("Hello World!");
}

然后在文档中引用：

参见#lineref(<main-entry>)处的入口方法

高级技巧

空白处理

typst-codelst 会自动处理代码中的空白：

• 移除开头和结尾不必要的空行
• 消除多余的缩进

可通过 showlines 和 gobble 参数控制此行为。

与其他包集成

typst-codelst 可以与其他样式包如 showybox 结合使用：

#import "@preview/showybox:2.0.1": showybox

#let showycode = sourcecode.with(
  frame: (code) => showybox(
    frame: (
      title-color: red.darken(40%),
      body-color: red.lighten(90%),
      border-color: black,
      thickness: 2pt
    ),
    title: "Source code",
    code
  )
)

全局代码样式设置

通过 show 规则可以为所有特定语言的代码块应用样式：

#show raw.where(lang: "clst-typ"): code => sourcecode(lang:"typ", code)

```clst-typ
// 你的代码

## 参数参考

### sourcecode 主要参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `lang` | 代码语言 | 自动检测 |
| `numbering` | 行号格式 | "1" |
| `numbers-start` | 起始行号 | auto |
| `numbers-side` | 行号位置 | left |
| `highlighted` | 高亮行号列表 | () |
| `highlight-color` | 高亮颜色 | rgb(234,234,189) |
| `label-regex` | 行标记正则表达式 | `// <([a-z-]{3,})>$` |
| `frame` | 代码框样式函数 | code-frame |

## 结语

typst-codelst 为 Typst 文档中的代码展示提供了专业级的解决方案。无论是简单的代码片段展示，还是需要复杂行号管理和行引用的技术文档，typst-codelst 都能完美胜任。通过灵活的配置选项，你可以轻松实现各种风格的代码展示效果，使你的技术文档更加清晰和专业。

建议读者结合示例文档进行实践，逐步探索 typst-codelst 提供的各种可能性，找到最适合自己文档风格的配置方式。