AGENTS.md

This file provides guidance to AI agents when working with blog/writings/content in this repository.

Development Commands

Using justfile (requires Just task runner):

  • just serve - Start dev server with drafts and live reload
  • just write "Title" - Create new draft post
  • just publishPage - Publish a draft (uses fzf for interactive selection)
  • just publishToGitHub - Push to GitHub
  • just tags - List all tags used in posts

Direct Jekyll commands:

  • bundle exec jekyll serve --drafts --open-url --livereload - Start dev server
  • bundle exec jekyll draft "Title" - Create new draft
  • bundle exec jekyll publish _drafts/filename.md - Publish a draft

Some important operations with the blog:

  • Use just write "Title" to create a draft post and edit the file
  • Use just tags to see what are existing tags. Refrain from adding new tags. If there’s genuine use for a new tag, ask me.
  • Use bundle exec jekyll publish _drafts/filename.md to publish a draft

Git Commit Style

For new posts, just use Write (one word)

Architecture

Jekyll static site with Minima theme, deployed via GitHub Pages.

  • _posts/ - Published blog posts (YYYY-MM-DD-title.markdown naming)
  • _drafts/ - Unpublished draft posts
  • _layouts/ - Custom Jekyll templates
  • _includes/ - Reusable template components (header, footer, head)
  • _config.yml - Jekyll configuration

GitHub Pages automatically builds and deploys on push to main branch.

URL scheme is /:title/ (no dates). For example, _posts/2024-08-13-how-i-use-tmux.md becomes /how-i-use-tmux/ unless there is permalink in frontmatter for that post.

To find and copy theme files for customization: bundle info --path minima

Writing Style

Voice: Direct, first-person, conversational but technical. Uses “I” extensively. States opinions clearly without hedging.

Structure:

  • Opens with 1-2 sentences establishing context or the problem being solved
  • Gets to the point quickly—no lengthy introductions
  • Uses headers to break up longer posts — headers should be descriptive and state the point directly, not clever or cryptic
  • Includes code snippets, configs, and shell commands liberally
  • Ends simply—often just stops after the content, occasionally with “Have fun!” or a brief call for feedback
  • Uses footnotes for asides and tangential details

Tone:

  • Practical and solution-focused—shows the journey from problem to solution
  • Casual phrases: “kick the tires”, “Who knows why”, “it’s a steal”
  • Light humor, sometimes self-deprecating: “I joke that I’m paying it to do what I love while I do what I don’t like to do”
  • No fluff or padding—respects reader’s time

Technical content:

  • Heavy on working code examples—actual snippets, not pseudocode
  • Includes specific numbers when relevant ($75/hour, 10k monthly expenses, $100/month)
  • References previous posts when building on past topics
  • Explains decisions and trade-offs: “The key decisions I made here…”

Formatting patterns:

  • Dashes and parentheticals for inline context
  • Bold for emphasis on key terms
  • Bullet points for lists of features or steps
  • Code blocks with language hints (typescript,bash, ```yaml)

What to avoid:

  • Excessive introductions or conclusions
  • Marketing-speak or hype
  • Overly formal language
  • Generic advice without specific examples
  • Emoticons or emoji (e.g., :P, :), etc.)
  • Abstract metaphors — be concrete and specific instead
  • Implementation details that aren’t directly relevant to the point

Tools & Commands

Image Tools

Use /Applications/ImageOptim.app/Contents/MacOS/ImageOptim <filenames> to optimize images