Skip to content

AGENTS.md

Latest commit

 

History

History
183 lines (138 loc) · 4.62 KB

AGENTS.md

File metadata and controls

183 lines (138 loc) · 4.62 KB

AGENTS.md - Coding Guidelines for Joel Cano's Website

This is a Jekyll-based personal blog hosted on GitHub Pages using the Minimal Mistakes theme.

Build Commands

# Install dependencies
bundle install

# Serve locally (auto-regenerates on changes)
bundle exec jekyll serve

# Serve with drafts and future posts
bundle exec jekyll serve --drafts --future

# Build site (outputs to _site/)
bundle exec jekyll build

# Build for production
JEKYLL_ENV=production bundle exec jekyll build

# Clean build cache
bundle exec jekyll clean

Project Structure

├── _config.yml           # Site configuration
├── _data/navigation.yml  # Navigation menu
├── _pages/               # Static pages (About, 404, archives)
├── _posts/               # Blog posts (YYYY-MM-DD-title.markdown)
├── assets/css/main.scss  # Custom styles
├── index.markdown        # Homepage
└── Gemfile               # Ruby dependencies

Content Creation Guidelines

New Blog Posts

Create files in _posts/ following naming convention: YYYY-MM-DD-title.markdown

Required front matter:

---
title: "Your Post Title"
date: YYYY-MM-DD
---

Optional front matter:

categories: [category1, category2]  # Use for broad topics
tags: [tag1, tag2, tag3]            # Use for specific keywords
excerpt: "Short description"
toc: true                           # Enable table of contents
toc_label: "Contents"
toc_icon: "rocket"
header:
  overlay_color: "#333"
  overlay_filter: "0.5"

New Pages

Create in _pages/ or root directory with front matter:

---
layout: single
title: "Page Title"
permalink: /custom-path/
author_profile: true
classes: wide
toc: true
---

Navigation

Update _data/navigation.yml to add menu items:

main:
  - title: "Page Name"
    url: /permalink/

Code Style Guidelines

Markdown

  • Use ATX-style headers (#, ##) not Setext
  • Indent lists with 2 spaces
  • Use fenced code blocks with language specifiers
  • Include blank lines around block elements
  • Prefer reference-style links for repeated URLs

YAML (Front Matter & Config)

  • Use 2-space indentation
  • Quote strings with special characters
  • Use arrays for lists: [item1, item2]
  • Follow existing _config.yml structure

SCSS/CSS

  • Located in assets/css/main.scss
  • Import theme first, then add custom styles
  • Use CSS variables from theme: var(--primary-color)
  • Group related styles together
  • Include responsive breakpoints with @media
  • Prefer rem and em over pixels for sizing

Naming Conventions

  • Posts: YYYY-MM-DD-kebab-case-title.markdown
  • Categories: lowercase, hyphenated (e.g., web-development)
  • Tags: lowercase, hyphenated (e.g., javascript, best-practices)
  • Files: kebab-case for multi-word names
  • Images: descriptive-kebab-case.jpg in /assets/images/

Configuration Standards

_config.yml

  • Maintain existing structure and comments
  • Update author section for bio/social changes
  • Test changes locally (requires restart)
  • Keep sensitive data out (no API keys)

Plugins

Available plugins (in Gemfile):

  • github-pages - GitHub Pages compatibility
  • jekyll-feed - RSS feed
  • jekyll-include-cache - Performance
  • jekyll-paginate - Post pagination
  • jekyll-sitemap - XML sitemap
  • jekyll-gist - Embed gists
  • jemoji - Emoji support

Error Handling & Validation

Before Committing

  1. Test locally: bundle exec jekyll serve
  2. Check for YAML syntax errors in front matter
  3. Verify all internal links work
  4. Ensure images exist in /assets/images/
  5. Review in both desktop and mobile widths

Common Issues

  • YAML errors: Check indentation and special characters
  • Build failures: Run bundle exec jekyll clean then rebuild
  • Missing pages: Verify permalink in front matter
  • Style not applying: Check SCSS syntax, restart server

Deployment

  • Auto-deploys on push to master branch
  • Uses GitHub Pages with github-pages gem
  • Production URL: https://canito0890.github.io
  • Build output goes to _site/ (gitignored)

Theme Information

Copilot Instructions (Preserved)

This project has .github/copilot-instructions.md with detailed guidance on:

  • Architecture and key components
  • Development workflow
  • Content creation patterns
  • Theme customization
  • Archive and navigation setup

Refer to that file for comprehensive project context.