第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 [
`
这样就完成了。
用例 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 }, }, ] }) ```