VS Code 插件
这款插件让你可以直接在 VS Code 中使用 Scholarly 的模板、布局、组件、引用、主题设置和项目检查。侧边栏按照创建、制作、定制和检查的顺序组织。
插件会跟随 VS Code 的显示语言，提供英文和简体中文界面。本页使用中文命令名称，截图展示英文界面；可在命令面板中搜索 Slidev Scholarly 查找对应操作。
安装
从 VS Code Marketplace 安装 Slidev Scholarly，需要 VS Code 1.106.0 或更新版本。预览和导出还需要在演示项目中安装 Slidev 和主题，详见快速开始。
打开插件
- 打开一个 Markdown 文件。
- 打开右侧的 Secondary Side Bar。
- 选择 Slidev Scholarly。
侧边栏按任务排列：
| 阶段 | 视图 | 作用 |
|---|---|---|
| 开始 | 开始 · 模板 | 从模板创建演示 |
| 制作 | 制作 · 布局 | 插入整张幻灯片的结构 |
| 制作 | 制作 · 组件 | 插入定理、指标、证据等内容 |
| 制作 | 制作 · 引用与锚点 | 插入 BibTeX key、论文摘要和内部链接 |
| 定制 | 定制 · 主题 | 设置预设、颜色、字体和明暗模式 |
| 参考 | 参考 · CLI 操作 | 运行 CLI 任务、项目检查和帮助 |
1. 创建演示
在开始 · 模板中选择模板，插件会调用 CLI 创建完整项目。输入新文件夹或空文件夹的名称，再打开该目录，安装依赖并启动预览：
pnpm install
pnpm run dev命令面板中的 Slidev Scholarly: 新建演示 则只创建起步 Markdown 文件：有工作区时写入工作区，没有工作区时打开未命名文档。预览前需要将该文件放入 Slidev 项目。
用 Deck Builder 搭好大纲
运行 Slidev Scholarly: 打开 Deck Builder，按以下步骤操作：
- 选择一种工作流，例如论文汇报或答辩。
- 查看每张幻灯片的布局缩略图，再补充或调整顺序。
- 选中幻灯片，填写这一页的内容。
大纲完成后，可以生成一份未命名的 Markdown 文档，也可以把当前页追加到已打开 Markdown 文件的末尾，保留原有全局配置和页面。后续编辑和实时预览仍在 Slidev 中完成。
含引用的工作流还需要在保存的 Markdown 旁提供 references.bib。生成大纲后，点击通知中的创建完整模板项目，初始化包含引用文件的模板，再将当前大纲保存到该项目中。关闭通知不会更改大纲；创建项目会拒绝覆盖非空文件夹。
切换布局会保留该页各布局的草稿，生成时只使用当前布局。编辑区较窄时，按需展开工作流、布局库或大纲。可以用方向键选择工作流，再按 Tab 进入后续控件。
2. 制作幻灯片
插入布局和组件
从侧边栏选择布局或组件。点击项目会在光标处插入 Markdown；点击眼睛图标可以先看预览。插入整页片段时，应将光标放在页面边界，并检查前后的 --- 分隔符。
三类内容的分工如下：
输入时补全
| 触发内容 | 补全结果 |
|---|---|
layout: | 布局名称 |
colorTheme:、fontTheme: | 主题值 |
contentMode:、chromeMode:、sectionMode: | 浅色和深色模式 |
< | Scholarly 组件 |
::: | Markdown 指令 |
](#、href="#、to="# | 内部锚点 |
ss-、scholarly- | 内置代码片段 |
如果补全没有自动出现，按 Ctrl+Space。
插入引用和锚点
制作 · 引用与锚点 会列出当前文档中的 BibTeX 条目和内部锚点。
常用命令：
Slidev Scholarly: 插入引用Slidev Scholarly: 插入内部锚点Slidev Scholarly: 插入内部锚点引用Slidev Scholarly: 插入论文概览
使用代码片段
输入前缀后按 Tab：
| 前缀 | 插入内容 |
|---|---|
ss-cover | 封面 |
ss-section | 章节页 |
ss-figure | 带说明的图片 |
ss-theorem | 定理组件 |
ss-results | 结果布局 |
ss-cite | BibTeX 引用 |
ss-anchor | 内部锚点 |
ss-frontmatter | Scholarly 文件头配置 |
完整列表在补全菜单和侧边栏中都能找到。旧的 scholarly-* 前缀仍然可用。
3. 定制演示
定制 · 主题 包含四组设置：
- 预设
- 配色主题
- 字体主题
- 明暗模式
主题操作只会更新当前 Markdown 文件的 frontmatter，不会改写幻灯片内容。
4. 检查并获取帮助
参考 · CLI 操作 按任务整理命令：
| 分组 | 操作 |
|---|---|
| 开始 | 创建演示或查看模板 |
| 制作 | 查看布局和组件、添加片段或应用工作流 |
| 定制 | 设置主题或查看预设 |
| 检查与帮助 | 运行 doctor 或查看 CLI 帮助 |
引用诊断
文档中出现 @citekey 或 !@citekey 时，插件会检查：
- 是否缺少
bibFile配置； .bib文件是否存在；- key 是否重复或无法解析；
- 是否缺少
layout: references参考文献页。
常见问题可以通过 Quick Fix 自动修复。
故障排除
补全或代码片段没有出现
- 确认插件已安装并启用。
- 打开一个
.md文件。 - 按
Ctrl+Space。
侧边栏没有显示
- 运行
View: Toggle Secondary Side Bar。 - 如果仍未出现，运行
View: Reset View Locations。
插件开发
安装本地 VSIX
- 下载或构建
.vsix文件。 - 按
Cmd+Shift+P或Ctrl+Shift+P打开命令面板。 - 运行
Extensions: Install from VSIX...。 - 选择文件并重新加载 VS Code。
打开开发诊断
运行 Slidev Scholarly: 切换开发模式。开启后，状态栏会显示 Scholarly Dev，Slidev Scholarly 输出通道会记录操作耗时。
设置项：
slidevScholarly.devMode.enabledslidevScholarly.devMode.slowThresholdMs（默认25）
发现问题或希望增加功能，请在 GitHub 提交 issue。