llms.txt

LLM GUIDANCE NOTES
==================

Repository: Taemin Park — Personal Site & Blog (https://taemincode.github.io)
Purpose: Provide strict guardrails for LLM edits and responses.

Response Checklist
------------------
1. **Follow repository tone** – educational, positive, concise. Avoid first-person unless writing blog content.
2. **Summaries** – describe what changed, reference file paths, note tests or manual verification (if skipped, explain why).
3. **Cite files** – always mention exact files and important line numbers when explaining changes.
4. **Never edit `_site/`** – this directory is build output.
5. **Respect liquid tags** – preserve `{% ... %}` and `{{ ... }}` syntax; do not convert to JSX, Vue, etc.
6. **Keep ASCII** – introduce UTF-8 only when existing content already uses it (e.g., emoji in posts).

Key Files & Roles
-----------------
- `index.html` – Home page sections (hero with email reveal toggle, timeline, snapshot, now, blog preview). Uses Bootstrap grid classes plus custom SCSS hooks; keep the `.hero-email-message` behavior intact and the blog preview fallback that grabs the first inline `<img>` when front matter art is missing. Any new section must reuse existing typography classes defined in `_sass/_about.scss`.
- `blogs.html` – Full blog listing; cards rely on `.blog-card` styles, AOS attributes, and a helper script that wires `data-href`, restores stored AOS attributes, and clears inline transforms. For new filters or sort options, update the loop over `site.posts`, keep the `blog-card-inspiration` overlay fed by `inspired_by`, and adjust `_sass/_blog.scss`. The template mirrors the homepage logic to fall back to the first inline `<img>` when no cover image is set.
- `_layouts/default.html` – Global wrapper: head tags, navbar, footer, MathJax, Bootstrap, AOS, theme toggle, copy buttons, lightbox JS. Changes here affect every page—double-check accessibility attributes.
- `_layouts/post.html` – Post layout with publish/updated logic, categories, previous/next nav. Honor Liquid conditionals when altering metadata blocks.
- `_sass/_variables.scss` – Design tokens. Add new variables here before using raw hex codes. Apply both light and dark theme values.
- `_sass/_about.scss`, `_blog.scss`, `_footer.scss`, `_post.scss`, `_nav.scss` – Section-specific styles. Keep selectors scoped (e.g., `.hero`, `.blog-card`) and rely on variables.
- `assets/css/site.scss` – SCSS entry point plus the mobile/touch override block that neutralizes hover-only flourishes. Import new partials here; keep alphabetical order by topic when adding and mirror the override rules when introducing new hover effects.
- `_includes/responsive-image.html` – Centralized helper that builds `srcset` entries by looking for `*-<width>w` siblings in `site.static_files`. Always pass descriptive `alt`; provide `width`/`height` when the intrinsic size is known.
- `_posts/` – Markdown with YAML front matter. Filenames are `YYYY-MM-DD-slug.md`. Do not change dates unless adjusting publish time intentionally.
- `assets/images/posts/<year>/<slug>/` – Source of WebP derivatives for posts. Keep filenames aligned with the responsive include suffix pattern (`thumbnail.webp`, `thumbnail-480w.webp`, etc.).
- `static/` – Fixed hero/snapshot assets with pre-generated responsive widths (`about-photo-*.webp`). Update the whole set together to preserve `srcset`.
- `manim/` – Source of generated images/animations. Update Python scenes when refreshing assets; never hand-edit renders in `media/`.
- `certificates/` – PDF proofs linked from timeline cards in `index.html`; replace files in place to avoid breaking URLs.
- `README.md` – Contributor docs. Update when workflows or dependencies change.

Theming & Styling Rules
-----------------------
- Use CSS custom properties from `_variables.scss`: `--color-bg`, `--color-text`, `--primary-color`, etc. If a new semantic color is needed, add both light and dark definitions and document usage.
- For responsive tweaks, reuse breakpoints already present (`max-width: 992px`, `768px`, `576px`). Keep mobile-first adjustments consistent across partials.
- Avoid inline styles unless necessary for dynamic Liquid output; prefer adding classes and styling in SCSS.
- When touching `_sass/_about.scss`, note that hero, snapshot, timeline, and “now” modules share spacing conventions. Mirror existing transitions and animation reductions (see mobile/touch overrides in `site.scss`).
- Dark mode logic: selectors include both `@media (prefers-color-scheme: dark)` and `[data-theme="dark"]`. Update both blocks when changing a component.

Liquid & Markdown Conventions
-----------------------------
- Use `{{ site.baseurl }}` when creating absolute asset URLs from Markdown (e.g., `{{ site.baseurl }}/assets/images/...`).
- Prefer `{% include responsive-image.html %}` for inline images; it builds `srcset` automatically when companion `*-<width>w` files exist. Pass `loading`, `width`, or `height` only when you need to override the defaults.
- Front matter keys currently recognized:
  - `layout`, `title`, `date`, `categories`, `tags`, `description`, `thumbnail`, `cover_image`, `image`, `featured_image`, `inspired_by`, `artist_inspiration`, `last_modified_at`, `updated`, `edited`.
  - Use `inspired_by` (or `artist_inspiration`) to populate the “Inspired by …” ribbon on listing cards; keep values short.
  - Additional keys must be consumed by layouts before adding widely.
- Category names in front matter should be lowercase or PascalCase without spaces (e.g., `[ML, Notes]`).
- When embedding HTML inside Markdown posts, wrap with blank lines to avoid parser quirks.
- MathJax inline: `$...$`. Block equations: `$$ ... $$`. Escaping underscores may be required (`\\_`) when writing plain text.

JavaScript Specifics
--------------------
- `default.html` includes:
  - Theme toggle code manipulating `localStorage` and `<html data-theme>`.
  - On-scroll navbar class toggling; maintain the `handleScroll` threshold (50px) unless UX change is intentional.
  - AOS initialization with custom `disable` logic (prefers-reduced-motion, small screens, touch/coarse pointers). Respect this when extending animations.
  - Code-copy enhancement for `.markdown pre`: maintain `code-copy-btn` structure and accessible labels.
  - Image lightbox limited to descendants of `.post-content`; only intercept `<img>` clicks when you need lightbox behavior.
- `index.html` hero email button toggles `aria-expanded`/`aria-pressed` and reveals `#hero-email-message`; keep the keyboard handlers and message span synced with the icon list.
- `blogs.html` attaches listeners to `.blog-card[data-href]` so cards respond to click or Enter/Space, replays AOS animations, and clears inline transforms; it also caches/restores AOS attributes when reduced motion disables animations. Keep data attributes and script logic aligned.
- `404.html` script:
  - Provides `window.ROCKET_CONFIG`, `window.setRocketExitOffset`, `window.setRocketExitMode`. Adjust rocket flight through these helpers. Keep reduced-motion fallback intact.

Content Creation Rules
----------------------
- Blog posts:
  - Write introductions with emoji headings (e.g., `## 📌 Introduction`) if consistent with current style.
  - Include at least one image or diagram when referencing data/visuals. Place supporting images in `assets/images/posts/<year>/<slug>/` alongside the `*-<width>w.webp` variants that power `responsive-image.html`.
  - Generate responsive image sets as WebP derivatives (e.g., `thumbnail.webp`, `thumbnail-480w.webp`, `thumbnail-768w.webp`). The include wires `srcset` automatically; keep a fallback format only when required by the template.
  - Always ship meaningful `alt` text. `responsive-image.html` defaults to `loading="lazy"`; add `width`/`height` attributes when you know the intrinsic dimensions to minimize layout shift.
  - For tutorials, code blocks should include language hints (```` ```python ````). `rouge` handles highlighting.
  - Add `last_modified_at` when editing existing posts to surface “Updated” badge.
  - Populate `inspired_by` (or `artist_inspiration`) to credit artwork on listing cards; omit when not applicable.
  - Use callouts with blockquotes and `ℹ️`/`⚠️` emoji for tips/warnings as seen in existing posts.
- Landing page content:
  - Timeline entries follow the markup in `index.html`: `.timeline-entry` with `.timeline-marker` (year/dot) and `.timeline-card` content. Keep chronological order descending.
  - The “Now” section items use `.now-item` with `<i class="fas ...">`. Choose icons available in Font Awesome 6.5.2.
  - The hero email icon reveals a contact message via `.hero-email-message`; preserve `role`, `aria-expanded`, and `aria-pressed` when modifying the social list.

Accessibility & UX
------------------
- Maintain `aria-label`, `aria-pressed`, `role`, `tabindex`, and keyboard handlers already present.
- Any new interactive element must support keyboard activation (Enter/Space) and respond to reduced-motion preferences where animations are introduced.
- Focus states should be visible. Use `outline` with `var(--primary-color)` as seen in existing components.
- When linking out, set `target="_blank"` and `rel="noopener noreferrer"` consistently (see hero social links example).
- `.blog-card` elements depend on `role="link"`, `tabindex="0"`, and JS listeners; keep accessibility attributes in sync with card markup.

Development Workflow
--------------------
- Ruby environment:
  ```
  bundle install
  bundle exec jekyll serve --livereload  # localhost:4000
  bundle exec jekyll build               # outputs to _site/
  ```
- Jekyll plugins currently enabled: `jekyll-feed`, `jekyll-seo-tag`, `jekyll-last-modified-at`, `jekyll-sitemap`. Update `_config.yml` and the README in tandem if you add or remove one.
- Node tooling is not used; avoid introducing npm unless coordinated.
- Manim assets: install dependencies (`brew install cairo pkg-config pango ffmpeg`, create Python venv, `pip install manim`). Render with `manim -pqh <file> <SceneName> --format=png`. Move curated output into `assets/images/posts/...`.

Do / Don’t
----------
- **Do** reuse existing SCSS mixins and patterns; ensure both themes stay legible.
- **Do** add inline comments sparingly when logic is non-obvious (e.g., Liquid condition for post updates).
- **Don’t** rename SCSS classes without updating every template that references them.
- **Don’t** depend on external JS libraries beyond existing CDNs unless added to `default.html` head/body with integrity attributes.
- **Don’t** commit large binaries (videos) unless needed for posts; host heavies on YouTube and embed responsibly.
- **Don’t** hand-edit files inside `vendor/bundle/`; regenerate via Bundler when dependency updates are required.

Reference Docs
--------------
- README.md – contributor workflow, post authoring guide, Manim instructions.
- `_layouts/default.html` & `_layouts/post.html` – inspect before touching global behavior.
- `_sass/_variables.scss` – check when introducing new colors/spacing.
- Existing posts in `_posts/` – copy style conventions.

Keep this file current when processes or conventions change.