Material for MkDocs 文档格式化完全指南：Critic Markup、文本高亮、上下标与键盘按键

Material for MkDocs 文档格式化完全指南Critic Markup、文本高亮、上下标与键盘按键【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-materialMaterial for MkDocs 通过 Python Markdown Extensions 为文档写作提供了丰富的行内格式化能力你既可以用 Critic Markup 在文档中展示建议增删式的变更追踪也可以用极简的符号语法实现文本高亮、插入、删除、上下标以及键盘按键的渲染。本文以仓库中的 格式化参考文档 为主体结合主题源码样式定义与配置逐项讲解如何开启、书写与定制这些格式化语法读完即可在你的文档站点中直接落地使用。概览格式化能力的组成Material for MkDocs 支持的格式化能力全部来自 PyMdown Extensions它们共同解决了文档协作与表达中的四类需求变更追踪Critic Markup在文档中高亮建议删除、建议新增、替换、批注等协作痕迹适合审阅场景文本高亮Caret、Mark Tilde用、^^、~~等简洁符号实现高亮、插入下划线与删除删除线比手写 HTML 标签更易维护上下标Caret Tilde以~2~、^T^形式书写化学式、数学符号等键盘按键Keys用ctrlaltdel渲染带图标样式的键盘按键组合。这些能力的开启位置统一在mkdocs.yml的markdown_extensions配置中属于解析阶段的 Markdown 扩展不依赖主题的 JavaScript 运行时。从仓库根目录的 mkdocs.yml 可以看到Material for MkDocs 官方文档自身就启用了pymdownx.caret、pymdownx.keys、pymdownx.mark与pymdownx.tilde即文本格式化相关扩展与文档站点是开箱即用的组合。配置在 mkdocs.yml 中启用格式化扩展将以下配置追加到你的mkdocs.yml若你的站点尚未配置任何扩展直接作为顶层markdown_extensions字段markdown_extensions: - pymdownx.critic - pymdownx.caret - pymdownx.keys - pymdownx.mark - pymdownx.tilde各扩展的详细配置选项可参见仓库中的 Python Markdown Extensions 设置文档对应章节如下Critic 扩展配置除基本开启外还支持mode选项控制解析行为Caret、Mark Tilde 扩展配置三个扩展通常一起启用它们只影响 Markdown 解析阶段配置项均沿用 PyMdown Extensions 的默认约定Keys 扩展配置支持class等选项但官方明确要求class选项必须保持默认值否则会破坏主题内置的按键图标样式详见下文键盘按键的渲染原理。Critic 的 mode 选项查看、接受与拒绝变更pymdownx.critic是格式化扩展中唯一拥有 Material for MkDocs 专属文档化选项的扩展其mode选项决定了 Critic Markup 的解析方式默认值为view 查看全部建议变更默认 yaml markdown_extensions: - pymdownx.critic: mode: view 直接接受全部变更 yaml markdown_extensions: - pymdownx.critic: mode: accept 直接拒绝全部变更 yaml markdown_extensions: - pymdownx.critic: mode: reject accept与reject模式适合在文档审阅流程的定稿环节使用前者让建议的新内容直接生效后者则回退为原文无需手工逐条修改 Markdown 源码。变更追踪使用 Critic Markup 展示建议修改启用pymdownx.critic后即可在文档正文中使用 Critic Markup 语法。它能够高亮建议删除、建议新增的内容支持组合式替换、行内批注甚至可以对整块段落做块级高亮Text can be {--deleted--} and replacement text {added}. This can also be combined into {~~one~a single~~} operation. {Highlighting} is also possible {and comments can be added inline}. { Formatting can also be applied to blocks by putting the opening and closing tags on separate lines and adding new lines between the tags and the content. }渲染结果对应如下 HTML 结构{--deleted--}渲染为del classcriticdeleted/del删除内容带红色底色{added}渲染为ins classcriticadded/ins新增内容带绿色底色{~~one~a single~~}渲染为del classcriticone/delins classcritica single/ins先删后增的组合操作{Highlighting}渲染为mark classcriticHighlighting/mark{comments can be added inline}渲染为span classcritic comment…/span行内批注块级写法开闭标签各占一行、标签与内容间保留空行渲染为mark classcritic block包裹的段落。源码视角Critic 样式如何工作主题对上述语义化类名的视觉呈现定义在 _critic.scss 中作用域限定在.md-typeset内以保证与正文文本的选择器优先级一致del.critic使用var(--md-typeset-del-color)背景色ins.critic使用var(--md-typeset-ins-color)两者都设置了box-decoration-break: clone确保跨行折行时高亮背景不会断裂.critic.comment的文字颜色复用var(--md-code-hl-comment-color)并通过::before与::after伪元素自动添加/*与*/前后缀让行内批注呈现为代码注释的视觉效果.critic.block为块级高亮设置了display: block、左右内边距16px、上下外边距1em与overflow: auto并对首尾子元素做 0.5em 的间距补偿。而配色变量的默认取值定义在 _colors.scss--md-typeset-del-color为半透明红色hsla(6, 90%, 60%, 0.15)--md-typeset-ins-color为半透明绿色hsla(150, 90%, 44%, 0.15)因此变更内容在明暗两种配色方案下都能保持清晰可辨。文本高亮Mark、Insert 与 Deletion 语法启用pymdownx.caret、pymdownx.mark与pymdownx.tilde三个扩展后文本高亮有了比直接书写 HTML 标签更便捷的语法- This was marked (highlight) - ^^This was inserted (underline)^^ - ~~This was deleted (strikethrough)~~渲染效果This was marked (highlight)^^This was inserted (underline)^^This was deleted (strikethrough)三者与标准 HTML 元素的对应关系如下语义语义保持不变便于屏幕阅读器与搜索引擎理解语法对应 HTML 元素语义…mark高亮标记^^…^^ins插入内容渲染为下划线~~…~~del删除内容渲染为删除线主题对mark的视觉实现位于 _typeset.scss文字颜色继承当前前景色背景色取自var(--md-typeset-mark-color)默认值在 _colors.scss 中定义为基于黄色 A200 色板的 50% 透明度hsla(#{hex2hsl($clr-yellow-a200)}, 0.5)同样设置了box-decoration-break: clone以保持折行时的完整性。上下标Caret 与 Tilde 的数学与化学书写利用pymdownx.caret上标^…^与pymdownx.tilde下标~…~可以快速书写化学式与矩阵记号- H~2~O - A^T^A渲染效果H~2~OA^T^A相比手写sub与supHTML 标签这种语法在表格、列表等复杂嵌套结构中更不易出错也更容易阅读。注意上下标依赖的是 Caret 与 Tilde 两个扩展Mark 扩展只提供…高亮与上下标无关。键盘按键用 Keys 渲染快捷键组合启用pymdownx.keys后用包裹按键名即可渲染出带有键盘图标的按键组合ctrlaltdel渲染效果ctrlaltdel按键名使用 PyMdown Extensions 的短码shortcode体系完整可用按键清单包括alt、shift、command、windows、arrow-up、enter、tab、escape、page-up等以及left-/right-前缀变体可参考 PyMdown Extensions 官方 Keys 扩展文档中的按键映射索引。源码视角按键图标从哪来按键渲染的视觉核心并非图片资源而是主题在 _keys.scss 中通过 CSS 伪元素为各类按键注入的 Unicode 字符图标修饰键与方向键等如alt、shift、arrow-up通过.key-name::before在按键左侧注入图标字符例如shift映射\21E7⇧、arrow-up映射\2191↑、command映射\2318⌘、windows映射\229E⊞tab、enter、num-enter三个按键通过::after在右侧注入图标如tab→\21E5、enter→\23CE.keys span即连接符使用var(--md-default-fg-color--light)弱化显示让组合键之间的连接符不那么抢眼。同时基础kbd元素的样式在 _typeset.scss 中定义内联块布局、12px字号、2px圆角并通过三层box-shadow叠加出凸起按键的立体效果相关配色变量按键底色、边框色、高光色集中在 _colors.scss。这也解释了为什么 Keys 扩展配置 特别强调class选项不能改动——主题正是依赖默认生成的.keys与.key-name类名来挂接上述样式的。组合使用与最佳实践将上述语法组合起来可以写出信息密度更高的技术文档段落例如当前版本中接口 GET /api/v1/users 的认证方式已由 {~~API Key~OAuth 2.0~~} 请使用 ctrlshiftf 检索文档中所有 TODO 标记H~2~O 相关的 实验数据在 ^^附录 B^^ 中完整给出。实践建议变更追踪优先用于协作文档Critic 语法适合 PR 审阅、文档校对等场景在正式发布前可用mode: accept或mode: reject一键定稿高亮语法有明确语义、^^、~~分别对应mark、ins、del语义元素不要仅因为视觉效果相近而混用键盘按键保持默认 class如需自定义按键视觉请通过主题的 CSS 变量覆盖kbd相关颜色见 _colors.scss而非修改 Keys 扩展的class选项格式与布局功能各司其职本节讨论的是行内文本格式化块级排版、引用框、网格等能力可分别参考 Admonitions 参考、Grids 参考 与 Content tabs 参考 文档。小结Material for MkDocs 的格式化能力完全由配置驱动在mkdocs.yml中启用pymdownx.critic、pymdownx.caret、pymdownx.keys、pymdownx.mark与pymdownx.tilde五个扩展即可获得变更追踪、文本高亮、上下标与键盘按键四类能力。它们的渲染样式由主题内置的 SCSS 模块_critic.scss、_keys.scss、_typeset.scss与配色变量_colors.scss统一管理因此无需额外引入脚本或资源文件。若需进一步了解扩展级配置细节可直接查阅 Python Markdown Extensions 设置文档 中的 Critic、Caret/Mark/Tilde 与 Keys 章节。【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考