MkDocs Material 代码块完全指南语法高亮、注释、行号与复制选择按钮配置【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material代码块与示例是技术文档不可或缺的组成部分。Material for MkDocs 提供了从构建期Pygments到运行期JavaScript 语法高亮器的多种代码块呈现方式并内置了复制按钮、代码选择、行号、代码注释、外部文件嵌入等一整套增强特性。读完本文你将掌握如何在mkdocs.yml中配置高亮扩展、按需启用复制/选择/注释按钮并学会通过源码级的 CSS 变量与词法类名对代码块做深度定制。前置知识Material for MkDocs 的代码高亮方案Material for MkDocs 支持两条高亮技术路线构建期高亮推荐使用 Pygments由 Python 在渲染阶段生成带语义类名的 HTML 代码配合 SCSS 词法映射表输出样式运行期高亮使用 JavaScript 语法高亮器如 highlight.js、Prism在浏览器端对代码着色。本文后续所有特性复制按钮除外的基础交互、代码选择、代码注释等都以 Pygments 为前提切换为 JavaScript 高亮器时部分功能不可用。项目源码中Pygments 输出的词法类名与主题配色的对应关系集中在 词法映射样式表例如.s2双引号字符串、.nf函数名、.k关键字等均在此文件内被逐一映射到对应的 CSS 变量。基础配置一次启用四个关键扩展语法高亮、内联代码高亮与外部文件嵌入依赖 Python Markdown Extensions 的四个扩展。在 mkdocs.yml 中添加markdown_extensions: - pymdownx.highlight: anchor_linenums: true line_spans: __span pygments_lang_class: true - pymdownx.inlinehilite - pymdocs.snippets - pymdownx.superfences各扩展职责如下扩展作用pymdownx.highlight对代码块做 Pygments 语法高亮anchor_linenums: true为行号生成锚点line_spans: __span让每行代码包裹在独立 span 中代码选择功能依赖它pygments_lang_class: true让高亮容器带语言类名pymdownx.inlinehilite支持对内联代码片段做语法高亮pymdownx.snippets支持通过--8--表示法把外部文件内容嵌入代码块pymdownx.superfences提供对围栏代码块的深度控制标题、行号、高亮行等需要说明的是pymdownx.snippets在项目自己的 mkdocs.yml 中实际还配置了auto_append: [includes/mkdocs.md]用于在每个页面自动附加约定内容这只是站点的额外用法非启用该扩展的必选项。四个扩展的完整参数说明可参见 Python Markdown Extensions 配置指南。代码复制按钮开启后每个代码块右侧会自动渲染一个一键复制到剪贴板的按钮自版本 9.0.0 起提供theme: features: - content.code.copy复制按钮的前端实现位于 代码块组件只有ClipboardJS.isSupported()浏览器支持 Clipboard API时才会挂载按钮且按钮通过renderClipboardButton生成DOM 结构为一个带data-clipboard-target属性的button见 按钮模板复制的目标即为对应代码块的code元素。按代码块单独控制不想全局开启时可基于 Attribute Lists 扩展参见 Attribute Lists 配置为单个代码块启用 { .yaml .copy } # Code block content 注意语言短码必须放在第一位且同样要以.前缀。同理可对单个代码块禁用 { .yaml .no-copy } # Code block content 若希望在无需高亮的情况下单独使用复制按钮可用.text语言短码——它不做任何语法着色 { .text .copy } plain text content 代码选择按钮实验特性自版本 9.7.0 起代码块可提供行范围选择按钮让读者像选中文本一样高亮某几行生成可分享、可链接的局部高亮——非常适合把读者精准引导到代码块的某个子段落与下面的 高亮特定行 配合使用theme: features: - content.code.select源码中代码选择功能同样在 代码块组件 实现它依赖line_spans: __span生成的每行独立 span点击按钮后进入选择模式鼠标点按某行即可高亮该行按住 Shift 再点按可扩展区间选择结果会通过history.replaceState写入 URL hash形如#__codelineno-{id}-{起始行}:{结束行}因此整个选区可以作为链接分享。按代码块单独控制# 仅对当前代码块启用选择按钮# 全局开启时对当前代码块禁用选择按钮同样遵循语言短码第一位、以.前缀的规则。代码注释Code annotations代码注释允许你在代码块的行内注释位置放置数字标记把任意 Markdown 内容文字、代码、图片等附着到代码的具体片段上自版本 8.0.0 起提供theme: features: - content.code.annotate # (1)!:man_raising_hand: 我是一条代码注释我可以包含代码、格式化文本、图片……凡是 Markdown 能写的都可以。按代码块单独启用不喜欢全局自动内联行为时可为单个代码块开启 { .yaml .annotate } # Code block content 代码注释的挂载逻辑见 代码块组件只有当代码块容器带有.annotate类或全局启用了content.code.annotate特性时才挂载且注释列表ol会被findList在代码块紧邻位置找到并绑定注释仅在代码块可见时激活例如隐藏在 Content tabs 中的代码块不会提前渲染注释。自定义选择器实验特性9.7.0默认情况下注释标记只能放在注释里因为注释对于放置标记是安全的。但某些场景需要把标记放进不允许写注释的位置例如 JSON 字符串内部。此时可以为每种语言配置额外的选择器即 Pygments 词法类名extra: annotate: json: [.s2] # (1)!.s2是 Pygments 为双引号字符串生成的词法名对应 词法映射表 中的.s2。若想在其他词法中放置注释请先在代码块中检查目标 token 对应的词法类名再加入额外选择器列表。重要代码注释不能跨词法拆分即一个标记的两端必须落在同一个词法 token 内。配置完成后JSON 字符串内部即可使用代码注释{ key: value (1) }:man_raising_hand: 我是一条位于 JSON 字符串中的代码注释剥离注释符号如果想去掉包裹注释标记的注释符号如 YAML 的#在注释标记右括号后加一个!即可自版本 8.5.0 起提供实验特性 yaml # (1)! 1. Look ma, less line noise!注意剥离模式每条注释只允许渲染一个标记若一条注释需要多个标记出于技术原因不能剥离注释符号。使用从基础代码块到高级特性基础代码块与语言短码代码块用两个独立行各包含三个反引号包裹语言短码直接写在开头的反引号之后可参考 Pygments 词法器列表 查找语言短码 py import tensorflow as tf 渲染效果import tensorflow as tf添加标题为了提供上下文可在语言短码后用title自定义标题给代码块添加标题例如显示文件名 py titlebubble_sort.py def bubble_sort(items): for i in range(len(items)): for j in range(len(items) - 1 - i): if items[j] items[j 1]: items[j], items[j 1] items[j 1], items[j] 渲染效果def bubble_sort(items): for i in range(len(items)): for j in range(len(items) - 1 - i): if items[j] items[j 1]: items[j], items[j 1] items[j 1], items[j]添加注释代码注释可以放在该语言允许放置注释的任何位置例如 JavaScript 的#!js // ...和#!js /* ... */、YAML 的#!yaml # ...等 yaml theme: features: - content.code.annotate # (1) 1. :man_raising_hand: 我是一条代码注释我可以包含 代码、__格式化文本__、图片……凡是 Markdown 能写的都可以。渲染效果theme: features: - content.code.annotate # (1):man_raising_hand: 我是一条代码注释我可以包含代码、格式化文本、图片……凡是 Markdown 能写的都可以。注意代码注释依赖 Pygments 语法高亮目前与 JavaScript 高亮器不兼容也不适用于语法中没有注释的语言项目正在探索替代方案例如允许把注释统一放在行尾。添加行号在语言短码后使用linenums起始行号可显示行号起始行号不必是1这允许把大段代码拆分成多个代码块展示而不丢失行号语义 py linenums1 def bubble_sort(items): for i in range(len(items)): for j in range(len(items) - 1 - i): if items[j] items[j 1]: items[j], items[j 1] items[j 1], items[j] 渲染效果def bubble_sort(items): for i in range(len(items)): for j in range(len(items) - 1 - i): if items[j] items[j 1]: items[j], items[j 1] items[j 1], items[j]高亮特定行把行号传给语言短码后的hl_lines参数即可高亮特定行。注意行号计数始终从1开始与linenums指定的起始行号无关 单行 markdown titleCode block with highlighted lines py hl_lines2 3 def bubble_sort(items): for i in range(len(items)): for j in range(len(items) - 1 - i): if items[j] items[j 1]: items[j], items[j 1] items[j 1], items[j] 渲染效果 py linenums1 hl_lines2 3 def bubble_sort(items): for i in range(len(items)): for j in range(len(items) - 1 - i): if items[j] items[j 1]: items[j], items[j 1] items[j 1], items[j] 行区间 markdown titleCode block with highlighted line range py hl_lines3-5 def bubble_sort(items): for i in range(len(items)): for j in range(len(items) - 1 - i): if items[j] items[j 1]: items[j], items[j 1] items[j 1], items[j] 渲染效果 py linenums1 hl_lines3-5 def bubble_sort(items): for i in range(len(items)): for j in range(len(items) - 1 - i): if items[j] items[j 1]: items[j], items[j 1] items[j 1], items[j] 高亮内联代码启用pymdownx.inlinehilite后内联代码块可以用#!前缀加上语言短码实现高亮The #!python range() function is used to generate a sequence of numbers.渲染效果The#!python range()function is used to generate a sequence of numbers.嵌入外部文件启用pymdownx.snippets后可通过--8--表示法把其他文件包括源码文件的内容直接嵌入代码块 title.browserslistrc ;--8-- .browserslistrc 渲染效果last 4 years这一特性非常适合在文档中维护单一事实来源示例代码只需在仓库中维护一份文档中按需引用。自定义按需调整代码块外观自定义语法主题使用 Pygments 时Material for MkDocs 提供了一套精心配比、深浅两套配色color scheme下都表现良好的代码块样式全部通过 CSS 变量控制。所有语法配色变量定义在 配色变量表:material-checkbox-blank-circle:{ stylecolor: var(--md-code-hl-number-color) }--md-code-hl-number-color数字:material-checkbox-blank-circle:{ stylecolor: var(--md-code-hl-special-color) }--md-code-hl-special-color特殊字面量:material-checkbox-blank-circle:{ stylecolor: var(--md-code-hl-function-color) }--md-code-hl-function-color函数名:material-checkbox-blank-circle:{ stylecolor: var(--md-code-hl-constant-color) }--md-code-hl-constant-color常量:material-checkbox-blank-circle:{ stylecolor: var(--md-code-hl-keyword-color) }--md-code-hl-keyword-color关键字:material-checkbox-blank-circle:{ stylecolor: var(--md-code-hl-string-color) }--md-code-hl-string-color字符串:material-checkbox-blank-circle:{ stylecolor: var(--md-code-hl-name-color) }--md-code-hl-name-color名称:material-checkbox-blank-circle:{ stylecolor: var(--md-code-hl-operator-color) }--md-code-hl-operator-color运算符:material-checkbox-blank-circle:{ stylecolor: var(--md-code-hl-punctuation-color) }--md-code-hl-punctuation-color标点:material-checkbox-blank-circle:{ stylecolor: var(--md-code-hl-comment-color) }--md-code-hl-comment-color注释:material-checkbox-blank-circle:{ stylecolor: var(--md-code-hl-generic-color) }--md-code-hl-generic-colorGeneric:material-checkbox-blank-circle:{ stylecolor: var(--md-code-hl-variable-color) }--md-code-hl-variable-color变量代码块的前景、背景与行高亮颜色由以下变量控制--md-code-fg-color前景--md-code-bg-color背景--md-code-hl-color行高亮颜色例如想把字符串的颜色改为新值可以通过 additional style sheet 覆盖浅色/深色配色切换机制见 Changing the colors :octicons-file-code-16:docs/stylesheets/extra.css css :root * { --md-code-hl-string-color: #0FF1CE; } :octicons-file-code-16:mkdocs.yml yaml extra_css: - stylesheets/extra.css 如果想只调整某一类字符串例如backticks可先在 语法主题定义 中查到对应词法类名如.sb为反引号字符串参见该文件 L44-L51 的注释再精确覆盖 :octicons-file-code-16:docs/stylesheets/extra.css css .highlight .sb { color: #0FF1CE; } :octicons-file-code-16:mkdocs.yml yaml extra_css: - stylesheets/extra.css 调整注释 tooltip 宽度如果代码注释内容较多可增大 tooltip 宽度 :octicons-file-code-16:docs/stylesheets/extra.css css :root { --md-tooltip-width: 600px; } :octicons-file-code-16:mkdocs.yml yaml extra_css: - stylesheets/extra.css 设置后注释将以更宽的 tooltip 渲染适合承载较长说明、图片或多段内容的注释。小结Material for MkDocs 的代码块体系由pymdownx.highlight、inlinehilite、snippets、superfences四个扩展与content.code.copy、content.code.select、content.code.annotate三个主题特性共同组成前者决定高亮与解析能力后者决定交互体验。复制按钮基于 Clipboard API 直接实现代码选择与代码注释则分别依赖行级 span 与词法类名在 代码块前端组件 中统一挂载因此自定义时既可以走 YAML 配置层面也可以直接覆盖 配色变量 或词法类样式实现精细控制。掌握这套组合即可为技术文档打造出专业、可交互、可分享的代码呈现体验。【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
