AGENTS.md

Agent Guidelines for al-folio

A simple, clean, and responsive Jekyll theme for academics.

Quick Links by Role

• Are you a coding agent? → Read .github/copilot-instructions.md first (tech stack, build, CI/CD, common pitfalls & solutions)
• Customizing the site? → See .github/agents/customize.agent.md
• Writing documentation? → See .github/agents/docs.agent.md
• Need setup/deployment help? → INSTALL.md
• Troubleshooting & FAQ? → TROUBLESHOOTING.md
• Customization & theming? → CUSTOMIZE.md
• Quick 5-min start? → QUICKSTART.md

Essential Commands

Local Development (Docker)

The recommended approach is using Docker.

# Initial setup & start dev server
docker compose pull && docker compose up
# Site runs at http://localhost:8080

# Rebuild after changing dependencies or Dockerfile
docker compose up --build

# Stop containers and free port 8080
docker compose down

Pre-Commit Checklist

Before every commit, you must run these steps:

1. Format Code:

   # (First time only)
   npm install --save-dev prettier @shopify/prettier-plugin-liquid
   # Format all files
   npx prettier . --write

2. Build Locally & Verify:

   # Rebuild the site
   docker compose up --build
   
   # Verify by visiting http://localhost:8080.
   # Check navigation, pages, images, and dark mode.

Critical Configuration

When modifying _config.yml, these must be updated together:

• Personal site: url: https://username.github.io + baseurl: (empty)
• Project site: url: https://username.github.io + baseurl: /repo-name/
• YAML errors: Quote strings with special characters: title: "My: Cool Site"

Development Workflow

• Git & Commits: For commit message format and Git practices, see .github/GIT_WORKFLOW.md.
• Code-Specific Instructions: Consult the relevant instruction file for your code type.

File Type	Instruction File
Markdown content (_posts/, _pages/, etc.)	markdown-content.instructions.md
YAML config (_config.yml, _data/)	yaml-configuration.instructions.md
BibTeX (_bibliography/)	bibtex-bibliography.instructions.md
Liquid templates (_includes/, _layouts/)	liquid-templates.instructions.md
JavaScript (_scripts/)	javascript-scripts.instructions.md

Common Issues

For troubleshooting, see:

• Common Pitfalls & Workarounds in copilot-instructions.md
• TROUBLESHOOTING.md for detailed solutions
• GitHub Issues to search for your specific problem.