Context Workshop

针对 ConTeXt 的 VSCode/VSCodium 扩展。

功能

功能	说明
编译	支持 .tex .ctx .mkiv .mklx .mkvi .mkxl 等扩展名，自动判断 mkiv/mkxl 引擎
预览	内置 PDF 查看器（基于 pdf.js，首次使用自动下载）、系统默认应用、指定外部应用
语法高亮	完整的 ConTeXt TextMate 语法
大纲 & 折叠	章节/标题层级大纲；\start...\stop... 环境与章节折叠
智能补全	Digestif 语言服务器提供命令、环境、参数、交叉引用、文献引用补全
悬停文档	Digestif 提供命令签名和文档弹窗
跳转定义	Digestif 支持标签、引用的定义跳转
查找引用	Digestif 支持标签、引用的全项目搜索
CJK 字体补全	自动检测系统中文字体，在字体相关命令中提供补全
环境检测	自动定位 context / mtxrun / luametatex，检查环境
下载/安装	接口已预留（默认值 + 空实现），见下文

安装

1. 把整个 context-workshop 文件夹复制到扩展目录：

   • VSCodium (macOS): ~/.vscode-oss/extensions/context-workshop
   • VSCode: ~/.vscode/extensions/context-workshop

2. 重启编辑器，左下角状态栏出现「Context: 就绪」即激活成功。

需要安装 Digestif 语言服务器才能获得完整的语言智能功能。 可以通过 LuaRocks 安装：luarocks install digestif 或通过 TeX Live 安装：tlmgr install digestif

打包与分发（.vsix 安装包）

普通用户不需要命令行。在项目目录执行一次：

npx --yes @vscode/vsce package --allow-missing-repository

会生成 context-workshop-<版本号>.vsix 单文件安装包。把它发给用户，用户在 VSCode / VSCodium 中：

1. 打开「扩展」面板（Cmd/Ctrl+Shift+X）
2. 点击右上角 ⋯ 菜单 → 从 VSIX 安装…
3. 选择该文件，重启编辑器即可

命令数据库生成工具（参考）

tools/gen-commanddb.py 保留作为参考工具，可用于生成 ConTeXt 命令数据库。补全功能现已委托给 Digestif 语言服务器。

python3 tools/gen-commanddb.py <interface-dir> lib/context-commands.json

<interface-dir> 为含 context-en.xml 与 i-*.xml 的目录，一般在 TeX 发行版 tex/context/interface/mkiv/ 下。

使用

• 编译：Ctrl/Cmd+Alt+B，或右键 → Context Workshop → 编译

• 内置预览：Ctrl/Cmd+Alt+V

• 补全：

  • Digestif 提供完整的命令、环境、参数补全
  • CJK 字体补全：在 \definefontfamily、\setupbodyfont 等命令中自动补全中文字体名
  • 普通文本里直接打词根也会触发补全

• 系统默认程序打开：Ctrl/Cmd+Alt+W

• 清理辅助文件：Ctrl/Cmd+Alt+N

• 检查环境：命令面板 → Context Workshop: 检查环境

首次使用内置预览时，扩展会自动从 unpkg 下载 pdf.js 到扩展的全局存储目录。

中文支持

• 命令面板 → Context Workshop: 插入中文字体配置：扫描系统里 ConTeXt 能识别的中文字体，插入 \definefontfamily 配置。
• 若系统没有中文字体，使用 Context Workshop: 下载并安装中文字体（见下）。

下载/安装接口（待实现，留给你填写）

下载类功能目前只提供接口与默认值，实现留空。你只需要修改：

• lib/installer.js 中的函数：installConTeXt、downloadChineseFonts、downloadModules、configureEnvironment；另提供可直接使用的 detectSystem()（平台/发行版检测）与 resolveDownloadUrl()（gh-proxy 加速）
• 默认值集中在 lib/installer.js 的 DEFAULT_OPTIONS，同时暴露为设置项 context-workshop.install.*：

设置	默认值	含义
install.installDir	~/context	ConTeXt standalone 安装目录
install.distribution	current	current / beta / stable
install.contextURL	contextgarden 的 first-setup.sh	安装脚本地址
install.modules	all	要安装的模块
install.ghProxy	https://gh-proxy.org/	GitHub 下载加速前缀（留空直连）
install.fontDir	""（自动检测）	Windows→%WINDIR%\Fonts；macOS/Linux→~/context/tex/texmf-local/fonts
install.fontSources	LXGW 新致宋/新晰黑/文楷 3 个 URL	中文字体下载源

检测到 TeX Live 发行版时，detectSystem().suggestedEnv 会建议把 TEXMFHOME=~/context/tex/texmf-local、TEXMFCACHE=~/context/tex/texmf-cache 写入环境设置（见下），使字体与缓存都落在 ~/context/tex 下。

实现提示已写在各函数的注释里。返回值约定：{ ok: boolean, message: string }。

