Skip to content

CLAUDE.md

Latest commit

 

History

History
106 lines (68 loc) · 7.56 KB

CLAUDE.md

File metadata and controls

106 lines (68 loc) · 7.56 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

A single-file static documentation site (GitBook-style SPA) that explains 13 foundational LLM papers in Vietnamese, ELI5 style. Source PDFs live in docs/, extracted/crafted figures in assets/. Everything ships as one file: index.html — pure HTML+CSS+JS, no framework, no build step. Open with file:// in a browser to run.

See _BUILD_GUIDE.md for the full authoring playbook — it is the canonical guide for adding/editing paper content and must be followed when working on this repo.

Running / previewing

No build, no install, no tests. To view the site:

open index.html              # macOS (file://)
python3 -m http.server 8000  # then open http://localhost:8000 (needed if you hit file:// asset issues)

The only "build" verification is the sanity-check shell snippets below.

Design system

The site uses a "blueprint / technical-manual" aesthetic (modeled on aiengineeringfromscratch.com). Fonts: JetBrains Mono (display headings — bold, UPPERCASE — and all mono labels/eyebrows) + Source Serif 4 (body). VT323 pixel display font is deliberately not used — it can't render Vietnamese diacritics. Palette: cream paper #fafaf5 + ink #1a1a1a + a green accent #1ED760 (the --blueprint token — historically blue, now green), with a deep-navy dark mode; a radial dot-grid texture sits on body. Do not add new CSS — reuse existing classes/tokens for visual + dark-mode consistency.

Architecture of index.html

The whole site is one file, in order:

  1. <head>: Google-Fonts links, a tiny inline theme-init script (reads localStorage["ua-theme"] before paint), then all CSS in one <style> (design tokens, header, reading typography, callouts, figure-card, modal, command palette, 3-col detail layout, reveal animations, responsive).
  2. <body> chrome (static): <a class="skip-link">, a fixed <header class="site-header"> (logo · nav · ⌘K search button · theme toggle), <main id="main"> holding the router target <div id="content"> + <footer>, the #cmdPalette overlay, and the #modalOverlay phase modal. There is no sidebar — the left paper-nav only exists on detail pages and is generated by the router.
  3. <div id="pages" style="display:none"> — contains every page as <div id="page-XXX">…</div> (templates copied into #content on route). Order inside this container does not matter. #page-home is the manual landing (masthead · preface · #statRows · #phasesGrid mục-lục · colophon — the two #… containers are filled by JS).
  4. <script> at the end: NAV array (drives the home mục-lục, the modal, and the detail sidebar) + ORDER (auto-derived, drives prev/next pager) + routing, modal, command-palette, theme, progress, reveal, scrollspy logic.

Navigation flow (mirrors the reference): home mục-lục row → modal listing that paper's pages (with reading-progress chip/bar + per-page done toggles) → click ĐỌC/page → 3-column detail page (.doc: left .doc-side = this paper's pages + "next paper →" link; center .doc-main = content + mark-as-read + pager; right .doc-toc = on-this-page anchors with scrollspy). Reading progress is stored in localStorage["ua-progress"] as {pageId:1}; theme in localStorage["ua-theme"].

Routing: hash-based. #XXX renders #page-XXX into #content (home → manual landing; any id inside a NAV group → detail layout; else → plain .reading). Pager prev/next is generated from ORDER, not DOM order. ⌘K / the header search button opens the command palette over all pages.

Page IDs follow p<number>-<slug> (e.g. p7-overview, p7-glossary). Intro module uses p0-*.

Asset conventions

Images live in assets/ with a per-paper prefix so files don't collide:

Paper Prefix Paper Prefix
01 Attention fig1_, fig2_ 08 CoT cot_
02 GPT-3 g3_ 09 InstructGPT igpt_
03 ResNet rn_ 10 Constitutional AI cai_
04 Scaling Laws sl_ 11 LoRA lora_
05 Chinchilla cc_ 12 QLoRA qlora_
06 FFN KV kv_ 13 GPTQ gptq_
07 ROME rome_

HTML references images by relative path: <img src="assets/rome_fig1_xxx.png">.

Figures sourced from a paper PDF must include "(trích từ paper gốc)" in <figcaption>. Extract via PyMuPDF at 3× scale, thumbnail to 1/3 to estimate crop coordinates, then crop — see _BUILD_GUIDE.md §7 Step 2.

Writing-style invariants (non-negotiable)

  • Vietnamese, ELI5 tone, intuition over math. Keep technical terms in English.
  • Every hard concept → one everyday-life example in a box analogy.
  • Every paper: first page has a TL;DR (box tip), last page has a glossary table + "Đọc gì tiếp theo" linking to the next paper in the curriculum.
  • Cross-link papers when concepts recur (e.g. residuals from Paper 03 reappear in Paper 01/06).

Reusable callout classes: box tip (green, key points/TL;DR), box note (blue, guiding questions), box analogy (purple, everyday examples), box warn (orange, caveats/limitations). Other reusable classes: eyebrow, lead, page-meta, formula, tbl, svgwrap. Page-template skeleton lives in _BUILD_GUIDE.md §6.

Adding a new paper (workflow)

The home mục-lục, the modal, and the detail sidebar are all generated from NAV — there are no per-paper home cards to maintain anymore. To add a paper:

  1. NAV entry: add a {type:"group", num, cat, title, desc, done:true, children:[{id,title}…]} object in NAV (inside the <script>). cat is the category eyebrow (e.g. KIẾN TRÚC), desc shows in the modal header, children are the page ids in reading order.
  2. Insert pages: append <div id="page-p<n>-…"> blocks inside #pages. The stable anchor for Edit is the comment <!-- ===== HOME ===== --> — insert just before it. Split into ~3–4 pages per Edit to keep diffs small.

No home-card / soon / pcard editing is needed (those mechanics were removed in the blueprint redesign). _BUILD_GUIDE.md §7's page-content recipe (figure extraction, TL;DR, glossary) still applies; ignore its sidebar/home-card steps.

Sanity checks after edits

Run from repo root:

# every NAV page id has a matching <div id="page-…">? (empty diff = OK)
comm -23 <(grep -oE '\{id:"(p[0-9]+-[a-z-]+|home)"' index.html | sed 's/{id:"//;s/"//' | sort -u) \
         <(grep -oE 'id="page-(p[0-9]+-[a-z-]+|home)"' index.html | sed 's/id="page-//;s/"//' | sort -u)

# div tags balanced?
echo "open $(grep -o '<div' index.html|wc -l) / close $(grep -o '</div>' index.html|wc -l)"

# exactly one <style>, two <script> (inline theme-init + app)?
echo "style $(grep -o '<style>' index.html|wc -l)  script $(grep -o '<script>' index.html|wc -l)"

# all referenced images exist?
for f in $(grep -o 'assets/[a-z0-9_]*\.png' index.html|sort -u); do
  [ -f "$f" ] && echo "OK $f" || echo "MISSING $f"
done

# JS syntax (extract last <script> → node --check)
python3 -c "import io,re;io.open('/tmp/app.js','w').write(re.findall(r'<script>(.*?)</script>',io.open('index.html').read(),re.S)[-1])" && node --check /tmp/app.js && echo "JS OK"

Known leftover files

assets/page3_full.png and assets/page4_full.png are leftover raw renders from Paper 01 that can't be deleted due to mount permissions. They are not referenced from index.html — leave them alone.

Status

All 13 papers + the intro module (p0-*) are complete (see _BUILD_GUIDE.md §8). When extending or editing, preserve the style invariants above.