MkDocs Material 插件智能缓存机制详解cache 与 cache_dir 配置实战【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-materialMkDocs Material 的多个内置插件实现了智能缓存intelligent caching机制能够大幅缩短连续构建的耗时——只要源文件内容没有变化插件就会复用上一次构建的结果而不是重复执行高开销的任务。本文以仓库中的 缓存指南 为核心结合 social、optimize、privacy、projects 四个插件的源码实现系统讲解缓存的默认行为、cache与cache_dir两个配置项的用法以及何时需要把缓存提交进 Git 仓库这一进阶场景的完整落地方法。什么是插件智能缓存在 MkDocs Material 中部分内置插件会缓存构建过程中生成的中间产物从而在连续多次构建时跳过重复计算。缓存机制在 文档 中被描述为Some of the built-in plugins implement intelligent caching mechanisms, which massively speed up consecutive builds by reducing the amount of work that needs to be done.也就是说缓存的价值在于减少需要重复完成的工作量典型的高开销任务包括social 插件为每个页面渲染一张社交卡片Social Cards图片涉及 SVG → PNG 的光栅化成本极高optimize 插件对站点中的 PNG/JPG 图片进行有损压缩与元数据剥离同样属于 CPU 密集型操作privacy 插件从外部如 Google Fonts下载字体等外部资源到本地缓存可以避免每次构建都重新发起网络请求projects 插件构建由多个独立 MkDocs 项目组成的多项目站点缓存用于记录项目元数据与构建状态。从源码可以确认正是这四个插件在配置类中同时定义了cache与cache_dir两个选项其余内置插件没有实现缓存机制插件配置类cache默认值cache_dir默认值socialsrc/plugins/social/config.pytrue.cache/plugin/socialoptimizesrc/plugins/optimize/config.pytrue.cache/plugin/optimizeprivacysrc/plugins/privacy/config.pytrue.cache/plugin/privacyprojectssrc/plugins/projects/config.pytrue.cache/plugin/projects四个插件的cache_dir默认值都以.cache为根、按插件名分子目录对应 缓存指南 中所说的插件会把数据缓存在项目根目录的.cache文件夹中。对应的 JSON Schema如 docs/schema/plugins/social.json也同步了这些默认值可作为 IDE 自动补全与校验的依据。智能缓存的工作方式源码视角所谓智能指的是缓存并非简单的永远复用而是通过一个manifest清单文件精确追踪每个缓存条目的状态。以 social 插件为例其核心流程在 src/plugins/social/plugin.py 中清晰可见1. 解析缓存目录并加载 manifest在on_config阶段L119-L144插件会将cache_dir解析为绝对路径并且始终相对于配置文件mkdocs.yml所在目录解析而不是相对于当前工作目录。源码注释明确指出这是为了让缓存机制在 projects 插件的多项目场景下也能正确工作自动创建缓存目录os.makedirs(..., exist_ok True)如果cache选项为true且manifest.json已存在则加载该清单文件。2. 逐条比对并复用缓存后续生成卡片时插件会把每个条目的关键变量如页面路径、布局变量、字体、图标等计算成哈希并记录在 manifest 中self.manifest[file.url] hash。只有当某个条目的内容发生变化、或该条目不在缓存中时才会真正触发重新生成。这正是文档中卡片内容不变就不重新生成这一行为见 docs/plugins/social.md 的说明的底层实现。3. 回写 manifest构建结束时插件把更新后的 manifest 写回磁盘on_post_build阶段 L279-L283以及on_shutdown阶段 L305-L308。optimize 插件采用完全相同的模式在 on_config 加载 manifest在 on_post_build 写回并利用cache_dir下的文件作为已优化图片的直接来源。privacy 插件的逻辑则更为直观在_fetch方法src/plugins/privacy/plugin.py中只有当本地文件不存在或cache被显式关闭时才会真正发起外部资源下载。理解了上述机制就能明白两个配置项的语义cache总开关。置为false即绕过缓存、强制重做cache_dir缓存落盘位置。决定 manifest 与缓存产物存放在哪个目录。基础配置把缓存目录加入 .gitignore缓存是完全可选但默认开启的。由于默认情况下缓存位于项目根目录的.cache文件夹而缓存内容属于构建中间产物、会随构建不断变化文档强烈建议在项目根目录创建.gitignore文件.cache这样能确保缓存文件不会被打进 Git 仓库。将缓存提交进版本库在绝大多数情况下都不推荐原因在于缓存内容与本地环境强相关换一台机器或换一个构建环境后往往失效每次构建都会改写 manifest 与缓存产物会导致 Git 历史中出现大量无意义的变更噪声.cache目录本身没有任何源码价值属于可再生资产。按插件关闭缓存cache 选项如果某个插件的行为不符合预期例如正在调试该插件本身可以在mkdocs.yml中针对单个插件关闭缓存。以 social 插件为例plugins: - social: cache: false配置为false后插件会跳过 manifest 的加载与写入无条件重新执行全部工作social 插件会为所有页面重新生成社交卡片optimize 插件会重新优化全部媒体文件privacy 插件会重新调度下载所有外部资源projects 插件会重建所有子项目。各插件对应文档social、optimize、privacy、projects均说明了这一点并强调通常没有必要指定此设置除非在调试插件本身。自定义缓存位置cache_dir 选项cache_dir是所有实现缓存的插件共享的配置项用于改变缓存目录在项目根目录中的路径。例如将 social 插件的缓存移到自定义目录plugins: - social: cache_dir: my/custom/dir此时缓存 manifest 会出现在my/custom/dir/manifest.json。需要注意两点路径始终相对于mkdocs.yml所在目录解析而非当前工作目录详见 src/plugins/social/plugin.py 的实现注释这保证了无论从哪个目录执行mkdocs build缓存位置都保持一致每个插件实例拥有独立的cache_dir因此可以通过多次声明同一个插件并搭配不同cache_dir实现互不干扰的多个缓存实例。例如为两套不同布局分别生成社交卡片plugins: - social: cards_layout: default cache_dir: .cache/social/default - social: cards_layout: variant cache_dir: .cache/social/variant何时需要把缓存提交进 Git文档同时指出了一个例外场景在极少数情况下你可能需要把缓存文件提交进仓库。最典型的情形是——预生成社交卡片e.g. when you need to pre-generate social cards locally, e.g., when youre not able to install the image processing dependencies in your continuous integration (CI) environment.也就是说如果你的 CI 环境无法安装图片处理依赖详见 图片处理指南 中关于 Cairo Graphics、Pillow、pngquant 的安装说明那么可以在本地开发机已装好依赖上先运行一次构建生成全部社交卡片把生成好的卡片连同缓存清单一起提交到 Git 仓库CI 构建时直接复用仓库中的缓存产物从而绕开图片处理依赖。这种情况下文档给出的建议是更改cache_dir设置——把它指向一个你愿意纳入 Git 的目录而不是默认的.cacheplugins: - social: cache_dir: assets/cache/social同时调整.gitignore让该目录可以被 Git 追踪.cache/* !assets/cache/将缓存纳入版本控制时建议留意以下几点避免仓库膨胀与缓存失效只提交必要插件的缓存仅对确需预生成的插件通常是 social设置并提交cache_dir其余插件保持默认的.cache忽略策略保持缓存可再生成即使提交了缓存也应保证 CI 或本机具备重新生成缓存的能力依赖齐全因为 manifest 中的条目一旦失效如布局变量变化插件仍会重新生成对应产物注意仓库体积社交卡片是 PNG 图片随着页面增多会占用可观空间提交前请评估是否值得。若 CI 环境实际上已经预装了所需依赖例如 GitHub Actions 的 Ubuntu runner 或 Docker 镜像 均预装了 Cairo Graphics 与 pngquant则通常无需此方案。小结MkDocs Material 的智能缓存是一套以 manifest 清单 内容哈希为核心、默认开启、可逐插件开关与重定位的增量构建基础设施配置项类型默认值作用cachebooleantrue是否启用该插件的智能缓存置false可强制全部重做cache_dirstring.cache/plugin/插件名缓存目录位置相对mkdocs.yml解析可逐实例独立设置日常使用中只需在.gitignore中忽略.cache即可享受连续构建大幅提速的默认收益当遇到 CI 无法安装图片处理依赖、需要预生成社交卡片等特殊场景时再通过调整cache_dir将缓存纳入版本控制。相关配置的完整说明可继续查阅 social、optimize、privacy、projects 各自页面中的 Caching 小节以及内置插件总览。【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MkDocs Material 插件智能缓存机制详解：cache 与 cache_dir 配置实战
MkDocs Material 插件智能缓存机制详解cache 与 cache_dir 配置实战【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-materialMkDocs Material 的多个内置插件实现了智能缓存intelligent caching机制能够大幅缩短连续构建的耗时——只要源文件内容没有变化插件就会复用上一次构建的结果而不是重复执行高开销的任务。本文以仓库中的 缓存指南 为核心结合 social、optimize、privacy、projects 四个插件的源码实现系统讲解缓存的默认行为、cache与cache_dir两个配置项的用法以及何时需要把缓存提交进 Git 仓库这一进阶场景的完整落地方法。什么是插件智能缓存在 MkDocs Material 中部分内置插件会缓存构建过程中生成的中间产物从而在连续多次构建时跳过重复计算。缓存机制在 文档 中被描述为Some of the built-in plugins implement intelligent caching mechanisms, which massively speed up consecutive builds by reducing the amount of work that needs to be done.也就是说缓存的价值在于减少需要重复完成的工作量典型的高开销任务包括social 插件为每个页面渲染一张社交卡片Social Cards图片涉及 SVG → PNG 的光栅化成本极高optimize 插件对站点中的 PNG/JPG 图片进行有损压缩与元数据剥离同样属于 CPU 密集型操作privacy 插件从外部如 Google Fonts下载字体等外部资源到本地缓存可以避免每次构建都重新发起网络请求projects 插件构建由多个独立 MkDocs 项目组成的多项目站点缓存用于记录项目元数据与构建状态。从源码可以确认正是这四个插件在配置类中同时定义了cache与cache_dir两个选项其余内置插件没有实现缓存机制插件配置类cache默认值cache_dir默认值socialsrc/plugins/social/config.pytrue.cache/plugin/socialoptimizesrc/plugins/optimize/config.pytrue.cache/plugin/optimizeprivacysrc/plugins/privacy/config.pytrue.cache/plugin/privacyprojectssrc/plugins/projects/config.pytrue.cache/plugin/projects四个插件的cache_dir默认值都以.cache为根、按插件名分子目录对应 缓存指南 中所说的插件会把数据缓存在项目根目录的.cache文件夹中。对应的 JSON Schema如 docs/schema/plugins/social.json也同步了这些默认值可作为 IDE 自动补全与校验的依据。智能缓存的工作方式源码视角所谓智能指的是缓存并非简单的永远复用而是通过一个manifest清单文件精确追踪每个缓存条目的状态。以 social 插件为例其核心流程在 src/plugins/social/plugin.py 中清晰可见1. 解析缓存目录并加载 manifest在on_config阶段L119-L144插件会将cache_dir解析为绝对路径并且始终相对于配置文件mkdocs.yml所在目录解析而不是相对于当前工作目录。源码注释明确指出这是为了让缓存机制在 projects 插件的多项目场景下也能正确工作自动创建缓存目录os.makedirs(..., exist_ok True)如果cache选项为true且manifest.json已存在则加载该清单文件。2. 逐条比对并复用缓存后续生成卡片时插件会把每个条目的关键变量如页面路径、布局变量、字体、图标等计算成哈希并记录在 manifest 中self.manifest[file.url] hash。只有当某个条目的内容发生变化、或该条目不在缓存中时才会真正触发重新生成。这正是文档中卡片内容不变就不重新生成这一行为见 docs/plugins/social.md 的说明的底层实现。3. 回写 manifest构建结束时插件把更新后的 manifest 写回磁盘on_post_build阶段 L279-L283以及on_shutdown阶段 L305-L308。optimize 插件采用完全相同的模式在 on_config 加载 manifest在 on_post_build 写回并利用cache_dir下的文件作为已优化图片的直接来源。privacy 插件的逻辑则更为直观在_fetch方法src/plugins/privacy/plugin.py中只有当本地文件不存在或cache被显式关闭时才会真正发起外部资源下载。理解了上述机制就能明白两个配置项的语义cache总开关。置为false即绕过缓存、强制重做cache_dir缓存落盘位置。决定 manifest 与缓存产物存放在哪个目录。基础配置把缓存目录加入 .gitignore缓存是完全可选但默认开启的。由于默认情况下缓存位于项目根目录的.cache文件夹而缓存内容属于构建中间产物、会随构建不断变化文档强烈建议在项目根目录创建.gitignore文件.cache这样能确保缓存文件不会被打进 Git 仓库。将缓存提交进版本库在绝大多数情况下都不推荐原因在于缓存内容与本地环境强相关换一台机器或换一个构建环境后往往失效每次构建都会改写 manifest 与缓存产物会导致 Git 历史中出现大量无意义的变更噪声.cache目录本身没有任何源码价值属于可再生资产。按插件关闭缓存cache 选项如果某个插件的行为不符合预期例如正在调试该插件本身可以在mkdocs.yml中针对单个插件关闭缓存。以 social 插件为例plugins: - social: cache: false配置为false后插件会跳过 manifest 的加载与写入无条件重新执行全部工作social 插件会为所有页面重新生成社交卡片optimize 插件会重新优化全部媒体文件privacy 插件会重新调度下载所有外部资源projects 插件会重建所有子项目。各插件对应文档social、optimize、privacy、projects均说明了这一点并强调通常没有必要指定此设置除非在调试插件本身。自定义缓存位置cache_dir 选项cache_dir是所有实现缓存的插件共享的配置项用于改变缓存目录在项目根目录中的路径。例如将 social 插件的缓存移到自定义目录plugins: - social: cache_dir: my/custom/dir此时缓存 manifest 会出现在my/custom/dir/manifest.json。需要注意两点路径始终相对于mkdocs.yml所在目录解析而非当前工作目录详见 src/plugins/social/plugin.py 的实现注释这保证了无论从哪个目录执行mkdocs build缓存位置都保持一致每个插件实例拥有独立的cache_dir因此可以通过多次声明同一个插件并搭配不同cache_dir实现互不干扰的多个缓存实例。例如为两套不同布局分别生成社交卡片plugins: - social: cards_layout: default cache_dir: .cache/social/default - social: cards_layout: variant cache_dir: .cache/social/variant何时需要把缓存提交进 Git文档同时指出了一个例外场景在极少数情况下你可能需要把缓存文件提交进仓库。最典型的情形是——预生成社交卡片e.g. when you need to pre-generate social cards locally, e.g., when youre not able to install the image processing dependencies in your continuous integration (CI) environment.也就是说如果你的 CI 环境无法安装图片处理依赖详见 图片处理指南 中关于 Cairo Graphics、Pillow、pngquant 的安装说明那么可以在本地开发机已装好依赖上先运行一次构建生成全部社交卡片把生成好的卡片连同缓存清单一起提交到 Git 仓库CI 构建时直接复用仓库中的缓存产物从而绕开图片处理依赖。这种情况下文档给出的建议是更改cache_dir设置——把它指向一个你愿意纳入 Git 的目录而不是默认的.cacheplugins: - social: cache_dir: assets/cache/social同时调整.gitignore让该目录可以被 Git 追踪.cache/* !assets/cache/将缓存纳入版本控制时建议留意以下几点避免仓库膨胀与缓存失效只提交必要插件的缓存仅对确需预生成的插件通常是 social设置并提交cache_dir其余插件保持默认的.cache忽略策略保持缓存可再生成即使提交了缓存也应保证 CI 或本机具备重新生成缓存的能力依赖齐全因为 manifest 中的条目一旦失效如布局变量变化插件仍会重新生成对应产物注意仓库体积社交卡片是 PNG 图片随着页面增多会占用可观空间提交前请评估是否值得。若 CI 环境实际上已经预装了所需依赖例如 GitHub Actions 的 Ubuntu runner 或 Docker 镜像 均预装了 Cairo Graphics 与 pngquant则通常无需此方案。小结MkDocs Material 的智能缓存是一套以 manifest 清单 内容哈希为核心、默认开启、可逐插件开关与重定位的增量构建基础设施配置项类型默认值作用cachebooleantrue是否启用该插件的智能缓存置false可强制全部重做cache_dirstring.cache/plugin/插件名缓存目录位置相对mkdocs.yml解析可逐实例独立设置日常使用中只需在.gitignore中忽略.cache即可享受连续构建大幅提速的默认收益当遇到 CI 无法安装图片处理依赖、需要预生成社交卡片等特殊场景时再通过调整cache_dir将缓存纳入版本控制。相关配置的完整说明可继续查阅 social、optimize、privacy、projects 各自页面中的 Caching 小节以及内置插件总览。【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考