跳转至

MkDocs / Zensical 使用说明

记录本站（Zensical / Material 主题）常用写法与配置。通用 Markdown 语法见 Markdown 语法。

🧩 内容选项卡

=== · alternate_style · 同名联动。定义可切换的内容选项卡。

=== 定义选项卡，同一组选项卡会自动合并切换：

=== "折叠 1"

    这是第一个选项卡的内容。

=== "折叠 2"

    这是第二个选项卡的内容。

📂 折叠与提示框

??? 默认折叠，???+ 默认展开：

??? 折叠

    折叠内容

???+ 展开

    默认展开的折叠内容

提示框类型：note、info、abstract、tip、success、question、warning、failure、danger、bug、example、quote。

!!! note "标题"

    提示内容

📑 生成目录并折叠

<details markdown="1"> · [TOC] · toc/md_in_html。可折叠的页面目录。

在 <details> 中添加 markdown="1"，配合 toc、md_in_html 扩展：

<details markdown="1">
<summary>Linux环境</summary>
[TOC]
</details>

markdown 属性取值：block（强行全部解析）、1（默认解析）、span（只解析内联，不解析块级）。

✅ 本站已启用的扩展

类型 已启用
核心扩展 abbr、admonition、attr_list、def_list、footnotes、md_in_html、toc（带 permalink）
pymdownx arithmatex、betterem、caret、details、emoji（to_svg）、highlight、inlinehilite、keys、magiclink、mark、smartsymbols、superfences（含 mermaid）、tabbed、tasklist、tilde、quotes（callouts）、snippets（auto_append = ["includes/abbreviations.md"]）

🔤 自定义字体

font · extra_css · LXGW WenKai。Material 主题字体配置。

mkdocs.yml
theme:
  name: material
  font:
    text: LXGW WenKai Screen
    code: LXGW WenKai Screen
extra_css:
  - https://cdn.bootcdn.net/ajax/libs/lxgw-wenkai-screen-webfont/1.7.0/style.min.css

其他网站直接使用时：

body { font-family: "LXGW WenKai Screen", sans-serif; }

🌙 黑暗模式（CSS 滤镜）

不改站点样式，用 filter 的 invert + hue-rotate 快速切黑。对 img、picture、video 再反向过滤，避免图片被反色。

document.documentElement.style.filter = 'invert(85%) hue-rotate(180deg)'

javascript: (function () {
    const docStyle = document.documentElement.style;
    if (!window.modeIndex) window.modeIndex = 0;
    const styleList = ['', 'invert(85%) hue-rotate(180deg)', 'invert(100%) hue-rotate(180deg)'];
    modeIndex = modeIndex >= styleList.length - 1 ? 0 : modeIndex + 1;
    docStyle.filter = styleList[modeIndex];
    document.body.querySelectorAll('img, picture, video').forEach(el =>
        el.style.filter = modeIndex ? 'invert(1) hue-rotate(180deg)' : '');
})();

原理：invert(85%) 反色（百分比避免纯黑纯白刺眼）、hue-rotate(180deg) 修正色相偏移、媒体元素再次 invert(1) 抵消父级滤镜。

🐳 临时调试

docker 本地预览。镜像与命令见 Docker 部署。

🎨 Material 主题

配置说明与源码。