AGENTS.md

AGENTS.md

Project Overview

Jekyll static site (personal blog) deployed to GitHub Pages at gdunhao.com. Uses the Minima theme with heavy custom overrides — not a vanilla Minima site.

Architecture

  • Layout chain: All pages use default.html → includes head.html, header.html, footer.html. Content layouts (home.html, post.html, page.html, category.html) extend default and inject sidebar.html via `<aside class="sidebar">
    Gustavo Dunhao

    Gustavo Dunhao

</aside> `.

  • Sidebar-first design: The Minima site-header is hidden with CSS (:has(.home-with-sidebar)) and replaced by a fixed sidebar (_includes/sidebar.html). Every content layout wraps content in div.home-with-sidebar. Do not add layouts without this wrapper or the nav will break.
  • Styling: assets/css/style.scss imports Minima then overrides ~950 lines of custom SCSS. All custom styles live in this single file — there are no partials. The file requires empty front matter (---\n---) for Jekyll to process it.
  • Custom head.html: Loads Font Awesome 6.4 from CDN and links style.css (not main.css). Icons use FA classes like fab fa-github, far fa-calendar.
  • Category system: Posts are grouped into series via category index pages (e.g., java/java26.md, ai/augmenting-llms.md) that use layout: category with permalink and category front matter. The category.html layout filters posts by page.category. To add a new series: create a top-level dir with an index .md, a matching _posts/<topic>/<series>/ subdirectory, and add a nav entry in _includes/sidebar.html.
  • Sidebar nav: Navigation links in _includes/sidebar.html are hardcoded, not generated from data. Category groups use a CSS-only collapsible pattern (<input type="checkbox"> + <label> + :checked sibling selector). When adding a new category series, manually add a sidebar-nav-group block to sidebar.html.

Key Configuration (_config.yml)

Site identity and sidebar content are driven by config values: author.name, bio, avatar, tagline, github_username, twitter_username, linkedin_username. Update these in _config.yml, not in templates. Changes to _config.yml require a server restart.

Development

bundle install                          # install dependencies
bundle exec jekyll serve --livereload   # dev server at localhost:4000
bundle exec jekyll serve --drafts       # include _drafts/ posts
bundle exec jekyll build                # build to _site/

Creating Posts

File: _posts/<topic>/<series>/YYYY-MM-DD-title.markdown (e.g., _posts/java/java26/2026-03-18-java26-http3.markdown). Front matter:

---
layout: post
title: "Title"
date: YYYY-MM-DD HH:MM:SS +0100
categories: topic series
---

Categories use a two-level scheme: the first category is the broad topic (e.g., java, ai) and the second is the series slug (e.g., java26, augmenting-llms). Both must match the category index page’s category front matter for the post to appear in the series listing.

Conventions

  • Layouts always include the sidebar — home.html, post.html, page.html, and category.html all use the home-with-sidebar + sidebar.html pattern. New layouts must follow this.
  • No JavaScript — the site is pure HTML/CSS; avoid adding JS unless explicitly requested. Exception: post.html has a small inline script that opens post-content links in new tabs (target="_blank").
  • Responsive breakpoint: 1024px — sidebar collapses from fixed left column to stacked top section. Maintain this breakpoint in new styles.
  • _site/ is generated output — never edit files there; they are overwritten on build.
  • Deployment: push to main branch triggers GitHub Pages auto-deploy. CNAME file maps the custom domain.