LeetCode-Go 电子书目录生成机制:menu.md 模板与 BookMenu 渲染原理

原创2026-10-09 22:19:221,345 阅读
文章标签:示例工程

LeetCode-Go 电子书目录生成机制:menu.md 模板与 BookMenu 渲染原理

本指南深入剖析 LeetCode-Go 仓库中电子书侧边栏目录(BookMenu)的生成原理。它以 ctl/template/menu.md 为模板骨架,由 ctl 命令行工具扫描并替换其中的 {{.BookMenu}} 占位符,最终产出 Hugo 站点可用的菜单文件。读完本文,你将掌握这套"headless 模板 + 正则占位符替换 + 章节顺序驱动"的目录生成流程,并能理解修改菜单顺序、新增章节条目时应从何处入手。

模板文件本体:headless 页面与占位符

ctl/template/menu.md 全文极短,却是一个结构完整的 Hugo 模板:

---
headless: true
---

<hr>

{{.BookMenu}}

<br />

它由三部分组成:

  1. front matter headless: true:这是 Hugo 的关键配置。声明为 headless 的页面不会生成独立的 HTML 页面,只作为内容数据被其他页面引用。电子书的菜单页因此不需要被直接访问,而只需把菜单条目数据提供给主题渲染。
  2. <hr> 与 <br />:菜单区块的排版分隔标记,位于占位符前后,用于在侧边栏中区分目录与正文内容。
  3. {{.BookMenu}} 占位符:渲染时的替换锚点,由 ctl 在构建菜单时用整棵书籍目录树替换掉。

这种"占位符 + 模板"的写法在整个 ctl/template 目录中是统一约定。例如章节页模板 Array.md 使用 {{.AvailableTagTable}} 承载题解表格,而 menu.md 使用 {{.BookMenu}} 承载菜单树,均由对应渲染函数逐行替换。

渲染引擎:buildBookMenu 与 renderBookMenu

菜单的构建入口是 ctl/render.go 中的 buildBookMenu():

func buildBookMenu() {
	copyLackFile()
	// 按照模板重新渲染 Menu
	res, err := renderBookMenu("./template/menu.md")
	if err != nil {
		fmt.Println(err)
		return
	}
	util.WriteFile("../website/content/menu/index.md", res)
	fmt.Println("generate Menu successful")
}

整个流程分三步:

  1. copyLackFile():先补齐第四章缺失的题解文件(详见下文);
  2. renderBookMenu("./template/menu.md"):读取模板并完成占位符替换;
  3. util.WriteFile("../website/content/menu/index.md", res):把渲染结果写入 Hugo 内容目录,作为电子书菜单数据源。

renderBookMenu()(ctl/render.go)的实现体现了"逐行扫描 + 正则替换"的渲染模式:

func renderBookMenu(filePath string) ([]byte, error) {
	f, err := os.OpenFile(filePath, os.O_RDONLY, 0644)
	if err != nil {
		return nil, err
	}
	defer f.Close()
	reader, output := bufio.NewReader(f), []byte{}

	for {
		line, _, err := reader.ReadLine()
		if err != nil {
			if err == io.EOF {
				return output, nil
			}
			return nil, err
		}
		if ok, _ := regexp.Match("{{.BookMenu}}", line); ok {
			reg := regexp.MustCompile("{{.BookMenu}}")
			newByte := reg.ReplaceAll(line, []byte(generateMenu()))
			output = append(output, newByte...)
			output = append(output, []byte("\n")...)
		} else {
			output = append(output, line...)
			output = append(output, []byte("\n")...)
		}
	}
}

要点如下:

  • 使用 bufio.Reader 逐行读取模板,非占位符行原样透传(front matter、<hr>、<br /> 均保留);
  • 命中 {{.BookMenu}} 的行,用正则 reg.ReplaceAll 将该占位符替换为 generateMenu() 的返回值;
  • 渲染结果为 []byte 直接交给 util.WriteFile 落盘,菜单文件生成即完成。

renderBookMenu 与 renderReadme、renderChapterTwo 是同一套"打开模板 → 正则替换 → 输出字节流"模式,区别仅在占位符名称与替换数据的来源不同。

菜单数据的组装:四章结构如何拼出

generateMenu()(ctl/render.go)负责把四章菜单逐段拼接:

func generateMenu() string {
	res := ""
	res += menuLine(chapterOneMenuOrder, "ChapterOne")
	res += menuLine(chapterTwoFileOrder, "ChapterTwo")
	res += menuLine(chapterThreeFileOrder, "ChapterThree")
	chapterFourFileOrder, _ := getChapterFourFileOrder()
	res += menuLine(chapterFourFileOrder, "ChapterFour")
	return res
}

菜单整体对应电子书《LeetCode Cookbook》的四章结构,每个章节调用一次 menuLine() 生成一组菜单条目。

章节顺序与显示名:label.go 中的硬编码映射

各章的条目顺序与显示标题定义在 ctl/label.go:

  • chapterOneMenuOrder:第一章(序章)条目顺序,其中用 "#关于作者" 作为作者页的特殊锚点;
  • chapterTwoFileOrder:第二章(算法专题)的 19 个专题文件顺序,从 Array、String、Two_Pointers 一直到 Sliding_Window、Segment_Tree、Binary_Indexed_Tree;
  • chapterThreeFileOrder:第三章(一些模板)的顺序,即 Segment_Tree、UnionFind、LRUCache、LFUCache;
  • chapterMap:文件 ID → 菜单显示标题的映射,例如第二章里 "Array" 显示为 2.01 Array,"Two_Pointers" 显示为 2.03 ✅ Two Pointers,已完成全部题目的专题会带 ✅ 标记。

