feat: add v1/v2 versioning with language selector (#494)

* feat: add v1/v2 versioning and language selector for mdbook

- Copy current content to v1/ directory (1st Edition)
- Create v2/ directory with new TOC structure (2nd Edition) and placeholder chapters
- Add version selector (V1/V2) and language toggle (EN/ZH) in top-right nav bar
- Add build scripts: build_mdbook_v1.sh, build_mdbook_v2.sh
- Update assemble_docs_publish_tree.py to support v1/v2 deployment layout
- Fix mdbook preprocessor to use 'sections' key (v0.4.43 compatibility)
- Update .gitignore for new build artifact directories
- Deployment layout: / = v2 EN, /cn/ = v2 ZH, /v1/ = v1 EN, /v1/cn/ = v1 ZH

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* build: update CI to build and verify all four books (v1/v2 x EN/ZH)

- Clarify step names: "Build v2 (EN + ZH)" and "Build v1 (EN + ZH)"
- Add verification step to check all four index.html outputs exist
- Deploy workflow assembles: / = v2 EN, /cn/ = v2 ZH, /v1/ = v1 EN, /v1/cn/ = v1 ZH

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: gracefully skip missing TOC entries instead of crashing

resolve_toc_target() now returns None for missing files instead of
raising FileNotFoundError. This fixes v1 EN build where chapter index
files reference TOC entry names that don't match actual filenames.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

.github/workflows/main.yml

@@ -31,8 +31,18 @@ jobs:
           python3 -m unittest discover -s tests -p 'test_ensure_book_resources.py'
           python3 -m unittest discover -s tests -p 'test_update_docs_workflow.py'
 
-      - name: Build English HTML with mdBook
-        run: bash build_mdbook.sh
+      - name: Build v2 (EN + ZH) with mdBook
+        run: bash build_mdbook_v2.sh
 
-      - name: Build Chinese HTML with mdBook
-        run: bash build_mdbook_zh.sh
+      - name: Build v1 (EN + ZH) with mdBook
+        run: bash build_mdbook_v1.sh
+
+      - name: Verify build outputs
+        run: |
+          for d in .mdbook-v2/book .mdbook-v2-zh/book .mdbook-v1/book .mdbook-v1-zh/book; do
+            if [ ! -f "$d/index.html" ]; then
+              echo "ERROR: $d/index.html not found"
+              exit 1
+            fi
+            echo "OK: $d/index.html exists"
+          done

.github/workflows/update_docs.yml

@@ -29,13 +29,23 @@ jobs:
           python3 -m unittest discover -s tests -p 'test_assemble_docs_publish_tree.py'
           python3 -m unittest discover -s tests -p 'test_ensure_book_resources.py'
 
-      - name: Build English HTML with mdBook
-        run: bash build_mdbook.sh
+      - name: Build v2 (EN + ZH) with mdBook
+        run: bash build_mdbook_v2.sh
 
-      - name: Build Chinese HTML with mdBook
-        run: bash build_mdbook_zh.sh
+      - name: Build v1 (EN + ZH) with mdBook
+        run: bash build_mdbook_v1.sh
 
-      - name: Deploy to openmlsys.github.io
+      - name: Verify build outputs
+        run: |
+          for d in .mdbook-v2/book .mdbook-v2-zh/book .mdbook-v1/book .mdbook-v1-zh/book; do
+            if [ ! -f "$d/index.html" ]; then
+              echo "ERROR: $d/index.html not found"
+              exit 1
+            fi
+            echo "OK: $d/index.html exists"
+          done
+
+      - name: Assemble and deploy to openmlsys.github.io
         env:
           DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
         run: |
@@ -44,8 +54,10 @@ jobs:
           python3 tools/assemble_docs_publish_tree.py \
             --destination-root openmlsys.github.io \
             --docs-subdir docs \
-            --en-source .mdbook/book \
-            --zh-source .mdbook-zh/book
+            --v2-en-source .mdbook-v2/book \
+            --v2-zh-source .mdbook-v2-zh/book \
+            --v1-en-source .mdbook-v1/book \
+            --v1-zh-source .mdbook-v1-zh/book
 
           cd openmlsys.github.io
           git config user.name "github-actions[bot]"