跳转至

样式定制

本指南介绍如何定制 Material for MkDocs 的外观和样式。

颜色主题

主色调

Material 提供了多种预设颜色：

theme:
  palette:
    primary: indigo  # 主色调
    accent: indigo   # 强调色

可用的颜色选项：

颜色 示例
red 红色
pink 粉色
purple 紫色
deep purple 深紫色
indigo 靛蓝色
blue 蓝色
light blue 浅蓝色
cyan 青色
teal 蓝绿色
green 绿色
light green 浅绿色
lime 柠檬绿
yellow 黄色
amber 琥珀色
orange 橙色
deep orange 深橙色

深色模式

配置亮色/暗色主题切换：

theme:
  palette:
    # 浅色模式
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: 切换到深色模式

    # 深色模式
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: 切换到浅色模式

自定义颜色

创建 docs/stylesheets/extra.css 文件：

:root {
  --md-primary-fg-color: #0066cc;
  --md-primary-fg-color--light: #3399ff;
  --md-primary-fg-color--dark: #003d7a;
}

在 mkdocs.yml 中引用：

extra_css:
  - stylesheets/extra.css

字体

更改字体

theme:
  font:
    text: Roboto        # 正文字体
    code: Roboto Mono   # 代码字体

使用自定义字体

theme:
  font: false  # 禁用 Google Fonts

然后在自定义 CSS 中定义字体：

@font-face {
  font-family: "Custom Font";
  src: url("../fonts/custom-font.woff2") format("woff2");
}

body {
  font-family: "Custom Font", sans-serif;
}

更改 Logo

theme:
  icon:
    logo: material/library  # 使用 Material 图标

或使用自定义图片：

theme:
  logo: assets/logo.png

更改 Favicon

将 favicon.ico 或 favicon.png 放在 docs/ 目录下，或在配置中指定：

theme:
  favicon: assets/favicon.png

仓库图标

theme:
  icon:
    repo: fontawesome/brands/github  # GitHub 图标

导航定制

导航功能

theme:
  features:
    - navigation.instant      # 即时加载
    - navigation.tracking     # 锚点跟踪
    - navigation.tabs         # 顶部标签
    - navigation.tabs.sticky  # 固定标签
    - navigation.sections     # 导航分组
    - navigation.expand       # 展开导航
    - navigation.indexes      # 索引页面
    - navigation.top          # 返回顶部按钮
    - toc.follow              # 目录跟随
    - toc.integrate           # 集成目录

搜索功能

theme:
  features:
    - search.suggest    # 搜索建议
    - search.highlight  # 搜索高亮
    - search.share      # 分享搜索

内容功能

theme:
  features:
    - content.code.copy       # 代码复制按钮
    - content.code.annotate   # 代码注释
    - content.tabs.link       # 链接选项卡
    - content.tooltips        # 工具提示

页脚定制

版权信息

copyright: Copyright © 2025 Your Name

社交链接

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/username
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/username
    - icon: fontawesome/brands/linkedin
      link: https://linkedin.com/in/username

自定义 CSS

创建自定义样式表

创建 docs/stylesheets/extra.css：

/* 自定义标题颜色 */
.md-typeset h1 {
  color: #0066cc;
}

/* 自定义链接样式 */
.md-typeset a {
  color: #0066cc;
  text-decoration: underline;
}

/* 自定义代码块背景 */
.md-typeset pre > code {
  background-color: #f5f5f5;
}

/* 自定义提示框 */
.md-typeset .admonition {
  border-left: 4px solid #0066cc;
}

在 mkdocs.yml 中引用：

extra_css:
  - stylesheets/extra.css

自定义 JavaScript

添加自定义脚本

创建 docs/javascripts/extra.js：

// 添加自定义功能
document.addEventListener('DOMContentLoaded', function() {
  console.log('Custom script loaded');

  // 示例：添加点击统计
  document.querySelectorAll('a').forEach(function(link) {
    link.addEventListener('click', function() {
      console.log('Link clicked:', this.href);
    });
  });
});

在 mkdocs.yml 中引用：

extra_javascript:
  - javascripts/extra.js

自定义模板

覆盖模板

创建 overrides 目录并在配置中指定：

theme:
  name: material
  custom_dir: overrides

扩展主题

在 overrides/main.html 中：

{% extends "base.html" %}

{% block content %}
  <!-- 在内容前添加自定义内容 -->
  <div class="custom-banner">
    欢迎访问我们的文档！
  </div>

  {{ super() }}
{% endblock %}

响应式设计

Material 主题默认是响应式的，但您可以进一步定制：

/* 移动设备 */
@media screen and (max-width: 76.1875em) {
  .md-typeset {
    font-size: 0.9rem;
  }
}

/* 平板设备 */
@media screen and (min-width: 60em) and (max-width: 76.1875em) {
  .md-sidebar {
    width: 12rem;
  }
}

/* 桌面设备 */
@media screen and (min-width: 76.25em) {
  .md-sidebar {
    width: 15rem;
  }
}

最佳实践

样式定制建议

  1. 保持一致性 - 使用统一的颜色方案和字体
  2. 测试响应式 - 在不同设备上测试外观
  3. 性能优化 - 避免过多的自定义样式
  4. 可访问性 - 确保足够的对比度和可读性
  5. 版本控制 - 将自定义文件纳入版本控制

示例配置

完整的样式配置示例：

theme:
  name: material
  language: zh
  custom_dir: overrides

  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: 切换到深色模式
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: 切换到浅色模式

  font:
    text: Roboto
    code: Roboto Mono

  icon:
    logo: material/library
    repo: fontawesome/brands/github

  features:
    - navigation.instant
    - navigation.tracking
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - search.suggest
    - search.highlight
    - content.code.copy

extra_css:
  - stylesheets/extra.css

extra_javascript:
  - javascripts/extra.js

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/username

下一步