Repository Guidelines

Project Structure & Module Organization

This repository is a Jekyll blog. Root pages such as index.md, essays.md, and 404.html define top-level routes. Posts live in _posts/ and must follow YYYY-MM-DD-title.md. Shared templates are in _layouts/, reusable partials in _includes/, and site styling/images in assets/css/ and assets/images/. Site metadata, plugins, and output rules are configured in _config.yml.

Build, Test, and Development Commands

• bundle install: install Ruby gems from Gemfile.
• bundle exec jekyll serve: run the local site at http://localhost:4000 with live reload.
• bundle exec jekyll build: generate the production site into _site/ and catch build-time errors before pushing.
• bundle update: refresh gem versions when local Jekyll setup breaks.

Coding Style & Naming Conventions

Use Markdown with YAML front matter for pages and posts. Follow existing indentation: 4 spaces in HTML/CSS, concise front matter keys, and lowercase hyphenated filenames for posts. Keep layouts and includes minimal and reuse Jekyll filters such as relative_url for internal links. In CSS, prefer the existing custom properties in :root and extend current typography/spacing patterns instead of introducing one-off styles.

Testing Guidelines

There is no automated test suite in this repository. Validation is done by building and previewing the site locally:

• bundle exec jekyll build
• bundle exec jekyll serve

Before opening a PR, confirm that new posts render correctly, internal links resolve, and navigation/footer changes work on both desktop and mobile widths.

Commit & Pull Request Guidelines

Recent commits use short, imperative subjects such as Fix escaping in site title... and Update header formatting.... Keep commit titles brief, present tense, and specific; avoid vague messages like Minor Change when the scope is known.

Pull requests should include:

• a short summary of content or template changes
• linked issue/context when applicable
• screenshots for visible layout or typography updates
• confirmation that bundle exec jekyll build succeeded locally

Content Notes

Posts usually include layout, title, date, categories, and excerpt. Example:

_posts/2026-03-20-well-that-didnt-happen.md

Use tags: [favorite] only when the post should appear in the homepage favorites list.

Writing Style Guide

When writing new blog posts, use index.md as the primary style reference. It explains the voice of the site more clearly than any individual post. The recent post _posts/2026-03-20-well-that-didnt-happen.md can be used as a secondary reference for how that voice should sound in a longer essay.

The writing voice should be:

• simple, direct, and reflective
• minimal, with short paragraphs and plain words
• human and opinionated, not polished into generic internet prose
• explanatory without sounding academic or over-structured
• willing to use emphasis through short sentences and contrast

The writing should avoid:

• AI-sounding transitions and filler
• corporate, motivational, or self-help jargon
• overly long essays unless explicitly requested
• complex vocabulary where simpler wording works
• list-heavy structure unless the topic genuinely needs it

When drafting posts:

• start from a simple observation from everyday life
• break the idea down so it feels easy to follow
• prefer a few strong paragraphs over many sections
• keep the tone conversational, but not sloppy
• let the conclusion land in a simple, memorable line

When using external sources:

• use them to support or sharpen the thought, not to dominate it
• paraphrase more than quote
• prefer linking inline inside the prose instead of adding a large references section
• keep the post feeling like a personal reflection, not a literature review

For new posts in _posts/:

• follow YYYY-MM-DD-title.md
• use lowercase hyphenated slugs
• include front matter with layout: post, title, date, categories, and excerpt
• keep categories simple and sparse unless the post clearly needs more