前端静态站点【免费下载链接】minimal-mistakes:triangular_ruler: Jekyll theme for building a personal site, blog, project documentation, or portfolio.项目地址https://gitcode.com/gh_mirrors/mi/minimal-mistakes点击查看免费下载导读本指南围绕 minimal-mistakes 主题中侧边栏导航列表这一功能展开通过 Jekyll 数据文件与页面 YAML Front Matter 的组合你可以在文章或页面的侧边栏中渲染一份支持父子两级层级、可折叠、可自动高亮当前项的导航菜单。读完本文你将掌握从数据文件定义、Front Matter 引用、多导航合并到样式定制与移动端交互的完整配置方案并理解其底层 include 的渲染逻辑。一、功能概述与适用场景minimal-mistakes 的侧边栏导航列表sidebar navigation list由两部分协作完成数据层在_data/navigation.yml中新增一个顶级 key如sidebar-sample定义菜单的分组parent与子项children引用层在文章或页面的 YAML Front Matter 中通过sidebar.nav指向该 key并可通过sidebar.title为菜单设置标题。这一模式适合为文档站、帮助中心、多章节长文等场景提供局部导航例如本仓库 docs/_data/navigation.yml 中docs键即为整个文档站配置的侧边栏导航其结构如下节选docs: - title: Getting Started children: - title: Quick-Start Guide url: /docs/quick-start-guide/ - title: Structure url: /docs/structure/ - title: Customization children: - title: Configuration url: /docs/configuration/ - title: Navigation url: /docs/navigation/二、在_data/navigation.yml中定义导航数据导航列表的数据统一存放在站点根目录的_data/navigation.yml中。你只需在文件末尾或任意位置新增一个顶级 key例如本关联文档对应的sidebar-samplesidebar-sample: - title: Parent Page A children: - title: Child Page A1 url: / - title: Child Page A2 url: / - title: Child Page A3 url: / - title: Child Page A4 url: / - title: Parent Page B children: - title: Child Page B1 url: / - title: Child Page B2 url: / - title: Child Page B3 url: / - title: Child Page B4 url: / - title: Child Page B5 url: / - title: Parent Page C children: - title: Child Page C1 url: / - title: Child Page C2 url: / - title: Child Page C3 url: / - title: Child Page C4 url: / - title: Child Page C5 url: / - title: Parent Page D children: - title: Child Page D1 url: / - title: Child Page D2 url: /该 key此处为sidebar-sample的命名规则是保持简短、易记因为它随后要通过 YAML Front Matter 被引用nav: sidebar-sample与数据文件中的 key 必须完全一致docs/_docs/10-layouts.md 对此有明确提示。数据文件中的main、foo等其他 key 与侧边栏互不干扰一个文件可同时存放页头导航与多个侧边栏导航。结构约定每个顶层条目对应一个分组标题渲染为nav__sub-title每个条目的children为该分组下的链接列表侧边栏菜单仅支持 1 层嵌套链接即分组下不能再套分组每个子项由title显示文本与url链接地址构成url支持站内相对路径如/docs/quick-start-guide/也支持外部绝对地址若某个条目省略children则该条目本身会渲染为一个可直接点击的链接若省略url则仅渲染为纯文本分组标题。三、通过 YAML Front Matter 挂载侧边栏导航定义好数据之后在任意文章或页面的 Front Matter 中引用它。以下即本关联文档 docs/_posts/2012-03-15-layout-sidebar-nav-list.md 的完整用法--- title: Layout: Sidebar with Navigation List excerpt: A post with a sidebar navigation list. author_profile: false sidebar: title: Sample Title nav: sidebar-sample ---其中Front Matter 键作用sidebar.title侧边栏导航列表上方显示的标题渲染为nav__titlesidebar.nav引用_data/navigation.yml中的 key告诉主题渲染哪份导航数据author_profile: false关闭作者信息卡让侧边栏只保留导航列表默认开启时作者卡会显示在导航上方如果你希望用title还是nav只选其一也完全可以仅写sidebar.nav会得到不带标题的纯菜单仅写sidebar.title会得到只有标题没有菜单的侧边栏块。sidebar还支持image、image_alt、text等键用于在侧边栏插入图片与自定义文本Markdown 可用详见 docs/_docs/10-layouts.md 的 Custom Sidebar 小节。3.1 一次挂载多个导航v4.26.0如果定义了多份侧边栏导航例如同时存在main与docs两个 keysidebar.nav也可以是一个列表一次性渲染多份菜单sidebar: nav: - main - docs3.2 用 Front Matter Defaults 全局应用若多个页面都要使用同一份侧边栏导航逐个写入 Front Matter 过于繁琐。更优做法是在_config.yml中通过 Jekyll Front Matter Defaults 批量应用defaults: # _docs - scope: path: type: docs values: sidebar: nav: docs上述配置会对type: docs的所有文档页自动挂载docs导航无需在每篇文档中重复声明。四、渲染链路从数据到 HTML 的源码级解析理解底层渲染逻辑有助于排查问题和深度定制。侧边栏的渲染由两个 include 协作完成4.1_includes/sidebar.html入口与装配sidebar.html 首先判断是否满足渲染条件page.author_profile or layout.author_profile or page.sidebar任一为真时才输出侧边栏容器div classsidebar sticky。随后依次处理若author_profile开启先引入 author-profile.html作者信息卡遍历page.sidebar的每个块按顺序渲染image图片、title标题、textMarkdown 文本以及nav对应的导航末尾再引入 sidebar-custom.html允许站点自定义额外侧边栏内容。值得注意当page.sidebar.nav为字符串时会在循环结束后再次调用nav_list旧版兼容逻辑避免双份渲染而 v4.26.0 引入的nav 为列表能力则由循环内的{% if s.nav %}分支逐项渲染两者共同保证了新旧写法的兼容。4.2_includes/nav_list导航数据渲染核心nav_list 是真正把 YAML 数据转成 HTML 的模板其核心逻辑{% for navname in include.nav %} {% assign navigation site.data.navigation[navname] %} {% for nav in navigation %} li {% if nav.url %} a href{{ nav.url | relative_url }}span classnav__sub-title{{ nav.title }}/span/a {% else %} span classnav__sub-title{{ nav.title }}/span {% endif %} {% if nav.children ! null %} ul {% for child in nav.children %} lia href{{ child.url | relative_url }}{% if child.url page.url %} classactive{% endif %}{{ child.title }}/a/li {% endfor %} /ul {% endif %} /li {% endfor %} {% endfor %}要点解析include.nav支持字符串或列表两种形态内部统一按数组遍历每个元素即为_data/navigation.yml的一个 key分组标题若带url则包裹为链接否则输出为纯文本span classnav__sub-title子项链接通过relative_url过滤器转换为站内相对地址当前项高亮当child.url page.url时自动为链接添加classactive该特性使访问者在文档站中能随时定位自己所在章节分组下的ul仅在有children时输出因此菜单严格保持一层嵌套。4.3 单篇文档的完整示例本关联文档 docs/_posts/2012-03-15-layout-sidebar-nav-list.md 中展示的正是Front Matter 挂载 _data/navigation.yml定义的最小可运行组合文章 YAML 中声明sidebar.title与sidebar.nav: sidebar-sample数据文件docs/_data/navigation.yml 中第 95 行起提供同名 key 的完整菜单数据二者共同构成一份带标题、含 4 个分组、共 15 个子项的侧边栏导航列表。五、样式与响应式行为_navigation.scss解读导航列表的视觉样式集中定义在 _sass/minimal-mistakes/_navigation.scss 的 Navigation list 小节.nav__title侧边栏菜单标题来自sidebar.title使用$sans-serif-narrow字体、粗体显示.nav__sub-title分组标题全大写text-transform: uppercase、加粗底部带1px solid $border-color分隔线视觉上起到分组区隔作用.nav__list .nav__items菜单主体字号为1.25rem其中的.active子项会获得加粗与左右内边距实现当前位置高亮效果移动端折叠交互在小于$large断点时.nav__list内的隐藏 checkbox 与label变为可见形成Toggle menu手风琴按钮文案来自_data/ui-text.yml中的menu_label键如英文 Toggle menu、中文 切换菜单。默认.nav__items被压缩为max-height: 0; opacity: 0隐藏勾选 checkbox 后通过.nav__list input:checked ~ .nav__items展开为max-height: 9999px并淡入从而实现移动端展开/收起交互。include breakpoint(max-width $large - 1px) { .nav__list input:checked ~ .nav__items { -webkit-transition: 0.5s ease-in-out; transition: 0.5s ease-in-out; max-height: 9999px; /* exaggerate max-height to accommodate tall lists*/ overflow: visible; opacity: 1; margin-top: 1em; -webkit-transform: translate(0, 0); transform: translate(0, 0); } }桌面端≥$large断点时 checkbox 与 label 默认隐藏display: none菜单常驻显示无折叠行为。若需自定义样式可在站点的assets/css/main.scss中追加覆盖规则或参考 docs/_docs/16-stylesheets.md 的样式定制流程。六、实战速查三分钟接入侧边栏导航以下是最小接入清单按顺序完成即可在站点任意页面启用导航列表编辑_data/navigation.yml新增导航数据 keymy-menu: - title: 分组一 children: - title: 子项一 url: /page-1/ - title: 子项二 url: /page-2/在目标页面的 YAML Front Matter 中挂载sidebar: title: 我的导航 nav: my-menu可选批量应用在_config.yml的defaults中按path/type作用域添加sidebar.nav可选定制文案在_data/ui-text.yml中按语言覆盖menu_label的折叠按钮文案可选定制样式在_sass/minimal-mistakes/_navigation.scss或站点自定义样式中调整.nav__title、.nav__sub-title、.active的字体、颜色与间距。完成后bundle exec jekyll serve本地预览桌面端侧边栏常驻显示分组菜单移动端出现手风琴折叠按钮点击任意子项时若其url与当前页面 URL 一致该链接会自动高亮。七、注意事项与常见问题key 必须匹配Front Matter 中的nav值与_data/navigation.yml的 key 一字不差否则菜单为空可检查构建日志中的 Liquid 输出仅支持一级嵌套children内不能再声明children深层级需求可通过在页面正文引入 toc.html目录或使用多个导航块组合实现URL 匹配高亮.active依赖child.url page.url的精确相等判断URL 尾部斜杠、大小写不一致会导致高亮失效建议统一 permalink 风格与作者卡共存author_profile: true默认时作者卡会出现在导航列表上方如关联文档所示仅需导航时可显式设置author_profile: falsesticky 定位侧边栏容器带有sticky类页面滚动时侧边栏会吸顶跟随若与其他 sticky 元素冲突可调整相关样式。八、延伸阅读导航数据文件定义docs/_data/navigation.yml含docs、sidebar-sample、main等多个示例 key侧边栏导航官方文档docs/_docs/10-layouts.mdCustom Sidebar Navigation Menu 小节含 Front Matter Defaults 用法导航整体指南docs/_docs/07-navigation.md页头 masthead 导航、面包屑与侧边栏导航入口渲染实现nav_list、sidebar.html样式实现navigation.scssNavigation list 小节折叠按钮文案ui-text.yml 中的menu_label键赞分享前端静态站点【免费下载链接】minimal-mistakes:triangular_ruler: Jekyll theme for building a personal site, blog, project documentation, or portfolio.项目地址https://gitcode.com/gh_mirrors/mi/minimal-mistakes点击查看免费下载相关推荐Scala Maven 插件技术文档Scala Maven 插件技术文档 安装指南 要开始使用 Scala Maven 插件首先确保您的开发环境满足以下条件 环境要求 Maven : 至少版本前端静态站点Minimal Mistakes 自定义侧边栏完全指南用 YAML Front Matter 定制 sidebar 内容与导航Minimal Mistakes 自定义侧边栏完全指南用 YAML Front Matter 定制 sidebar 内容与导航 本文以 Minimal Mis前端静态站点Minimal Mistakes 导航系统配置指南Masthead 主导航、面包屑与自定义侧边栏菜单实战Minimal Mistakes 导航系统配置指南Masthead 主导航、面包屑与自定义侧边栏菜单实战 本指南以 Minimal Mistakes Jeky前端静态站点创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
