如何使用 mkdocs-material 的 shadow tags 在正式构建中过滤 Draft 等未发布内容【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material文档站点中经常存在还没定稿的页面你希望给它们打上Draft之类的标记在开发预览时一眼看出哪些内容未发布但在mkdocs build产出的正式站点里又不希望读者看到这些标记。Material for MkDocs 内置 tags 插件提供的 shadow tags 机制就是为此设计的把Draft登记为 shadow tag 后这个标签会在预览和正式构建中走不同的渲染规则——预览默认显示构建默认排除。版本与前提shadow tags 相关设置shadow_tags、shadow、shadow_on_serve、shadow_tags_prefix、shadow_tags_suffix均自 9.7.0 引入文档中带有 experimental 标记。本仓库当前版本为 9.7.6满足要求。tags 插件是 Material for MkDocs 内置插件不需要额外安装只需在mkdocs.yml中启用。在 mkdocs.yml 中登记 shadow tags在mkdocs.yml中启用 tags 插件并用shadow_tags列出哪些标签属于 shadow tagsplugins: - tags: shadow_tags: - Draft - Internal官方文档对 shadow tags 的定义是Shadow tags are tags that are solely meant to organization, which can be included or excluded for rendering with a simple flag. 也就是说它们只承担组织用途是否渲染由一个开关控制。除了显式列表文档还提供了两种基于前后缀的登记方式适合标签命名有规律的项目plugins: - tags: shadow_tags_prefix: _plugins: - tags: shadow_tags_suffix: Internalshadow_tags_prefix下以_开头的标签会被标记为 shadow tagshadow_tags_suffix下以Internal结尾的标签会被标记为 shadow tag。三种方式都写在同一个插件配置块里按需选择一种即可。给未发布页面打上 Draft 标记在 Markdown 文件头部的 front matter 中用tags属性给页面打标签--- tags: - Draft --- ...如果需要给整个目录的所有页面统一加标签可以在对应目录创建.meta.yml依赖内置 meta 插件内容如下tags: - Draft.meta.yml中的标签会与页面自身的标签合并去重方便按目录批量标记未发布内容。如果担心标签拼写错误导致过滤失效可以配合tags_allowed设定允许列表plugins: - tags: tags_allowed: - Draft - Internal - HTML5 - JavaScript - CSS页面引用了列表之外的标签时插件会终止构建这样Draf这类拼写错误会在构建阶段立刻暴露而不是让一个看似打了 Draft、实际未生效的页面溜进正式站点。开发预览默认显示 shadow tags启动预览服务器mkdocs serve --livereloadshadow_on_serve的默认值是true因此预览时带Draft标签的页面会正常渲染出该标签你可以在本地确认哪些页面还未发布。如果不希望在预览中显示显式关闭plugins: - tags: shadow_on_serve: false正式构建默认排除 shadow tags执行构建mkdocs buildshadow的默认值是false。文档描述的行为是If a document is tagged withDraft, the tag will only be rendered ifshadowsetting is enabled, and excluded when it is disabled. 即在默认配置下正式构建产物中Draft标签不会出现在页面或 tags 列表里而未标记的页面不受影响。如果某次构建是给内部审阅用的 deploy preview希望保留这些标记把shadow打开plugins: - tags: shadow: true单个 tags 列表listing还可以用自己的shadow值覆盖全局设置例如某个索引页要展示全部标签!-- material/tags { shadow: true } --让 tags 索引彻底排除 Draft 页面shadow tags 控制的是标签本身的渲染如果你还想让打了Draft的页面从 tags 索引列表中整体消失用 listing 的exclude设置。文档说明Each page that features a tag that is part of this setting, is excluded from the listing entirely——注意作用范围是 listing不会把页面从站点中删除。先建一个标签索引页例如tags.md需位于nav中# Tags Following is a list of relevant tags: !-- material/tags --渲染效果如文档截图所示然后让索引排除Draft页面内联写法!-- material/tags { exclude: [Draft] } --或者把配置放进mkdocs.yml的listings_map供多处索引复用plugins: - tags: listings_map: public: exclude: - Draft索引页中引用配置标识符即可!-- material/tags public --文档同时提示listing 标记不能出现在代码块内部。验证结果文档给出的判断依据是对比两个环境下的渲染结果运行mkdocs serve --livereload打开带Draft标签的页面标签应显示在标题上方默认shadow_on_serve: true。运行mkdocs build打开site目录中对应页面的渲染结果Draft标签不应出现在页面上tags 索引里也不应列出带Draft的页面若使用了exclude。若启用了tags_allowed把某个页面标签改成列表外的名称再构建构建应直接失败以此验证过滤链路依赖的标签名是受控的。限制说明文档中 shadow tags 的效果限定在标签是否渲染以及页面是否进入 listing并未提供把整页从构建产物中移除的机制需要隔离内容本身时应结合nav的取舍另行处理。相关设置自 9.7.0 引入且文档标注为 experimental升级大版本前建议对照 changelog 确认行为未变。更多配置项shadow、shadow_on_serve、shadow_tags的默认值等见 内置 tags 插件文档标签索引与 shadow tags 的使用示例见 Setting up tags预览与构建命令见 Creating your site。【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
