CLAUDE.md

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

Project Overview

Jekyll-based static blog deployed to GitHub Pages at sgeos.github.io. The repository is the source for the live site. Pushing to master triggers automatic Jekyll builds and deployment via GitHub Pages.

Common Commands

Preview locally (includes drafts and future-dated posts):

./_preview.sh            # serves at http://localhost:4000/
./_preview.sh 8080       # custom port

Create a new draft:

./_new_draft.sh my-post-slug   # creates _drafts/my-post-slug.markdown from template

Publish a draft (moves from _drafts/ to _posts/ with date prefix from front matter):

./_publish.sh _drafts/my-post-slug.markdown

The publish script extracts the date: field from YAML front matter, stages the file with git add, then uses git mv to rename it into _posts/YYYY-MM-DD-my-post-slug.markdown. It does not commit automatically.

Content Authoring

Posts use Markdown with YAML front matter. The template at _drafts/template.markdown defines the required structure:

---
layout: post
mathjax: false
comments: true
title:  "Post Title"
date:   2026-01-01 00:00:00 +0000
categories:
---
  • Set mathjax: true to enable LaTeX math rendering. Inline math uses $...$ or \(...\).
  • Set comments: true to enable Disqus comments on the post.
  • Published post filenames follow the pattern _posts/YYYY-MM-DD-slug.markdown.
  • Drafts prefixed with hidden. are gitignored and will not be committed.

Architecture

  • Layouts (_layouts/): Three templates. default.html is the base. post.html extends default and adds schema.org metadata, MathJax include, and Disqus comments. page.html is for static pages.
  • Includes (_includes/): Reusable partials for head, header, footer, MathJax loading, Disqus integration, and social icons.
  • Styles (_sass/, css/main.scss): Sass-based styling with separate files for base typography, layout, and syntax highlighting.
  • WASM modules (assets/wasm/): Some posts embed interactive WebAssembly calculators. Each module directory contains .js, .wasm, .d.ts, and package.json files generated by wasm-bindgen from Rust source.

Configuration

_config.yml uses Kramdown for Markdown processing and Rouge for syntax highlighting. The excerpt_separator is set to empty string as a workaround for a Jekyll tag-closing bug. Changes to _config.yml require restarting the Jekyll server.

Documentation

A knowledge graph is maintained in _docs/. Start at _docs/README.md for navigation.

Section Path Description
Writing _docs/writing/ Prose style, post structure, and content conventions
Architecture _docs/architecture/ Jekyll site structure, layouts, and asset integration
Process _docs/process/ Content workflow, communication protocol, and task tracking
Reference _docs/reference/ Glossary and supplementary reference material

Commit Convention

Use scoped conventional commits: <scope>: <imperative summary>. Common scopes: feat, fix, docs, refactor, chore, draft. Include Co-Authored-By: Claude <noreply@anthropic.com> when AI-assisted. See _docs/process/GIT_STRATEGY.md for full details.

The AI agent commits once after all tasks in a prompt are complete, including the REVERSE_PROMPT.md update. PROMPT.md is read-only for the AI agent but must be included in the commit if the human pilot has modified it.

Session Startup Protocol

  1. Read _docs/process/TASKLOG.md for current task state.
  2. Read _docs/process/REVERSE_PROMPT.md for last AI communication.
  3. Wait for human prompt before proceeding.