企业官网建设流程全解析

如何使用 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 tags：

plugins: - 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: Internal

shadow_tags_prefix下，以_开头的标签会被标记为 shadow tag；shadow_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 --livereload

shadow_on_serve的默认值是true，因此预览时带Draft标签的页面会正常渲染出该标签，你可以在本地确认哪些页面还未发布。如果不希望在预览中显示，显式关闭：

plugins: - tags: shadow_on_serve: false

正式构建：默认排除 shadow tags

执行构建：

mkdocs build

shadow的默认值是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 标记不能出现在代码块内部。

验证结果

文档给出的判断依据是对比两个环境下的渲染结果：

1. 运行mkdocs serve --livereload，打开带Draft标签的页面，标签应显示在标题上方（默认shadow_on_serve: true）。
2. 运行mkdocs build，打开site目录中对应页面的渲染结果，Draft标签不应出现在页面上，tags 索引里也不应列出带Draft的页面（若使用了exclude）。
3. 若启用了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