mirror of
https://github.com/luongnv89/claude-howto.git
synced 2026-05-23 10:19:41 +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)
105 lines
2.9 KiB
CSS
105 lines
2.9 KiB
CSS
/* Site-specific styles layered on top of Tailwind. */
|
|
|
|
html {
|
|
font-family: 'Inter', ui-sans-serif, system-ui, sans-serif;
|
|
}
|
|
|
|
code,
|
|
pre,
|
|
kbd,
|
|
samp {
|
|
font-family: 'JetBrains Mono', ui-monospace, monospace;
|
|
}
|
|
|
|
/* Mermaid diagrams: centre and constrain width so they read on mobile. */
|
|
.mermaid {
|
|
background: transparent !important;
|
|
padding: 1rem 0;
|
|
margin: 1.5rem 0;
|
|
text-align: center;
|
|
overflow-x: auto;
|
|
}
|
|
|
|
.mermaid svg {
|
|
max-width: 100%;
|
|
height: auto;
|
|
}
|
|
|
|
/* Prevent prose pre/code from inheriting the Tailwind dark prose background
|
|
which can clash with our slate-900 preference. */
|
|
.prose pre {
|
|
border-radius: 0.5rem;
|
|
padding: 1rem 1.25rem;
|
|
overflow-x: auto;
|
|
line-height: 1.55;
|
|
font-size: 0.875rem;
|
|
}
|
|
|
|
.prose pre code {
|
|
background: transparent;
|
|
padding: 0;
|
|
color: inherit;
|
|
font-size: inherit;
|
|
}
|
|
|
|
/* Inline code gets a softer treatment than fenced blocks. */
|
|
.prose :where(p, li, h1, h2, h3, h4) code {
|
|
font-size: 0.875em;
|
|
font-weight: 500;
|
|
}
|
|
|
|
/* Tables wrap on mobile rather than forcing horizontal scroll on every page. */
|
|
.prose table {
|
|
display: block;
|
|
overflow-x: auto;
|
|
white-space: nowrap;
|
|
}
|
|
|
|
@media (min-width: 768px) {
|
|
.prose table {
|
|
display: table;
|
|
white-space: normal;
|
|
}
|
|
}
|
|
|
|
/* Anchor offset so sticky header doesn't cover heading targets. */
|
|
.prose :where(h1, h2, h3, h4, h5, h6) {
|
|
scroll-margin-top: 6rem;
|
|
}
|
|
|
|
/* Hide focus rings on mouse, keep for keyboard. */
|
|
:focus:not(:focus-visible) {
|
|
outline: none;
|
|
}
|
|
|
|
/* Pygments syntax highlighting (paired with `markdown` codehilite extension). */
|
|
.codehilite { background: transparent; }
|
|
.codehilite .hll { background-color: #ffffcc }
|
|
.codehilite .c, .codehilite .c1, .codehilite .cm { color: #999988; font-style: italic }
|
|
.codehilite .k, .codehilite .kc, .codehilite .kd, .codehilite .kn, .codehilite .kp,
|
|
.codehilite .kr, .codehilite .kt { color: #f0883e; font-weight: 600 }
|
|
.codehilite .s, .codehilite .s1, .codehilite .s2 { color: #a5d6ff }
|
|
.codehilite .nb { color: #79c0ff }
|
|
.codehilite .nf { color: #d2a8ff }
|
|
.codehilite .o, .codehilite .p { color: #ff7b72 }
|
|
.codehilite .m, .codehilite .mi, .codehilite .mf { color: #79c0ff }
|
|
.codehilite .nv, .codehilite .vc, .codehilite .vg, .codehilite .vi { color: #ffa657 }
|
|
.codehilite .err { color: inherit }
|
|
|
|
/* Light-theme readability tweaks for code colours. */
|
|
:root:not(.dark) .codehilite .k,
|
|
:root:not(.dark) .codehilite .kc,
|
|
:root:not(.dark) .codehilite .kd,
|
|
:root:not(.dark) .codehilite .kn,
|
|
:root:not(.dark) .codehilite .kp,
|
|
:root:not(.dark) .codehilite .kr,
|
|
:root:not(.dark) .codehilite .kt { color: #cf222e; }
|
|
:root:not(.dark) .codehilite .s,
|
|
:root:not(.dark) .codehilite .s1,
|
|
:root:not(.dark) .codehilite .s2 { color: #0a3069; }
|
|
:root:not(.dark) .codehilite .nb { color: #0550ae; }
|
|
:root:not(.dark) .codehilite .nf { color: #6f42c1; }
|
|
:root:not(.dark) .codehilite .m,
|
|
:root:not(.dark) .codehilite .mi,
|
|
:root:not(.dark) .codehilite .mf { color: #0550ae; }
|