为 Hugoplate 添加多文档系统（2）

内容目录

Hugo 虚拟文档系统设计与实现详解

✨ 前言

之前尝试为 Hugoplate 模板添加一个“多文档体系”功能，用于维护结构化的学习笔记。最终实现了一个基于 Hugo 的虚拟文档系统，主要的特点如下：

目录结构完全yaml文件决定，通过解析yaml文件来筛选文章组成文档。
文档总览页与单文档页分开模板控制，支持不同的展示样式。
利用 partial 函数递归渲染章节结构，支持多级目录。

具体参考: 为 Hugoplate 添加多文档系统（1）

重要缺陷：

仅能得到一个文档的目录结构，以及文章的跳转链接，而无法直接在目录结构中展示文章预览卡片列表，因为hugo仅维护标签和分类两个自动页，并且Hugo 是构建时静态渲染，不是运行时动态系统，这导致我们无法从url中的变量来动态获取文章列表。解决方法是通过 frontmatter 中的字段来在构建时生成目录结构。那么就会违背目录结构完全yaml文件决定的设计目标。所以需要重新设计一个实现方式。

🎯 设计目标

本系统围绕以下四条核心设计原则构建：

目录结构完全由 frontmatter 决定，与物理路径解耦，提升内容迁移与重构灵活性。
data/docs/*.yaml 文件 仅记录文档 ID 与索引信息，不直接参与构建逻辑，保持低耦合。
支持通过 Go 脚本自动从文章中读取 frontmatter.docmeta 字段 生成目录索引文件。
支持通过 YAML 文件 反向批量写入 frontmatter，实现集中式元信息维护。

📦 Frontmatter 结构规范

每篇 Markdown 文件的 frontmatter 均需包含以下结构：

docmeta:
  id: htmlcss                    # 所属文档 ID（对应 data/docs/htmlcss.yaml）
  path: htmlcss/basics/html5     # 虚拟路径（用来构建目录树）
  title: HTML5 简介              # 显示标题
  weight: 1                      # 同层级排序

id 决定该文章属于哪个文档集合。
path 仅作为逻辑路径使用，不受物理目录结构影响。
_index.md 用于为虚拟目录赋予标题与排序能力。

🏗️ 文档树构建机制

通过模板在运行时构建完整目录树，无需依赖 YAML 文件或物理结构。

🔧 主要变量说明：

变量名	说明
`nodeMap`	映射路径 → 页面列表，用于展示文章
`tree`	映射父路径 → 子路径列表，用于构建树结构
`docmeta.path`	用于拆分路径、建立层级结构

📂 树构建逻辑步骤：

从 site.Pages 中筛选出当前文档 ID 的所有文章。
遍历每篇文章的 docmeta.path，拆分生成所有中间路径。
构建 tree[parent] = []childPaths 映射关系。
同时建立 nodeMap[path] = []pages 映射以关联页面内容。

🧭 模板渲染机制（tree-recursive.html）

递归遍历目录树并展示文档结构：

支持多级嵌套与层级缩进。
每个节点可点击展开折叠（基于 Alpine.js）。
支持文章排序与当前页面高亮。
_index.md 用于目录排序与重命名。

📌 示例样式渲染：

<div class="ml-8 py-1 bg-light dark:bg-darkmode-light rounded-xl p-6">
  <div class="cursor-pointer" @click="open = !open">
    <span x-text="open ? '▼' : '▶'"></span>
    <a href="/docs/htmlcss/basics/" class="font-semibold hover:underline text-gray-700 dark:text-white">
      basics
    </a>
  </div>
  <div x-show="open">
    <!-- 渲染该路径下的所有文章链接 -->
  </div>
</div>

⚙️ YAML 索引生成工具

使用 Go 脚本读取所有文章的 docmeta 字段，按路径分类并生成如下格式：

id: htmlcss
title: "前端基础"
routes:
  htmlcss/basics:
    - title: "HTML 示例"
      url: /blog/html-example/
      weight: 1
      path: htmlcss/basics
      source: content/chinese/blog/html-example.md
  htmlcss/basics/html5:
    - title: "HTML5 基础"
      url: /blog/html-html5/
      weight: 1
      path: htmlcss/basics/html5

该 YAML 可用于：

浏览器端快速构建路由或目录索引
辅助生成物理 _index.md 文件
反向写入 frontmatter

🔄 Frontmatter 批量反写工具

另一个 Go 脚本可从 YAML 文件中读取元信息，将其批量写入对应 Markdown 文件的 frontmatter，支持：

精确定位文章路径
只覆盖 docmeta 部分
保留原有 Markdown 正文与其他字段

💡 页面右栏卡片渲染逻辑

点击目录树节点时，系统通过 URL 查询参数 ?path=... 确定当前目录路径，然后从 nodeMap 中查找并展示该路径下的所有文章：

<div class="grid grid-cols-2 gap-4">
  {{ range $articles }}
    {{ partial "components/blog-card.html" . }}
  {{ end }}
</div>

支持使用自定义卡片组件（如 blog-card.html）展示标题、描述、跳转链接等内容。

🎨 样式与深色模式支持

目录样式采用 rounded-xl、bg-light/bg-darkmode-light 自适应色彩。
链接在深色模式下显示为白色，普通链接为灰色或 hover 下亮色。
当前选中页面使用加粗字体与显著颜色提示。

📌 当前优势总结

维度	优势说明
解耦性	路由与物理路径解耦，路径自由灵活
自动化	支持 YAML 自动生成与反写
可维护性	结构集中维护，改动成本低
用户体验	支持目录折叠、深色模式、卡片展示
扩展性	支持 ID 多文档并存、多级虚拟目录结构

📁 示例结构

content/
└── chinese/
    └── blog/
        └── html-example.md         # 原文章

data/
└── docs/
    └── htmlcss.yaml                # 记录文档树

layouts/
├── docs/
│   ├── section.html               # 主模板
│   └── tree-recursive.html        # 树递归组件
└── components/
    └── blog-card.html             # 文章卡片组件

scripts/
├── generate_yaml.go              # frontmatter → YAML
└── reverse_write.go              # YAML → frontmatter

🧾 结语

本系统为 Hugo 文档平台提供了一种非侵入式、虚拟结构驱动的构建方案，适合大型文档、教学平台、组件库文档等复杂信息组织场景。通过清晰的结构定义与自动化工具支持，实现了内容与结构的彻底解耦与可维护性提升。