3 Commits

Include renames

Author	SHA1	Message	Date
Luong NGUYEN	4f5703855c	feat(website): add landing page with interactive learning roadmap (#185) ... * feat(website): add landing page with interactive learning roadmap The site home was the rendered README, which neither sells the guide nor helps learners track where they are. The new landing page explains the value vs the official docs and turns the curriculum into a checklist roadmap (10 modules, 60 lessons) with progress saved in localStorage. - README now renders to guide.html; landing is index.html (English only, since translated anchors differ) - roadmap.json is validated at build time: every lesson heading must resolve to an anchor, so doc drift fails the build - light/dark theme toggle shared with the docs pages - vendor Fraunces + Manrope; font CSS cache keyed on the request URL - pin build_website.py PEP 723 deps to requirements.txt: markdown 3.11 mis-parses `</dev/tty>` in a code span and silently truncated the rendered hooks page * fix(website): address landing page review findings	2026-09-26 13:14:55 +02:00
Luong NGUYEN	4f3fa85d7e	docs: follow-ups from the v2.1.220 accuracy review (#161) ... * fix(ci): move the EPUB build out of pre-commit into CI The build-epub hooks called scripts/build_epub.py, which raises when the mmdc binary is missing, while check_mermaid.py skips with a warning in the same situation. On arm64 — where @mermaid-js/mermaid-cli has no working build — that made 'pre-commit run --all-files' impossible to satisfy for a docs-only change without --no-verify. Remove the build-epub, vietnamese-build-epub and japanese-build-epub hooks and widen the CI build-epub job to a language matrix so PR-time coverage is not reduced: it previously built en only, and now builds en, vi, zh and ja. zh was covered by neither the hooks nor this job, so a broken zh diagram could only surface at release time. Closes #156 * docs: replace the stale Kroki narrative with local mmdc rendering Commit e76bbe4 swapped the Kroki HTTP dependency for local mmdc rendering but left the docs describing the old design. The claim appeared in seven live files, not the two originally reported: CLAUDE.md, scripts/README.md and their ja/uk/vi copies. Also corrects what the same staleness dragged along: - scripts/README.md documented --timeout and --max-concurrent, which no longer exist, and omitted --mmdc-path, --lang and --puppeteer-config - 'Async concurrent fetching' described a render_all() that is now a plain sequential loop with a dedupe cache - the network-error/rate-limiting troubleshooting entries are replaced with the failures that actually occur now (missing mmdc, Chromium sandbox) CHANGELOG entries recording the Kroki-to-mmdc switch are left alone; they describe the past accurately. Closes #157 * fix(scripts): make the ruff config match files that exist Ruff resolves include/per-file-ignores patterns relative to the directory holding pyproject.toml. Since the config lives in scripts/, the pattern "scripts/**/*.py" meant scripts/scripts/**/*.py, which matches nothing — 'ruff check scripts/' printed 'warning: No Python files found under the given path(s)' and then 'All checks passed!'. per-file-ignores had the same mistake. Both are now relative to scripts/, so ruff sees all 14 files. This silently disabled the pre-commit ruff hooks too, not just the documented command, and two test files had drifted out of format as a result. Reformatting them exposed a second problem: the pre-commit hook pinned ruff v0.8.2 while the CI lint job installs unpinned latest and this venv has 0.15.10. The versions disagree on formatting, so each reverted the other's output, and CI would have started failing on a file the local hook kept rewriting. Bump the hook pin and the requirements-dev floor to 0.15.10 so all three agree. Verified: 'pre-commit run --all-files' is stable across consecutive runs, 'ruff format --check scripts/' and 'ruff check scripts/' both pass, 92 tests pass. Closes #160 * docs: point localized module links at their own trees Files at the root of a language directory used ../NN-module/, which from uk/CATALOG.md resolves to the English 05-mcp/ at the repo root rather than uk/05-mcp/. Readers following a count stated about the localized tree landed in the English one. The link checker never caught it because the English target does exist. Files one level deeper (uk/04-subagents/README.md and friends) were already correct — ../06-hooks/ from there resolves to uk/06-hooks/ — so this is scoped to the 7 depth-1 files that actually escape: CATALOG.md in uk, vi, ja and zh, LEARNING-ROADMAP.md in uk and vi, and ja/claude_concepts_guide.md. 119 links in total. The ../NN- occurrences left in STYLE_GUIDE.md and TRANSLATION_NOTES.md are inside fenced examples showing what a module page should contain, where the ../ form is the correct convention. All 119 rewritten targets were verified to exist. Closes #158 * docs(hooks): stop conflating hook types with hook event categories '**Hook Types** (5 types, 31 events)' sat above four bullets, so the count read as wrong. It was not — the two numbers describe different axes that had been merged into one label. 06-hooks/README.md:126 documents five hook *types*: command, http, prompt, mcp_tool and agent. Those describe how a hook runs. The four bullets are event *categories* — Tool, Session, Task, Lifecycle — holding 31 events (6+7+6+12), and describe when it runs. Split the label so each number belongs to the axis it counts, in all nine affected files: README.md and INDEX.md plus the ja, uk, vi and zh copies. QUICK_REFERENCE.md and LEARNING-ROADMAP.md already stated '5 types' with the handler names attached and needed no change. Closes #159 * chore(scripts): drop the unused httpx dependency httpx was the HTTP client for Kroki rendering. Nothing has imported it since e76bbe4 moved diagram rendering to a local mmdc subprocess — check_links.py, the only other network caller, uses stdlib urllib.request. The PEP 723 blocks in build_epub.py and build_website.py had already dropped it; only the manifests and docs still declared it. Removes it from requirements.txt, pyproject.toml dependencies, the dependency tables and uv --with lines in scripts/README.md and its ja/uk copies, and the .cspell.json word list. Also drops the B113 bandit suppression, which existed solely for an httpx timeout false positive — bandit reports no issues without it. Also corrects two Requirements lines missed in the previous pass: the ja and uk script READMEs still listed an internet connection rather than mmdc. Note: tenacity is now dead for the same reason and is left in place. * chore(scripts): drop the unused tenacity dependency Nothing imports tenacity — the retry logic it was added for went away with the Kroki HTTP fetching in e76bbe4. It was still declared in requirements.txt, pyproject.toml, both `uv run --with` lines and all three dependency tables. * docs(i18n): sync the localized pre-commit check lists The ja/uk/vi CLAUDE.md files still listed build-epub as pre-commit check #5, stale since 6da8184 moved the EPUB build to CI. They also omitted markdown-rendering, and the ja/uk stated counts disagreed with their own lists. Now matches the English CLAUDE.md. * fix(scripts): silence PLR0917 now stable in ruff 0.16 CI installs the latest ruff (uv pip install ruff, unpinned), and 0.16.1 promoted too-many-positional-arguments from preview to stable, hard-failing the Code Quality check on build_epub.py's long-signature draw/helper functions. These sit in the same family as PLR0913, which is already ignored. Add PLR0917 so the local 0.15.10 pin and unpinned CI lint agree again.	2026-08-06 07:58:46 +07:00
Luong NGUYEN	3557d791f5	feat(scripts): add static website generator from markdown sources (#85) (#121) ... * 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)	2026-05-15 08:55:29 +02:00