跳转至

书籍章节 Sidebar 设计

概述

章节 section 页面的右侧 sidebar 专注于章节元信息,帮助读者快速回答两个核心问题：

  1. 这个章节规模多大/需要投入多少时间？(递归统计所有子页面)
  2. 这个章节当前完成度如何？

设计原则

章节 sidebar 是"章节元信息",不是"内容延伸"

只要新增信息不能直接帮助读者决定是否阅读这个章节,就不应该出现在 sidebar。

Front Matter 配置

配置字段

在章节的 _index.md 文件中添加以下 front matter:

---
title: "章节标题"
status: "建设中"        # 章节状态
# 注意: 章节统计数据 (页面数、字数、阅读时间) 由 Hugo 递归自动计算，无需手动配置
---

字段说明

1. status - 章节状态

用途： 表达内容成熟度，管理读者预期

可选值：

  • 草稿 - 初稿阶段，内容可能不完整
  • 建设中 - 正在完善，主要内容已有
  • 已完成 - 内容完整，经过审校
  • 持续更新 - 完整但会定期更新

示例：

status: "建设中"

渲染效果： 显示带状态标识的徽章

2. 章节统计 - 递归自动计算

用途： 帮助读者判断时间投入和规模

计算方式 (递归统计):

  • pages: 递归统计章节下的所有页面数量，包括子章节中的页面 (不包括 section 本身)
  • words: 递归累加所有页面的字数
  • reading_time: 根据总字数自动计算
  • 中文：350 字/分钟
  • 英文：220 词/分钟

递归统计说明：

  • 如果一个章节包含子章节，会自动统计子章节中的所有页面
  • 只统计普通页面 (index.md),不包括章节页面 (_index.md)
  • 确保显示的是整个章节树的完整规模

无需配置： 这些数据由 Hugo 模板递归自动计算，始终保持准确

渲染效果：

章节规模
📄 8 篇文章
📝 约 18,400 字
⏱️ 约 90 分钟

实现细节

模板文件

  • 位置：layouts/partials/book/section-sidebar.html
  • 触发条件：仅在 .IsSection = true 时显示
  • 显示顺序：
  • 章节级别 (level)
  • 章节状态 (status)
  • 章节规模 (section_stats)

样式类名

.section-sidebar-info          // 主容器
.section-info-block            // 每个信息块
.section-info-title            // 信息块标题
.section-info-content          // 信息块内容
.section-status-badge          // 状态徽章
  .section-status-草稿
  .section-status-建设中
  .section-status-已完成
  .section-status-持续更新
.section-stat-item             // 统计项

国际化支持

需要在 i18n/zh.yaml 和 i18n/en.yaml 中添加以下翻译键：

# zh.yaml
section_status: "章节状态"
section_stats: "章节规模"
pages_count: "篇文章"
about: "约"

# en.yaml
section_status: "Status"
section_stats: "Section Stats"
pages_count: "pages"
about: "About"

维护指南

自动维护

章节统计数据完全由 Hugo 自动计算，无需任何手动维护：

  • 新增/删除页面时，统计自动更新
  • 修改内容字数时，统计自动更新
  • 始终保持准确，零维护成本

需要手动维护的字段

只需要维护一个字段：

  1. status: 章节完成状态

对比：普通页面 vs 章节页面

特性 普通页面 (Page) 章节页面 (Section)
Right Sidebar TOC 目录 章节元信息
显示内容 页面内标题导航 level + status + stats
信息密度 中 低 (精简)
维护成本 自动生成 手动/半自动

不包含的内容

以下内容明确不进入章节 sidebar:

  • ❌ Outcome(学习目标)
  • ❌ 能力地图
  • ❌ 相关章节推荐
  • ❌ 学习路径
  • ❌ 作者见解/备注
  • ❌ AI 自动总结
  • ❌ 页面创建/更新时间
  • ❌ 作者信息
  • ❌ 分类/标签

这些信息要么：

  • 信息密度过高
  • 维护成本过大
  • 或破坏章节的"工具属性"

示例

完整示例

---
title: "模型系统"
weight: 70
date: 2025-11-14T00:00:00+08:00
description: "抽象层面理解 vLLM 的模型识别、配置与权重加载。"
icon: fa-solid fa-cubes
lastmod: 2025-11-14T00:00:00+08:00

# 章节 sidebar 专用字段 (统计数据递归自动计算)
status: "建设中"
---

本章聚焦模型系统的抽象与实现,涵盖模型注册、配置解析与权重加载。

{{< section-toc show_summary="true" style="cards" >}}

渲染效果预览

┌─────────────────────┐
│ 章节状态            │
│ [建设中]            │
├─────────────────────┤
│ 章节规模 (递归)     │
│ 📄 12 篇文章        │
│ 📝 约 28,400 字     │
│ ⏱️ 约 81 分钟       │
└─────────────────────┘

注：如包含子章节，统计
    数字会递归包含所有
    子章节中的页面

迁移指南

从现有章节迁移

  1. 打开章节的 _index.md
  2. 在 front matter 中添加 level 字段
  3. 添加 status 字段
  4. (可选) 添加 section_stats 字段
  5. 保存并预览

批量更新脚本

# 为所有章节添加默认 level 和 status
find content/zh/book -name "_index.md" -type f | while read file; do
  # 检查是否已有 level 字段
  if ! grep -q "^level:" "$file"; then
    # 在 front matter 中添加默认值
    sed -i '' '/^---$/a\
level: "进阶"\
status: "建设中"
' "$file"
  fi
done