LeetCode-Go 电子书目录生成机制:menu.md 模板与 BookMenu 渲染原理
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 />
它由三部分组成:
- front matter
headless: true:这是 Hugo 的关键配置。声明为 headless 的页面不会生成独立的 HTML 页面,只作为内容数据被其他页面引用。电子书的菜单页因此不需要被直接访问,而只需把菜单条目数据提供给主题渲染。 <hr>与<br />:菜单区块的排版分隔标记,位于占位符前后,用于在侧边栏中区分目录与正文内容。{{.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")
}
整个流程分三步:
copyLackFile():先补齐第四章缺失的题解文件(详见下文);renderBookMenu("./template/menu.md"):读取模板并完成占位符替换;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
}
可以归纳出四条生成规则:
- 顶层条目:每章第一个元素(如
_index)输出为一级列表项- [...],使用带.md后缀的relref,对应章节首页; - 第一章的特殊锚点:
ChapterOne的第二个条目(#关于作者)不带.md后缀,使用裸relref指向锚点位置,且缩进为两级; - 普通子条目:第二章、第三章的其余条目输出为两级列表项
- [...],标题取自chapterMap的显示名,链接带.md; - 第四章子条目:所有题解条目输出为四级列表项
- [...](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 是否被重新写入即可验证整条链路是否正常。