Added copilot instructions, AGENTS.md, improved README files (#3486 )

This pull request introduces several documentation improvements and adds
comprehensive Copilot and agent instruction files to the al-folio
repository. The most significant changes are the addition of
repository-wide and path-specific Copilot instructions, updates to agent
documentation to reference these instructions, and improvements to the
documentation structure and clarity regarding file purposes and
workflows.

**Copilot and Agent Instruction Enhancements:**

- Added a new `.github/copilot-instructions.md` file providing detailed,
repository-wide setup, build, CI/CD, troubleshooting, and file format
guidance for Copilot coding agents.
- Introduced `.github/instructions/bibtex-bibliography.instructions.md`
with specific instructions for editing and validating BibTeX files,
including custom keywords, formatting rules, and integration with
Jekyll-Scholar.
- Updated agent documentation files (`customize.agent.md`,
`docs.agent.md`) to reference the new Copilot instruction files and
explain their purpose and usage for both repository-wide and
path-specific scenarios.
[[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L57-R65)
[[2]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L107-R122)
[[3]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L49-R51)
[[4]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L106-R137)

**Documentation Structure and Clarity Improvements:**

- Clarified and reorganized the documentation file list in agent files,
removing references to deprecated or merged files (e.g.,
`MAINTENANCE.md`, `ACCESSIBILITY.md`) and updating descriptions to
reflect current usage.
[[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L57-R65)
[[2]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L21-R21)
[[3]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L106-R137)
- Enhanced documentation on the purpose and application of each
documentation file, and added detailed explanations of Copilot
instruction files and their role in project development.

**Workflow and Validation Updates:**

- Updated references and descriptions for GitHub Actions workflows in
agent documentation to include the Copilot environment setup and clarify
pre-commit and CI/CD requirements.
[[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L57-R65)
[[2]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L49-R51)
- Corrected references for accessibility guidance, now directing users
to `TROUBLESHOOTING.md` instead of the removed `ACCESSIBILITY.md`.

These changes collectively improve the onboarding experience for both
human contributors and AI agents, ensuring consistent adherence to
project conventions and reducing errors.

**References:**  

[[1]](diffhunk://#diff-227c2c26cb2ee0ce0f46a320fc48fbcbdf21801a57f59161b1d0861e8aad55f5R1-R253)
[[2]](diffhunk://#diff-6fd2827fb8d9c2dd6dc973572201853487ecbbd1120b00425d4f1c21dfdcf35fR1-R174)
[[3]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L57-R65)
[[4]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L107-R122)
[[5]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L550-R562)
[[6]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L21-R21)
[[7]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L49-R51)
[[8]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L106-R137)

---------

Signed-off-by: George Araújo <george.gcac@gmail.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

2026-01-28 22:55:05 -03:00

4.8 KiB

Raw Blame History

Agent Guidelines for al-folio

This is a hub for AI agents and automation tools working with the al-folio repository. It directs you to specialized resources by role and task type.

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)

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

# Rebuild with updated dependencies
docker compose up --build

# Stop containers
docker compose down

Pre-Commit Checklist

# 1. Format code
npm install --save-dev prettier @shopify/prettier-plugin-liquid  # (first time only)
npx prettier . --write

# 2. Build locally
docker compose up --build

# 3. Verify site
# → Visit http://localhost:8080 and check navigation, pages, images, dark mode

# 4. Commit with clear message
git add .
git commit -m "type: description"  # See "Commit Format" below

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"

Common Issues

For troubleshooting common build, deployment, and configuration issues, see:

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

Commit Format

<type>: <subject>

<body (optional)>

Types: feat (feature), fix (bug), docs (docs), style (formatting), config (configuration), chore (maintenance)

Examples:

feat: Add dark mode toggle button to header
fix: Correct baseurl in project site configuration
docs: Update INSTALL.md with Docker troubleshooting
style: Format all Liquid templates with Prettier
config: Enable blog section in _config.yml
chore: Update Jekyll dependencies with bundle update --all

Always git add explicitly – Do not stage everything with git add . unless you're certain of what's being committed. Check git status first.

Code-Specific Instructions

Always 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

Auto-Loaded Context

The following files are automatically available to you in this agent context:

.github/copilot-instructions.md – Primary technical reference
.github/instructions/*.md – Code-specific instruction files (loaded when editing relevant file types)

Other files need to be accessed explicitly.

What NOT to Commit

Always obey .gitignore. It prevents accidental commits of:

Build outputs (_site/, .jekyll-cache/, etc.)
Dependencies (node_modules/, Gemfile.lock, vendor/)
OS files (.DS_store)
Editor temp files (.idea/, .swp, .swo)
Secrets and API keys (never commit credentials)

If you create new files, ensure they follow the patterns in .gitignore.

4.8 KiB Raw Blame History Unescape Escape