文档静态站点开发工具【免费下载链接】docz✍ It has never been so easy to document your things!项目地址https://gitcode.com/gh_mirrors/do/docz点击查看免费下载Docz 是一个基于 Gatsby 的文档站点生成器它通过 MDX 让你在 Markdown 中直接使用 React 组件。当文档中需要对外部链接、内部路由进行差异化处理例如外部链接自动在新标签页打开时examples/with-custom-links提供了一个极简且完整的官方示例。本文以该示例为骨架深入讲解 Docz 的 MDX 组件注入机制、gatsby-theme-docz的组件 Shadowing 原理以及如何自定义链接组件以满足真实项目需求。示例概览with-custom-links 要解决的问题在 MDX 文档中普通 Markdown 链接text会被渲染为a标签。默认情况下Docz 主题gatsby-theme-docz并未提供自定义的a组件因此所有链接都表现为标准行为。而examples/with-custom-links演示了如何通过 Shadowing 机制向 MDX 的组件映射component map中注入一个自定义的a组件从而实现对链接行为的完全控制。该示例的核心文件结构如下examples/with-custom-links/ ├── README.md # 本示例的说明文档 ├── package.json # 项目依赖与脚本 └── src/ ├── index.mdx # 示例文档页面 └── gatsby-theme-docz/ └── components/ └── index.js # Shadowing 目标覆盖主题的组件导出其中最关键的是src/gatsby-theme-docz/components/index.js它通过 Gatsby 主题的 Shadowing 能力重写了主题默认的组件映射为a链接提供了自定义实现。你可以在 示例的组件注入文件 中查看完整代码。获取并运行示例方式一使用create-docz-app脚手架推荐create-docz-app是 Docz 官方提供的脚手架工具支持--example参数直接拉取官方示例模板npx create-docz-app docz-app-with-custom-links --example with-custom-links # 或使用 yarn yarn create docz-app docz-app-with-custom-links --example with-custom-links方式二手动下载你也可以从仓库的examples目录中手动提取该示例curl https://codeload.github.com/doczjs/docz/tar.gz/main | tar -xz --strip2 docz-main/examples/with-custom-links mv with-custom-links docz-with-custom-links-example cd docz-with-custom-links-example注意手动下载方式直接从 docz 仓库的main分支提取examples/with-custom-links目录适用于需要离线查看或修改示例源码的场景。安装依赖示例项目使用 Yarn 作为包管理器npm 亦可yarn # 或 npm i启动开发服务器yarn dev # 或 npm run devdev命令对应docz dev见 示例的 package.json启动后即可在浏览器中预览文档站点。生产构建与预览yarn build # 或 npm run build # 执行 docz build生成静态站点 yarn serve # 或 npm run serve # 执行 docz serve本地预览构建产物从 package.json 可以看到示例的脚本定义非常精简{ scripts: { dev: docz dev, build: docz build, serve: docz serve }, dependencies: { docz: latest, prop-types: ^15.7.2, react: ^16.11.0, react-dom: ^16.11.0 } }其中docz包是核心依赖react/react-dom是运行 MDX 组件所必需的而prop-types则是 Docz 内部组件声明 props 类型所用的库。核心机制MDX 组件注入与 ShadowingMDX 的组件映射Component MapMDX 允许通过MDXProvider向所有 MDX 内容注入自定义组件映射。例如将a映射为自定义组件后Markdown 中的text就会被渲染为你的自定义组件而非默认的a。Docz 主题gatsby-theme-docz的组件索引文件 core/gatsby-theme-docz/src/components/index.js 导出了一个默认组件映射对象import * as headings from ./Headings import { Code } from ./Code import { Layout } from ./Layout import { Playground } from ./Playground import { Pre } from ./Pre import { Props } from ./Props export default { ...headings, // h1 ~ h6 等标题组件 code: Code, playground: Playground, pre: Pre, layout: Layout, props: Props, }可以看到主题默认映射中并没有a链接组件这正是示例需要自定义注入的原因。Shadowing覆盖主题的组件导出Gatsby 主题支持 Shadowing在你的站点源码中创建与主题组件相同相对路径的文件即可覆盖主题中的对应组件。示例正是在src/gatsby-theme-docz/components/index.js创建了与主题组件路径一致的 Shadowing 文件。示例的 Shadowing 文件 完整代码如下import React from react import * as headings from gatsby-theme-docz/src/components/Headings import { Code } from gatsby-theme-docz/src/components/Code import { Layout } from gatsby-theme-docz/src/components/Layout import { Playground } from gatsby-theme-docz/src/components/Playground import { Pre } from gatsby-theme-docz/src/components/Pre import { Props } from gatsby-theme-docz/src/components/Props const a props props.href.startsWith(http://) || props.href.startsWith(https://) ? ( a {...props} target_blank relnoreferrer nofollow {props.children} /a ) : ( a {...props}{props.children}/a ) export default { ...headings, code: Code, a, playground: Playground, pre: Pre, layout: Layout, props: Props, }关键点解读复用主题组件通过import ... from gatsby-theme-docz/src/components/...显式引入主题的原有组件避免 Shadowing 后丢失默认行为注入a组件在默认映射基础上新增a键指向自定义实现导出结构一致保持与主题export default相同的对象结构确保主题内部引用不受影响。注意示例中headings通过import * as headings导入因此...headings展开后即为 h1h6 等标题组件与主题默认映射完全对齐。自定义链接组件实现解析自定义的a组件是示例的核心逻辑其行为规则清晰外部链接href以http://或https://开头渲染为带target_blank和relnoreferrer nofollow的a即在新标签页打开且不传递来源信息、不传递权重内部链接相对路径或锚点渲染为普通a保持站内导航行为不变。const a props props.href.startsWith(http://) || props.href.startsWith(https://) ? ( a {...props} target_blank relnoreferrer nofollow {props.children} /a ) : ( a {...props}{props.children}/a )这种内外分流的实现非常适合文档站点的典型需求文档中既有站内路由链接如侧边栏导航、目录跳转也有指向外部文档、仓库或参考资料的链接。统一将外部链接在新标签页打开可以避免用户离开文档站点同时relnoreferrer nofollow也遵循了外部链接的安全与 SEO 惯例。在 MDX 文档中使用自定义链接示例文档 src/index.mdx 演示了自定义链接的实际效果--- name: Getting Started route: / --- import { Playground } from docz import { useState } from react # Getting Started [Link that opens in new tab](https://duckduckgo.com) Playground {() { const [toggle, setToggle] useState(true) return ( button onClick{() { setToggle(a !a) }} {toggle ? Hello : Good bye} /button ) }} /Playground文档 frontmatter 中的name和route定义了页面名称与路由路径route: /表示首页。正文中的[Link that opens in new tab](https://duckduckgo.com)会被渲染为自定义的a组件——由于href以https://开头它将以新标签页打开。同时Playground组件展示了 Docz 的实时交互示例能力你可以在文档中直接嵌入可运行的 React 组件代码块。这里还演示了与自定义链接的配合场景——当组件内也存在链接时同样的规则同样适用。扩展思路更多链接定制场景基于示例的 Shadowing 模式你可以轻松扩展出更多场景站内路由使用 Gatsby Link对于站内链接可将其渲染为gatsby的Link组件Docz 在 core/docz/src/components/Link.tsx 中直接导出了Link与LinkProps来源于gatsby以获得 Gatsby 的预加载prefetch与 SPA 式路由切换体验根据域名白名单判断不仅判断协议前缀还可以按href是否属于本站域名来决定是否新开标签页自定义rel策略根据链接用途动态设置rel如noopener、nofollow、ugc等组合统计埋点在自定义a组件中拦截点击事件上报外部链接点击数据。总结examples/with-custom-links虽然代码量极小却完整演示了 Docz 主题定制中最实用的能力通过Gatsby 主题 Shadowing覆盖gatsby-theme-docz的组件导出通过MDX 组件映射注入自定义的a组件以极简逻辑实现外部链接新标签页打开、内部链接保持默认的常见文档需求。掌握了这一模式你就掌握了 Docz 文档站点组件级定制的钥匙——无论是链接、代码块、标题还是其他 MDX 元素都可以通过同样的方式注入自定义实现从而打造完全贴合业务需求的文档体验。赞分享文档静态站点开发工具【免费下载链接】docz✍ It has never been so easy to document your things!项目地址https://gitcode.com/gh_mirrors/do/docz点击查看免费下载相关推荐Docz 实战通过 Component Shadowing 深度自定义 Playground 组件Shadowed Playground 示例解析Docz 实战通过 Component Shadowing 深度自定义 Playground 组件Shadowed Playground 示例解析 本篇技文档静态站点开发工具tRPC 客户端 Links 链接链完全指南数据流定制、自定义 Link 与终止 LinktRPC 客户端 Links 链接链完全指南数据流定制、自定义 Link 与终止 Link 本篇技术指南围绕 tRPC 官方文档中「Links Overvie后端RPC框架前端在 Wails3 中实现自定义协议深链接custom-protocol-example 实战指南在 Wails3 中实现自定义协议深链接custom protocol example 实战指南 本篇技术指南以 Wails3 仓库中 custom prot桌面应用跨平台CLI前端上一篇模型性能基准测试DeepSeek-V2.5在不同硬件配置下的表现下一篇thinking-in-spring-boot-samples中的SpringBootApplication注解你必须知道的5个要点创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Docz 自定义链接（Custom Links）实战指南：通过组件 Shadowing 定制 MDX 链接行为
文档静态站点开发工具【免费下载链接】docz✍ It has never been so easy to document your things!项目地址https://gitcode.com/gh_mirrors/do/docz点击查看免费下载Docz 是一个基于 Gatsby 的文档站点生成器它通过 MDX 让你在 Markdown 中直接使用 React 组件。当文档中需要对外部链接、内部路由进行差异化处理例如外部链接自动在新标签页打开时examples/with-custom-links提供了一个极简且完整的官方示例。本文以该示例为骨架深入讲解 Docz 的 MDX 组件注入机制、gatsby-theme-docz的组件 Shadowing 原理以及如何自定义链接组件以满足真实项目需求。示例概览with-custom-links 要解决的问题在 MDX 文档中普通 Markdown 链接text会被渲染为a标签。默认情况下Docz 主题gatsby-theme-docz并未提供自定义的a组件因此所有链接都表现为标准行为。而examples/with-custom-links演示了如何通过 Shadowing 机制向 MDX 的组件映射component map中注入一个自定义的a组件从而实现对链接行为的完全控制。该示例的核心文件结构如下examples/with-custom-links/ ├── README.md # 本示例的说明文档 ├── package.json # 项目依赖与脚本 └── src/ ├── index.mdx # 示例文档页面 └── gatsby-theme-docz/ └── components/ └── index.js # Shadowing 目标覆盖主题的组件导出其中最关键的是src/gatsby-theme-docz/components/index.js它通过 Gatsby 主题的 Shadowing 能力重写了主题默认的组件映射为a链接提供了自定义实现。你可以在 示例的组件注入文件 中查看完整代码。获取并运行示例方式一使用create-docz-app脚手架推荐create-docz-app是 Docz 官方提供的脚手架工具支持--example参数直接拉取官方示例模板npx create-docz-app docz-app-with-custom-links --example with-custom-links # 或使用 yarn yarn create docz-app docz-app-with-custom-links --example with-custom-links方式二手动下载你也可以从仓库的examples目录中手动提取该示例curl https://codeload.github.com/doczjs/docz/tar.gz/main | tar -xz --strip2 docz-main/examples/with-custom-links mv with-custom-links docz-with-custom-links-example cd docz-with-custom-links-example注意手动下载方式直接从 docz 仓库的main分支提取examples/with-custom-links目录适用于需要离线查看或修改示例源码的场景。安装依赖示例项目使用 Yarn 作为包管理器npm 亦可yarn # 或 npm i启动开发服务器yarn dev # 或 npm run devdev命令对应docz dev见 示例的 package.json启动后即可在浏览器中预览文档站点。生产构建与预览yarn build # 或 npm run build # 执行 docz build生成静态站点 yarn serve # 或 npm run serve # 执行 docz serve本地预览构建产物从 package.json 可以看到示例的脚本定义非常精简{ scripts: { dev: docz dev, build: docz build, serve: docz serve }, dependencies: { docz: latest, prop-types: ^15.7.2, react: ^16.11.0, react-dom: ^16.11.0 } }其中docz包是核心依赖react/react-dom是运行 MDX 组件所必需的而prop-types则是 Docz 内部组件声明 props 类型所用的库。核心机制MDX 组件注入与 ShadowingMDX 的组件映射Component MapMDX 允许通过MDXProvider向所有 MDX 内容注入自定义组件映射。例如将a映射为自定义组件后Markdown 中的text就会被渲染为你的自定义组件而非默认的a。Docz 主题gatsby-theme-docz的组件索引文件 core/gatsby-theme-docz/src/components/index.js 导出了一个默认组件映射对象import * as headings from ./Headings import { Code } from ./Code import { Layout } from ./Layout import { Playground } from ./Playground import { Pre } from ./Pre import { Props } from ./Props export default { ...headings, // h1 ~ h6 等标题组件 code: Code, playground: Playground, pre: Pre, layout: Layout, props: Props, }可以看到主题默认映射中并没有a链接组件这正是示例需要自定义注入的原因。Shadowing覆盖主题的组件导出Gatsby 主题支持 Shadowing在你的站点源码中创建与主题组件相同相对路径的文件即可覆盖主题中的对应组件。示例正是在src/gatsby-theme-docz/components/index.js创建了与主题组件路径一致的 Shadowing 文件。示例的 Shadowing 文件 完整代码如下import React from react import * as headings from gatsby-theme-docz/src/components/Headings import { Code } from gatsby-theme-docz/src/components/Code import { Layout } from gatsby-theme-docz/src/components/Layout import { Playground } from gatsby-theme-docz/src/components/Playground import { Pre } from gatsby-theme-docz/src/components/Pre import { Props } from gatsby-theme-docz/src/components/Props const a props props.href.startsWith(http://) || props.href.startsWith(https://) ? ( a {...props} target_blank relnoreferrer nofollow {props.children} /a ) : ( a {...props}{props.children}/a ) export default { ...headings, code: Code, a, playground: Playground, pre: Pre, layout: Layout, props: Props, }关键点解读复用主题组件通过import ... from gatsby-theme-docz/src/components/...显式引入主题的原有组件避免 Shadowing 后丢失默认行为注入a组件在默认映射基础上新增a键指向自定义实现导出结构一致保持与主题export default相同的对象结构确保主题内部引用不受影响。注意示例中headings通过import * as headings导入因此...headings展开后即为 h1h6 等标题组件与主题默认映射完全对齐。自定义链接组件实现解析自定义的a组件是示例的核心逻辑其行为规则清晰外部链接href以http://或https://开头渲染为带target_blank和relnoreferrer nofollow的a即在新标签页打开且不传递来源信息、不传递权重内部链接相对路径或锚点渲染为普通a保持站内导航行为不变。const a props props.href.startsWith(http://) || props.href.startsWith(https://) ? ( a {...props} target_blank relnoreferrer nofollow {props.children} /a ) : ( a {...props}{props.children}/a )这种内外分流的实现非常适合文档站点的典型需求文档中既有站内路由链接如侧边栏导航、目录跳转也有指向外部文档、仓库或参考资料的链接。统一将外部链接在新标签页打开可以避免用户离开文档站点同时relnoreferrer nofollow也遵循了外部链接的安全与 SEO 惯例。在 MDX 文档中使用自定义链接示例文档 src/index.mdx 演示了自定义链接的实际效果--- name: Getting Started route: / --- import { Playground } from docz import { useState } from react # Getting Started [Link that opens in new tab](https://duckduckgo.com) Playground {() { const [toggle, setToggle] useState(true) return ( button onClick{() { setToggle(a !a) }} {toggle ? Hello : Good bye} /button ) }} /Playground文档 frontmatter 中的name和route定义了页面名称与路由路径route: /表示首页。正文中的[Link that opens in new tab](https://duckduckgo.com)会被渲染为自定义的a组件——由于href以https://开头它将以新标签页打开。同时Playground组件展示了 Docz 的实时交互示例能力你可以在文档中直接嵌入可运行的 React 组件代码块。这里还演示了与自定义链接的配合场景——当组件内也存在链接时同样的规则同样适用。扩展思路更多链接定制场景基于示例的 Shadowing 模式你可以轻松扩展出更多场景站内路由使用 Gatsby Link对于站内链接可将其渲染为gatsby的Link组件Docz 在 core/docz/src/components/Link.tsx 中直接导出了Link与LinkProps来源于gatsby以获得 Gatsby 的预加载prefetch与 SPA 式路由切换体验根据域名白名单判断不仅判断协议前缀还可以按href是否属于本站域名来决定是否新开标签页自定义rel策略根据链接用途动态设置rel如noopener、nofollow、ugc等组合统计埋点在自定义a组件中拦截点击事件上报外部链接点击数据。总结examples/with-custom-links虽然代码量极小却完整演示了 Docz 主题定制中最实用的能力通过Gatsby 主题 Shadowing覆盖gatsby-theme-docz的组件导出通过MDX 组件映射注入自定义的a组件以极简逻辑实现外部链接新标签页打开、内部链接保持默认的常见文档需求。掌握了这一模式你就掌握了 Docz 文档站点组件级定制的钥匙——无论是链接、代码块、标题还是其他 MDX 元素都可以通过同样的方式注入自定义实现从而打造完全贴合业务需求的文档体验。赞分享文档静态站点开发工具【免费下载链接】docz✍ It has never been so easy to document your things!项目地址https://gitcode.com/gh_mirrors/do/docz点击查看免费下载相关推荐Docz 实战通过 Component Shadowing 深度自定义 Playground 组件Shadowed Playground 示例解析Docz 实战通过 Component Shadowing 深度自定义 Playground 组件Shadowed Playground 示例解析 本篇技文档静态站点开发工具tRPC 客户端 Links 链接链完全指南数据流定制、自定义 Link 与终止 LinktRPC 客户端 Links 链接链完全指南数据流定制、自定义 Link 与终止 Link 本篇技术指南围绕 tRPC 官方文档中「Links Overvie后端RPC框架前端在 Wails3 中实现自定义协议深链接custom-protocol-example 实战指南在 Wails3 中实现自定义协议深链接custom protocol example 实战指南 本篇技术指南以 Wails3 仓库中 custom prot桌面应用跨平台CLI前端上一篇模型性能基准测试DeepSeek-V2.5在不同硬件配置下的表现下一篇thinking-in-spring-boot-samples中的SpringBootApplication注解你必须知道的5个要点创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
