Storybook 文档页自定义语法高亮用 react-syntax-highlighter 为 MDX 文档添加 SCSS 高亮支持【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本篇技术指南聚焦 Storybook 的 MDX 文档页面如何接入自定义语法高亮方案以仓库中的官方示例片段 my-component-with-custom-syntax-highlight.md 为核心完整讲解如何在单个文档页内通过react-syntax-highlighter的 Prism 引擎为 SCSS 等默认不支持的语言启用高亮并结合 Storybook 核心源码说明内置高亮器的语言注册机制与可替换点。读完后你将掌握单页级自定义高亮的完整写法、全局注册语言的替代路径以及两种方案在源码层面的对应关系。背景Storybook 内置语法高亮的覆盖范围与限制Storybook 的 Docs 页面默认会对代码块进行语法高亮。从核心源码 syntaxhighlighter.tsx 可以看到Storybook 内部的高亮组件基于react-syntax-highlighter的PrismLight构建并预注册了如下语言集合export const supportedLanguages { jsextra: jsExtras, jsx, json, yml, md, bash, css, html, tsx, typescript, graphql, }; Object.entries(supportedLanguages).forEach(([key, val]) { ReactSyntaxHighlighter.registerLanguage(key, val); });即默认支持 JavaScript/JSX、TypeScript/TSX、JSON、YAML、Markdown、Bash、CSS、HTML、GraphQL。需要特别注意的是SCSS 并不在默认语言列表中因此 Markdown 文档中写出的scss代码块不会被自动高亮。FAQ 中对此也有明确说明内置高亮覆盖 JS、Markdown、CSS、HTML、TypeScript、GraphQL 等语言而通过 API 注册自定义语言存在已知限制见 docs/faq.mdx 中 syntax highlight 相关条目。正因如此官方示例给出了在单个 MDX 文档内直接引入 react-syntax-highlighter 自带高亮器的自包含方案——这也是本文要展开的主题。单页自定义高亮的完整示例以下示例来自 my-component-with-custom-syntax-highlight.md演示在一个名为MyComponent.mdx的文档页中为 SCSS 代码块启用高亮。注意原片段中用双引号包裹的 SCSS 代码块是文档站渲染片段时的占位写法拷贝到你自己项目时必须还原为三个反引号。import { Meta } from storybook/addon-docs/blocks; import { Prism as SyntaxHighlighter } from react-syntax-highlighter; Meta titleA Storybook doc with a custom syntax highlight for SCSS / # SCSS example This is a sample SCSS code block example highlighted in Storybook scss $font-stack: Helvetica, sans-serif; $primary-color: #333; body { font: 100% $font-stack; color: $primary-color; }export const Component () { return ; };示例中逐行说明三个关键要素 **1. 从 addon-docs 导入 Meta 设置文档元信息** mdx import { Meta } from storybook/addon-docs/blocks; Meta titleA Storybook doc with a custom syntax highlight for SCSS /Meta用于声明该文档页的 title使自定义高亮文档可以独立于任何组件存在标题 A Storybook doc with a custom syntax highlight for SCSS 即为此例的文档页名称。2. 直接导入 react-syntax-highlighter 的 Prism 高亮器import { Prism as SyntaxHighlighter } from react-syntax-highlighter;这里把Prism别名导入为SyntaxHighlighter。示例中的注释特意强调这一点是有意为之The usage of this Component is intentional to enable react-syntax-highlighters own highlighterStorybook 的核心组件与react-syntax-highlighter使用同一个 PrismLight 运行时因此在 MDX 页面中显式渲染SyntaxHighlighter/能直接激活该库自身的高亮管线而不是依赖 Storybook 封装层的默认行为。3. 导出Component组件以激活高亮器export const Component () { return SyntaxHighlighter/; };在 MDX 文档页中导出的Component会被渲染在文档主体位置。返回一个空的SyntaxHighlighter/组件本身就是目的所在——它让 Prism 高亮器在该页面上下文中生效从而页面上的scss代码块得以按其内置语言定义被着色。4. 被高亮的 SCSS 代码块$font-stack: Helvetica, sans-serif; $primary-color: #333; body { font: 100% $font-stack; color: $primary-color; }这是一个典型的 SCSS 片段变量定义 嵌套引用用来验证 SCSS 语法$开头的变量、颜色值、选择器能够被正确着色而不再是纯文本样式。源码印证为什么替换高亮器是可行的从核心实现看Storybook 的 SyntaxHighlighter 组件 内部就是包装了react-syntax-highlighter/dist/esm/prism-light组件在挂载时通过ReactSyntaxHighlighter.registerLanguage(key, val)逐个注册内置语言syntaxhighlighter.tsx同时对外暴露了SyntaxHighlighter.registerLanguage静态方法直接转发到 PrismLight 的注册接口syntaxhighlighter.tsxSyntaxHighlighter.registerLanguage ( ...args: Parameterstypeof ReactSyntaxHighlighter.registerLanguage ) ReactSyntaxHighlighter.registerLanguage(...args);组件的 props 类型定义在 syntaxhighlighter-types.ts其中SupportedLanguage text | keyof typeof supportedLanguages——也就是说未注册的语言会退化为text这正是 SCSS 代码块默认不高亮的根因。由于底层与文档页示例共用同一套 Prism 运行时示例中直接渲染 react-syntax-highlighter 的SyntaxHighlighter/才能与文档页面的渲染环境协同工作。替代方案在 preview 中全局注册语言如果你的目标不是单页自定义而是让整个 Storybook 的所有文档页都支持某语言如 SCSS可以在.storybook/preview文件中全局注册。仓库中对应的示例片段为 storybook-preview-register-language-globally.md核心写法为// .storybook/preview.ts import { PrismLight as SyntaxHighlighter } from react-syntax-highlighter; import scss from react-syntax-highlighter/dist/esm/languages/prism/scss; // Registers and enables scss language support SyntaxHighlighter.registerLanguage(scss, scss);该片段同时提供了 JS/TS、CSF 3 与 CSF NextdefinePreview、以及 React/Vue/Angular/Web Components 等各框架的变体。而配套的纯文档效果示例见 my-component-with-global-syntax-highlight.md——其中 SCSS 代码块无需在文档页内做任何 import 或导出直接写scss即可高亮。两种方案的取舍可以归纳为方案作用域改动位置适用场景MDX 页面内引入SyntaxHighlighter/本文主方案单个文档页目标.mdx文件只有一两页需要特殊语言高亮不想改动全局配置preview 中registerLanguage全部文档页.storybook/preview.(ts\|js)团队统一需要某语言如 SCSS/LESS高亮此外Docs 中Source文档块也支持通过language参数指定高亮语言见 doc-block-source.mdx但其可选语言同样受限于 Prism 运行时已注册的语言集合——这与前文源码分析相互印证。实操注意事项语言键名必须与注册名一致Prism 是按字符串键如scss、css匹配高亮器的代码块标注的语言名写错会静默退化为纯文本。默认语言表不含 SCSS/LESS内置集合只有 css 而无 scss任何 SCSS 高亮都依赖显式注册或本文的页面级方案。主题样式跟随 Storybook 主题核心高亮组件通过theme.code映射生成 Prism 样式syntaxhighlighter.tsx切换 Storybook 主题亮/暗时代码块配色会随之变化无需额外配置。MDX 转义细节示例片段源码中以代替是文档仓库自身的占位约定避免嵌套代码块截断实际项目中请使用标准 Markdown 围栏语法。组件渲染容错核心SyntaxHighlighter组件在children非字符串或为空时会直接返回nullsyntaxhighlighter.tsx即空代码块不会报错也不会渲染高亮容器排查代码块没高亮时可先检查内容是否为空字符串。小结本文围绕 Storybook 官方示例 my-component-with-custom-syntax-highlight.md 展开讲解了在 MDX 文档页内通过react-syntax-highlighter的Prism高亮器为 SCSS 启用自定义语法高亮的完整做法导入Meta声明文档页、导入Prism as SyntaxHighlighter并导出渲染它的Component、再配合标准scss代码块即可生效。结合 syntaxhighlighter.tsx 的源码可以看到该方案与 Storybook 内置高亮器共用 PrismLight 运行时而内置supportedLanguages集合不含 SCSS 这一事实也正是需要此类自定义方案的根本原因。若需要在整个项目中统一启用某语言则建议改用 storybook-preview-register-language-globally.md 所示的 preview 全局注册路径。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考