Minimal Mistakes 导航系统配置指南：Masthead 主导航、面包屑与自定义侧边栏菜单实战

本指南以 Minimal Mistakes Jekyll 主题的导航模块为核心，完整讲解如何通过 _data/navigation.yml 数据文件定制顶部 Masthead 导航栏、启用面包屑（Breadcrumbs）导航，以及搭建自定义侧边栏导航菜单。读完本文你将掌握 priority plus 响应式导航模式的配置要点、面包屑的启用条件与潜在限制，并理解这些功能在主题源码中的真实实现机制，可直接应用于个人博客、项目文档或作品集站点的导航搭建。

导航配置的入口：Jekyll 数据文件

Minimal Mistakes 的导航链接统一通过 Jekyll 数据文件管理，即仓库根目录下的 _data/navigation.yml。主题约定该文件使用 main 作为顶层键来定义站点顶部导航（Masthead），你也可以在其中追加其他命名键，供侧边栏等场景复用（详见后文）。默认仓库自带的 _data/navigation.yml 内容如下：

# main links
main:
  - title: "Quick-Start Guide"
    url: https://mmistakes.github.io/minimal-mistakes/docs/quick-start-guide/
  # - title: "About"
  #   url: https://mmistakes.github.io/minimal-mistakes/about/
  # - title: "Sample Posts"
  #   url: /year-archive/
  # - title: "Sample Collections"
  #   url: /collection-archive/
  # - title: "Sitemap"
  #   url: /sitemap/

其中 title 是链接显示文本，url 是链接地址，支持站内绝对路径（如 /year-archive/）与站外完整 URL 两种形式。

Masthead 主导航：priority plus 响应式设计模式

Masthead（页头导航栏）使用 priority plus（优先显示）设计模式：尽可能在水平方向展示更多导航项，装不下的链接自动收进一个可展开的「更多」切换按钮中，保证任意屏幕宽度下导航都不会换行或溢出。仓库中的 _includes/masthead.html 负责渲染该区域，它遍历 site.data.navigation.main 生成导航列表：

<ul class="visible-links">
  {%- for link in site.data.navigation.main -%}
    <li class="masthead__menu-item">
      <a
        href="{{ link.url | relative_url }}"
        {% if link.description %} title="{{ link.description }}"{% endif %}
        {% if link.target %} target="{{ link.target }}"{% endif %}
      >{{ link.title }}</a>
    </li>
  {%- endfor -%}
</ul>

同时模板中还包含站内搜索按钮（当 _config.yml 中 search: true 时渲染）、汉堡菜单切换按钮 greedy-nav__toggle 以及隐藏链接容器 hidden-links，它们共同构成 priority plus 的交互骨架。

定义 main 键下的导航项

在 _data/navigation.yml 的 main 键下，每个列表项支持三个字段：

main:
  - title: "Quick-Start Guide"
    url: /docs/quick-start-guide/
  - title: "Posts"
    url: /year-archive/
  - title: "Categories"
    url: /categories/
  - title: "Tags"
    url: /tags/
  - title: "Pages"
    url: /page-archive/
  - title: "Collections"
    url: /collection-archive/
  - title: "External Link"
    url: https://google.com
    target: _blank

字段说明：

字段	类型	说明
title	字符串（必填）	导航链接的显示文本
url	字符串（必填）	链接地址；站内路径以 / 开头，站外链接使用完整 URL
description	字符串（可选）	鼠标悬停时的提示文本（tooltip），在桌面浏览器上生效
target	字符串（可选）	设置 _blank 可让外部链接在新标签页打开，如上面示例中的 https://google.com

description 字段由 _includes/masthead.html 中的 title="{{ link.description }}" 渲染为 HTML 的 title 属性，浏览器会将其显示为原生 tooltip；target 则直接透传到 <a> 标签的 target 属性。

配置完成后，站点会得到一个响应式 Masthead，效果如下：

ProTip： 把最重要的链接放在最前面，确保它们始终可见，而不是被收进 menu 切换按钮里隐藏起来。

priority plus 的底层实现机制

这一模式并非纯 CSS 实现，而是由 assets/js/plugins/jquery.greedy-navigation.js（基于 GreedyNav 的 jQuery 插件）驱动。从源码结构看，其核心逻辑为：

• 测量与断点计算：measureLinks() 遍历可见链接与隐藏链接，累加每个链接的宽度形成 breakWidths 数组，作为导航「换行断点」；窗口宽度跨越不同 CSS 断点（<768px、<1024px、<1280px、≥1280px）时重新测量；
• 空间判断：check() 用导航容器总宽度减去 logo、站点标题、搜索按钮、切换按钮的宽度得到 availableSpace，再与 requiredSpace（当前可见链接累计宽度）比较；
• 自动收敛与展开：空间不足时把最后一个可见链接 prependTo 移入 hidden-links；空间充裕时把隐藏链接 appendTo 移回可见区域，并同步更新切换按钮的 count 属性与 hidden 类；
• 交互细节：点击切换按钮展开/收起隐藏菜单，鼠标离开隐藏菜单 1 秒（closingTime = 1000）后自动收起。

因此导航项的宽度会直接影响断点分布，短标题链接在窄屏下能保留更多可见项，这也是建议把重要链接前置的原因之一。

Breadcrumbs 面包屑导航（beta）

面包屑导航帮助访客在层级较深的站点中定位当前位置。Minimal Mistakes 默认关闭该功能，启用只需在 _config.yml 中设置：

