仓库里另一套官方主题 docs 解决的是另一个问题:博客要的是「按时间倒序的信息流」,文档要的是「按层级组织的知识树」。同一套内容,用 default 渲染像博客,用 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 的四处差别
| 维度 | default | docs |
|---|---|---|
| 导航 | 顶部水平导航 | 顶部 + 左侧分组目录 |
| 首页 | Hero + 卡片流 + 侧栏 | 前言 + 目录清单 |
| 归档 / 分类索引 | 有 archives.html、categories.html | 只有 taxonomy.html、collection.html |
| 深浅色 | 右上角按钮切换,记忆在 localStorage | 只有 CSS [data-theme="dark"] 变量,没有开关 |
最后一条要特别注意:docs 主题的 style.css 里深色变量是齐的,但模板没有输出切换按钮,也没有读取系统偏好的脚本。想给文档站加深色模式,得自己在 base.html 里补一个按钮和一小段设置 documentElement.dataset.theme 的脚本,或者直接放弃——文档站白天阅读居多。
从博客切到文档的操作顺序
- 配置里改成
theme: 'docs'; - 给要进侧栏的文章补
group与weight; - 关掉
indexes(这个主题没有对应布局,开着也只是不生成,但配置更干净); - 首页
content/index.md改成前言 + 你希望的第一屏内容; - 构建,看侧栏分组顺序是否符合预期,再微调
weight。
适合谁
产品文档、API 手册、系列教程的官方网站——一页一知识点,靠目录而不是时间组织内容。它的长处是「什么都不用装」,短处是视觉上没什么可玩的:想让它好看,得自己写 CSS,而不是换几个变量就行。
评论