Modernize 2014books publishing pipeline

.github/workflows/build.yml

@@ -0,0 +1,54 @@
+name: Build Check
+
+on:
+  push:
+    branches: [master, phase/*]
+  pull_request:
+    branches: [master, phase/*]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y pandoc
+
+      - name: Check shell script syntax
+        run: |
+          bash -n mmd2bok
+          bash -n scripts/build_pdf.sh
+          bash -n scripts/build_epub.sh
+
+      - name: Check Python syntax
+        run: |
+          python3 -m py_compile scripts/generate_web.py
+
+      - name: Build web
+        run: |
+          python3 scripts/generate_web.py
+          test -f web/index.html
+          test -f web/data/books.json
+
+      - name: Build EPUB
+        run: |
+          make epub
+          test -f dist/2014books.epub
+
+      # PDF build requires texlive-xetex which is heavy (~1.3GB).
+      # Skip in CI for speed; PDF is verified locally in Phase B/C.
+      # Uncomment below if PDF CI is needed:
+      # - name: Build PDF
+      #   run: |
+      #     sudo apt-get install -y texlive-xetex texlive-latex-recommended texlive-latex-extra texlive-lang-chinese fonts-noto-cjk
+      #     make pdf
+      #     test -f dist/2014books.pdf

.github/workflows/pages.yml

@@ -0,0 +1,49 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Generate web output
+        run: |
+          python3 -m py_compile scripts/generate_web.py
+          python3 scripts/generate_web.py
+
+      - name: Verify web artifacts
+        run: |
+          test -f web/index.html
+          test -f web/.nojekyll
+          test -f web/data/books.json
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: web/
+
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,29 @@
+# LaTeX intermediate files
+*.aux
+*.log
+*.out
+*.toc
+*.lof
+*.lot
+*.fls
+*.fdb_latexmk
+
+# Build directories
+build/
+dist/tmp/
+
+# We intentionally track dist/2014books.pdf if present
+__pycache__/
+
+# Generated LaTeX source files (rebuilt from markdown by mmd2bok)
+latex/2014books.tex
+latex/2014books.aux
+latex/2014books.log
+latex/2014books.out
+latex/2014books.toc
+latex/2014books.pdf
+latex/chapters.tex
+latex/appendix.tex
+latex/preface.tex
+latex/template.tex
+latex/template-win.tex

Makefile

@@ -0,0 +1,18 @@
+.PHONY: pdf web epub clean all release
+
+pdf:
+	bash scripts/build_pdf.sh
+
+web:
+	python3 scripts/generate_web.py
+
+epub:
+	bash scripts/build_epub.sh
+
+release:
+	bash scripts/package_release.sh
+
+clean:
+	rm -rf web dist latex/*.aux latex/*.log latex/*.out latex/*.toc latex/*.lof latex/*.lot latex/*.fls latex/*.fdb_latexmk build/
+
+all: web pdf epub

README.md

@@ -1,48 +1,123 @@
 2014年值得你阅读的100本书
 ========================
 
-# 前言 #
+## 项目简介
 
-2013年就要结束了，2014年又如何呢？在[第一财经周刊](http://www.cbnweek.com/)的网站上看到了这个专题——[值得你阅读的100本书-2014年开始摆脱庸常生活](http://www.cbnweek.com/v/subject?id=22)。感觉还不错，制作这个小册子也是自己2014年读书的一个清单。
+本项目是 2014 年第一财经周刊专题「值得你阅读的100本书」的 Markdown 制书复刻。原始内容来自周刊网站，由 Conan Xin 整理为可编译的 Markdown 源码，并生成 PDF 小册子。
 
-此外想要试一下[如何使用Markdown写书](https://github.com/larrycai/kaiyuanbook/blob/master/zh/chapters/01-chapter3.markdown)，之前已经试过了如何[使用Sphinx和reStructuredText作为写出工具](http://myshare.dscloud.me/scipydoc/pydoc_write_tools.html)，并整理完成了一个笔记——[工程设计方法学](http://conanxincv.sinaapp.com/project1/index.html)，放在了SAE上。不过使用reStructuredText时，多少还是有些不习惯。所以这里就使用Markdown来完成这本小册子。
+## 项目来源
 
-## 说明 ##
+- 原始专题：[第一财经周刊 · 值得你阅读的100本书](http://www.cbnweek.com/v/subject?id=22)
+- 整理者：Conan Xin
+- 源码仓库：https://github.com/conanxin/2014books
 
-1. 源码放在了[Github](https://github.com/conanxin/2014books)上：
-
-		git clone https://github.com/conanxin/2014books.git
+## 现在可以生成 PDF、Web 和 EPUB
 
-2. 下面介绍在Ubuntu上编译，先安装软件：
-
-	    $ sudo apt-get install ruby1.9.1
-    	$ sudo apt-get install pandoc
-    	$ sudo apt-get install texlive-xetex
-    	$ sudo apt-get install texlive-latex-recommended # main packages
-    	$ sudo apt-get install texlive-latex-extra # package titlesec
-
-	安装中文字体：
-
-		$ sudo apt-get install ttf-arphic-gbsn00lp ttf-arphic-ukai # from arphic 
-		$ sudo apt-get install ttf-wqy-microhei ttf-wqy-zenhei # from WenQuanYi
+本项目已从原始的单一脚本构建升级为支持多种输出格式：
 
-3. 使用命令：
+- **PDF**：通过 `pandoc` + `xelatex` 生成排版精美的中文 PDF
+- **静态网页**：通过 Python 标准库生成可离线浏览的静态网页，支持搜索和筛选
+- **EPUB**：通过 `pandoc` 生成电子书，兼容主流阅读器
 
-		$ bash ./mmd2bok
+## GitHub Pages 自动部署
 
-### 注意 ###
+仓库已配置 GitHub Actions 工作流，支持 `push` 到 `master` 时自动部署到 GitHub Pages。
 
-现在生成的pdf格式并不是很perfect，因为我修改了文件**mmd2bok**中的内容。原因是我在Ubuntu上安装**[multimarkdown](http://fletcherpenney.net/multimarkdown/)**没有成功，不知道什么地方出了问题。 
+- 启用方式：仓库 Settings → Pages → Source: GitHub Actions
+- 手动触发：Actions 标签页 → Deploy to GitHub Pages → Run workflow
+- 预期地址：https://conanxin.github.io/2014books/
 
-然后我将下面的代码：
+详见 [docs/GITHUB_PAGES_DEPLOYMENT.md](docs/GITHUB_PAGES_DEPLOYMENT.md)。
 
-		multimarkdown -t latex meta.txt ../contents/0-preface*.markdown -o preface.tex
-		multimarkdown -t latex meta.txt ../contents/1-chapter*.markdown -o chapters.tex
-		multimarkdown -t latex meta.txt ../contents/2-appendix*.markdown -o appendix.tex
+## 本地构建方法
 
-改成了：
+### 依赖安装（Ubuntu/Debian）
 
-		pandoc -t latex ../contents/0-preface*.markdown -o preface.tex
-		pandoc -t latex ../contents/1-chapter*.markdown -o chapters.tex
-		pandoc -t latex ../contents/2-appendix*.markdown -o appendix.tex
+```bash
+sudo apt-get install pandoc texlive-xetex texlive-latex-recommended texlive-latex-extra
+sudo apt-get install fonts-noto-cjk fonts-wqy-microhei fonts-wqy-zenhei
+```
 
+### 构建命令
+
+```bash
+# 生成 PDF
+make pdf
+
+# 生成静态网页
+make web
+
+# 生成 EPUB
+make epub
+
+# 生成 release package（zip）
+make release
+
+# 同时生成所有输出
+make all
+
+# 清理构建产物
+make clean
+```
+
+### 传统入口（兼容旧用法）
+
+```bash
+bash ./mmd2bok
+```
+
+## 项目结构
+
+```
+2014books/
+├── contents/          # Markdown 源文件（章节内容）
+│   ├── 0-preface*.markdown
+│   ├── 1-chapter*.markdown
+│   └── 2-appendix*.markdown
+├── data/              # 书目元数据增强（人工/半人工入口）
+│   ├── book_metadata_overrides.json
+│   └── missing_book_candidates.json
+├── template/          # LaTeX 模板文件
+├── latex/             # LaTeX 构建工作目录
+├── scripts/           # 现代构建脚本
+│   ├── build_pdf.sh   # PDF 构建入口
+│   ├── build_epub.sh  # EPUB 构建入口
+│   ├── generate_web.py # 静态网页生成器
+│   └── package_release.sh # Release package 打包
+├── web/               # 生成的静态网页输出
+│   ├── index.html
+│   ├── .nojekyll
+│   ├── assets/style.css
+│   └── data/books.json
+├── dist/              # 生成的 PDF/EPUB/Release 输出
+│   ├── 2014books.pdf
+│   ├── 2014books.epub
+│   └── release/
+├── .github/workflows/  # CI/CD 工作流
+│   ├── build.yml
+│   └── pages.yml
+├── mmd2bok            # 传统 PDF 构建脚本（已修复章节排序）
+├── Makefile           # 现代构建入口
+└── README.md          # 本文件
+```
+
+## 已知限制
+
+1. **书单完整性**：当前已从附录结构化整理 **97 本** 书目。项目标题中的"100本"为原始专题名称，实际可验证数量为 97 本，剩余 3 本需对照原始《第一财经周刊》专题进一步核对。缺失候选已单独记录在 `data/missing_book_candidates.json`，不会自动进入正式书单。
+2. **PDF 字体依赖**：需要系统中安装 WenQuanYi 或 Noto CJK 系列中文字体，否则 xelatex 编译可能失败。模板已添加字体回退链。
+3. **封面图片**：模板支持 `img/cover.pdf` 封面；若缺失则自动生成文字封面。
+4. **网页搜索**：静态网页的搜索功能为前端 JavaScript 实现，无需后端服务，但仅支持当前页面已加载的内容。
+5. **章节排序**：已修复原始脚本中 `1-chapter10` 排在 `1-chapter2` 之前的排序问题。
+
+## 元数据增强
+
+- `data/book_metadata_overrides.json`：人工/半人工增强元数据入口。用 `id` 匹配附录书目，非 null 字段覆盖或补充生成字段。
+- `data/missing_book_candidates.json`：低置信度缺失候选池，不进入正式 `books.json`。
+
+## 下一阶段路线图
+
+- **Phase E**：补齐剩余 3 本书目缺口（需外部原始来源核对）；增强书籍元数据（ISBN、出版社等）；优化封面设计。
+
+---
+
+> 原始 README 历史背景保留：本项目最初创建于 2014 年，用于尝试使用 Markdown 写书。最初使用 multimarkdown 工具链，后因安装问题改为 pandoc。2024 年进行现代化升级，增加了网页版本和 Makefile 构建入口。

data/book_metadata_overrides.json

@@ -0,0 +1 @@
+[]

data/missing_book_candidates.json

@@ -0,0 +1,26 @@
+[
+  {
+    "title": "《世界是平的》",
+    "chapter": "chapter 2",
+    "reason": "章节中以粗体形式出现，附录中无对应条目",
+    "confidence": "low",
+    "evidence": "章节2中提到的书目，未在附录1-97中找到匹配",
+    "should_add_to_books_json": false
+  },
+  {
+    "title": "《通用汽车的缔造者》",
+    "chapter": "chapter 2",
+    "reason": "章节中以粗体形式出现，附录中无对应条目",
+    "confidence": "low",
+    "evidence": "章节2中提到的书目，未在附录1-97中找到匹配",
+    "should_add_to_books_json": false
+  },
+  {
+    "title": "《总开关—信息帝国的兴衰变迁》",
+    "chapter": "chapter 22",
+    "reason": "章节中以粗体形式出现，附录中无对应条目",
+    "confidence": "low",
+    "evidence": "章节22中提到的书目，未在附录1-97中找到匹配",
+    "should_add_to_books_json": false
+  }
+]

docs/GITHUB_PAGES_DEPLOYMENT.md

@@ -0,0 +1,60 @@
+# GitHub Pages 部署说明
+
+## 目录结构
+
+`web/` 目录已准备为可直接发布的静态站点：
+
+- `index.html` — 主页面（相对路径引用）
+- `assets/style.css` — 样式表
+- `data/books.json` — 结构化书目数据
+- `.nojekyll` — 禁用 Jekyll 处理（确保以纯静态文件方式服务）
+
+## 发布方式
+
+### 方式一：GitHub Actions 自动部署（推荐）
+
+仓库已配置 `.github/workflows/pages.yml`，支持以下触发方式：
+
+- `push` 到 `master` 分支时自动部署
+- `workflow_dispatch` 手动触发部署
+
+#### 启用步骤
+
+1. 打开仓库 GitHub 页面 → Settings → Pages
+2. Build and deployment → Source: 选择 **GitHub Actions**
+3. 保存后，下次 push 到 master 或手动触发 workflow 即可自动部署
+
+#### 预期访问地址
+
+https://conanxin.github.io/2014books/
+
+#### 如果页面 404
+
+- 检查 Pages 是否已在 Settings → Pages 中启用
+- 检查 Actions 标签页中 workflow 是否成功运行
+- 确认 `web/index.html` 存在且构建步骤未报错
+- 确认已合并到 `master` 分支（phase 分支不自动部署）
+
+### 方式二：手动发布到 gh-pages 分支
+
+```bash
+cd /path/to/2014books
+git checkout --orphan gh-pages
+git rm -rf .
+cp -r web/* .
+git add .
+git commit -m "Deploy to GitHub Pages"
+git push origin gh-pages
+```
+
+然后在仓库 Settings → Pages 中选择 "Deploy from a branch" → `gh-pages`。
+
+## 当前工作流说明
+
+- phase 分支仅验证构建，不直接发布到 Pages
+- 只有 `master` 分支的 push 会触发自动部署
+- 手动触发 `workflow_dispatch` 可用于测试部署流程
+
+- 所有资源使用相对路径，不依赖外部 CDN
+- 站点完全离线可用
+- 无需构建工具，直接复制 `web/` 内容即可发布