第四章没有静态顺序,而是动态扫描得出(详见下节)。注意 label.go 中特意注释说明:上下页导航已改由 Hugo 主题在渲染时动态生成,因此原先"读写 markdown 导航链接"的整套逻辑已被移除,菜单模板只需要提供目录树即可。

第四章的动态组装:getChapterFourFileOrder

第四章(Leetcode 题解)的菜单无法静态枚举,因为它随 leetcode/ 目录下的题解数量增长而变化。ctl/label.go 中的 getChapterFourFileOrder() 调用 util.LoadChapterFourDir()(ctl/util/util.go),递归扫描 website/content/ChapterFour/ 下所有 .md 文件,解析出题号并排序,动态生成第四章的条目顺序,再交给 menuLine 输出。

补全第四章:copyLackFile

在渲染菜单前,buildBookMenu() 先执行 ctl/render.go 中的 copyLackFile(),保证第四章与 leetcode/ 题解目录保持一致:

  • 读取 leetcode/ 下已收录题解(util.LoadSolutionsDir())与第四章现有文件(util.LoadChapterFourDir());
  • 二分查找找出第四章缺失的题解,逐个将 leetcode/<题号>.<题名>/README.md 拷贝为 website/content/ChapterFour/<章节编号>/<题号>.<题名>.md;
  • 同时为每个子目录拷贝 ctl/template/collapseSection.md 作为 _index.md——该文件 front matter 中 bookCollapseSection: true 表示 Hugo book 主题下该节默认折叠,weight: 20 控制其在侧边栏中的排序权重。

Hugo 链接的生成规则:menuLine 的实现细节

每个章节的菜单条目由 menuLine()(ctl/render.go)生成,其链接使用 Hugo 的 relref shortcode,以保证渲染为站点内部链接:

func menuLine(order []string, chapter string) string {
	res := ""
	for i := 0; i < len(order); i++ {
		if i == 1 && chapter == "ChapterOne" {
			res += fmt.Sprintf("  - %v\n", chapterMap[chapter][order[i]], chapter, order[i])
			continue
		}
		if i == 0 {
			res += fmt.Sprintf("- %v\n", chapterMap[chapter][order[i]], chapter, order[i])
		} else {
			if chapter == "ChapterFour" {
				res += fmt.Sprintf("    - %v\n", order[i], chapter, order[i])
			} else {
				res += fmt.Sprintf("  - %v\n", chapterMap[chapter][order[i]], chapter, order[i])
			}
		}
	}
	return res
}

可以归纳出四条生成规则:

  1. 顶层条目:每章第一个元素(如 _index)输出为一级列表项 - [...],使用带 .md 后缀的 relref,对应章节首页;
  2. 第一章的特殊锚点:ChapterOne 的第二个条目(#关于作者)不带 .md 后缀,使用裸 relref 指向锚点位置,且缩进为两级;
  3. 普通子条目:第二章、第三章的其余条目输出为两级列表项 - [...],标题取自 chapterMap 的显示名,链接带 .md;
  4. 第四章子条目:所有题解条目输出为四级列表项 - [...](4 空格缩进),标题直接用题解文件名(如 0001.Two-Sum),链接指向 ChapterFour 下的对应页面。

生成后的完整菜单写入 website/content/menu/index.md,其内容大致形如:

---
headless: true
---

<hr>

- 第一章 序章
  - 1.1 数据结构知识
  ...
- 第二章 算法专题
  - 2.01 Array
  ...
- 第四章 Leetcode 题解
    - 0001.Two-Sum
    ...

<br />

与 CLI 命令体系的联动

菜单构建是 ctl 命令行工具的一条完整链路。入口在 ctl/command.go,根命令 leetcode-go 注册了 version、build、pdf、refresh 等子命令;ctl/refresh.go 中的 refresh() 会依次执行 copyLackFile()、buildREADME()、buildChapterTwo(true) 来刷新全部文档。

从源码结构看,buildBookMenu() 的调用入口目前处于注释状态(refresh() 内的 //buildBookMenu() 以及 newBuildCommand() 中 // newBuildMenu()),即当前 CLI 默认流程不再自动重建菜单,但 buildBookMenu()、renderBookMenu() 等完整函数仍然保留,可在需要时手动恢复调用以重新生成 website/content/menu/index.md。

如何验证与查看渲染结果

  • 查看模板:ctl/template/menu.md 是唯一的菜单模板源文件,front matter 与占位符即上文所示;
  • 查看渲染实现:ctl/render.go 中 buildBookMenu(第 281 行)、generateMenu(第 325 行)、menuLine(第 335 行)、renderBookMenu(第 355 行)构成完整链路;
  • 查看章节定义:ctl/label.go 中的 chapterOneMenuOrder、chapterTwoFileOrder、chapterThreeFileOrder 与 chapterMap 决定了菜单的静态骨架;
  • 查看渲染输出样例:website/content/ChapterTwo/Array.md 等文件展示了章节页最终渲染结果,其中 {{< relref ... >}} 链接即由同套模板机制生成(由 renderChapterTwo 替换 {{.AvailableTagTable}} 得到,ctl/render.go)。

若菜单构建入口被重新启用,运行 refresh 或对应子命令后,检查 website/content/menu/index.md 是否被重新写入即可验证整条链路是否正常。

登录后查看全文
LeetCode-Go