进阶 sli.dev 2026-11-21 18:58:32 · 1 阅读

第30章 配置 Pre-Parser

第30章 配置 Pre-Parser

​INFO 自定义 pre-parser 不建议频繁使用,通常用 Transformer 来实现自定义语法就够了。

Slidev 解析演示文稿文件(如 slides.md)分三步进行:

1. 先执行"预解析":用 --- 分隔符把文件拆分成多张幻灯片,同时处理可能存在的 frontmatter 块。 2. 每张幻灯片由外部库解析。 3. Slidev 处理特殊的 frontmatter 属性 src: ...,用于引入其他 md 文件。

Markdown Parser ​

第 2 步使用的 markdown 解析器可以通过配置 Vite 内部插件来调整。

Preparser 扩展 ​

自 v0.37.0 起可用。

WARNING 注意:修改 preparser 配置后,需要停止并重新启动 Slidev(仅重启可能不够)。

preparser(上文第 1 步)具有很高的可扩展性,可以为 md 文件实现自定义语法。扩展 preparser 属于高级特性,由于会隐式改变语法,可能导致编辑器集成失效。

要自定义它,创建一个 ./setup/preparser.ts 文件,内容如下:

./setup/preparser.ts ts

```ts import { definePreparserSetup } from '@slidev/types'

export default definePreparserSetup(({ filepath, headmatter, mode }) => { return [ { transformRawLines(lines) { for (const i in lines) { if (lines[i] === '@@@') lines[i] = 'HELLO' } }, } ] }) ```

这个例子会把所有 @@@ 行系统地替换为 hello。它展示了 preparser 配置文件的基本结构和几个核心概念:

- definePreparserSetup 必须以一个函数作为参数调用。 - 该函数接收文件路径(根演示文稿文件)、headmatter(来自 md 文件),以及自 v0.48.0 起提供的 mode(dev、build 或 export)。你可以利用这些信息(例如根据演示文稿文件或是否导出 PDF 来启用扩展)。 - 函数必须返回一组 preparser 扩展。 - 每个扩展可以包含: - transformRawLines(lines) 函数:在解析 md 文件的 headmatter 后立即执行,接收所有行的列表(来自 md 文件),可以任意修改该列表。 - transformSlide(content, frontmatter) 函数:在文件拆分后对每张幻灯片调用,接收幻灯片内容(字符串)和该幻灯片的 frontmatter(对象)。可以修改 frontmatter,必须返回内容字符串(可修改,未修改时也可返回 undefined)。 - transformNote(note, frontmatter) 函数:在文件拆分后对每张幻灯片调用,接收幻灯片备注(字符串或 undefined)和该幻灯片的 frontmatter(对象)。可以修改 frontmatter,必须返回备注字符串(可修改,未修改时也可返回 undefined)。 - 一个 name

Preparser 扩展示例 ​

用例 1:顶层演示文稿的紧凑语法 ​

设想你的演示文稿(或其中一部分)主要是展示封面图并引入其他 md 文件,你可能希望用更紧凑的写法,例如 slides.md(的一部分)如下:

```md @cover: /nice.jpg

Welcome

@src: page1.md

@src: page2.md

@cover: /break.jpg

@src: pages3-4.md

@cover: https://cover.sli.dev

Questions?

see you next time ```

要支持这种 @src: 和 @cover: 语法,创建 ./setup/preparser.ts 文件,内容如下:

./setup/preparser.ts ts

```ts import { definePreparserSetup } from '@slidev/types'

export default definePreparserSetup(() => { return [ { transformRawLines(lines) { let i = 0 while (i < lines.length) { const l = lines[i] if (/^@cover:/i.test(l)) { lines.splice( i, 1, '---', 'layout: cover', `background: ${l.replace(/^@cover: */i, '')}`, '---', '' ) continue } if (/^@src:/i.test(l)) { lines.splice( i, 1, '---', `src: ${l.replace(/^@src: */i, '')}`, '---', '' ) continue } i++ } } }, ] }) ```

这样就完成了。

用例 2:用自定义 frontmatter 包装幻灯片 ​

设想你经常想缩放某些幻灯片,但又想继续使用各种现有布局,因此新建一个布局并不合适。例如你可能想这样写 slides.md:

```md --- layout: quote _scale: 0.75 ---

Welcome

> great!

--- _scale: 4 --- # Break

---

Ok

--- layout: center _scale: 2.5 --- # Questions? see you next time ```

这里在 scale 前加了下划线(_scale),是为了避免与现有 frontmatter 属性冲突(确实,不带下划线的 scale 可能引发问题)。

要处理 frontmatter 中的 _scale: ... 语法,创建 ./setup/preparser.ts 文件,内容如下:

./setup/preparser.ts ts

```ts import { definePreparserSetup } from '@slidev/types'

export default definePreparserSetup(() => { return [ { async transformSlide(content, frontmatter) { if ('_scale' in frontmatter) { return [ ``, '', content, '', '' ].join('\n') } }, }, ] }) ```

这样就完成了。

用例 3:用自定义 frontmatter 转换备注 ​

设想你想用自定义内容替换幻灯片的默认备注。例如你可能想这样写 slides.md:

```md --- layout: quote _note: notes/note.md ---

Welcome

> great!

```

这里在 note 前加了下划线(_note),是为了避免与现有 frontmatter 属性冲突。

要处理 frontmatter 中的 _note: ... 语法,创建 ./setup/preparser.ts 文件,内容如下:

./setup/preparser.ts ts

```ts import fs, { promises as fsp } from 'node:fs' import { definePreparserSetup } from '@slidev/types'

export default definePreparserSetup(() => { return [ { async transformNote(note, frontmatter) { if ('_note' in frontmatter && fs.existsSync(frontmatter._note)) { try { const newNote = await fsp.readFile(frontmatter._note, 'utf8') return newNote } catch (err) { } }

return note }, }, ] }) ```

评论 (0)