前端静态站点Web框架【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址https://gitcode.com/gh_mirrors/ga/gatsby点击查看免费下载本篇指南以 Gatsby 官方示例站点 using-emotion-prismjs 及其核心示例文档 2017-10-16-code-highlighting/index.md 为主线讲解如何在 Gatsby 博客的 Markdown 中接入 PrismJS 完成代码语法高亮并用 Emotion 定制与 React 官方文档同款的深色高亮主题。读完本文你将掌握gatsby-remark-prismjs的完整配置、指令式行高亮写法、源码级渲染原理以及把该方案落地到自己的 Gatsby 站点中的全部步骤。一、示例文档与示例站点概览示例站点的核心内容是一篇带代码高亮的 Markdown 博文位于 examples/using-emotion-prismjs/src/pages/2017-10-16-code-highlighting/index.md。文件开头是标准的 YAML frontmatter声明了标题、描述、日期与路由--- title: Blog Post with Code Example description: Post containing a code example with syntax highlighting date: 2017-10-16T15:12:03.284Z path: /code-example/ ---正文则是一个标准的 fenced code block使用jsx语言标记渲染后由 PrismJS 完成语法高亮jsx function NumberList(props) { const numbers props.numbers const listItems numbers.map(number ( li key{number.toString()}{number}/li )) return ul{listItems}/ul } const numbers [1, 2, 3, 4, 5] ReactDOM.render( NumberList numbers{numbers} /, document.getElementById(root) ) 文档中明确说明该高亮主题与 React 官方文档使用的是同一套配色The highlight theme is the same one used in the official React documentation。同目录的姊妹篇 2017-10-17-code-highlighting-with-line-highlight/index.md 在相同代码块基础上加入了行高亮指令path为/code-example-line-highlighting/两篇合起来完整演示了「普通高亮 → 指定行高亮」的递进用法我们将在下文逐一还原。二、端到端数据流Markdown 如何变成高亮 HTML要理解这段代码块最终如何被着色需要沿着示例站点的数据管道走一遍数据源gatsby-config.js 中gatsby-source-filesystem把src/pages目录挂载为名为pages的源Markdown 解析gatsby-transformer-remark将.md文件解析为MarkdownRemark节点其plugins数组内的gatsby-remark-prismjs在这一阶段就把代码块转成高亮后的 HTML页面生成gatsby-node.js 通过 GraphQL 查询allMarkdownRemark逐条读取 frontmatter 中的path用createPage把每篇博文映射到模板 src/templates/blog-post.js渲染输出模板查询markdownRemark(frontmatter: { path: { eq: $path } })取得html字段通过dangerouslySetInnerHTML{{ __html: post.html }}注入页面见 blog-post.js。其中第 2 步是关键gatsby-remark-prismjs在构建期就完成高亮而非浏览器端因此最终产物是纯静态的带token类名的 HTML天然利于 SEO 与首屏性能。三、gatsby-config.js插件配置拆解示例站点的完整配置位于 gatsby-config.jsmodule.exports { siteMetadata: { title: Gatsby with Emotion and PrismJS, }, plugins: [ { resolve: gatsby-source-filesystem, options: { path: ${__dirname}/src/pages, name: pages, }, }, { resolve: gatsby-transformer-remark, options: { plugins: [ gatsby-plugin-emotion, { resolve: gatsby-remark-prismjs, options: { classPrefix: language-jsx, }, }, ], }, }, { resolve: gatsby-plugin-typography, options: { pathToConfigModule: src/utils/typography, }, }, { resolve: gatsby-plugin-google-analytics, options: { trackingId: UA-93349937-2, }, }, gatsby-plugin-react-helmet, ], }需要注意三个细节gatsby-remark-prismjs必须嵌套在gatsby-transformer-remark的plugins数组中因为它本质上是 remark 的插件按数组顺序在 Markdown 解析流水线中执行见 packages/gatsby-remark-prismjs/src/index.js 对code节点的visit。示例把gatsby-plugin-emotion也放在 remark 插件列表里用于在解析阶段处理 JSX 内联样式相关的 Babel 转换Emotion 的运行时样式如css模板字符串则由 src/prism-styles.js 通过injectGlobal全局注入并在 layout.js 中import ../prism-styles加载。classPrefix: language-jsx是示例特意设置的默认值是language-。源码注释解释了动机——允许自定义类前缀避免站点在浏览器端还加载了 Prism 时Prism 误把已经高亮过的pre再次处理对应 issue 讨论见 packages/gatsby-remark-prismjs/src/index.js。四、主题样式prism-styles.js 与 React 文档同款配色文档所述「React 官方文档同款主题」的具体实现就在 src/prism-styles.js。它定义了两组颜色容器色dark: #282c34One Dark 风格背景、white: #fffffftoken 色板prismColorskeyword: #c5a5c5、string: #8dc891、function: #79b6f2、className: #FAC863、operator: #fc929e、comment: #999999、punctuation: #5FB3B3等十余项。随后用injectGlobal一次性注入全局样式其中最关键的结构是插件生成的.gatsby-highlight容器.gatsby-highlight { background: #282c34; color: #ffffff; border-radius: 1em; overflow: auto; tab-size: 1.5em; padding: 1em; margin: 1em 0; }其余规则把 PrismJS 输出的.token.*类名逐一映射到色板例如.token.comment使用#999999、.token.function使用#79b6f2、.token.class-name使用#FAC863等。此外还包含.gatsby-highlight-code-line行高亮背景样式lineHighlight: #14161a下一节会看到它对应的 HTML 结构。需要说明的是PrismJS 本身自带多套官方主题如prism-solarizedlight在gatsby-browser.js里require(prismjs/themes/prism-solarizedlight.css)即可换肤示例站点选择的是完全自定义方案——不引入 Prism 自带主题而是针对gatsby-remark-prismjs生成的固定类名自行着色可控性更强。五、指令式行高亮highlight-line / highlight-start / highlight-end姊妹篇文档 2017-10-17-code-highlighting-with-line-highlight/index.md 演示了行高亮写法它把// highlight-line、// highlight-start、// highlight-end作为注释写进代码块jsx function NumberList(props) { // highlight-line const numbers props.numbers const listItems numbers.map(number ( // highlight-start li key{number.toString()}{number}/li )) // highlight-end return ul{listItems}/ul } const numbers [1, 2, 3, 4, 5] ReactDOM.render( NumberList numbers{numbers} /, document.getElementById(root) ) gatsby-remark-prismjs支持四类高亮指令directives.js 中通过createDirectiveRegExp生成匹配规则highlight-line高亮当前行highlight-next-line高亮下一行highlight-start/highlight-end高亮两标记之间的所有行highlight-range{1, 4-6}按数字区间高亮相对行行号解析依赖parse-numeric-range包1, 4-6表示第 1 行以及第 4、5、6 行。还可以把区间直接写进语言标记外部例如javascript{1,4-6}表示高亮第 1 行和第 46 行——此时解析逻辑走的是 parse-options.js 对{...}的花括号解析分支。高亮行的底层实现从源码看高亮处理发生在 Prism 完成分词之后highlight-code.js 先Prism.highlight再handleDirectives。directives.js 的做法是用正则剥离指令注释本身包括 Prism 为{/*、!--生成的span classtoken comment包裹见stripComment对被标记的行套上span classgatsby-highlight-code-line包裹遇到 JSX/注释中跨行的多行 token先把一个span拆成多个再处理避免行高亮错位。生成的 HTML 结构由 index.js 拼装div classgatsby-highlight has-highlighted-lines>npm install gatsby-transformer-remark gatsby-remark-prismjs prismjs按代码块级联的选项numberLines 与 shell 提示符行号、输出行等可以只作用于单个代码块。语法是把选项写进语言标记的花括号中选项顺序任意解析逻辑见 parse-options.jsjavascript{numberLines: true}显示行号{numberLines: 5}则从第 5 行开始编号shell{outputLines: 2-10,12}只有第 210、12 行显示为输出shell{promptUser: alice}{promptHost: dev.localhost}覆盖全局prompt的用户名与主机名只对bash/shell语言生效的提示符满足prompt.global为真、或块级给出outputLines/promptUser/promptHost之一时启用index.js。diff 高亮、隐藏行、行内代码与禁用高亮diff用diff-javascript标记即可获得 diff 风格的增删着色匹配正则见 index.js。隐藏行与高亮指令对称提供hide-line、hide-next-line、hide-start/hide-end、hide-range{1,4-6}常用于配合gatsby-remark-embed-snippet引用代码片段时隐藏多余行。行内代码默认情况下反引号代码也会过 Prism 高亮inlineCode分支index.js设置inlineCodeMarker后可给行内代码指定语言。彻底禁用把语言写成none内容将原样输出、不做任何转义与高亮highlight-code.js。七、源码实现要点按需加载语言与「构建期高亮」的取舍highlight-code.js 揭示了两个实现细节语言按需加载Prism.highlight之前会检查Prism.languages[language]不存在时调用loadPrismLanguage动态加载加载失败则回退为「仅 HTML 转义」的通用代码块并打印unable to find prism language ... applying generic code block警告不会中断构建highlight-code.js。为何自研行高亮而非用 Prism 官方插件README 的 Implementation notes 明确说明PrismJS 的 line-highlight 插件是面向浏览器端运行时的且其实现无法支撑「溢出部分也铺满背景色」的全宽高亮gatsby-remark-prismjs参考 Pygments 系React 文档的实现改用div.gatsby-highlight包裹 span.gatsby-highlight-code-line行包裹 float:left; min-width:100%的 CSS 组合来达成效果。仓库中还为这些特性准备了成体系的测试夹具例如 highlight-start-end.jshighlight-start/end块、highlight-line.js、highlight-next-line.js、highlight-range.js、hide-line.js等对应快照文件位于 packages/gatsby-remark-prismjs/src/tests/snapshots可作为理解各指令输出格式的参考。八、在本地运行该示例示例站点的脚本定义在 package.jsonscripts: { develop: gatsby develop, build: gatsby build, start: npm run develop }在examples/using-emotion-prismjs目录下依次执行npm install npm run develop浏览器打开开发服务器后可访问/code-example/与/code-example-line-highlighting/两篇文章对比普通高亮与行高亮的效果差异npm run build可产出静态文件验证构建期高亮产物。要复用到自己的项目只需三步安装gatsby-transformer-remark、gatsby-remark-prismjs、prismjs把插件按本文第三节方式挂进gatsby-transformer-remark的plugins数组再引入一份 Prism 主题官方主题或仿照 prism-styles.js 自写 token 样式即可。九、小结以 2017-10-16-code-highlighting/index.md 为入口可以清晰看到 Gatsby 博客代码高亮的完整链路gatsby-source-filesystem收集 Markdown →gatsby-transformer-remarkgatsby-remark-prismjs在构建期完成 PrismJS 分词与指令解析 → 模板通过dangerouslySetInnerHTML输出高亮 HTML → Emotion 全局样式负责着色。classPrefix、行高亮指令、{numberLines}等花括号选项则提供了从「整块高亮」到「指定行高亮、行号、shell 提示符」的精细控制。这套方案在构建期完成高亮、不依赖浏览器端脚本配合自定义主题即可轻松复刻 React 官方文档级别的代码展示效果。赞分享前端静态站点Web框架【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址https://gitcode.com/gh_mirrors/ga/gatsby点击查看免费下载相关推荐使用 gatsby-remark-prismjs 在 Gatsby 中实现代码与语法高亮完整配置与实现原理使用 gatsby remark prismjs 在 Gatsby 中实现代码与语法高亮完整配置与实现原理 导读 本文基于 Gatsby 官方示例站点 exa前端静态站点Web框架在 Gatsby 中使用 Emotion基于 using-emotion 示例的 CSS-in-JS 实战指南在 Gatsby 中使用 Emotion基于 using emotion 示例的 CSS in JS 实战指南 导读 本文以仓库内 examples/usin前端静态站点Web框架Gatsby 使用 gatsby-transformer-remark 构建 Markdown 博客using-remark 示例站点全解析Gatsby 使用 gatsby transformer remark 构建 Markdown 博客using remark 示例站点全解析 本文以 Gats前端静态站点Web框架创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/21 18:14:40 · 阅读 1.2k Gatsby 中借助 gatsby-remark-prismjs 与 Emotion 实现 Markdown 代码高亮：using-emotion-prismjs 实战解析
前端静态站点Web框架【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址https://gitcode.com/gh_mirrors/ga/gatsby点击查看免费下载本篇指南以 Gatsby 官方示例站点 using-emotion-prismjs 及其核心示例文档 2017-10-16-code-highlighting/index.md 为主线讲解如何在 Gatsby 博客的 Markdown 中接入 PrismJS 完成代码语法高亮并用 Emotion 定制与 React 官方文档同款的深色高亮主题。读完本文你将掌握gatsby-remark-prismjs的完整配置、指令式行高亮写法、源码级渲染原理以及把该方案落地到自己的 Gatsby 站点中的全部步骤。一、示例文档与示例站点概览示例站点的核心内容是一篇带代码高亮的 Markdown 博文位于 examples/using-emotion-prismjs/src/pages/2017-10-16-code-highlighting/index.md。文件开头是标准的 YAML frontmatter声明了标题、描述、日期与路由--- title: Blog Post with Code Example description: Post containing a code example with syntax highlighting date: 2017-10-16T15:12:03.284Z path: /code-example/ ---正文则是一个标准的 fenced code block使用jsx语言标记渲染后由 PrismJS 完成语法高亮jsx function NumberList(props) { const numbers props.numbers const listItems numbers.map(number ( li key{number.toString()}{number}/li )) return ul{listItems}/ul } const numbers [1, 2, 3, 4, 5] ReactDOM.render( NumberList numbers{numbers} /, document.getElementById(root) ) 文档中明确说明该高亮主题与 React 官方文档使用的是同一套配色The highlight theme is the same one used in the official React documentation。同目录的姊妹篇 2017-10-17-code-highlighting-with-line-highlight/index.md 在相同代码块基础上加入了行高亮指令path为/code-example-line-highlighting/两篇合起来完整演示了「普通高亮 → 指定行高亮」的递进用法我们将在下文逐一还原。二、端到端数据流Markdown 如何变成高亮 HTML要理解这段代码块最终如何被着色需要沿着示例站点的数据管道走一遍数据源gatsby-config.js 中gatsby-source-filesystem把src/pages目录挂载为名为pages的源Markdown 解析gatsby-transformer-remark将.md文件解析为MarkdownRemark节点其plugins数组内的gatsby-remark-prismjs在这一阶段就把代码块转成高亮后的 HTML页面生成gatsby-node.js 通过 GraphQL 查询allMarkdownRemark逐条读取 frontmatter 中的path用createPage把每篇博文映射到模板 src/templates/blog-post.js渲染输出模板查询markdownRemark(frontmatter: { path: { eq: $path } })取得html字段通过dangerouslySetInnerHTML{{ __html: post.html }}注入页面见 blog-post.js。其中第 2 步是关键gatsby-remark-prismjs在构建期就完成高亮而非浏览器端因此最终产物是纯静态的带token类名的 HTML天然利于 SEO 与首屏性能。三、gatsby-config.js插件配置拆解示例站点的完整配置位于 gatsby-config.jsmodule.exports { siteMetadata: { title: Gatsby with Emotion and PrismJS, }, plugins: [ { resolve: gatsby-source-filesystem, options: { path: ${__dirname}/src/pages, name: pages, }, }, { resolve: gatsby-transformer-remark, options: { plugins: [ gatsby-plugin-emotion, { resolve: gatsby-remark-prismjs, options: { classPrefix: language-jsx, }, }, ], }, }, { resolve: gatsby-plugin-typography, options: { pathToConfigModule: src/utils/typography, }, }, { resolve: gatsby-plugin-google-analytics, options: { trackingId: UA-93349937-2, }, }, gatsby-plugin-react-helmet, ], }需要注意三个细节gatsby-remark-prismjs必须嵌套在gatsby-transformer-remark的plugins数组中因为它本质上是 remark 的插件按数组顺序在 Markdown 解析流水线中执行见 packages/gatsby-remark-prismjs/src/index.js 对code节点的visit。示例把gatsby-plugin-emotion也放在 remark 插件列表里用于在解析阶段处理 JSX 内联样式相关的 Babel 转换Emotion 的运行时样式如css模板字符串则由 src/prism-styles.js 通过injectGlobal全局注入并在 layout.js 中import ../prism-styles加载。classPrefix: language-jsx是示例特意设置的默认值是language-。源码注释解释了动机——允许自定义类前缀避免站点在浏览器端还加载了 Prism 时Prism 误把已经高亮过的pre再次处理对应 issue 讨论见 packages/gatsby-remark-prismjs/src/index.js。四、主题样式prism-styles.js 与 React 文档同款配色文档所述「React 官方文档同款主题」的具体实现就在 src/prism-styles.js。它定义了两组颜色容器色dark: #282c34One Dark 风格背景、white: #fffffftoken 色板prismColorskeyword: #c5a5c5、string: #8dc891、function: #79b6f2、className: #FAC863、operator: #fc929e、comment: #999999、punctuation: #5FB3B3等十余项。随后用injectGlobal一次性注入全局样式其中最关键的结构是插件生成的.gatsby-highlight容器.gatsby-highlight { background: #282c34; color: #ffffff; border-radius: 1em; overflow: auto; tab-size: 1.5em; padding: 1em; margin: 1em 0; }其余规则把 PrismJS 输出的.token.*类名逐一映射到色板例如.token.comment使用#999999、.token.function使用#79b6f2、.token.class-name使用#FAC863等。此外还包含.gatsby-highlight-code-line行高亮背景样式lineHighlight: #14161a下一节会看到它对应的 HTML 结构。需要说明的是PrismJS 本身自带多套官方主题如prism-solarizedlight在gatsby-browser.js里require(prismjs/themes/prism-solarizedlight.css)即可换肤示例站点选择的是完全自定义方案——不引入 Prism 自带主题而是针对gatsby-remark-prismjs生成的固定类名自行着色可控性更强。五、指令式行高亮highlight-line / highlight-start / highlight-end姊妹篇文档 2017-10-17-code-highlighting-with-line-highlight/index.md 演示了行高亮写法它把// highlight-line、// highlight-start、// highlight-end作为注释写进代码块jsx function NumberList(props) { // highlight-line const numbers props.numbers const listItems numbers.map(number ( // highlight-start li key{number.toString()}{number}/li )) // highlight-end return ul{listItems}/ul } const numbers [1, 2, 3, 4, 5] ReactDOM.render( NumberList numbers{numbers} /, document.getElementById(root) ) gatsby-remark-prismjs支持四类高亮指令directives.js 中通过createDirectiveRegExp生成匹配规则highlight-line高亮当前行highlight-next-line高亮下一行highlight-start/highlight-end高亮两标记之间的所有行highlight-range{1, 4-6}按数字区间高亮相对行行号解析依赖parse-numeric-range包1, 4-6表示第 1 行以及第 4、5、6 行。还可以把区间直接写进语言标记外部例如javascript{1,4-6}表示高亮第 1 行和第 46 行——此时解析逻辑走的是 parse-options.js 对{...}的花括号解析分支。高亮行的底层实现从源码看高亮处理发生在 Prism 完成分词之后highlight-code.js 先Prism.highlight再handleDirectives。directives.js 的做法是用正则剥离指令注释本身包括 Prism 为{/*、!--生成的span classtoken comment包裹见stripComment对被标记的行套上span classgatsby-highlight-code-line包裹遇到 JSX/注释中跨行的多行 token先把一个span拆成多个再处理避免行高亮错位。生成的 HTML 结构由 index.js 拼装div classgatsby-highlight has-highlighted-lines>npm install gatsby-transformer-remark gatsby-remark-prismjs prismjs按代码块级联的选项numberLines 与 shell 提示符行号、输出行等可以只作用于单个代码块。语法是把选项写进语言标记的花括号中选项顺序任意解析逻辑见 parse-options.jsjavascript{numberLines: true}显示行号{numberLines: 5}则从第 5 行开始编号shell{outputLines: 2-10,12}只有第 210、12 行显示为输出shell{promptUser: alice}{promptHost: dev.localhost}覆盖全局prompt的用户名与主机名只对bash/shell语言生效的提示符满足prompt.global为真、或块级给出outputLines/promptUser/promptHost之一时启用index.js。diff 高亮、隐藏行、行内代码与禁用高亮diff用diff-javascript标记即可获得 diff 风格的增删着色匹配正则见 index.js。隐藏行与高亮指令对称提供hide-line、hide-next-line、hide-start/hide-end、hide-range{1,4-6}常用于配合gatsby-remark-embed-snippet引用代码片段时隐藏多余行。行内代码默认情况下反引号代码也会过 Prism 高亮inlineCode分支index.js设置inlineCodeMarker后可给行内代码指定语言。彻底禁用把语言写成none内容将原样输出、不做任何转义与高亮highlight-code.js。七、源码实现要点按需加载语言与「构建期高亮」的取舍highlight-code.js 揭示了两个实现细节语言按需加载Prism.highlight之前会检查Prism.languages[language]不存在时调用loadPrismLanguage动态加载加载失败则回退为「仅 HTML 转义」的通用代码块并打印unable to find prism language ... applying generic code block警告不会中断构建highlight-code.js。为何自研行高亮而非用 Prism 官方插件README 的 Implementation notes 明确说明PrismJS 的 line-highlight 插件是面向浏览器端运行时的且其实现无法支撑「溢出部分也铺满背景色」的全宽高亮gatsby-remark-prismjs参考 Pygments 系React 文档的实现改用div.gatsby-highlight包裹 span.gatsby-highlight-code-line行包裹 float:left; min-width:100%的 CSS 组合来达成效果。仓库中还为这些特性准备了成体系的测试夹具例如 highlight-start-end.jshighlight-start/end块、highlight-line.js、highlight-next-line.js、highlight-range.js、hide-line.js等对应快照文件位于 packages/gatsby-remark-prismjs/src/tests/snapshots可作为理解各指令输出格式的参考。八、在本地运行该示例示例站点的脚本定义在 package.jsonscripts: { develop: gatsby develop, build: gatsby build, start: npm run develop }在examples/using-emotion-prismjs目录下依次执行npm install npm run develop浏览器打开开发服务器后可访问/code-example/与/code-example-line-highlighting/两篇文章对比普通高亮与行高亮的效果差异npm run build可产出静态文件验证构建期高亮产物。要复用到自己的项目只需三步安装gatsby-transformer-remark、gatsby-remark-prismjs、prismjs把插件按本文第三节方式挂进gatsby-transformer-remark的plugins数组再引入一份 Prism 主题官方主题或仿照 prism-styles.js 自写 token 样式即可。九、小结以 2017-10-16-code-highlighting/index.md 为入口可以清晰看到 Gatsby 博客代码高亮的完整链路gatsby-source-filesystem收集 Markdown →gatsby-transformer-remarkgatsby-remark-prismjs在构建期完成 PrismJS 分词与指令解析 → 模板通过dangerouslySetInnerHTML输出高亮 HTML → Emotion 全局样式负责着色。classPrefix、行高亮指令、{numberLines}等花括号选项则提供了从「整块高亮」到「指定行高亮、行号、shell 提示符」的精细控制。这套方案在构建期完成高亮、不依赖浏览器端脚本配合自定义主题即可轻松复刻 React 官方文档级别的代码展示效果。赞分享前端静态站点Web框架【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址https://gitcode.com/gh_mirrors/ga/gatsby点击查看免费下载相关推荐使用 gatsby-remark-prismjs 在 Gatsby 中实现代码与语法高亮完整配置与实现原理使用 gatsby remark prismjs 在 Gatsby 中实现代码与语法高亮完整配置与实现原理 导读 本文基于 Gatsby 官方示例站点 exa前端静态站点Web框架在 Gatsby 中使用 Emotion基于 using-emotion 示例的 CSS-in-JS 实战指南在 Gatsby 中使用 Emotion基于 using emotion 示例的 CSS in JS 实战指南 导读 本文以仓库内 examples/usin前端静态站点Web框架Gatsby 使用 gatsby-transformer-remark 构建 Markdown 博客using-remark 示例站点全解析Gatsby 使用 gatsby transformer remark 构建 Markdown 博客using remark 示例站点全解析 本文以 Gats前端静态站点Web框架创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考