Agents Instructions

Repository Context

This is a personal portfolio and blog site hosted on GitHub Pages, built with Jekyll.

Site Architecture

The site uses Jekyll for templating, layouts, and blog post generation. GitHub Pages runs Jekyll natively – there is no custom build workflow for the blog.

Shared Layout System

• _layouts/default.html - Base layout used by every page. Contains the full HTML document structure, shared <head> (fonts, CSS, favicon), nav via {% include header.html %}, and footer via {% include footer.html %}.
• _layouts/post.html - Extends default. Used by blog posts. Contains the post hero section with back link, title, date, and content wrapper.
• _includes/header.html - Shared navigation (logo, nav menu with About, Projects, Skills, Contact, Blog, Web Tools).
• _includes/footer.html - Shared footer (copyright, Support/Privacy/Web Tools links, WakaTime badge).

Blog System

• Source Files: /_posts/ - Markdown files with YAML front matter
• Filename Convention: YYYY-MM-DD-slug-with-hyphens.md (Jekyll standard)
• Front Matter: Each post requires layout: post, title:, and date: in YAML front matter
• Output: Jekyll generates blog post pages automatically based on the permalink setting in _config.yml
• Blog Index: /blog/index.html uses a {% for post in site.posts %} Liquid loop to list all posts

Guidelines for Contributors and AI Assistants

• DO create new blog posts in /_posts/ with proper front matter and filename convention
• DO use the layout: default front matter on all pages, layout: post on blog posts
• DO use {{ ... | relative_url }} filter for all internal asset and page links in layouts/includes
• DO follow the existing CSS class system from css/trailfront.css (page-hero, card, card-grid, section, container, etc.)
• DO NOT create custom build workflows for blog posts – Jekyll handles this natively
• DO NOT manually create HTML blog post files – write markdown in _posts/ with front matter

Blog Post Example

Filename: _posts/2025-12-26-local-gitea-instance.md

---
layout: post
title: "Local Gitea Instance"
date: 2025-12-26
---

Blog post content in markdown here...

Web Tools Build System

The web tools page (/web-tools/index.html) is generated by .github/workflows/build-web-tools.yml:

1. Source: web-tools/tools.jsonc defines the list of tools
2. Template: web-tools/templates/tools-template.html is the Jekyll-compatible page template
3. Build: The workflow replaces TOOLS_PLACEHOLDER in the template with rendered tool cards
4. Output: web-tools/index.html is committed with the rendered tools and Jekyll front matter

• DO edit web-tools/tools.jsonc to add or modify tools
• DO NOT manually edit web-tools/index.html – it will be overwritten by the build workflow
• DO NOT modify the standalone web tool apps in web-tools/note-tool/, web-tools/h3-power-timer/, or web-tools/base64-tools/ – they are self-contained

Site Structure

• / - Main portfolio site (index.html)
• /blog/ - Blog landing page (blog/index.html)
• /_posts/ - Blog post markdown source files
• /_layouts/ - Jekyll layout templates
• /_includes/ - Jekyll shared partials (header, footer)
• /web-tools/ - Web tools landing page
• /web-tools/templates/ - Web tools build template
• /assets/, /css/ - Static assets and stylesheets
• /_config.yml - Jekyll configuration
• /.github/workflows/ - CI/CD automation (web tools build only)

CSS Design System

All pages use css/trailfront.css with a unified class system:

• Layout: .container, .container--narrow, .section, .section-header, .section-title
• Hero: .page-hero, .page-hero--landing, .page-hero--compact, .page-hero--post
• Cards: .card, .card-grid, .card-title, .card-description, .card-tags, .card-date, .card-cta, .card--interactive
• Buttons: .btn, .btn-primary, .btn-secondary
• Tags: .tag
• Utilities: .text-center, .text-muted, .mt-xl, .mb-xl