Docz 接入 gatsby-remark-vscode用 VSCode 主题替换默认 Prism 代码高亮【免费下载链接】docz✍ It has never been so easy to document your things!项目地址: https://gitcode.com/gh_mirrors/do/docz本文基于 docz 仓库中的 with-gatsby-remark-vscode 示例 展开完整讲解如何在 Docz 文档站中集成 gatsby-remark-vscode 插件让 markdown 内嵌代码块以 VSCode 的 TextMate 语法高亮与主题风格渲染。读完本文你将掌握示例项目的安装/运行/构建全流程、Docz 中两类代码块的本质区别以及通过 Gatsby 主题 shadowing 移除默认pre/code组件的三步配置法并理解其背后的 MDXProvider 渲染机制。背景为什么 Docz 需要 gatsby-remark-vscodeDocz 底层基于 Gatsby 构建其 markdown/mdx 内容中的代码块默认由主题提供的pre和code组件渲染Docz 内部使用 Prism 方案。而 gatsby-remark-vscode 是面向 Gatsby 的 remark 插件它把代码高亮任务从 Prism 切换到 VSCode 的语法高亮体系——使用 TextMate 语法做分词、以 VSCode 主题配色输出从而获得与编辑器一致的高亮效果。需要明确的是这个插件运行在Gatsby 构建期服务端只能处理静态的、被 remark 管线解析的代码块因此并不是 Docz 中所有代码都能被它接管这正是下一节要区分的核心问题。示例项目结构一览仓库中 examples/with-gatsby-remark-vscode 是一个最小可运行的完整示例其关键文件如下examples/with-gatsby-remark-vscode/ ├── doczrc.js # Docz 配置含 gatsbyRemarkPlugins ├── package.json # 依赖与 dev/build/serve 脚本 └── src/ ├── components/ │ ├── Alert.jsx # 示例组件 │ └── Alert.mdx # 含 markdown 代码块与 Playground 的文档 ├── gatsby-theme-docz/ │ └── components/ │ └── index.js # 主题 shadowing去掉 pre/code 组件 └── index.mdx # 首页文档演示 JS/JSX/TS 代码块其中 doczrc.js 已经预置了gatsbyRemarkPlugins配置shadowing 文件 也已就位你可以直接对照下文逐步理解每一处的作用。获取示例项目两种方式方式一使用 create-docz-app 脚手架原文档推荐通过官方脚手架创建然后在生成的工程内自行添加gatsby-remark-vscodenpx create-docz-app docz-app-with-gatsby-remark-vscode # or yarn create docz-app docz-app-with-gatsby-remark-vscode方式二手动下载示例目录原文档提供了直接从 docz 仓库提取该示例目录的命令curl https://codeload.github.com/doczjs/docz/tar.gz/main | tar -xz --strip2 docz-main/examples/with-gatsby-remark-vscode mv with-gatsby-remark-vscode docz-with-gatsby-remark-vscode-example cd docz-with-gatsby-remark-vscode-example也可以直接克隆仓库后从本地提取该目录git clone https://gitcode.com/gh_mirrors/do/docz cp -r docz/examples/with-gatsby-remark-vscode ./docz-with-gatsby-remark-vscode-example cd docz-with-gatsby-remark-vscode-example安装依赖yarn # npm i查看 examples/with-gatsby-remark-vscode/package.json示例依赖了doczlatest、gatsby-remark-vscode^1.4.0、react、react-dom以及prop-types并把docz dev/build/serve分别映射到 npm 脚本dev/build/serve。运行、构建与预览示例提供了完整的三段式工作流# 开发模式启动本地热更新文档服务 yarn dev # npm run dev # 生产构建输出静态站点 yarn build # npm run build # 预览构建产物即 docz serve yarn serve # npm run serveTutorialDocz 中的两类代码块原文档指出 Docz 中存在两类代码块这是理解本插件适用边界的关键第一类markdown 内嵌代码块即直接写在 mdx 文件中的围栏代码块js、jsx、ts 等。它们在构建期被 remark/mdx 管线解析为静态 HTML可以被 gatsby-remark-vscode 接管渲染。在 examples/with-gatsby-remark-vscode/src/index.mdx 中可以看到 JS、JSX、TypeScript 三种语言的内嵌代码块示例例如js const a abc; const b bca; console.log(${a}-${b}) 第二类Playground 组件中的代码通过Playground组件包裹的代码是可编辑且在前端客户端渲染的Playground {/* this code is editable by the user */} SomeComponent / /Playground由于这类代码块在浏览器中动态渲染、由用户实时编辑构建期的 remark 插件无法介入因此gatsby-remark-vscode 对 Playground 中的代码不生效。这是插件能力边界并非配置遗漏。示例中 Alert.mdx 即同时包含 markdown 内嵌 JS 代码块与Playground组件两种形态。接入 gatsby-remark-vscode 的三步配置第 1 步安装插件yarn add gatsby-remark-vscode第 2 步在 doczrc.js 中声明 gatsbyRemarkPlugins在你的doczrc.js中加入如下配置与示例 doczrc.js 完全一致export default { menu: [Getting Started, Components], gatsbyRemarkPlugins: [ { resolve: gatsby-remark-vscode, // OPTIONAL options: {}, }, ], }gatsbyRemarkPlugins是 Docz 透传给底层 Gatsby 的 remark 插件数组resolve指向插件包名options可传入 gatsby-remark-vscode 自身的参数如主题选择等不配置时使用插件默认值。第 3 步shadowing 移除默认的 pre / code 组件原文档特别提示仅完成前两步时站点是broken的。原因在于 Docz 主题默认通过 MDXProvider 向所有 mdx 内容注入pre和code组件基于 Prism 渲染它们与 gatsby-remark-vscode 的构建期输出发生冲突。必须通过 Gatsby 主题 shadowing 覆盖主题的组件导出把pre/code从 MDXProvider 的映射中拿掉把代码块渲染完全交给 gatsby-remark-vscode。在项目中创建src/gatsby-theme-docz/components/index.js路径与示例一致内容如下import * as headings from gatsby-theme-docz/src/components/Headings import { Layout } from gatsby-theme-docz/src/components/Layout import { Playground } from gatsby-theme-docz/src/components/Playground import { Props } from gatsby-theme-docz/src/components/Props export default { ...headings, playground: Playground, layout: Layout, props: Props, }这一文件的实际内容即 examples/with-gatsby-remark-vscode/src/gatsby-theme-docz/components/index.js。shadowing 的原理Gatsby 主题允许用户在src/gatsby-theme-docz/下放置与主题内部同路径的文件来覆盖主题实现。主题默认的组件映射位于 core/gatsby-theme-docz/src/components/index.js它导出了export default { ...headings, code: Code, // 默认代码组件Prism 渲染 playground: Playground, pre: Pre, // 默认代码块容器组件 layout: Layout, props: Props, }其中Pre的实现位于 core/gatsby-theme-docz/src/components/Pre/index.js仅是一个包裹children的div真正的 Prism 高亮逻辑由Code完成。shadow 文件刻意不再导出code与preMDXProvider 便不会为代码块注入 Prism 组件静态代码块的渲染权由此交还给 gatsby-remark-vscode。验证效果完成以上三步后运行yarn docz dev你会看到 mdx 中内嵌的 JS/JSX/TS 代码块以 VSCode 风格的高亮与主题呈现。同时请记住Playground 内的代码依然保持原有的可编辑、客户端渲染行为不受本插件影响。总结与注意事项适用边界gatsby-remark-vscode 只作用于 markdown 内嵌代码块构建期静态渲染对Playground组件的客户端可编辑代码不生效。冲突根源Docz 主题默认导出pre/code组件注入 MDXProvider必须通过 主题 shadowing 移除它们否则站点渲染会出错原文档称之为 broken。配置要点doczrc.js中的gatsbyRemarkPlugins数组按 Gatsby 插件规范书写options可选默认为插件自身行为。完整参考本示例的全部配置与文档源文件均可直接查看 examples/with-gatsby-remark-vscode主题默认组件映射可对照 core/gatsby-theme-docz/src/components/index.js将两者对比即可透彻理解 shadowing 的作用范围。【免费下载链接】docz✍ It has never been so easy to document your things!项目地址: https://gitcode.com/gh_mirrors/do/docz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考