Pandoc 3.10.1 是一次以细节改进和错误修复为主的版本更新。最值得关注的变化有两项：Txt2Tags（t2t）正式成为输出格式；默认设置文件可以不带扩展名。这些调整看似不大，却能减少文档流水线中的自定义脚本和文件命名约束。
t2t 从输入支持走向可直接输出
Pandoc 的核心定位不是简单替换文本标记，而是先把输入文档解析成内部抽象语法树，再由不同 writer 生成目标格式。3.10.1 增加 t2t 输出后，可以直接把 Markdown 等受支持的输入转换成 Txt2Tags 文档。
升级后，可以先确认当前二进制是否提供该 writer：
pandoc --version
pandoc --list-output-formats | grep -x 't2t'
准备一个最小输入文件：
cat > input.md <<'EOF'
# 发布说明
Pandoc 现在可以输出 **Txt2Tags**。
- 适合接入现有文档流水线
- 不再需要手写基础转换脚本
[项目主页](https://pandoc.org/)
EOF
pandoc input.md --from markdown --to t2t --output output.t2t
cat output.t2t
如果只想检查标准输出，可以省略 --output：
pandoc input.md -f markdown -t t2t
这项能力适合需要维护 Txt2Tags 文档、向旧系统交付 .t2t 文件，或希望用统一转换入口管理多种发布格式的团队。
不过，“能够转换”不等于“能够无损往返”。Markdown 与 Txt2Tags 的表达能力、扩展语法和元数据模型并不完全相同。表格、脚注、复杂嵌套列表、原始代码块以及自定义属性等内容，都应该用真实文档做回归测试，而不是仅检查命令是否成功退出。
无扩展名 defaults 文件让任务入口更干净
Pandoc 的 defaults 文件可以集中保存输入格式、输出格式和输出路径等选项，避免在 CI 脚本中堆叠很长的参数。3.10.1 允许使用不带扩展名的默认设置文件；与扩展名有关的查找或补全只在指定名称的文件不存在时介入。
可以这样准备一个名为 publish、没有 .yaml 后缀的配置文件：
cat > publish <<'EOF'
from: markdown
to: t2t
standalone: true
input-files:
- input.md
output-file: output.t2t
EOF
pandoc --defaults ./publish
执行后检查结果：
test -s output.t2t && echo 'conversion succeeded'
head -n 20 output.t2t
无扩展名文件尤其适合作为仓库中的任务入口。例如，项目可以使用 publish、manual、release-notes 等业务名称，而不必让调用方关心配置文件采用什么扩展名。
需要注意的是，仓库里不要同时放置多个可能产生歧义的同名 defaults 文件。升级前后最好执行一次：
find . -maxdepth 2 -type f \( -name 'publish' -o -name 'publish.yaml' -o -name 'publish.yml' \) -print
如果输出多个文件，应明确团队实际使用哪一个，并在 CI 中传入清晰路径。
把转换结果纳入 CI，而不是只验证退出码
格式转换工具最常见的风险并非进程崩溃，而是输出成功但内容发生细微变化。升级 Pandoc 时，可以为关键文档保留一份期望输出，并在流水线中比较差异。
下面是一段可以直接改造的 Shell 检查脚本，假设仓库中已有 input.md、无扩展名 defaults 文件 publish，以及经过人工确认的 expected/output.t2t：
#!/usr/bin/env bash
set -euo pipefail
required_version='3.10.1'
actual_version="$(pandoc --version | head -n 1 | awk '{print $2}')"
if [[ "$actual_version" != "$required_version" ]]; then
echo "expected pandoc $required_version, got $actual_version" >&2
exit 1
fi
pandoc --list-output-formats | grep -qx 't2t'
pandoc --defaults ./publish
diff -u expected/output.t2t output.t2t
将它保存为 scripts/check-docs.sh 后运行：
chmod +x scripts/check-docs.sh
./scripts/check-docs.sh
如果输出中包含时间戳、自动生成标识或其他不稳定字段，应先固定这些输入，或者对结果做可解释的规范化处理，避免测试长期处于误报状态。
升级时该检查什么
Pandoc 3.10.1 更像是一次适合稳步跟进的补丁版本，而不是要求重写文档系统的大版本迁移。实际采用时可以按以下清单推进：
- 用
pandoc --version固定本地与 CI 的版本，避免不同环境生成不同结果。 - 用
--list-output-formats确认运行中的二进制确实支持 t2t 输出。 - 为表格、链接、代码块、脚注和嵌套列表准备代表性样例。
- 检查无扩展名 defaults 文件与
.yaml、.yml文件是否存在命名冲突。 - 对生成文件执行文本差异比较，并人工复核第一次基线更新。
- 如果通过 Haskell 库直接集成 Pandoc，还应运行项目自身的编译与转换测试，而不只测试命令行工具。
对于已经使用 Pandoc 的团队，这次升级的直接收益是拓宽输出目标并简化配置命名；对于准备引入 t2t 输出的项目，最稳妥的方式仍然是从一组真实文档开始，建立可重复的转换命令和回归基线。