增加pdf文档目录

[qizidog]

希望增加pdf的文档目录，方便统筹阅读

[jerrylususu]

手动做了一个目录。使用方式如下：

1. 先准备 python 环境，安装一个叫 pdf.tocgen 的包
2. 下载下面这个 toc.txt，和从官网下载的 the-fenix-project.pdf 放在一起

Windows 下可以直接用，Mac/Linux 可能需要调整文件编码

toc.txt

3. 运行以下命令

pdftocio the-fenix-project.pdf < toc.txt

再次打开 PDF，就应该已经有完整目录了，所有层级应该都是正常的，如下图

[jerrylususu]

如果遇到未来 PDF 版本更新，或者想要从头生成带目录的 PDF，可以按照如下步骤操作

0. 安装 Python 环境和 pdf.tocgen 依赖

pip install -U pdf.tocgen

1. 准备一个临时的工作目录
2. 把整个项目 git clone 到本地
3. 打开 .vuepress\plugins\export\index.js，在 line 93 (exportPages 定义结束，browser 定义开始前) 插入以下内容，以生成层级数据文件
   注意需要将 {path_to_folder} 换成 1 中工作目录的路径

  fs.writeFileSync("{path_to_folder}" + "/sidebar.json", JSON.stringify(sidebar));
  fs.writeFileSync("{path_to_folder}" + "/exportPages.json", JSON.stringify(exportPages));

4. 把生成完成的 PDF （位于 .vuepress/dist/pdf 下，文件名为 the-fenix-project.pdf）复制到 1 中的临时工作目录。此时 1 中目录应包含 sidebar.json, exportPages.json, the-fenix-project.pdf 三个文件
5. 从 这里 获取 generate_pdf_with_toc.py 脚本，放置于 1 中工作目录
6. 在终端中切换到 1 中工作目录，运行 5 中的脚本

python generate_pdf_with_toc.py

7. 若一切正常，会新生成两个文件，其中 the-fenix-project-with-toc.pdf 为带目录的 PDF 文件，toc.txt 为目录描述文件。只要有了目录描述文件，就可以直接在有原始 PDF 的情况下添加目录，而不需要再完成以上的步骤了，链接

如果不想自己生成 PDF，只是想要自己生成目录的话，只需要做如下改动

• 上文步骤 3 中，添加的代码最后加一行 return，提前结束函数跳过 PDF 生成，但依然生成必要的层级数据文件
• 上文步骤 4 中，直接使用官网下载到的 PDF 文件

但这样可能会有一些小问题：如果官网比 PDF 新（新在这里指文章增加），用官网的文件结构生成的 PDF 目录会包含实际 PDF 文件中没有的项，在脚本中会自动跳过，但是依然会提示。

WARNING: missing some chapters, the PDF provided might not be the most up-to-date version.
警告：部分存在于网站中的章节不存在于 PDF 中。这可能是因为 PDF 构建后网站中增加了新章节。重新构建 PDF 可以解决这一问题。
missing chapter:  ArchSummit2021主题演讲：从软件的历史看架构的未来

生成原理：

1. 用 vuepress 中的 sidebar 获得层级结构，exportPages 获得页面标题和 URL
2. 用 pdf.tocgen 中的 extract_toc 从 PDF 文件中提取出文章标题和对应的页码
3. 匹配 1 中的树形目录和 2 中的文章页码，生成带层级的目录
4. 将带层级的目录信息写入 PDF 文件中