主题模板 发布于 2026-11-21

docs 主题:把内容站变成带侧栏的文档站

封面图 5 分钟阅读 # xfmpress# 主题

仓库里另一套官方主题 docs 解决的是另一个问题:博客要的是「按时间倒序的信息流」,文档要的是「按层级组织的知识树」。同一套内容,用 default 渲染像博客,用 docs 渲染就像一本手册——左侧目录常驻,正文更宽,读起来是「查」而不是「刷」。

docs 主题文章页:左侧分组目录、宽正文与右侧留白

上图是文档页的真实渲染(1200×630):顶部导航放站名与全局入口,左侧按「开始使用 / 内容与模板 / 扩展」分组列出条目并高亮当前页,主区是文章标题、meta、正文与代码块。没有卡片、没有封面,一切为了扫读。

三栏骨架

base.html 把页面切成三块:

  • 顶部导航:nav 配置项 + 语言切换 + 搜索按钮,宽度用 wrap-wide,比博客主题更宽;
  • 左侧栏 docs-nav:遍历 site.navGroups,每个分组一个标题,组内按 weight 升序排列;
  • 主区 docs-main:正文 + 右侧 toc.html 目录,页脚缩在主区里而不是横跨整屏。

配色是冷静的蓝(--accent: #2563eb),无衬线正文,代码块灰底,整页更像 IDE 文档而不是杂志排版。

侧栏是「长」出来的,不是配出来的

这是 docs 主题最省事也最容易踩的一点:侧栏条目来自文章 front-matter,而不是某个菜单配置文件。

---
title: 安装与升级
group: 使用指南
weight: 1
---

引擎在收集阶段把带 group(或等价的 section)的页面按组聚合,排序后注入 site.navGroups。所以:

  • 想让文章进侧栏,就写 group;
  • 想让顺序符合阅读逻辑,就写 weight(数字小的在前);
  • 不想让它出现在侧栏,写 nav: false;
  • 漏写 group 的文章不会消失,只是不出现在侧栏里,会集中落到首页的「目录」清单中。

weight 只在组内比较,跨组排序由分组第一次出现的顺序决定——所以多个分组时,建议给分组也留出空档(10、20、30),插入新组时不用改一堆数字。

首页是一张目录

docs 的 index.html 不渲染文章卡片流,而是把 content/ 里的正文当作前言,下面列出所有 navGroups 条目,每条后面标着它所属的分组。对文档站来说这比「最新文章」有用得多:访客第一眼看到的是结构,不是时间线。

与 default 的四处差别

维度defaultdocs
导航顶部水平导航顶部 + 左侧分组目录
首页Hero + 卡片流 + 侧栏前言 + 目录清单
归档 / 分类索引有 archives.html、categories.html只有 taxonomy.html、collection.html
深浅色右上角按钮切换,记忆在 localStorage只有 CSS [data-theme="dark"] 变量,没有开关

最后一条要特别注意:docs 主题的 style.css 里深色变量是齐的,但模板没有输出切换按钮,也没有读取系统偏好的脚本。想给文档站加深色模式,得自己在 base.html 里补一个按钮和一小段设置 documentElement.dataset.theme 的脚本,或者直接放弃——文档站白天阅读居多。

从博客切到文档的操作顺序

  1. 配置里改成 theme: 'docs';
  2. 给要进侧栏的文章补 group 与 weight;
  3. 关掉 indexes(这个主题没有对应布局,开着也只是不生成,但配置更干净);
  4. 首页 content/index.md 改成前言 + 你希望的第一屏内容;
  5. 构建,看侧栏分组顺序是否符合预期,再微调 weight。

适合谁

产品文档、API 手册、系列教程的官方网站——一页一知识点,靠目录而不是时间组织内容。它的长处是「什么都不用装」,短处是视觉上没什么可玩的:想让它好看,得自己写 CSS,而不是换几个变量就行。

评论