fumadocs/tailwind 排版系统解析基于--tw-prose-size的可缩放 Prose 排版【免费下载链接】fumadocsThe beautiful flexible React.js docs framework.项目地址: https://gitcode.com/GitHub_Trending/fu/fumadocsFumadocs 是一个基于 React.js 构建的文档框架其 UI 层围绕 Tailwind CSS 设计。fumadocs/tailwind包正是「The Tailwind CSS utils for Fumadocs UI」——为 Fumadocs 文档渲染提供一套开箱即用的 Prose 排版工具链。本文围绕该包的版本演进核心0.1.1引入的无单位--tw-prose-size可缩放排版、0.1.0的 Base UI 切换以及其完整源码实现讲解如何理解、配置并使用这套排版系统读完后你将掌握在 Fumadocs 或任意 Tailwind CSS v4 项目中定制文档正文排版的能力。包定位Fumadocs 的排版工具包fumadocs/tailwind是一个独立的 npm 包仅对外暴露两个入口见 packages/tailwind/package.json{ name: fumadocs/tailwind, version: 0.1.1, exports: { .: ./dist/index.mjs, ./typography: ./dist/typography/index.mjs, ./package.json: ./package.json } }主入口fumadocs/tailwind目前为空实现src/index.ts仅export {}用于包的基础占位真正有价值的是fumadocs/tailwind/typography子路径它导出一个完整的 Tailwind CSS 插件用于生成文档正文prose的排版样式。从依赖关系看该包将tailwindcss声明为peerDependencies^4.0.0且为 optional也就是说它面向 Tailwind CSS v4设计。构建产物由tsdown生成构建配置见 packages/tailwind/tsdown.config.ts其中将fastify/deepmerge、postcss-selector-parser等运行时依赖直接内联打包onlyBundle保证了插件安装后开箱即用、无需额外解析依赖。核心机制一无单位--tw-prose-size实现整体缩放这是fumadocs/tailwind0.1.1引入的关键能力也是 packages/tailwind/CHANGELOG.md 中描述的重头戏Scale prose typography with the unitless--tw-prose-sizevariable and add aprose-smmodifier for optically adjusted small text.其设计思路是不再像传统排版系统那样为每个字号硬编码固定像素值而是把所有尺寸都包进一个calc()乘上一个无单位的 CSS 自定义属性--tw-prose-size。这样只需改变这一个变量整个文档正文的字体、间距、表格内边距等就会按比例整体缩放。缩放工具函数的实现在 packages/tailwind/src/typography/styles.ts 中可以清楚看到这套缩放逻辑function scaled(value: string) { return calc(${value} * var(--tw-prose-size)); } function scaledPx(value: number) { return scaled(${round(value)}px); } function scaledRem(px: number) { return scaled(rem(px)); }scaled()是核心任意 CSS 值都会被包装为calc(value * var(--tw-prose-size))scaledPx()用于像素值如内边距生成calc(3px * var(--tw-prose-size))scaledRem()先将像素除以 16 换算为 rem再参与缩放。默认样式中的落地应用DEFAULT配置styles.ts#L141-L460在根选择器上声明了基线--tw-prose-size: 1, color: var(--tw-prose-body), maxWidth: none, fontSize: calc(1rem * var(--tw-prose-size)), lineHeight: calc(1.75rem * var(--tw-prose-size)),即默认--tw-prose-size: 1所有尺寸保持原始比例。其余元素则大量引用缩放后的值例如标题h1使用scaled(var(--text-3xl))字号跟随设计令牌与缩放系数行内代码code的padding为calc(3px * var(--tw-prose-size))、fontSize为calc(13px * var(--tw-prose-size))表格th/td的内边距为calc(var(--spacing) * 2.5 * var(--tw-prose-size))。值得注意的是并非所有值都会被缩放border: solid 1px与border-radius: 5px刻意保持不缩放。这一行为在 packages/tailwind/test/typography.test.ts 中有专门断言expect(css).toContain(border: solid 1px;); expect(css).not.toContain(border: solid calc(1px * var(--tw-prose-size));); expect(css).not.toContain(border-radius: calc(5px * var(--tw-prose-size)););这体现了「视觉细节边框、圆角不随字号缩放而间距与字号随排版缩放」的精细化设计哲学避免小字号下边框和圆角显得过粗。核心机制二prose-sm修饰符与视觉微调0.1.1同时新增了prose-sm修饰符用于「optically adjusted small text」光学调整的小号文本。它并不是简单地等比例缩小而是在缩小字号的同时做了字重上的视觉补偿。SMALL配置在 packages/tailwind/src/typography/styles.tsexport const SMALL: Config { css: [ { --tw-prose-size: 0.875, dt, strong, blockquote, h1, h2, h3, h4, kbd, thead th, a:not([data-card]): { fontWeight: 450, }, }, ], };它做了两件事将--tw-prose-size设为0.875即默认字号的 87.5%对标题、强调、引用、表格表头等原本字重较高的元素统一收敛到font-weight: 450以抵消小字号下的视觉「发胖」感实现光学上的均衡。对应测试 typography.test.ts 断言了该修饰符不会把粗体还原为 600/700/800/900expect(smallCss).toContain(font-weight: 450;); expect(smallCss).not.toContain(font-weight: 600;);用法上prose与prose-sm是同时挂在正文容器上的两个类article classprose prose-sm !-- 文档正文 -- /article插件选项自定义类名与圆角表格开关插件入口位于 packages/tailwind/src/typography/index.ts通过plugin.withOptions暴露两个配置项export interface Options { className?: string; /** * Disable custom table styles */ disableRoundedTable?: boolean; }className更换默认类名前缀默认排版类名为prose可通过className重命名。例如在 Tailwind CSS v4 配置中plugin fumadocs/tailwind/typography { className: content; }测试 typography.test.ts 验证了自定义类名后content/content-sm生效、prose-sm不再生成。插件内部还通过prefix处理 Tailwind 的前缀配置并用:where()与not(:where([class~not-prose] ...))结构实现「not-prose白名单逃逸」保证嵌套内容可以跳出排版样式。disableRoundedTable切换两种表格风格styles.ts中内置了两套表格样式roundedTable默认styles.ts#L47-L84使用border-collapse: separateborder-radius: var(--radius-lg)表头使用var(--color-fd-muted)背景、单元格带border-inline-start分隔线契合 Fumadocs 卡片化设计语言normalTablestyles.ts#L86-L135经典的分隔线表格表头与行使用--tw-prose-th-borders/--tw-prose-td-borders变量控制边框色。插件在addComponents阶段把对应表格样式合并进.prose类见 index.ts默认追加roundedTable设置disableRoundedTable: true后切换为normalTable。与 Fumadocs 设计令牌的联动整套排版颜色并不写死而是通过 CSS 自定义属性映射到 Fumadocs 主题令牌styles.ts例如--tw-prose-body: color-mix(in oklab, var(--color-fd-foreground) 90%, transparent); --tw-prose-headings: var(--color-fd-foreground); --tw-prose-bullets: var(--color-fd-muted-foreground); --tw-prose-hr: var(--color-fd-border); --tw-prose-kbd-shadows: color-mix(in oklab, var(--color-fd-primary) 50%, transparent);这意味着正文、标题、链接、引用、代码块、键盘键帽等颜色均自动跟随 Fumadocs 的--color-fd-*主题变量无需任何额外配置即可适配浅色/深色主题。正文链接还会获得基于--color-fd-primary的强调色下划线textUnderlineOffset: 3.5px、textDecorationThickness: 1.5px同时a:not([data-card])选择器保证链接卡片组件不受正文链接样式干扰。DEFAULT配置还完整覆盖了列表、dl/dt/dd、引用块含 open-quote/close-quote 引号、ol[typeA s]这类带s修饰的列表类型、picture图片、kbd、figure/figcaption、hr等文档场景是一个结构完整的排版体系而不只是简单的字号预设。从版本历史理解演进方向packages/tailwind/CHANGELOG.md 记录了这一排版能力的演进脉络版本关键变更0.1.1引入无单位--tw-prose-size实现可缩放排版新增prose-sm修饰符0.1.0内部包与模板从 Radix UI 切换为 Base UI影响 UI 层依赖排版 API 不变0.0.5修复npm pack跳过嵌套node_modules的发布问题0.0.4打包更多运行时依赖0.0.3升级 Shiki.js v4影响代码高亮相关样式生态0.0.2升级 tsdown 构建工具0.0.1初始发布从这些变更可以看到一个清晰的工程化思路早期版本主要解决「打包与发布可靠性」问题onlyBundle内联依赖、修复npm pack随后转向「排版体验」的精细化可缩放排版与prose-sm同时跟随 Fumadocs 的 UI 基础设施演进Base UI。这也解释了为什么package.json中peerDependencies将tailwindcss标记为可选——排版插件是渐进增强的即便没有显式声明 tailwind 依赖也能在宿主项目中正常参与编译。安装与使用小结在 Tailwind CSS v4 项目中启用该排版插件的方式pnpm add fumadocs/tailwind在全局样式中声明插件并可选传参import tailwindcss; plugin fumadocs/tailwind/typography;然后在正文容器上使用article classprose prose-sm max-w-none !-- 文档正文 -- /article如需自定义类名或切换表格风格在plugin中传参即可。验证编译结果可以复用包内测试所采用的 Tailwind CSS v4 官方compileAPI见 typography.test.ts它能在不启动完整构建的情况下快速断言生成的 CSS是调试排版插件的有力手段。总而言之fumadocs/tailwind以「一个 CSS 变量控制全局排版比例」为核心配合prose-sm的光学微调、设计令牌联动与白名单逃逸机制构成了 Fumadocs 文档正文排版的最小而完备的解决方案其源码与测试也一并开放于仓库的 packages/tailwind 目录下可作为 Tailwind CSS v4 插件开发的参考范本。【免费下载链接】fumadocsThe beautiful flexible React.js docs framework.项目地址: https://gitcode.com/GitHub_Trending/fu/fumadocs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考