mirror of
https://github.com/luongnv89/claude-howto.git
synced 2026-06-05 22:36:34 +02:00
Luong NGUYEN
3557d791f5
* feat(scripts): add static website generator from markdown sources (#85) Generate an elegant, mobile-friendly static site from the existing tutorial markdown files. The markdown remains the single source of truth — `scripts/build_website.py` reads from the same `.md` files the EPUB builder uses, rewrites cross-references to site URLs, and rewrites references to non-markdown repo files (`.json`, `.sh`, `.py`) to GitHub blob URLs so users can jump to the source on github.com. Highlights: - Reuses the chapter ordering convention from `build_epub.py` - Anchor algorithm mirrors `check_cross_references.heading_to_anchor` for parity with the validator - Mermaid renders client-side via `mermaid.js` (no pre-render step) - Tailwind CSS via CDN; light/dark theme toggle; sidebar nav; in-page TOC; prev/next page navigation; mobile responsive - 27 unit + smoke tests covering anchors, link rewriting (including `<source srcset>` inside `<picture>`), Mermaid handling, and a full end-to-end build - GitHub Pages deploy workflow at `.github/workflows/pages.yml` Closes #85 * fix(website): use relative URLs in sidebar nav and avoid INDEX.html collision Two bugs found by local browser dogfooding: 1. **Sidebar nav broke from deep pages.** `build_navigation` emitted raw `output_url` values (site-root-relative) which made every sidebar link 404 from any page below the root. Moved the call inside the per-page render loop so each page gets nav links computed relative to its own URL — `01-slash-commands/index.html` from the root, `../01-slash-commands/...` from a depth-1 page, `../../01-slash-commands/...` from depth-2. 2. **`INDEX.md` overwrote `index.html`.** On case-insensitive filesystems (macOS/Windows), `INDEX.html` and `index.html` are the same file, so `INDEX.md` clobbered the rendered `README.md`. Added `_disambiguate_url` that detects case-insensitive collisions and suffixes the colliding page with its source stem (`INDEX-index.html`). Added 2 tests; full suite stays at 83 passed. * fix(scripts): skip URLs with port in localhost/127.0.0.1 skip list `check_links.is_skipped()` did an exact-match comparison against the host, so `http://localhost:8080` (used in scripts/README.md as a preview example) was not skipped and CI's link check tried to fetch it, which fails on the GitHub runner. Strip the port before comparing. * chore(scripts): drop vestigial mypy ignore_errors for build_website The override silenced all mypy errors for build_website, making the "mypy: clean" claim technically vacuous. Removing it shows mypy is actually clean — 0 issues on build_website after type annotations were added during PR review. * feat(website): self-host Tailwind, Mermaid, and Inter fonts Drop all third-party CDN dependencies from rendered pages. The site previously loaded Tailwind from cdn.tailwindcss.com (Play CDN — JIT compile in browser, marked not-for-production), Mermaid from cdn.jsdelivr.net, and Inter/JetBrains Mono from fonts.googleapis.com. Replace with a vendored toolchain: - scripts/vendor_assets.py downloads the Tailwind standalone CLI (Go binary, no Node toolchain), Mermaid's UMD bundle, and Google Fonts CSS + WOFF2 files. Cached under scripts/.vendor-cache/ (gitignored), refetched only when missing. - Tailwind compiles a per-build site/assets/tailwind.css with only the utility classes actually used by the rendered HTML. - Mermaid and font files land in site/assets/vendor/ and load via relative URLs. - Tailwind config + entry CSS live in scripts/website_templates/ alongside the Jinja template. - build_website grows a skip_vendor flag so the smoke test runs offline. - pre-commit mypy hook gets types-Markdown so it can resolve the same imports as the project venv. Verification: 86/86 pytest pass, ruff/mypy/bandit clean, full build produces a working site with zero external requests (verified in a headless browser — no console errors, no failed network calls, Mermaid diagrams render). * fix(website): use tree URLs for repo directory links (#85) * fix(website): include additional top-level docs (#85)
195 lines
5.5 KiB
YAML
195 lines
5.5 KiB
YAML
# Pre-commit hooks for claude-howto project
|
|
# Run `pre-commit install` to set up hooks
|
|
# Run `pre-commit run --all-files` to check all files
|
|
|
|
default_language_version:
|
|
python: python3.11
|
|
|
|
repos:
|
|
# Ruff - Fast Python linter and formatter
|
|
- repo: https://github.com/astral-sh/ruff-pre-commit
|
|
rev: v0.8.2
|
|
hooks:
|
|
- id: ruff
|
|
name: ruff-lint
|
|
args: [--fix, --exit-non-zero-on-fix]
|
|
types_or: [python, pyi]
|
|
files: ^scripts/
|
|
- id: ruff-format
|
|
name: ruff-format
|
|
types_or: [python, pyi]
|
|
files: ^scripts/
|
|
|
|
# Bandit - Security linter
|
|
- repo: https://github.com/PyCQA/bandit
|
|
rev: 1.7.10
|
|
hooks:
|
|
- id: bandit
|
|
name: bandit-security
|
|
args: [-c, scripts/pyproject.toml]
|
|
additional_dependencies: ["bandit[toml]"]
|
|
types: [python]
|
|
files: ^scripts/
|
|
exclude: ^scripts/tests/
|
|
|
|
# Standard pre-commit hooks
|
|
- repo: https://github.com/pre-commit/pre-commit-hooks
|
|
rev: v5.0.0
|
|
hooks:
|
|
- id: check-yaml
|
|
name: check-yaml
|
|
args: [--allow-multiple-documents]
|
|
- id: check-toml
|
|
name: check-toml
|
|
- id: end-of-file-fixer
|
|
name: fix-end-of-file
|
|
- id: trailing-whitespace
|
|
name: fix-trailing-whitespace
|
|
- id: check-added-large-files
|
|
name: check-large-files
|
|
args: [--maxkb=1000]
|
|
- id: check-merge-conflict
|
|
name: check-merge-conflict
|
|
|
|
# mypy - Type checking
|
|
- repo: https://github.com/pre-commit/mirrors-mypy
|
|
rev: v1.13.0
|
|
hooks:
|
|
- id: mypy
|
|
name: mypy-type-check
|
|
args: [--config-file, scripts/pyproject.toml]
|
|
files: ^scripts/
|
|
exclude: ^scripts/tests/
|
|
additional_dependencies:
|
|
- types-Markdown
|
|
|
|
# Local doc quality hooks (mirrors CI checks — CI is a 2nd pass of these)
|
|
- repo: local
|
|
hooks:
|
|
- id: markdown-lint
|
|
name: markdown-lint
|
|
language: node
|
|
entry: markdownlint
|
|
args: ['--ignore', 'node_modules', '--ignore', '.venv', '--config', '.markdownlint.json']
|
|
types: [markdown]
|
|
additional_dependencies: ['markdownlint-cli']
|
|
|
|
- id: cross-references
|
|
name: cross-references
|
|
language: system
|
|
entry: python scripts/check_cross_references.py
|
|
pass_filenames: false
|
|
types: [markdown]
|
|
|
|
- id: mermaid
|
|
name: mermaid-syntax
|
|
language: system
|
|
entry: python scripts/check_mermaid.py
|
|
pass_filenames: false
|
|
types: [markdown]
|
|
verbose: true
|
|
|
|
- id: link-check
|
|
name: link-check
|
|
language: system
|
|
entry: python scripts/check_links.py
|
|
pass_filenames: false
|
|
types: [markdown]
|
|
verbose: true
|
|
|
|
- id: markdown-rendering
|
|
name: markdown-rendering
|
|
language: system
|
|
entry: python scripts/check_markdown_rendering.py
|
|
pass_filenames: false
|
|
types: [markdown]
|
|
|
|
- id: build-epub
|
|
name: build-epub
|
|
language: system
|
|
entry: uv run scripts/build_epub.py
|
|
pass_filenames: false
|
|
files: ^(.*\.md|scripts/build_epub\.py)$
|
|
|
|
# Vietnamese documentation checks
|
|
- repo: local
|
|
hooks:
|
|
- id: vietnamese-markdown-lint
|
|
name: vietnamese-markdown-lint
|
|
language: node
|
|
entry: markdownlint
|
|
args: ['--ignore', 'node_modules', '--ignore', '.venv', '--config', '.markdownlint.json']
|
|
files: ^vi/.*\.md$
|
|
additional_dependencies: ['markdownlint-cli']
|
|
|
|
- id: vietnamese-cross-references
|
|
name: vietnamese-cross-references
|
|
language: system
|
|
entry: python scripts/check_cross_references.py --lang vi
|
|
pass_filenames: false
|
|
files: ^vi/.*\.md$
|
|
|
|
- id: vietnamese-mermaid
|
|
name: vietnamese-mermaid-syntax
|
|
language: system
|
|
entry: python scripts/check_mermaid.py
|
|
pass_filenames: false
|
|
files: ^vi/.*\.md$
|
|
verbose: true
|
|
|
|
- id: vietnamese-link-check
|
|
name: vietnamese-link-check
|
|
language: system
|
|
entry: python scripts/check_links.py
|
|
pass_filenames: false
|
|
files: ^vi/.*\.md$
|
|
verbose: true
|
|
|
|
- id: vietnamese-build-epub
|
|
name: vietnamese-build-epub
|
|
language: system
|
|
entry: uv run scripts/build_epub.py --lang vi
|
|
pass_filenames: false
|
|
files: ^(vi/.*\.md|scripts/build_epub\.py)$
|
|
|
|
# Japanese documentation checks
|
|
- repo: local
|
|
hooks:
|
|
- id: japanese-markdown-lint
|
|
name: japanese-markdown-lint
|
|
language: node
|
|
entry: markdownlint
|
|
args: ['--ignore', 'node_modules', '--ignore', '.venv', '--config', '.markdownlint.json']
|
|
files: ^ja/.*\.md$
|
|
additional_dependencies: ['markdownlint-cli']
|
|
|
|
- id: japanese-cross-references
|
|
name: japanese-cross-references
|
|
language: system
|
|
entry: python scripts/check_cross_references.py
|
|
pass_filenames: false
|
|
files: ^ja/.*\.md$
|
|
|
|
- id: japanese-mermaid
|
|
name: japanese-mermaid-syntax
|
|
language: system
|
|
entry: python scripts/check_mermaid.py
|
|
pass_filenames: false
|
|
files: ^ja/.*\.md$
|
|
verbose: true
|
|
|
|
- id: japanese-link-check
|
|
name: japanese-link-check
|
|
language: system
|
|
entry: python scripts/check_links.py
|
|
pass_filenames: false
|
|
files: ^ja/.*\.md$
|
|
verbose: true
|
|
|
|
- id: japanese-build-epub
|
|
name: japanese-build-epub
|
|
language: system
|
|
entry: uv run scripts/build_epub.py --lang ja
|
|
pass_filenames: false
|
|
files: ^(ja/.*\.md|scripts/build_epub\.py)$
|