* 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)
Catches mechanical rendering bugs that look fine in a diff but render
wrong on GitHub / in the EPUB build: inner backticks inside inline-code
spans (PR #114), unescaped pipes in table cells (PR #115), stray
`$ARGUMENTS` outside code, and unmatched fences.
Scope: `**/README.md` across tutorial modules + translations (ja, uk,
vi, zh). Excludes dev tooling dirs (`.claude`, `.venv`, `openspec`, …).
Rule registry: each rule is `(Path, content) -> list[str]`. Adding a
new rule = one function + one registry entry + one test fixture.
- scripts/check_markdown_rendering.py: 4 rules, CommonMark-aware code-
span consumption, blockquote-fence-aware masking
- scripts/tests/test_check_markdown_rendering.py: 20 unit tests,
positive + negative per rule, currency-false-positive guard
- .pre-commit-config.yaml: new global `markdown-rendering` hook
* test(scripts): cover repo-root boundary in check_cross_references
Locks in the boundary behavior added in #91: links resolving outside
the repo root are silently skipped, in-repo broken links still error,
and valid in-repo links still pass.
* test(scripts): cover missing-README detection in numbered lesson dirs
* 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
Luong NGUYEN