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

What this is

A personal technical blog (AkashicMarga) built with Jekyll 4.3 on the minima theme, deployed via GitHub Pages from the main branch. Posts are long-form deep dives into ML systems topics (AI compilers, GPU kernels, speech codecs, speech LMs). Some posts embed custom Manim-rendered animations.

Commands

Requires Homebrew Ruby (4.x) on PATH — macOS system Ruby 2.6 lacks the Bundler 4.0.10 pinned in Gemfile.lock and fails with Could not find 'bundler' (4.0.10): export PATH="/opt/homebrew/opt/ruby/bin:/opt/homebrew/lib/ruby/gems/4.0.0/bin:$PATH"

bundle install                 # install Ruby gem dependencies (first time)
bundle exec jekyll serve --drafts   # also render _drafts/ (Part 4 lives there)
bundle exec jekyll serve       # local dev server with live reload at localhost:4000
bundle exec jekyll serve --future   # include posts dated in the future (config sets future:true already)
bundle exec jekyll build       # build static site into _site/

Animation pipeline (Python + Manim + ffmpeg, only when a post needs new animations):

cd assets/animations
manim -ql <script>.py <SceneClassName>   # render an MP4 (low quality / 480p15)
./convert_to_gif.sh                      # convert all rendered MP4s -> optimized GIFs in assets/images/codec-animations/

Architecture & conventions

  • Content lives in _posts/. Each post is a Markdown file named YYYY-MM-DD-Title-With-Dashes.md with YAML front matter (layout: post, title, date, categories, author, description). Posts default to tag Other unless tags are set (see _config.yml defaults). archive.md auto-groups all posts by tag.

  • Theme is minima (a gem), overridden locally. Only the files that diverge from the gem are present here: _layouts/post.html, and _includes/ (head.html, navlinks.html, sharelinks.html, bitrate_calculator.html). To change site-wide markup/head, edit these overrides — the rest of the theme comes from the installed gem.

  • _includes/head.html wires in the cross-cutting front-end behavior: highlight.js for code blocks, MathJax 3 (LaTeX math via $...$/$$...$$), and DarkReader for automatic dark mode. Kramdown’s own syntax highlighter is disabled in _config.yml in favor of highlight.js.

  • Interactive widgets are HTML+inline-JS includes (e.g. bitrate_calculator.html). Embed in a post with `<div class="bitrate-calculator" style="background:#161b22;border:1px solid #30363d;border-radius:8px;padding:1.5rem;margin:1.5rem 0;font-family:monospace;">

    Bitrate Calculator

    2^10 entries
    Frames / sec
    12.5
    Bits / frame
    80
    Total bitrate
    1.0 kbps
    0.5 kbps3 kbps (phone)128 kbps (MP3)

</div>

`. They use hardcoded GitHub-dark color values to match the DarkReader aesthetic.

  • Animations: source-to-asset flow. assets/animations/*.py are Manim Scene scripts. Rendering with Manim produces intermediates under assets/animations/media/ (gitignored). convert_to_gif.sh then renders the final GIFs into assets/images/codec-animations/, which posts reference via standard Markdown image syntax. The SCENES array in convert_to_gif.sh is the authoritative slug:ClassName mapping — keep it in sync when adding/renaming a scene. Note this script hardcodes absolute paths under /Users/akashsingh/....

  • _site/ is build output and is gitignored along with .jekyll-cache/, assets/animations/media/, and .claude/.

Deployment

GitHub Pages builds from main on push. There is no separate CI/test step — a clean bundle exec jekyll build is the verification. Publishing = committing a post to main.