Slidev 分页块级 Frontmatter（YAML 代码块写法）解析：语法、底层原理与适用边界

Slidev 分页块级 FrontmatterYAML 代码块写法解析语法、底层原理与适用边界【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidevBlock Frontmatter 是 Slidev 提供的第二种幻灯片元信息书写语法允许用 Markdown 围栏fenced代码块yaml取代---分隔符作为单页幻灯片的 frontmatter从而获得 YAML 语法高亮与格式化工具支持。本文以仓库 docs/features/block-frontmatter.md 为主线从概念、示例、解析器实现packages/parser/src/core.ts到与 Headmatter 的边界逐一拆解帮助你在不同场景下正确选择 frontmatter 写法。从 Frontmatter 与 Headmatter 说起在 docs/guide/syntax.md 的 Frontmatter Headmatter 一节中Slidev 把幻灯片slides.md里出现的 YAML 元信息分成两个概念Headmatter整个 Markdown 文件开头的第一个 frontmatter 块用于配置整份幻灯片主题、标题、字体、过渡动画、htmlAttrs、seoMeta等整份 deck 级选项。Frontmatter单页级其余每一页幻灯片开头的元信息块只作用于对应单页如该页的layout、clicks、background、class、transition等。两者可配置的全部默认项分别整理在 docs/custom/index.md 的## Slides Deck Configs#headmatter与## Per-slide Configs#frontmatter两节中。例如 deck 级有aspectRatio: 16/9、canvasWidth: 980、colorSchema: auto单页级有layout、background、clicksStart、routeAlias、src、title、level等。传统写法下frontmatter 与正文排版关系如下--- theme: seriph title: Welcome to Slidev --- # Slide 1 The frontmatter of this slide is also the headmatter --- layout: center background: /background-1.png class: text-white --- # Slide 2 --- # Slide 3传统写法的两个痛点与 Block Frontmatter 的引入---包裹的经典 frontmatter 写法足够简洁但有两个明显的体验短板这也是本页文档要解决的问题没有语法高亮在编辑器中---之间的 YAML 常被视为普通文本尤其当它位于幻灯片中间而不是 Markdown 文件头部时键值对层次一多就难以阅读缺少格式化支持主流的 Markdown 格式化工具Prettier 等通常只把「文件最开头、无空行紧跟的---...---」识别为可格式化的 frontmatter对嵌在文章中部、用于单页配置的---块无法稳定处理。仓库把 features/prettier-plugin 标记为本页的关联特性正是这一设计动机的体现。为此Slidev 引入Block Frontmatter用代码块语法承载单页的 YAML 元信息。由于它是标准 Markdown 代码块编辑器和 Prettier 都能正确高亮与格式化其中的 YAML。基本语法与示例把---/---替换成围栏代码块yaml与并把该块放在该页幻灯片内容的开头即可。文档给出的完整示例为--- theme: default --- # Slide 1 --- yaml layout: quote # Slide 2 --- # Slide 3需要特别注意示例中两个要点的叠加第 1 页使用经典---写法同时充当整个 deck 的Headmatter配置theme: default因为 Headmatter 只能用经典写法见下文「适用边界」第 2 页不使用---而是在其内容最前面用yaml代码块声明layout: quote即「块级 frontmatter」。yaml layout: quote 与经典写法完全等价--- layout: quote ---两者在语义上都是该页的 frontmatter可以被布局组件、$frontmatter见 docs/guide/global-context.md 中的说明等正常消费。代码块语言标注的细节源码中的识别正则给出了语言标注的精确范围const RE_YAML_CODEBLOCK /^\s*ya?ml([\s\S]*?)/即开头的围栏需要匹配yaml或yml两种标注之一ya?ml让a可选。如果你写成yaml或yml都能被识别为块级 frontmatter而其它语言标注如json则不会被当作 frontmatter而会被当作普通代码块渲染到页面上。底层实现解析器如何区分两种 frontmatter要想在生产环境放心混用两种写法值得理解 Slidev 解析器的真实处理顺序。相关逻辑集中在 packages/parser/src/core.ts。页面切分先按---分页、再按块识别parse()/parseSync()负责把 Markdown 按---行切成多页幻灯片core.ts 中的循环逻辑。关键在于该循环会跳过围栏代码块内部的内容// skip code block else if (line.trimStart().startsWith()) { const codeBlockLevel line.match(RE_LEADING_BACKTICKS)![0] let j i 1 for (; j lines.length; j) { if (lines[j].startsWith(codeBlockLevel)) break } if (j ! lines.length) i j }因此yaml块内部的任何---都不会被误判为分页符块级 frontmatter 不会干扰页面的切分边界。单页解析经典写法优先、YAML 块兜底matter()函数core.ts 的 matter 实现定义了两者的优先级function matter(code: string, options: SlidevParserOptions) { let type: FrontmatterStyle | undefined let raw: string | undefined let content code .replace(RE_FRONTMATTER, (_, f) { type frontmatter raw f return }) if (type ! frontmatter) { content content .replace(RE_YAML_CODEBLOCK, (_, f) { type yaml raw f return }) } ... }其中两个正则分别定义在文件顶部const RE_FRONTMATTER /^---.*\r?\n([\s\S]*?)---/ const RE_YAML_CODEBLOCK /^\s*ya?ml([\s\S]*?)/处理顺序可以概括为若幻灯片内容以---开头则按经典 frontmattertype frontmatter解析否则若以 YAML 代码块开头则按块级 frontmattertype yaml解析两套规则都不会命中时该页没有 frontmatter。parseSlide()会把识别结果写回幻灯片对象frontmatter, // 解析后的配置对象 frontmatterStyle: matterResult.type, // frontmatter | yaml | undefined frontmatterDoc: matterResult.doc, // YAML AST frontmatterRaw: matterResult.raw,见 core.ts 的 parseSlide 返回段也就是说两种写法的结果最终都会落到统一的frontmatter对象与FrontmatterStyle标记上后续的transformSlide扩展、标题推导、图片预加载等环节看到的都是同一份数据因此同一份 deck 中逐页混用两种写法在语义上完全等价。回写时保留块级写法prettifySlide()core.ts 中 prettifySlide 的实现在把幻灯片重新序列化时会依据frontmatterStyle决定输出形式data.raw data.frontmatterDoc?.contents ? data.frontmatterStyle yaml ? \\\yaml\n${data.frontmatterDoc.toString().trim()}\n\\\\n${data.content} : ---\n${data.frontmatterDoc.toString().trim()}\n---\n${data.content} : data.content当原写法是 YAML 代码块时格式化/回写仍会以yaml形式输出不会悄悄把用户的块级写法改回---。可以推断这一回写链路会被工具链如与块级 frontmatter 配套的 Prettier 插件复用以支持「格式化后仍保留作者偏好写法」的体验。适用边界为什么 Headmatter 不能使用块级写法原文档 用醒目的 warning 强调了一条硬性限制Headmatter in Slidev is exactly the usual frontmatter of a Markdown file, supported by most Markdown editors and formatters. So youcantuse a YAML block as the headmatter of the whole slide deck.把这段话拆成两层含义Headmatter 必须保持「经典 Markdown frontmatter」的身份。所谓 Headmatter本质就是 Markdown 文件最开头的---frontmatter——这是绝大多数编辑器、格式化器与解析器公认的语法。一旦改写成 YAML 代码块这些工具只会把它当成一个普通代码块语法高亮与格式化能力随之失效反而背离了引入块级写法的初衷。Slidev 内部对 headmatter 的识别同样依赖首行的经典---结构。在 packages/parser/src/fs.ts 中为了在真正解析前就能加载 preparser 扩展代码用两个严格正则从文件开头抓取 headmatterconst RE_FRONTMATTER_START /^---(?:[^-].*)?$/ const RE_FRONTMATTER_END /^---$/只有「第一行就是---且下一行非空」才会进入 headmatter 提取分支随后整份 deck 的全局配置由entry.slides[0]?.frontmatter汇总而来fs.ts 的 headmatter 汇总处。因此最终结论是整份 deck 级配置theme、fonts、title 等继续用文件顶部的---经典块书写块级 YAML frontmatter 面向的是「第二页及以后」的单页配置。第一条幻灯片若想携带单独的 frontmatter同样建议使用经典写法以保证其能被稳妥地当作 deck 起点处理。实践建议何时选择哪一种写法结合上面的解析顺序与边界可以给出清晰的选用准则deck 级配置Headmatter永远使用文件开头的经典---块。它承载theme、title、fonts、aspectRatio、transition、htmlAttrs、seoMeta等整份演示文稿配置并被编辑器、Prettier 与 Slidev 三方共同认可。普通单页配置两者皆可按可读性偏好选择。若你的幻灯片大量使用layout、class、background、clicks等单页字段块级写法能得到编辑器内真正的 YAML 高亮尤其当多个 frontmatter 字段嵌套较深时Prettier 等工具对代码块内容的格式化支持避免「文件中间出现游离---导致格式化器无从下手」的尴尬。混用是安全的解析器按「经典优先、YAML 块兜底、代码块内容自动跳过---切分」的顺序工作见 core.ts 的切分与 matter 实现并把两种写法统一成frontmatterStylefrontmatter的数据模型因此「首页经典 后续页块级」的组合正是官方文档推荐的典型形态。注意语言标注块级写法必须以yaml或yml开头否则不会被当作元信息。块必须位于该页内容最前正则^\s*要求代码块紧跟该页开头可容忍前导空白如果你在块前先写了一行普通 Markdown该页将不再命中块级 frontmatter。延伸阅读经典 frontmatter/headmatter 的完整写法与两者的差异Frontmatter Headmatterdeck 级与单页级配置项全量默认值Slides Deck Configs 与 Per-slide Configs面向 frontmatter 的代码格式化能力关联特性prettier-plugin解析器对 frontmatter 风格识别与回写的完整实现packages/parser/src/core.ts、packages/parser/src/fs.ts页面运行时读取当前页 frontmatter 的 API$frontmatter与currentFrontmatterglobal-context【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考