人工智能AI 技能/插件提示工程【免费下载链接】garden-skillsConardLis open-source Skills collection, featuring web design, knowledge retrieval, image generation, and more.项目地址https://gitcode.com/GitHub_Trending/we/garden-skills点击查看免费下载导读本篇技术指南聚焦 garden-skills 仓库中 beautiful-article Skill 的输出与构建链路文章不是手写裸 HTML而是运行在 Vite React TS 工作区中、由语义组件协议 reacticle 渲染、最终被vite-plugin-singlefile压成 CSS JS 全部内联的自包含单页 HTML。读完本文你将掌握四条构建命令的职责划分、单文件产物的实现原理、运行时主题的切换方式以及可选的 HTML→PDF 导出流程包括打印 CSS 注入的设计动机与 headless 浏览器渲染细节并理解交付自检的完整标准。一、工作区是什么一个从 npm 消费 reacticle 的 Vite 项目Beautiful Article 的文章工作区本质上是一个标准的Vite React TypeScript 项目从 npm 消费组件库reacticle最新发布版即reacticle: latest而不是在仓库内维护一份组件库源码。这一点在脚手架模板的 package.json 中写得很明确{ name: beautiful-article-workspace, private: true, version: 0.0.0, type: module, scripts: { dev: vite, build: tsc --noEmit vite build, html: npm run build node -e \require(fs).mkdirSync(article,{recursive:true});require(fs).copyFileSync(dist/index.html,article/article.html);console.log(built article/article.html)\, typecheck: tsc --noEmit, preview: vite preview }, dependencies: { react: ^18.3.1, react-dom: ^18.3.1, reacticle: latest }, devDependencies: { types/react: ^18.3.12, types/react-dom: ^18.3.1, vitejs/plugin-react: ^4.3.4, typescript: ^5.6.3, vite: ^5.4.11, vite-plugin-singlefile: ^2.0.3 } }几个值得注意的细节reacticle: latest脚手架创建完目录后会执行npm install reacticlelatest强制刷新到当下最新版并打印实际版本避免缓存到旧包。katex/prismjs作为 reacticle 的依赖会被自动带下来无需工作区单独声明。html脚本不是新构建它复用npm run build含tsc --noEmit类型检查再把dist/index.html复制到article/article.html——后者才是真正的交付物详情见下文命令表。tsc --noEmit vite build的顺序保证TS 报错会让构建直接失败错误不会漏进交付物。文章源码的组织方式与装配逻辑见 SKILL.md 与 scaffold.md工作区包含source/源文抽取、plan/规划、review/质检等长期记忆目录以及article/Article.tsxassembler、article/sections/NN-*.tsx一节一文件、article/raw-blocks/大型 Raw 隔离、article/assets/配图素材。核心铁律是Article.tsx只负责 import 与排序各 Section 组件绝不内联 Section 正文这是多 Agent 并行开发的前提。二、命令表四条命令各管一段关联文档给出了工作区根目录下的核心命令表这里逐一展开其作用与适用阶段命令作用npm run dev启动 Vite 开发预览对应脚本vite用于 Phase 4 / 5 边写边看首屏、每个 Section 完成后都靠它本地验收。npm run build先跑tsc --noEmit做类型检查再vite build产出自包含单页 HTML到dist/index.htmlCSS JS 全部内联。TS 报错即构建失败防止错误进入交付物。npm run html复用npm run build含类型检查再把单页 HTML 复制到article/article.html——这是最终交付物由内联的 node 单行命令完成mkdirSync(article, {recursive:true})copyFileSync。npm run typecheck仅执行tsc --noEmit类型检查不改动产物适合多 Agent 并行阶段快速验证某个 Section 是否类型正确。其中build与html都内建了类型检查这与 SKILL 的 Phase 5 多 Agent 模式直接相关并行编写sections/NN-*.tsx时主 Agent 需要维护Article.tsx的 import 与顺序、跑npm run typecheck/build、兜底主题与风格一致、解决冲突。三、单文件产物的原理vite-plugin-singlefile 内联一切npm run html之所以能产出一个断网可打开、可分享的单文件关键在于 Vite 插件vite-plugin-singlefile。脚手架模板的 vite.config.ts 完整展示了接线方式import { resolve } from node:path; import { defineConfig } from vite; import react from vitejs/plugin-react; import { viteSingleFile } from vite-plugin-singlefile; // reacticle is consumed from the published npm package (see package.json). // Builds a self-contained single-page HTML (CSS JS inlined, opens offline) // to dist/index.html. npm run html then copies it to article/article.html. export default defineConfig({ plugins: [react(), viteSingleFile()], build: { outDir: dist, emptyOutDir: true, rollupOptions: { input: resolve(__dirname, index.html), }, }, });要点拆解plugins: [react(), viteSingleFile()]viteSingleFile把所有产出的 CSS 与 JS 内联进 HTML静态资源也一并处理woff 字体等资源是否能内联取决于主题怎么写这会在 PDF 字体一节再次涉及。build.outDir: distemptyOutDir: true每次构建清空dist保证产物干净、无残留。入口是根index.htmlindex.html 中langzh-CN、div idroot/div、script typemodule src/article/main.tsx并预连接 Google Fonts 加载主题字体tufte主题 fallback 到 Georgiapress主题使用 Newsreader。从源码结构可以推断单文件策略是该 Skill 信息交付的核心承诺HTML 的价值在于提升信息密度、视觉清晰度、分享便利性和交互能力而单文件形态让这份 HTML 可以脱离网络、脱离构建环境直接被读者打开。四、切换主题只改一个字符串主题在文章入口 article/main.tsx 中固定createRoot(document.getElementById(root)!).render( StrictMode ThemeProvider theme__THEME__ Cover / ArticleDoc / /ThemeProvider /StrictMode );theme__THEME__是脚手架注入的占位符实际写入的是所选主题的runtime theme id。当前已注册的 id 为tufte/press完整清单见 theme-profiles/index.json改一个字即可整体切换观感。换主题必须同步改两处并保持一致①main.tsx的ThemeProvider theme...控制运行时主题②Article.tsx末尾 colophon 里的· 主题 theme控制文章印记中显示的主题名。colophon 是 scaffold 自带、不可删除的 Raw 块Made with beautiful-article · 主题 theme低对比小字、--ra-*token 自适应见 Article.tsx。main.tsx还揭示了渲染顺序的设计Cover封面可选→ ArticleDoc含 TOC 正文 colophon。Cover 故意不塞进Article内部那样会被挤到正文栏旁边而是与ArticleDoc /在ThemeProvider下做兄弟组件DOM 顺序天然就是封面 → TOC → 正文 → colophon。脚手架用__COVER_IMPORT_*__/__COVER_RENDER_*__标记包裹封面相关代码scaffold.sh在--no-cover时整段剥掉。版式宽度narrow/regular/wide/full与 TOC 开关在 Plan Checkpoint 确认与主题解耦见 SKILL.md 与references/layout.md。五、PDF 导出可选环节由 Checkpoint 3 触发PDF 不是主交付物——主交付物永远是article/article.html。PDF 只在 Phase 8 Delivery 时用户于 Checkpoint 3 选择通过 · 同时导出 HTML PDF才生成不选则完全不动作。这是 Skill 的显式设计避免替用户默认导出。一句话用法详见 references/pdf-output.mdnpm run html # 先有 article/article.html bash path-to-beautiful-article/scripts/html-to-pdf.sh # → article/article.pdf脚本支持自定义输入输出路径bash html-to-pdf.sh in.html out.pdf也可把该 bash 调用写进工作区package.json的 scripts 里让用户npm run pdf路径是用户机器上 Skill 的绝对路径不在脚手架模板里固化避免硬编码。5.1 前提条件探测系统 chromium-family 浏览器脚本 html-to-pdf.sh 不依赖 Node / npm 包 / puppeteer / playwright / weasyprint故意只用系统已装的浏览器。它按固定顺序探测chromium / chromium-browser / google-chrome / google-chrome-stable / chrome brave-browser / microsoft-edge /Applications/Google Chrome.app/... /Applications/Chromium.app/... /Applications/Microsoft Edge.app/... /Applications/Brave Browser.app/... /Applications/Arc.app/... /usr/bin/chromium / /snap/bin/chromium找不到任何浏览器时脚本不会报错崩溃它会打印已经注入打印 CSS 的临时 HTML 路径并给出回退指引——用户用任意浏览器打开该临时文件CmdP/CtrlP→ 另存为 PDF即可注入的 print 样式已让 TOC 在上、正文在下与 PDF 阅读习惯对齐。5.2 渲染流程与 Chrome 标志从源码看脚本的渲染流水线是article.html ──── awk 注入 print CSS ──── /tmp/article-print.html │ ▼ 探测的浏览器 --headless --print-to-pdf │ ▼ article.pdf调用的 headless 浏览器标志及其用途标志用途--headlessnew旧版 fallback 到--headless无窗口模式--no-pdf-header-footer/--print-to-pdf-no-header去掉浏览器自带的 URL / 日期 / 页码这些与 colophon 的角色冲突--virtual-time-budget5000给页面 JS 5 秒初始化时间让 Raw 组件、KaTeX、Prism 等渲染完再截屏--hide-scrollbars/--disable-gpu/--no-sandbox清洁渲染六、打印 CSS 注入为什么动 CSS 而不是动 reacticle这是本 Skill PDF 方案的核心设计原理值得展开1. 问题根源reacticle 的 TOC 在桌面是左右栅格.ra-article-layout--with-toc为display: grid两列TOC | 文章在移动端≤999px才塌成单列display: block。而 PDF 阅读习惯是上下排布TOC 先 / 正文后跟移动端体验对齐。2. 最干净的解法在 PDF 生成时注入一段media printCSS强制 TOC 容器display: block等价于复用移动端分支。这样同时满足三个约束不动 reacticle任何版本的 reacticle 都能用这个脚本生成合理 PDF不动用户的 Article.tsx用户源码完全不受影响CSS 只在打印生效浏览器里看 HTML 仍是左右栅格。reacticle 自带的print.css仍然生效白底黑字 / 隐藏 export bar /break-inside: avoid等脚本只补 TOC 排版那一块。3. 注入的实现细节CSS 被抽到独立文件 scripts/pdf-print-overrides.css脚本只用awk把它的内容包在style idra-pdf-overrides里、塞到/head之前。之所以抽成独立文件而非内联字符串是因为macOS 自带 BSD awk 对-v inject$INLINE_CSS这种多行字符串报newline in string错GNU awk 没事改用getline file从文件读取后两个 awk 都吃得下顺带让 CSS 变成可独立编辑 / lint / diff 的真正资源。4. 注入的规则分四组完整带注释版本直接看 CSS 文件0 · Theme surface.ra-root保持主题纸色与文字色铺满整页print-color-adjust: exact强制打印背景色padding: 0.45in提供内容留白page { margin: 0 }让主题纸色铺满再用内边距留白——因为 Chromium 的--print-to-pdf不支持命令行页面尺寸 / 边距参数。A · TOC 排版TOC 上 / 正文下A1.ra-article-layout--with-toc { display: block }塌成单列A2.ra-toc { position: static; break-after: page }解除 sticky TOC 独占首页A3 长 TOC 用column-count: 2双列省纸A4 TOC 项break-inside: avoid不被列间撕开A5 正文在 TOC 后自然流A6 打印时去掉正文链接下划线。B · 分页行为修长文章的大块空白页B1 用break-inside: auto !important撤销 reacticle print.css 里的.ra-section { break-inside: avoid-page }——那条规则对多页长 Section 会适得其反整节被推到下一页、前一页留大半空白B2 标题break-after: avoid不孤儿化B3 Hero / Lead / Conclusion 原子化不撕开B4orphans: 3; widows: 3段落不留 1–2 行寡行B5 图表、表格、代码块尽量整块过高时浏览器自动 fallback 分页。C · 封面.ra-cover { break-after: page }让 3:4 书封独占 PDF 首页TOC 从第二页开始。调样式换 break 策略 / 改双列阈值 / 加打印水印直接改这个 CSS 文件即可不用动 bash 脚本。七、Raw 交互在 PDF 里的边界PDF 是静态文档所有 Raw 交互滑块、按钮、动画、canvas、视频在 PDF 里只能渲染初始状态。关联文档对此给出了明确的设计建议interactive-explainer文章类型核心是操作PDF 价值有限用户可在 Plan 阶段不开 PDF 导出其它类型Raw 通常是辅助图解流程图 / SVG / 趋势图初始态已够看PDF 没问题Raw 内内容若依赖 hover / click 才显示写 Raw 时就考虑是否打印友好例如默认露出关键内容、用print:风格让 hover 状态在打印时强制展开。另外如需复制为提示词 / 行动项按钮可在文章里挂ExportBar组件——它与 PDF 无关reacticle 的 print.css 会自动在打印时隐藏它。八、交付自检清单进入 Phase 8 Delivery 前按关联文档执行以下自检npm run html成功article/article.html能在浏览器离线打开控制台无报错桌面与移动端都可读无文字溢出 / 遮挡 / 空白异常。九、故障排查速查PDF 场景从 references/pdf-output.md 提炼的常见问题与解法现象排查与修复找不到浏览器脚本打印注入过打印 CSS 的临时 HTML 路径手动 CmdP 即可PDF 里 TOC 没分页 / 跟正文挤在一起某些旧版 Chromium 对page-break-after: always支持有差异升级 Chrome 主版本或在打印对话框调两面 / 缩放 / 自定义边距分页奇怪 / 大块空白页 / 标题孤零零卡页底通常是原子块被强制不分页导致整块被推走。检查B1 是否生效DevTools Print Preview 看.ra-section的break-inside值理论上我们的!important一定能赢过 reacticle 无!important的规则自己写的 Raw 块里有没有 inlinestyle{{ breakInside: avoid }}——删掉想更激进地防孤儿标题把 B2 改成break-before: avoid; break-after: avoidRaw 没渲染完整 / 图表空白把脚本里--virtual-time-budget从 5000 改到 10000检查 Raw 的 JS 是否在 DOMContentLoaded 内同步渲染改造 Raw 为 SSR-friendly 初始态 客户端 hydratePDF 字体与浏览器不一致主题用了font-face远程字体时 headless Chrome 默认不等它加载完用 system font fallback多数主题已做或在 HTML 里把字体data:内联想自定义页面留白 / 纸张优先调pdf-print-overrides.css里.ra-root的 print padding更复杂的用浏览器 GUI 打印CmdP或派生 puppeteer 版脚本当前脚本默认按 Chrome 默认页面尺寸Letter 美区 / A4 其它区输出十、与 Skill 流程的关系从源码结构可以推断HTML/PDF 输出严格挂接在 SKILL.md 的三段式 Checkpoint 流程上Phase 4 First Spread 用npm run dev边写边看Phase 5 每节完成后npm run typecheck/build验证Phase 8 Delivery 时用户于 Checkpoint 3 选择交付决策——通过 · 导出 HTML 交付只跑npm run html选通过 · 同时导出 HTML PDF才追加bash html-to-pdf.sh交付article.htmlarticle.pdf两份产物用户事后想补 PDF 也可随时在工作区根目录手动重跑脚本。整个链路刻意保持脚手架轻量不在脚手架强行装任何 PDF 相关 npm 包、不在 Checkpoint 3 默认勾选 PDF、不改 reacticle 来支持 PDF——CSS 注入方案与 reacticle 版本解耦是这套构建体系最值得借鉴的设计取舍。赞分享人工智能AI 技能/插件提示工程【免费下载链接】garden-skillsConardLis open-source Skills collection, featuring web design, knowledge retrieval, image generation, and more.项目地址https://gitcode.com/GitHub_Trending/we/garden-skills点击查看免费下载相关推荐三步从地址到成片N_m3u8DL-RE 的 m3u8/MPD 下载新手实操三步从地址到成片N_m3u8DL RE 的 m3u8/MPD 下载新手实操 N_m3u8DL RE 是一款免费开源MIT 协议的跨平台流媒体下载工具m3CLI音视频Decimen Optical Transfer构建与部署指南从Vite插件到单文件HTML光传输打包Decimen Optical Transfer构建与部署指南从Vite插件到单文件HTML光传输打包 Decimen Optical Transfer 是一前端fireworks-tech-graph 离线交互式架构图实战从 JSON fixture 到单文件 HTMLfireworks tech graph 离线交互式架构图实战从 JSON fixture 到单文件 HTML fireworks tech graph 仓库AI 技能数据可视化上一篇3步搞定终极小说下载器novel-downloader让你心爱的小说永不消失的完整指南下一篇Montserrat开源字体专业设计的免费解决方案提升你的视觉传达效率创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Beautiful Article 的 HTML 输出与构建：从 Vite + React + TS 工作区到离线可分享的单文件交付物
人工智能AI 技能/插件提示工程【免费下载链接】garden-skillsConardLis open-source Skills collection, featuring web design, knowledge retrieval, image generation, and more.项目地址https://gitcode.com/GitHub_Trending/we/garden-skills点击查看免费下载导读本篇技术指南聚焦 garden-skills 仓库中 beautiful-article Skill 的输出与构建链路文章不是手写裸 HTML而是运行在 Vite React TS 工作区中、由语义组件协议 reacticle 渲染、最终被vite-plugin-singlefile压成 CSS JS 全部内联的自包含单页 HTML。读完本文你将掌握四条构建命令的职责划分、单文件产物的实现原理、运行时主题的切换方式以及可选的 HTML→PDF 导出流程包括打印 CSS 注入的设计动机与 headless 浏览器渲染细节并理解交付自检的完整标准。一、工作区是什么一个从 npm 消费 reacticle 的 Vite 项目Beautiful Article 的文章工作区本质上是一个标准的Vite React TypeScript 项目从 npm 消费组件库reacticle最新发布版即reacticle: latest而不是在仓库内维护一份组件库源码。这一点在脚手架模板的 package.json 中写得很明确{ name: beautiful-article-workspace, private: true, version: 0.0.0, type: module, scripts: { dev: vite, build: tsc --noEmit vite build, html: npm run build node -e \require(fs).mkdirSync(article,{recursive:true});require(fs).copyFileSync(dist/index.html,article/article.html);console.log(built article/article.html)\, typecheck: tsc --noEmit, preview: vite preview }, dependencies: { react: ^18.3.1, react-dom: ^18.3.1, reacticle: latest }, devDependencies: { types/react: ^18.3.12, types/react-dom: ^18.3.1, vitejs/plugin-react: ^4.3.4, typescript: ^5.6.3, vite: ^5.4.11, vite-plugin-singlefile: ^2.0.3 } }几个值得注意的细节reacticle: latest脚手架创建完目录后会执行npm install reacticlelatest强制刷新到当下最新版并打印实际版本避免缓存到旧包。katex/prismjs作为 reacticle 的依赖会被自动带下来无需工作区单独声明。html脚本不是新构建它复用npm run build含tsc --noEmit类型检查再把dist/index.html复制到article/article.html——后者才是真正的交付物详情见下文命令表。tsc --noEmit vite build的顺序保证TS 报错会让构建直接失败错误不会漏进交付物。文章源码的组织方式与装配逻辑见 SKILL.md 与 scaffold.md工作区包含source/源文抽取、plan/规划、review/质检等长期记忆目录以及article/Article.tsxassembler、article/sections/NN-*.tsx一节一文件、article/raw-blocks/大型 Raw 隔离、article/assets/配图素材。核心铁律是Article.tsx只负责 import 与排序各 Section 组件绝不内联 Section 正文这是多 Agent 并行开发的前提。二、命令表四条命令各管一段关联文档给出了工作区根目录下的核心命令表这里逐一展开其作用与适用阶段命令作用npm run dev启动 Vite 开发预览对应脚本vite用于 Phase 4 / 5 边写边看首屏、每个 Section 完成后都靠它本地验收。npm run build先跑tsc --noEmit做类型检查再vite build产出自包含单页 HTML到dist/index.htmlCSS JS 全部内联。TS 报错即构建失败防止错误进入交付物。npm run html复用npm run build含类型检查再把单页 HTML 复制到article/article.html——这是最终交付物由内联的 node 单行命令完成mkdirSync(article, {recursive:true})copyFileSync。npm run typecheck仅执行tsc --noEmit类型检查不改动产物适合多 Agent 并行阶段快速验证某个 Section 是否类型正确。其中build与html都内建了类型检查这与 SKILL 的 Phase 5 多 Agent 模式直接相关并行编写sections/NN-*.tsx时主 Agent 需要维护Article.tsx的 import 与顺序、跑npm run typecheck/build、兜底主题与风格一致、解决冲突。三、单文件产物的原理vite-plugin-singlefile 内联一切npm run html之所以能产出一个断网可打开、可分享的单文件关键在于 Vite 插件vite-plugin-singlefile。脚手架模板的 vite.config.ts 完整展示了接线方式import { resolve } from node:path; import { defineConfig } from vite; import react from vitejs/plugin-react; import { viteSingleFile } from vite-plugin-singlefile; // reacticle is consumed from the published npm package (see package.json). // Builds a self-contained single-page HTML (CSS JS inlined, opens offline) // to dist/index.html. npm run html then copies it to article/article.html. export default defineConfig({ plugins: [react(), viteSingleFile()], build: { outDir: dist, emptyOutDir: true, rollupOptions: { input: resolve(__dirname, index.html), }, }, });要点拆解plugins: [react(), viteSingleFile()]viteSingleFile把所有产出的 CSS 与 JS 内联进 HTML静态资源也一并处理woff 字体等资源是否能内联取决于主题怎么写这会在 PDF 字体一节再次涉及。build.outDir: distemptyOutDir: true每次构建清空dist保证产物干净、无残留。入口是根index.htmlindex.html 中langzh-CN、div idroot/div、script typemodule src/article/main.tsx并预连接 Google Fonts 加载主题字体tufte主题 fallback 到 Georgiapress主题使用 Newsreader。从源码结构可以推断单文件策略是该 Skill 信息交付的核心承诺HTML 的价值在于提升信息密度、视觉清晰度、分享便利性和交互能力而单文件形态让这份 HTML 可以脱离网络、脱离构建环境直接被读者打开。四、切换主题只改一个字符串主题在文章入口 article/main.tsx 中固定createRoot(document.getElementById(root)!).render( StrictMode ThemeProvider theme__THEME__ Cover / ArticleDoc / /ThemeProvider /StrictMode );theme__THEME__是脚手架注入的占位符实际写入的是所选主题的runtime theme id。当前已注册的 id 为tufte/press完整清单见 theme-profiles/index.json改一个字即可整体切换观感。换主题必须同步改两处并保持一致①main.tsx的ThemeProvider theme...控制运行时主题②Article.tsx末尾 colophon 里的· 主题 theme控制文章印记中显示的主题名。colophon 是 scaffold 自带、不可删除的 Raw 块Made with beautiful-article · 主题 theme低对比小字、--ra-*token 自适应见 Article.tsx。main.tsx还揭示了渲染顺序的设计Cover封面可选→ ArticleDoc含 TOC 正文 colophon。Cover 故意不塞进Article内部那样会被挤到正文栏旁边而是与ArticleDoc /在ThemeProvider下做兄弟组件DOM 顺序天然就是封面 → TOC → 正文 → colophon。脚手架用__COVER_IMPORT_*__/__COVER_RENDER_*__标记包裹封面相关代码scaffold.sh在--no-cover时整段剥掉。版式宽度narrow/regular/wide/full与 TOC 开关在 Plan Checkpoint 确认与主题解耦见 SKILL.md 与references/layout.md。五、PDF 导出可选环节由 Checkpoint 3 触发PDF 不是主交付物——主交付物永远是article/article.html。PDF 只在 Phase 8 Delivery 时用户于 Checkpoint 3 选择通过 · 同时导出 HTML PDF才生成不选则完全不动作。这是 Skill 的显式设计避免替用户默认导出。一句话用法详见 references/pdf-output.mdnpm run html # 先有 article/article.html bash path-to-beautiful-article/scripts/html-to-pdf.sh # → article/article.pdf脚本支持自定义输入输出路径bash html-to-pdf.sh in.html out.pdf也可把该 bash 调用写进工作区package.json的 scripts 里让用户npm run pdf路径是用户机器上 Skill 的绝对路径不在脚手架模板里固化避免硬编码。5.1 前提条件探测系统 chromium-family 浏览器脚本 html-to-pdf.sh 不依赖 Node / npm 包 / puppeteer / playwright / weasyprint故意只用系统已装的浏览器。它按固定顺序探测chromium / chromium-browser / google-chrome / google-chrome-stable / chrome brave-browser / microsoft-edge /Applications/Google Chrome.app/... /Applications/Chromium.app/... /Applications/Microsoft Edge.app/... /Applications/Brave Browser.app/... /Applications/Arc.app/... /usr/bin/chromium / /snap/bin/chromium找不到任何浏览器时脚本不会报错崩溃它会打印已经注入打印 CSS 的临时 HTML 路径并给出回退指引——用户用任意浏览器打开该临时文件CmdP/CtrlP→ 另存为 PDF即可注入的 print 样式已让 TOC 在上、正文在下与 PDF 阅读习惯对齐。5.2 渲染流程与 Chrome 标志从源码看脚本的渲染流水线是article.html ──── awk 注入 print CSS ──── /tmp/article-print.html │ ▼ 探测的浏览器 --headless --print-to-pdf │ ▼ article.pdf调用的 headless 浏览器标志及其用途标志用途--headlessnew旧版 fallback 到--headless无窗口模式--no-pdf-header-footer/--print-to-pdf-no-header去掉浏览器自带的 URL / 日期 / 页码这些与 colophon 的角色冲突--virtual-time-budget5000给页面 JS 5 秒初始化时间让 Raw 组件、KaTeX、Prism 等渲染完再截屏--hide-scrollbars/--disable-gpu/--no-sandbox清洁渲染六、打印 CSS 注入为什么动 CSS 而不是动 reacticle这是本 Skill PDF 方案的核心设计原理值得展开1. 问题根源reacticle 的 TOC 在桌面是左右栅格.ra-article-layout--with-toc为display: grid两列TOC | 文章在移动端≤999px才塌成单列display: block。而 PDF 阅读习惯是上下排布TOC 先 / 正文后跟移动端体验对齐。2. 最干净的解法在 PDF 生成时注入一段media printCSS强制 TOC 容器display: block等价于复用移动端分支。这样同时满足三个约束不动 reacticle任何版本的 reacticle 都能用这个脚本生成合理 PDF不动用户的 Article.tsx用户源码完全不受影响CSS 只在打印生效浏览器里看 HTML 仍是左右栅格。reacticle 自带的print.css仍然生效白底黑字 / 隐藏 export bar /break-inside: avoid等脚本只补 TOC 排版那一块。3. 注入的实现细节CSS 被抽到独立文件 scripts/pdf-print-overrides.css脚本只用awk把它的内容包在style idra-pdf-overrides里、塞到/head之前。之所以抽成独立文件而非内联字符串是因为macOS 自带 BSD awk 对-v inject$INLINE_CSS这种多行字符串报newline in string错GNU awk 没事改用getline file从文件读取后两个 awk 都吃得下顺带让 CSS 变成可独立编辑 / lint / diff 的真正资源。4. 注入的规则分四组完整带注释版本直接看 CSS 文件0 · Theme surface.ra-root保持主题纸色与文字色铺满整页print-color-adjust: exact强制打印背景色padding: 0.45in提供内容留白page { margin: 0 }让主题纸色铺满再用内边距留白——因为 Chromium 的--print-to-pdf不支持命令行页面尺寸 / 边距参数。A · TOC 排版TOC 上 / 正文下A1.ra-article-layout--with-toc { display: block }塌成单列A2.ra-toc { position: static; break-after: page }解除 sticky TOC 独占首页A3 长 TOC 用column-count: 2双列省纸A4 TOC 项break-inside: avoid不被列间撕开A5 正文在 TOC 后自然流A6 打印时去掉正文链接下划线。B · 分页行为修长文章的大块空白页B1 用break-inside: auto !important撤销 reacticle print.css 里的.ra-section { break-inside: avoid-page }——那条规则对多页长 Section 会适得其反整节被推到下一页、前一页留大半空白B2 标题break-after: avoid不孤儿化B3 Hero / Lead / Conclusion 原子化不撕开B4orphans: 3; widows: 3段落不留 1–2 行寡行B5 图表、表格、代码块尽量整块过高时浏览器自动 fallback 分页。C · 封面.ra-cover { break-after: page }让 3:4 书封独占 PDF 首页TOC 从第二页开始。调样式换 break 策略 / 改双列阈值 / 加打印水印直接改这个 CSS 文件即可不用动 bash 脚本。七、Raw 交互在 PDF 里的边界PDF 是静态文档所有 Raw 交互滑块、按钮、动画、canvas、视频在 PDF 里只能渲染初始状态。关联文档对此给出了明确的设计建议interactive-explainer文章类型核心是操作PDF 价值有限用户可在 Plan 阶段不开 PDF 导出其它类型Raw 通常是辅助图解流程图 / SVG / 趋势图初始态已够看PDF 没问题Raw 内内容若依赖 hover / click 才显示写 Raw 时就考虑是否打印友好例如默认露出关键内容、用print:风格让 hover 状态在打印时强制展开。另外如需复制为提示词 / 行动项按钮可在文章里挂ExportBar组件——它与 PDF 无关reacticle 的 print.css 会自动在打印时隐藏它。八、交付自检清单进入 Phase 8 Delivery 前按关联文档执行以下自检npm run html成功article/article.html能在浏览器离线打开控制台无报错桌面与移动端都可读无文字溢出 / 遮挡 / 空白异常。九、故障排查速查PDF 场景从 references/pdf-output.md 提炼的常见问题与解法现象排查与修复找不到浏览器脚本打印注入过打印 CSS 的临时 HTML 路径手动 CmdP 即可PDF 里 TOC 没分页 / 跟正文挤在一起某些旧版 Chromium 对page-break-after: always支持有差异升级 Chrome 主版本或在打印对话框调两面 / 缩放 / 自定义边距分页奇怪 / 大块空白页 / 标题孤零零卡页底通常是原子块被强制不分页导致整块被推走。检查B1 是否生效DevTools Print Preview 看.ra-section的break-inside值理论上我们的!important一定能赢过 reacticle 无!important的规则自己写的 Raw 块里有没有 inlinestyle{{ breakInside: avoid }}——删掉想更激进地防孤儿标题把 B2 改成break-before: avoid; break-after: avoidRaw 没渲染完整 / 图表空白把脚本里--virtual-time-budget从 5000 改到 10000检查 Raw 的 JS 是否在 DOMContentLoaded 内同步渲染改造 Raw 为 SSR-friendly 初始态 客户端 hydratePDF 字体与浏览器不一致主题用了font-face远程字体时 headless Chrome 默认不等它加载完用 system font fallback多数主题已做或在 HTML 里把字体data:内联想自定义页面留白 / 纸张优先调pdf-print-overrides.css里.ra-root的 print padding更复杂的用浏览器 GUI 打印CmdP或派生 puppeteer 版脚本当前脚本默认按 Chrome 默认页面尺寸Letter 美区 / A4 其它区输出十、与 Skill 流程的关系从源码结构可以推断HTML/PDF 输出严格挂接在 SKILL.md 的三段式 Checkpoint 流程上Phase 4 First Spread 用npm run dev边写边看Phase 5 每节完成后npm run typecheck/build验证Phase 8 Delivery 时用户于 Checkpoint 3 选择交付决策——通过 · 导出 HTML 交付只跑npm run html选通过 · 同时导出 HTML PDF才追加bash html-to-pdf.sh交付article.htmlarticle.pdf两份产物用户事后想补 PDF 也可随时在工作区根目录手动重跑脚本。整个链路刻意保持脚手架轻量不在脚手架强行装任何 PDF 相关 npm 包、不在 Checkpoint 3 默认勾选 PDF、不改 reacticle 来支持 PDF——CSS 注入方案与 reacticle 版本解耦是这套构建体系最值得借鉴的设计取舍。赞分享人工智能AI 技能/插件提示工程【免费下载链接】garden-skillsConardLis open-source Skills collection, featuring web design, knowledge retrieval, image generation, and more.项目地址https://gitcode.com/GitHub_Trending/we/garden-skills点击查看免费下载相关推荐三步从地址到成片N_m3u8DL-RE 的 m3u8/MPD 下载新手实操三步从地址到成片N_m3u8DL RE 的 m3u8/MPD 下载新手实操 N_m3u8DL RE 是一款免费开源MIT 协议的跨平台流媒体下载工具m3CLI音视频Decimen Optical Transfer构建与部署指南从Vite插件到单文件HTML光传输打包Decimen Optical Transfer构建与部署指南从Vite插件到单文件HTML光传输打包 Decimen Optical Transfer 是一前端fireworks-tech-graph 离线交互式架构图实战从 JSON fixture 到单文件 HTMLfireworks tech graph 离线交互式架构图实战从 JSON fixture 到单文件 HTML fireworks tech graph 仓库AI 技能数据可视化上一篇3步搞定终极小说下载器novel-downloader让你心爱的小说永不消失的完整指南下一篇Montserrat开源字体专业设计的免费解决方案提升你的视觉传达效率创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
