mirror of
https://github.com/luongnv89/claude-howto.git
synced 2026-04-26 09:56:01 +02:00
Luong NGUYEN
e76bbe40f2
* refactor(epub): replace Kroki HTTP dependency with local mmdc rendering (#10) Remove httpx/tenacity dependencies and Kroki.io API calls from the EPUB build pipeline. MermaidRenderer now invokes mmdc (mermaid-cli) as a local subprocess, eliminating intermittent CI failures caused by network unavailability. CI workflow installs @mermaid-js/mermaid-cli before build. * fix(epub): add subprocess timeout and fix deduplication log count - Add 60s timeout to mmdc subprocess.run to prevent hanging builds when Chromium/Puppeteer stalls in headless CI environments - Fix misleading log that printed unique/total as equal counts; now logs "N unique diagrams (M total blocks)" explicitly - Add test_render_all_timeout and strengthen deduplication assertion
EPUB Builder Script
Build an EPUB ebook from the Claude How-To markdown files.
Features
- Organizes chapters by folder structure (01-slash-commands, 02-memory, etc.)
- Renders Mermaid diagrams as PNG images via Kroki.io API
- Async concurrent fetching - renders all diagrams in parallel
- Generates a cover image from the project logo
- Converts internal markdown links to EPUB chapter references
- Strict error mode - fails if any diagram cannot be rendered
Requirements
- Python 3.10+
- uv
- Internet connection for Mermaid diagram rendering
Quick Start
# Simplest way - uv handles everything
uv run scripts/build_epub.py
Development Setup
# Create virtual environment
uv venv
# Activate and install dependencies
source .venv/bin/activate
uv pip install -r requirements-dev.txt
# Run tests
pytest scripts/tests/ -v
# Run the script
python scripts/build_epub.py
Command-Line Options
usage: build_epub.py [-h] [--root ROOT] [--output OUTPUT] [--verbose]
[--timeout TIMEOUT] [--max-concurrent MAX_CONCURRENT]
options:
-h, --help show this help message and exit
--root, -r ROOT Root directory (default: repo root)
--output, -o OUTPUT Output path (default: claude-howto-guide.epub)
--verbose, -v Enable verbose logging
--timeout TIMEOUT API timeout in seconds (default: 30)
--max-concurrent N Max concurrent requests (default: 10)
Examples
# Build with verbose output
uv run scripts/build_epub.py --verbose
# Custom output location
uv run scripts/build_epub.py --output ~/Desktop/claude-guide.epub
# Limit concurrent requests (if rate-limited)
uv run scripts/build_epub.py --max-concurrent 5
Output
Creates claude-howto-guide.epub in the repository root directory.
The EPUB includes:
- Cover image with project logo
- Table of contents with nested sections
- All markdown content converted to EPUB-compatible HTML
- Mermaid diagrams rendered as PNG images
Running Tests
# With virtual environment
source .venv/bin/activate
pytest scripts/tests/ -v
# Or with uv directly
uv run --with pytest --with pytest-asyncio \
--with ebooklib --with markdown --with beautifulsoup4 \
--with httpx --with pillow --with tenacity \
pytest scripts/tests/ -v
Dependencies
Managed via PEP 723 inline script metadata:
| Package | Purpose |
|---|---|
ebooklib |
EPUB generation |
markdown |
Markdown to HTML conversion |
beautifulsoup4 |
HTML parsing |
httpx |
Async HTTP client |
pillow |
Cover image generation |
tenacity |
Retry logic |
Troubleshooting
Build fails with network error: Check internet connectivity and Kroki.io status. Try --timeout 60.
Rate limiting: Reduce concurrent requests with --max-concurrent 3.
Missing logo: The script generates a text-only cover if claude-howto-logo.png is not found.