一些小细节

提示

这里所使用的功能均为免费功能

1. 自动启用/关闭暗黑模式

来自：System preference

在网站顶栏显示暗黑模式切换按钮，分为自动/日间/暗黑。

mkdocs.yml

theme:
  name: material
  palette:
  - media: "(prefers-color-scheme)"
      toggle:
      icon: material/link
      name: 切换至日间模式

  - media: "(prefers-color-scheme: light)"
      scheme: default 
      toggle:
      icon: material/toggle-switch-off-outline
      name: 切换至暗黑模式

  - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
      icon: material/toggle-switch
      name: 切换至系统默认

2. Emoji/Material Icons 支持

来自：Icons, Emojis

MarkDown拓展，使用 :xx: 以插入 Emoji 或 Material icons

mkdocs.yml

markdown_extensions:
    - attr_list
    - pymdownx.emoji:
    emoji_index: !!python/name:material.extensions.emoji.twemoji
    emoji_generator: !!python/name:material.extensions.emoji.to_svg

3. 美观的提示标签

来自：Tooltips

取代浏览器自带鼠标停留显示标签，使用 Material for MkDocs 提供的样式。

mkdocs.yml

markdown_extensions:
    - abbr
    - attr_list
    - pymdownx.snippets

theme:
    features:
    - content.tooltips

4. 文档 Git 创建时间

来自：Document dates

显示该文章的创建时间和修改时间。

需要安装一个叫git-revision-date-localized-plugin 的包，即在 .github/workflows/xx.yml 中加入安装命令 pip install mkdocs-git-revision-date-localized-plugin

.github/workflows/xx.yml mkdocs.yml

jobs:
  deploy:
    steps:
      - run: pip install mkdocs-git-revision-date-localized-plugin

plugins:
- git-revision-date-localized:
    type: date
    enable_creation_date: true

5. "这篇文章有用吗？"

来自：Was this page helpful?

在文章末尾添加一个互动模块，用以收集用户对文章的反馈，官方教程中则是配合 Google Analysis 来统计数量，我这里只是做了一个壳，如果需要可以加入问卷链接等等。

../feedback.js mkdocs.yml

var feedback = document.forms.feedback
feedback.hidden = false 

feedback.addEventListener("submit", function(ev) {
ev.preventDefault()

var page = document.location.pathname 
var data = ev.submitter.getAttribute("data-md-value")

feedback.firstElementChild.disabled = true 

var note = feedback.querySelector(
    ".md-feedback__note [data-md-value='" + data + "']"
)
if (note)
    note.hidden = false 
})

extra:
  analytics: 
    feedback:
      title: 这篇文章有用吗？
      ratings:
        - icon: material/emoticon-happy-outline
          name: 有用！
          data: 1
          note: 很高兴能帮到你！
        - icon: material/emoticon-sad-outline
          name: 需要改善
          data: 0
          note: 感谢反馈！我会尽量改善此页面！

extra_javascript:
  - ../feedback.js

6. 使用旧版警告提示

来自：Classic admonitions

将警告提示样式换为旧版。

笔记

这是新版

笔记

这是旧版

根据个人喜好切换。如果喜欢新版则无需修改。

../extra.css mkdocs.yml

.md-typeset .admonition,
.md-typeset details {
  border-width: 0;
  border-left-width: 4px;
}

extra_css:
  - ../extra.css

评论