文档静态站点开发工具【免费下载链接】docz✍ It has never been so easy to document your things!项目地址https://gitcode.com/gh_mirrors/do/docz点击查看免费下载Docz 本身基于 Gatsby 构建因此它的主题系统直接复用了 Gatsby 的 Theme Shadowing主题遮蔽机制你不需要 fork 整个主题只需要在项目里放置同名目录与同名文件就能覆盖 Docz 默认主题中的任意组件。本文以仓库中的examples/with-custom-docz-theme示例为骨架完整演示如何从零创建一个名为gatsby-theme-docz-pink的自定义主题为每个页面外层包裹带粉色背景与内边距的容器再在另一个 Docz 项目中安装并消费它同时结合源码说明 shadowing 的底层原理并给出覆盖 Header、Sidebar、Logo、Playground 等更多组件的扩展思路。读完本文你将能够独立打造一套属于自己的 Docz 文档站主题。先理解 Docz 主题的底层机制Docz 的运行时主题位于core/gatsby-theme-docz它在gatsby-config.js中通过gatsby-plugin-compile-es6-packages把自己以及docz、docz-core声明为需要被 webpack 编译的 ES6 包见 gatsby-config.js{ resolve: gatsby-plugin-compile-es6-packages, options: { modules: [docz, docz-core, gatsby-theme-docz], }, }Docz 主题系统依托的 Shadowing 规则非常简单Gatsby 会优先加载项目里路径为src/gatsby-theme-docz/组件名的文件用它“遮蔽”主题包内同名的默认组件。你可以遮蔽两大类东西单个组件文件例如wrapper.js、Sidebar/index.js、Header/index.js、Logo/index.js、Playground/index.js组件批量入口components/index.js一次性替换 MDX 渲染时用到的全套内置组件。以本示例遮蔽的wrapper.js为例Docz 主题包的原始实现只是一个透传容器见 core/gatsby-theme-docz/src/wrapper.jsimport React from react const Wrapper ({ children }) {children}/ export default Wrapper也就是说默认情况下每个页面外层没有任何包裹容器。自定义主题要做的就是用自己版本的wrapper.js把这个透传层替换成带样式的容器。创建一个自定义主题gatsby-theme-docz-pink示例的目标是写一个主题让每个页面都被一个带内边距和粉色背景的div包裹。你完全可以按需让主题做得更多或更少——它只是一个普通的 Gatsby 主题包。第 1 步建立主题包目录在项目中创建目录gatsby-theme-docz-pink其最终结构如下见 examples/with-custom-docz-theme/gatsby-theme-docz-pinkgatsby-theme-docz-pink/ ├── index.js # 空文件noop标记包入口 ├── package.json └── src/ └── gatsby-theme-docz/ # 关键目录声明要遮蔽 gatsby-theme-docz └── wrapper.js # 被遮蔽的目标组件其中src/gatsby-theme-docz这一层目录名是固定约定它告诉 Gatsby本包要遮蔽gatsby-theme-docz主题。其下再按“主题包内的相对路径”放置要覆盖的组件文件。第 2 步书写被遮蔽的 wrapper 组件在src/gatsby-theme-docz/wrapper.js中编写新组件。它引入了原始 Wrapper再把原始 Wrapper 包进一个带样式的div中见 wrapper.jsimport React from react import OriginalWrapper from gatsby-theme-docz/src/wrapper const Wrapper ({ children, doc }) { return ( div style{{ background: pink, padding: 30 }} OriginalWrapper{children}/OriginalWrapper /div ) } export default Wrapper这段代码有两个要点从gatsby-theme-docz/src/wrapper导入原始组件这是组合而非替换的惯用写法。先引入原组件再叠加自己的样式或逻辑可以保证不丢失默认行为。children是页面内容doc是当前文档的元数据route、name、menu 等由 Docz 的sourceNodes注入参见 core/gatsby-theme-docz/gatsby-node.js内联样式即可生效本示例使用style内联样式演示你完全可以用 emotion/theme-ui 或任何你熟悉的样式方案因为 shadow 组件本身就是一个普通 React 组件。第 3 步添加 package.json在gatsby-theme-docz-pink根目录添加package.json{ name: gatsby-theme-docz-pink, version: 1.0.0, main: index.js, license: MIT }main指向index.js因此还需要在包根目录创建一个空文件index.js让打包器bundler能识别这个包是存在的见 index.js// noop到这里这个主题就已经制作完成可以分发和消费了——你可以把它发布到 npm也可以托管在 git 仓库里用任意包管理器安装。消费一个自定义主题第 1 步把主题安装为项目依赖如果主题已发布到 npm直接添加依赖即可yarn add gatsby-theme-docz-pink本示例为了演示没有走 npm 发布流程而是把gatsby-theme-docz-pink目录直接复制到node_modules中cp -r gatsby-theme-docz-pink/ node_modules/gatsby-theme-docz-pink。示例项目的package.json里也内置了install:theme脚本见 package.jsoninstall:theme: cp -r gatsby-theme-docz-pink/ node_modules/gatsby-theme-docz-pink。第 2 步在 gatsby-config.js 中声明插件在项目根目录创建gatsby-config.js声明使用gatsby-theme-docz-pink同时让 webpack 编译这个包——因为包内是 JSX 语法并非合法的普通 JS见 gatsby-config.js// gatsby-config.js module.exports { plugins: [ gatsby-theme-docz-pink, { resolve: gatsby-plugin-compile-es6-packages, options: { modules: [gatsby-theme-docz-pink], }, }, ], }gatsby-plugin-compile-es6-packages的modules数组用于声明哪些包需要被 webpack 编译——Docz 自己的gatsby-config.js也是用同样的方式编译docz、docz-core与gatsby-theme-docz的。凡是包含 JSX 或未编译 ES 语法的自定义主题都必须在这里登记。第 3 步运行并观察效果安装好依赖后执行yarn docz dev此时打开开发服务器就能看到每个页面外层都被粉色背景 30px 内边距的容器包裹即自定义主题已经生效。从 wrapper 扩展到更多组件Shadowing 并不局限于wrapper.js。Docz 主题包默认暴露了这些可遮蔽组件见 core/gatsby-theme-docz/src/components 目录结构组件作用Header/index.js顶部栏含 Logo、搜索、导航开关Sidebar/index.js侧边栏含导航分组、搜索、当前文档高亮Logo/index.js站点 LogoNavGroup/index.js、NavLink/index.js、NavSearch/index.js侧边栏导航的组成单元Playground/index.jsMDX 中的Playground交互式示例组件Pre/index.js、Code/index.js代码块渲染Props/index.js组件属性表格配合Props of{Component} /Headings/index.js标题渲染MainContainer/index.js、Layout/index.js页面布局容器仓库中的其他示例给出了多种遮蔽套路遮蔽Sidebarexamples/logo-in-sidebar通过 Sidebar/index.js 在侧边栏顶部插入一张图片同时复用gatsby-theme-docz/src/components/NavSearch、NavLink、NavGroup以及样式模块gatsby-theme-docz/src/components/Sidebar/styles保持默认行为不变遮蔽components/index.jsexamples/with-custom-links通过 components/index.js 一次性导出全部内置组件headings、Code、Playground、Pre、Layout、Props并自定义a链接组件——外部链接自动target_blank加relnoreferrer nofollow站内链接保持默认行为遮蔽Playgroundexamples/shadowed-playground、examples/wrapped-playground、examples/with-styled-components-and-scoping均演示了如何定制Playground的渲染外壳对应Playground/Wrapper.js。遮蔽任意组件时都可以沿用本示例的“先导入原始组件、再包裹增强”的模式import React from react import OriginalHeader from gatsby-theme-docz/src/components/Header const Header props { return ( header style{{ borderBottom: 2px solid pink }} OriginalHeader {...props} / /header ) } export default Header快速起步create-docz-app 与手动下载使用 create-docz-app如果你的项目还没有初始化可以用官方脚手架直接创建一个 Docz 应用npx create-docz-app docz-app-with-custom-docz-theme # 或 yarn create docz-app docz-app-with-custom-docz-theme手动下载示例也可以直接获取本仓库中的with-custom-docz-theme示例目录随后进入目录即可# 从仓库的 examples 目录中取出 with-custom-docz-theme 示例等价于 curl 下载并解压该目录 mv with-custom-docz-theme docz-with-custom-docz-theme-example cd docz-with-custom-docz-theme-example你也可以直接git clone本仓库后查看并运行其中的 examples/with-custom-docz-theme 目录。安装、运行、构建与部署进入示例项目后按需执行yarn # 或 npm i安装完成后即可启动开发服务器yarn dev # 或 npm run dev生产构建yarn build # 或 npm run build本地预览构建产物yarn serve # 或 npm run serve对应的脚本定义在 package.json 中dev对应docz devbuild对应docz buildserve对应docz serve。示例项目的文档内容位于 src/index.mdx 与 src/components/Alert.mdx后者使用了docz提供的Playground、Props组件侧边栏菜单由 doczrc.js 中的menu: [Getting Started, Components]控制。小结Docz 的自定义主题能力本质上是把 Gatsby Theme Shadowing 暴露给文档站开发者创建主题包建立gatsby-theme-docz-pink目录在其中放置src/gatsby-theme-docz/组件路径覆盖目标组件补上package.json与空的index.js即可发布组合优先在 shadow 组件中先import原始组件再用样式与逻辑包裹增强避免丢失默认行为消费主题yarn add安装后在gatsby-config.js中声明插件并用gatsby-plugin-compile-es6-packages让 webpack 编译含 JSX 的主题包按需扩展wrapper.js之外Header、Sidebar、Logo、Playground、Props等组件以及批量入口components/index.js都可以用同一套机制遮蔽定制。掌握了这套机制你就能为团队构建带有专属品牌样式、定制导航与交互组件的文档站主题并像普通 npm 包一样分发和复用。赞分享文档静态站点开发工具【免费下载链接】docz✍ It has never been so easy to document your things!项目地址https://gitcode.com/gh_mirrors/do/docz点击查看免费下载相关推荐Gatsby 主题构建指南从 Workspace Starter 到 Shadowing 与主题组合Gatsby 主题构建指南从 Workspace Starter 到 Shadowing 与主题组合 导读 本文基于 Gatsby 官方文档 building前端静态站点Web框架utterances主题开发创建自定义主题的完整指南utterances主题开发创建自定义主题的完整指南 你是否厌倦了千篇一律的评论区样式想让自己网站的评论系统与众不同本文将带你一步步打造专属utteran前端UI组件Xcode项目终极清理工具三步快速识别并删除未使用资源文件Xcode项目终极清理工具三步快速识别并删除未使用资源文件 FengNiao是一款专为Xcode项目设计的Swift命令行工具能够智能扫描并清理iOS和ma文档静态站点开发工具上一篇Ansible Lint 技术详解提升Ansible代码质量的最佳实践下一篇5个实用技巧用Mac Mouse Fix让普通鼠标秒变触控板创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考