mirror of
https://github.com/luongnv89/claude-howto.git
synced 2026-04-21 21:45:58 +02:00
Luong NGUYEN
6d1e0ae4af
* refactor(ci): shift quality checks to pre-commit, CI as 2nd pass
- Remove ci.yml (lint, security, pytest were only for EPUB scripts)
- Move EPUB build to pre-commit local hook (runs on .md changes)
- Add check_cross_references.py, check_mermaid.py, check_links.py scripts
- Add markdown-lint, cross-references, mermaid-syntax, link-check as
pre-commit hooks — mirrors all 4 CI doc-check jobs locally
- Remove spell check job from docs-check.yml (breaks on translations)
- Refactor docs-check.yml to reuse scripts/ instead of inline Python
- Add .markdownlint.json config shared by pre-commit and CI
- Update CONTRIBUTING.md with required dependencies and hook table
* fix(ci): resolve all CI check failures in docs-check workflow
- fix(check_cross_references): skip code blocks and inline code spans
to avoid false positives from documentation examples; fix emoji
heading anchor generation (rstrip not strip); add blog-posts,
openspec, prompts, .agents to IGNORE_DIRS; ignore README.backup.md
- fix(check_links): strip trailing Markdown punctuation from captured
URLs; add wikipedia, api.github.com to SKIP_DOMAINS; add placeholder
URL patterns to SKIP_URL_PATTERNS; add .agents/.claude to IGNORE_DIRS
- fix(check_mermaid): add --no-sandbox puppeteer config support via
MERMAID_PUPPETEER_NO_SANDBOX env var for GitHub Actions Linux runners
- fix(docs-check.yml): pass MERMAID_PUPPETEER_NO_SANDBOX=true to mermaid job
- fix(content): repair broken anchors in README.md, 09-advanced-features;
fix #plugins -> #claude-code-plugins in claude_concepts_guide.md;
remove non-existent ./docs/performance.md placeholder links; fix
dependabot alerts URL in SECURITY_REPORTING.md; update auto-mode URL
in resources.md; use placeholder pattern for 07-plugins example URL
- remove README.backup.md (stale file)
* fix(check-scripts): fix strip_code_blocks regex and URL fragment handling
- fix regex in strip_code_blocks to avoid conflicting MULTILINE+DOTALL
flags that could fail to strip indented code fences; use DOTALL only
- strip URL fragments (#section) before dispatching link checks to avoid
false-positive 404s on valid URLs with anchor fragments
* fix(check-scripts): fix anchor stripping, cross-ref enforcement, and mermaid temp file cleanup
- heading_to_anchor: use .strip("-") instead of .rstrip("-") to also strip leading hyphens
produced by emoji-prefixed headings, preventing false-positive anchor errors
- check_cross_references: always exit with main()'s return code — filesystem checks
should block pre-commit unconditionally, not silently pass on errors
- check_mermaid: wrap file-processing loop in try/finally so the puppeteer config
temp file is cleaned up even if an unexpected exception (e.g. UnicodeDecodeError) occurs
- docs-check.yml: remove now-unused CROSS_REF_STRICT env var
* fix(scripts): fix anchor stripping and mermaid output path
- Replace .strip('-') with .rstrip('-') in heading_to_anchor() so leading
hyphens from emoji-prefixed headings are preserved, matching GitHub's
anchor generation behaviour.
- Use Path.with_suffix('.svg') in check_mermaid.py instead of
str.replace('.mmd', '.svg') to avoid replacing all occurrences of .mmd
in the full temp path.
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.