配置项（摘录）

设置面板按 六个分组 显示（Settings 编辑器里分组排序，组内按 order 排序）：

分组	设置	默认值	说明
核心	engine	auto	auto / mkiv / mkxl
核心	arguments	--nonstopmode --noconsole	附加编译参数
编译	autoBuildOnSave	false	保存后自动编译
编译	autoViewAfterBuild	false	编译成功后自动预览
编译	autoCleanOnSuccess	true	编译成功后自动清理辅助文件（保留 pdf）；失败时保留以便查看日志，并自动打开日志文件
编译	outputDir	""	PDF 输出目录
编译	cleanPatterns	常见 ConTeXt 辅助文件	清理的 glob 模式，* 替换为文件名主名
预览	viewPdfMode	internal	预览方式：internal=PDF Viewer 扩展，system=系统默认应用，ask=每次询问
预览	externalViewer	""	外部查看器应用名（如 Skim），留空则用系统默认
Digestif	digestif.executable	digestif	Digestif 可执行文件路径
Digestif	digestif.enabled	true	启用 Digestif 语言服务器
Digestif	digestif.arguments	[]	传递给 Digestif 的命令行参数
下载/安装	contextPath	""	context 可执行文件路径，留空自动检测
下载/安装	install.*	见上文	安装/字体相关全部设置

环境变量设置接口

编译等所有子进程会注入以下环境变量，支持 ~ 展开、${env:VAR} 引用：

设置	说明
texmfhome	TEXMFHOME：用户 TeX 树（放自定义字体/模块/typescripts）
texmfcache	TEXMFCACHE：ConTeXt 缓存目录
texmfvar	TEXMFVAR：可变文件目录
texmfconfig	TEXMFCONFIG：配置文件目录
environment	通用键值对，可设任意变量（如 OSFONTDIR），优先级最高，会覆盖上面四个 TEXMF*

设置后编译前会自动创建对应目录。运行「Context Workshop: 检查环境」可在输出面板核对实际生效值。 典型场景：把中文字体放进 ~/texmf/fonts/...，再设 texmfhome=~/texmf；或设 environment: {"OSFONTDIR": "~/Library/Fonts:~/.fonts"} 让 LuaMetaTeX 用系统字体。

与 LaTeX Workshop 共存

本扩展将 .tex 也注册为 ConTeXt 语言（语法/补全/大纲按 ConTeXt 处理）。 如果同时安装了 LaTeX Workshop，两个扩展对 .tex 的接管存在竞争；可在 VSCodium 中关闭其中一个的 .tex 关联，或通过 files.associations 指定。

已知限制

• SyncTeX：已移除 enableSynctex 设置；如需生成 synctex 文件，在 arguments 中自行添加 --synctex=1。
• 内置预览器未实现 SyncTeX 正反跳转。
• 下载/安装接口待实现。

Digestif 集成说明

本扩展集成了 Digestif 语言服务器，提供以下功能：

功能委托

功能	Digestif 提供	扩展保留	说明
命令补全	✅	-	Digestif 提供完整的 ConTeXt 命令补全
环境补全	✅	-	Digestif 提供环境补全（如 \startitemize）
参数补全	✅	-	Digestif 提供键值选项补全
交叉引用补全	✅	-	Digestif 提供标签和引用补全
文献引用补全	✅	-	Digestif 提供 BibTeX/BibLaTeX 引用补全
悬停文档	✅	-	Digestif 提供命令签名和文档弹窗
跳转定义	✅	-	Digestif 支持标签、引用的定义跳转
查找引用	✅	-	Digestif 支持标签、引用的全项目搜索
文档大纲	✅	-	Digestif 提供多文件项目的大纲
代码折叠	✅	-	Digestif 提供更准确的环境和章节折叠
CJK 字体补全	-	✅	扩展提供系统中文字体检测和补全
语法高亮	-	✅	扩展提供 TextMate 语法高亮
编译	-	✅	扩展提供 ConTeXt 编译功能
PDF 预览	-	✅	扩展提供内置 PDF 查看器
日志解析	-	✅	扩展提供 ConTeXt 日志解析和错误诊断
环境检测	-	✅	扩展提供环境检测和配置

配置选项

在 VS Code 设置中可以配置 Digestif：

{
  "context-workshop.digestif.executable": "digestif",
  "context-workshop.digestif.enabled": true,
  "context-workshop.digestif.arguments": []
}

安装 Digestif

Digestif 可以通过以下方式安装：

1. 通过 LuaRocks（推荐）：

   luarocks install digestif

2. 通过 TeX Live：

   tlmgr install digestif

3. 通过 MiKTeX：

   miktex packages install digestif

4. 从源代码安装：

   git clone https://github.com/astoff/digestif.git
   cd digestif
   luarocks make

验证安装

安装完成后，可以在终端中运行以下命令验证：

digestif --version

如果看到版本信息，说明安装成功。