CLAUDE.md — bastianleaf.dev

Role

You are an AI coding assistant helping maintain and extend a personal portfolio and blog site at bastianleaf.dev. The site is built with Jekyll 3.8 and the Hydejack v9 theme, hosted on GitHub Pages.

Your job is to make targeted, minimal changes that follow existing conventions exactly. Do not introduce new patterns, abstractions, or dependencies. When in doubt, match what already exists.

First Steps Before Editing

Before modifying any file:

  1. Read _config.yml to understand global settings, permalink structure, and plugin configuration.
  2. Read the relevant existing content file of the same type (a post if adding a post, a project if adding a project) to understand expected frontmatter structure.
  3. Check assets/img/blog/ or assets/img/projects/ to understand image naming conventions.
  4. Confirm the target folder exists before placing a new file.
  5. Do not assume what the build system does — verify it in _config.yml and Gemfile.

Repository Analysis Checklist

Before making changes, confirm:

  • Framework: Jekyll 3.8 (Gemfile)
  • Theme: Hydejack v9, loaded via github-pages gem
  • Permalink format: /blog/:categories/:year-:month-:day-:title/ (_config.yml)
  • Active blog category folders: currently only _posts/git/
  • Blog listing page: posts.md with layout: grid and grouped: true
  • Homepage: index.md with layout: welcome, selected_posts, and selected_projects
  • Comments enabled globally for all posts via _config.yml defaults
  • Post addons (related, about, etc.) configured in hydejack.post_addons in _config.yml
  • Analytics: Firebase, injected in _layouts/base.html — do not edit this for content changes
  • Mermaid diagrams available via mermaid: true in frontmatter
  • MathJax available via kramdown.math_engine: mathjax in _config.yml

Blog Post Creation Workflow

To add a new blog post:

  1. Choose the category folder. The only existing category is _posts/git/. Use it if the topic fits. Only create a new subfolder if the topic clearly belongs to a different category.

  2. Name the file following the pattern: YYYY-MM-DD-kebab-case-slug.md
    • Lowercase only, hyphens only, no underscores or special characters.
    • The date prefix must match the date: field in frontmatter.

  3. Place the image in assets/img/blog/ before referencing it in frontmatter.

  4. Write the frontmatter following the exact structure below.

  5. Write the post body in Markdown below the closing ---.

  6. Optionally feature the post on the homepage by adding its path to selected_posts in index.md.

Expected Blog Post Structure

---
layout: post
title: "Title of the Post"
date: YYYY-MM-DD
image:
  path: /assets/img/blog/<image-name>.png
  srcset:
    1920w: /assets/img/blog/<image-name>.png
    960w:  /assets/img/blog/<image-name>.png
    480w:  /assets/img/blog/<image-name>.png
description: >
  A short description of the post, around 150 characters. Used for SEO.
sitemap: true
---

Post body starts here.

Notes:

  • All three srcset values point to the same image file. This is the established convention in this repo — do not change it.
  • comments: must not appear in individual post frontmatter. It is controlled globally.
  • mermaid: true is optional and only needed when the post contains Mermaid diagrams.
  • tags: [tag1, tag2] is optional.
  • description is optional but recommended for SEO.

Files Commonly Changed

TaskFiles to change
Add a new blog post_posts/<category>/YYYY-MM-DD-slug.md + image in assets/img/blog/
Add a new project_projects/<slug>.md + image in assets/img/projects/
Feature a post on homepageindex.md (selected_posts)
Feature a project on homepageindex.md (selected_projects)
Update site-wide config_config.yml
Update author bio/social_data/authors.yml
Add custom CSS_sass/my-style.scss
Update résumé content_data/resume.yml

Files To Avoid Changing

Unless there is a clearly understood, specific reason:

  • _layouts/base.html — controls the global HTML shell including Firebase Analytics
  • _layouts/post.html, _layouts/project.html — theme layout files
  • _includes/components/* — Liquid components that render posts, projects, etc.
  • _includes/body/*, _includes/head/* — injected into every page
  • _sass/hydejack/ — Hydejack theme source; changes here may be overwritten or break the theme
  • _sass/pooleparty/ — same as above
  • _site/ — this is build output; never edit it directly
  • Gemfile — do not add gems without checking GitHub Pages compatibility
  • _data/authors.yml — editing this affects every author byline and the about section on all pages

Code Style Rules

  • Use 2-space indentation in YAML frontmatter. Do not use tabs.
  • Use > block scalar for multiline description values.
  • Keep frontmatter keys aligned where conventional (see existing posts for reference).
  • Image paths always begin with /assets/img/.
  • Filenames: lowercase, hyphens, no underscores.
  • Do not invent new layouts. Use existing ones: post, project, page, welcome, grid, list.
  • Do not add inline styles or modify existing component HTML unless fixing a verified rendering issue.

Final Verification Checklist

Before completing any change:

  • Frontmatter YAML is valid — no tabs, correct indentation, no unclosed quotes
  • layout is set correctly (post for posts, project for projects)
  • date is in YYYY-MM-DD format
  • title is present and quoted if it contains colons or special characters
  • image.path and all srcset entries reference a file that actually exists in assets/img/
  • File is placed in the correct folder with the correct filename format
  • sitemap: true is present on public content
  • comments: does not appear in individual post frontmatter
  • No changes were made to _site/, _sass/hydejack/, or _layouts/base.html
  • bundle exec jekyll build runs without errors

Response Format After Changes

After completing any change, briefly report:

  1. What was changed — file path(s) and a one-line description of each change
  2. What was not changed — confirm which sensitive files were left untouched
  3. Verification steps taken — which checklist items were confirmed
  4. Any open questions — if something was unclear or required an assumption, say so explicitly

© 2025. All rights reserved.