AGENTS.md

This file contains guidelines for AI assistant (Codex) when working on this Anchorlight Consulting website built with 11ty.

Project Overview

This is a professional consulting website for Chris Mincarelli's Anchorlight Consulting, specializing in AI-powered web development services for Florida Keys businesses. The site features a portfolio, blog with multiple categories (AI, Tech, Business), and service location pages.

Project Stack

• Static Site Generator: Eleventy (11ty) v3.0.0
• CSS Framework: Bootstrap (custom styling with utility classes)
• Plugins:
  • SEO Plugin (eleventy-plugin-seo)
  • Sitemap Generator (@quasibit/eleventy-plugin-sitemap)
  • Syntax Highlighting (@11ty/eleventy-plugin-syntaxhighlight)
  • YouTube Embed (eleventy-plugin-youtube-embed)
  • Schema.org structured data (@quasibit/eleventy-plugin-schema)
• Content Management: Markdown posts in _posts/ with category-based organization
• Testing: Playwright (for responsive verification)

Development Philosophy

Site Structure

/
├── _data/              # Site configuration and data
│   ├── site.json      # Main site configuration
│   ├── seo.js         # SEO configuration
│   ├── floridaKeys.js # Florida Keys location data
│   └── serviceTopics.js # Service categories
├── _includes/         # Reusable components
├── _layouts/          # Page templates
│   ├── base.njk       # Main layout
│   ├── post.njk       # Blog post layout
│   └── service-location.njk # Service location pages
├── _posts/            # Blog content
│   ├── ai/           # AI & Machine Learning posts
│   ├── tech/         # Technology posts
│   └── business/     # Business & Consulting posts
├── assets/           # Static assets (images, CSS, JS)
├── index.njk         # Homepage
├── blog.njk          # Blog listing
├── contact.njk       # Contact page
└── resume.njk        # Resume/About page

Content Strategy

Blog Categories

• AI & Machine Learning: Latest insights on AI integration for small businesses
• Technology: Web development trends and technical insights
• Business & Consulting: Business advice and consulting insights for Florida Keys entrepreneurs

Service Location Pages

• Automatically generated pages for each service + Florida Keys location combination
• SEO-optimized for local search (e.g., "Web Development in Key Largo, FL")

Development Philosophy

CSS and Styling

• Custom Theme: Uses a custom Bootstrap-based theme with brand colors and styling
• Component-Based: Leverages existing design components and utility classes
• Responsive: Mobile-first approach with Bootstrap's responsive grid system

Content Management

• Category-Based: Blog posts organized by topic in subdirectories
• SEO-Optimized: Rich metadata, structured data, and optimized URLs
• Local Focus: Content targets Florida Keys businesses and local market

Build & Development Commands

npm run build    # Build production site
npm run start    # Start development server
npm run dev      # Start development server with watch mode
npm run clean    # Clean build directory

Quality Assurance

• Build Verification: Always run npm run build to ensure site builds successfully
• Content Validation: Verify structured data and SEO metadata render correctly
• Responsive Testing: Test across Bootstrap breakpoints (xs, sm, md, lg, xl, xxl)
• Performance: Optimize images and ensure fast loading for Florida Keys internet speeds

Git Workflow

• Topic Branches: Create a new topic branch for every change request
• Branch Naming: Use descriptive names like feature/update-navbar-colors or fix/mobile-menu-alignment
• Single Purpose: Each branch should address only one specific request
• Clean Commits: Make atomic commits with clear, descriptive messages
• Commit Format: Use conventional commit format:

  type(scope): brief description
  
  Detailed explanation if needed
  

  Types: feat, fix, style, refactor, test, docs, chore
• Branch Cleanup: Delete topic branches after successful merge to keep repository clean

Workflow Guidelines

1. Create Branch: Start with a new topic branch for the request
2. Understand the Request: Clarify exactly what needs to be changed
3. Research Solutions: Check if Bootstrap classes or 11ty plugins can address the need
4. Implement Minimally: Make only the necessary changes
5. Test Thoroughly: Verify functionality and responsive behavior using Playwright MCP
6. Document Changes: Note what was modified and why in commit messages
7. Clean Up: Delete merged topic branch to maintain clean repository

Key Features to Preserve

• Local SEO: Structured data for Florida Keys business listings
• Blog Categories: AI, Tech, and Business post collections
• Service Location Pages: Dynamic location-based service pages
• YouTube Integration: Embedded videos with lite-youtube-embed
• SoundCloud Integration: Audio content embedding
• Contact Forms: Lead generation functionality
• Schema.org Markup: Rich snippets for search results

Content Guidelines

• Target Audience: Small business owners in the Florida Keys
• Tone: Professional but approachable, emphasizing local expertise
• SEO Focus: Local keywords, Florida Keys geographic terms
• Call-to-Actions: Drive consultation requests and project inquiries