feat: add GitBook sync workflow with markdown conversion script (#203)

- Convert inline math $...$ to $$...$$ for GitBook compatibility
- Convert GitHub callouts [!TIP/WARNING] to GitBook hint blocks
- Convert TOC anchor links (#N) to (#id-N) to match GitBook anchor format
- GitHub Actions workflow to auto-sync main branch to gitbook branch

Author: CoodingPenguin

.github/scripts/convert_for_gitbook.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Convert GitHub markdown syntax to GitBook-compatible syntax.
+
+Transformations:
+1. Inline math: $...$ → $$...$$
+2. Callouts: > [!TIP/WARNING/...] → {% hint style="..." %}
+3. TOC anchors: (#N) → (#id-N)
+"""
+
+import re
+import os
+
+
+def convert_inline_math(content):
+    """Convert $...$ inline math to $$...$$ for GitBook.
+    Skips code blocks and already-converted $$...$$ expressions.
+    """
+    # Split by fenced code blocks and inline code to avoid modifying them
+    parts = re.split(r'(```[\s\S]*?```|`[^`\n]+`)', content)
+    result = []
+    for i, part in enumerate(parts):
+        if i % 2 == 0:  # Non-code section
+            part = re.sub(
+                r'(?<!\$)\$(?!\$)([^\n$]+?)(?<!\$)\$(?!\$)',
+                r'$$\1$$',
+                part
+            )
+        result.append(part)
+    return ''.join(result)
+
+
+def convert_callouts(content):
+    """Convert GitHub [!TYPE] callouts to GitBook hint blocks.
+
+    GitHub:
+        > [!TIP]
+        > content
+
+    GitBook:
+        {% hint style="info" %}
+        content
+        {% endhint %}
+    """
+    style_map = {
+        'TIP': 'info',
+        'NOTE': 'info',
+        'WARNING': 'warning',
+        'IMPORTANT': 'warning',
+        'CAUTION': 'danger',
+    }
+
+    def replace_callout(match):
+        callout_type = match.group(1).upper()
+        body = match.group(2)
+        lines = re.sub(r'^> ?', '', body, flags=re.MULTILINE).strip()
+        style = style_map.get(callout_type, 'info')
+        return f'{{% hint style="{style}" %}}\n{lines}\n{{% endhint %}}'
+
+    pattern = r'> \[!(\w+)\]\s*\n((?:>[ \t]?[^\n]*\n)*)'
+    return re.sub(pattern, replace_callout, content)
+
+
+def convert_toc_anchors(content):
+    """Convert (#N) TOC links to (#id-N) for GitBook anchor compatibility.
+
+    GitBook generates 'id-N' anchors for headings like '## #N'.
+    """
+    return re.sub(r'\(#(\d+)\)', r'(#id-\1)', content)
+
+
+def convert_file(filepath):
+    with open(filepath, 'r', encoding='utf-8') as f:
+        content = f.read()
+
+    content = convert_inline_math(content)
+    content = convert_callouts(content)
+    content = convert_toc_anchors(content)
+
+    with open(filepath, 'w', encoding='utf-8') as f:
+        f.write(content)
+
+    print(f'Converted: {filepath}')
+
+
+def main():
+    for root, dirs, files in os.walk('.'):
+        dirs[:] = [d for d in dirs if not d.startswith('.')]
+        for filename in files:
+            if filename.endswith('.md'):
+                convert_file(os.path.join(root, filename))
+
+
+if __name__ == '__main__':
+    main()

.github/workflows/sync-gitbook.yml

@@ -0,0 +1,35 @@
+name: Sync to GitBook
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Convert markdown for GitBook
+        run: python .github/scripts/convert_for_gitbook.py
+
+      - name: Push to gitbook branch
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git checkout -B gitbook
+          git add -A
+          git diff --cached --quiet || git commit -m "chore: sync from main [skip ci]"
+          git push origin gitbook --force