mirror of
https://github.com/luongnv89/claude-howto.git
synced 2026-04-21 21:45:58 +02:00
Luong NGUYEN
58e586f09b
- Update all main markdown files (INDEX.md, LEARNING-ROADMAP.md, QUICK_REFERENCE.md, CONTRIBUTING.md, claude_concepts_guide.md, resources.md) with new responsive picture element - Add logo to all subdirectory README files in feature folders (01-10) and plugins - Replace old markdown image syntax with HTML picture element for dark/light mode adaptation - Logo automatically displays dark mode version when system prefers dark mode - Maintain correct relative paths for all nesting levels (../, ../../, etc.) - Update README.md with new logo syntax All markdown files now use the new V2.0 starburst logo design with professional dark/light mode support.
121 lines
3.1 KiB
Markdown
121 lines
3.1 KiB
Markdown
<picture>
|
|
<source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
|
|
<img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
|
|
</picture>
|
|
|
|
# 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](https://github.com/astral-sh/uv)
|
|
- Internet connection for Mermaid diagram rendering
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Simplest way - uv handles everything
|
|
uv run scripts/build_epub.py
|
|
```
|
|
|
|
## Development Setup
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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.
|