breadcrumbs: true  # disabled by default

启用后，主题会在页面正文上方渲染面包屑（由 _includes/breadcrumbs.html 输出），效果如下：

面包屑的生成原理与可靠性限制

主题官方将面包屑标记为 beta 功能，原因是其实现方式较为脆弱，不一定能稳定生成准确的链接。从 _includes/breadcrumbs.html 源码可以看到其工作方式：它将当前页面的 URL 按 / 拆分，逐段生成面包屑层级，并以 site.category_archive 作为分类归档基准拼接中间层链接。具体来说：

{% case site.category_archive.type %}
  {% when "liquid" %}
    {% assign path_type = "#" %}
  {% when "jekyll-archives" %}
    {% assign path_type = nil %}
{% endcase %}

{% if page.collection != 'posts' %}
  {% assign crumb_path = '/' %}
{% else %}
  {% assign crumb_path = site.category_archive.path %}
{% endif %}

• 对于普通 posts 文章，面包屑中间层链接基于 site.category_archive.path（如 /categories/）拼接；
• 对于其他 collection（如 portfolio、pets）中的页面，中间层退化为站点根路径 /；
• 链接文本由 URL 段经 url_decode、replace、capitalize 处理后生成，并用 schema.org 的 BreadcrumbList 微数据标记每个层级（itemprop="itemListElement" 与 position），对 SEO 有额外增益。

保证面包屑准确的两条最佳实践

由于中间层链接依赖归档页面真实存在，主题文档给出两条建议：

1. 使用基于分类的 permalink 结构，例如在 _config.yml 中设置 permalink: /:categories/:title/，让文章 URL 天然携带分类层级；
2. 为每个分类手动创建归档页面，或使用 jekyll-archives 插件自动生成。若这些页面不存在，面包屑指向它们的链接就会 404 失效。

与此配套的是 _config.yml 中的归档路径配置（当前仓库默认使用 Liquid 方案）：

category_archive:
  type: liquid
  path: /categories/

配置注释也明确警告：使用 Liquid 方式时归档页面必须真实存在于对应路径，否则极易出现坏链（尤其是启用了面包屑时）。另外，面包屑只在非分页页面上渲染——从源码可见 _layouts/single.html、_layouts/archive.html、_layouts/archive-taxonomy.html、_layouts/search.html 中均以 {% unless paginator %} 包裹 {% include breadcrumbs.html %}。

自定义面包屑起始文本与分隔符

面包屑的起始链接文本和分隔符都可以在 _data/ui-text.yml 中修改。默认的英文配置为：

breadcrumb_home_label : "Home"
breadcrumb_separator  : "/"

其他语言配置中同样包含这两个键（例如中文 zh 下为 首页 与 /）。若希望面包屑呈现类似 Start > Blog > My Awesome Post 的效果，只需改为：

breadcrumb_home_label : "Start"
breadcrumb_separator  : ">"

对应源码中 _includes/breadcrumbs.html 的默认兜底值也是 "Home" 与 "/"（通过 | default: 过滤器），即未配置时按此渲染。

自定义侧边栏导航菜单

除页头导航外，Minimal Mistakes 还支持在侧边栏放置自定义导航菜单。其数据源同样来自 _data/navigation.yml，但使用独立的命名键（如 sidebar、docs 等），由 _includes/nav_list 渲染：它接收 include.nav 参数（一个键名列表），按顺序遍历对应键下的导航项，并支持两级结构：

{% for nav in navigation %}
  <li>
    {% if nav.url %}
      <a href="{{ nav.url | relative_url }}"><span class="nav__sub-title">{{ nav.title }}</span></a>
    {% else %}
      <span class="nav__sub-title">{{ nav.title }}</span>
    {% endif %}

    {% if nav.children != null %}
    <ul>
      {% for child in nav.children %}
        <li><a href="{{ child.url | relative_url }}"{% if child.url == page.url %} class="active"{% endif %}>{{ child.title }}</a></li>
      {% endfor %}
    </ul>
    {% endif %}
  </li>
{% endfor %}

从源码可以看出：父级项用 nav__sub-title 样式显示，可带 url 或不带（仅作分组标题）；子级通过 children 键组织，且当 child.url 与当前页面 page.url 相等时自动添加 active 类高亮当前项。详细的配置方式（含如何用 nav_list include 传入导航键名、如何与页面 Front Matter 的 sidebar 配置组合）请参见仓库文档 layouts 自定义侧边栏导航菜单一节。

小结与排查建议

围绕导航配置，可以归纳出以下实践要点：

• Masthead：一切始于 _data/navigation.yml 的 main 键，title/url 为必填，description 提供悬停提示，target: _blank 用于外链新开页；重要链接务必前置，避免被 priority plus 收起。
• 面包屑：_config.yml 中 breadcrumbs: true 即可开启；为保证链接可靠，请使用 /:categories/:title/ 式 permalink 并确保分类归档页面存在；起始文本与分隔符在 _data/ui-text.yml 中调整。
• 侧边栏导航：在 _data/navigation.yml 新增命名键，通过 nav_list include 与页面侧边栏配置组合使用，children 实现二级菜单并自动高亮当前页。
• 排查路径：若导航未按预期渲染，可依次核对 _data/navigation.yml 的键名与 YAML 缩进、_includes/masthead.html 与 _includes/nav_list 中引用的数据键，以及 _config.yml 中 breadcrumbs、category_archive 的取值是否与归档页面实际路径一致。