25b758805c
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>
120 lines
4.8 KiB
Markdown
120 lines
4.8 KiB
Markdown
# 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`](.github/copilot-instructions.md) first (tech stack, build, CI/CD, common pitfalls & solutions)
|
||
**Customizing the site?** → See [`.github/agents/customize.agent.md`](.github/agents/customize.agent.md)
|
||
**Writing documentation?** → See [`.github/agents/docs.agent.md`](.github/agents/docs.agent.md)
|
||
**Need setup/deployment help?** → [INSTALL.md](INSTALL.md)
|
||
**Troubleshooting & FAQ?** → [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
|
||
**Customization & theming?** → [CUSTOMIZE.md](CUSTOMIZE.md)
|
||
**Quick 5-min start?** → [QUICKSTART.md](QUICKSTART.md)
|
||
|
||
## Essential Commands
|
||
|
||
### Local Development (Docker)
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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](https://github.com/alshedivat/al-folio/blob/master/.github/copilot-instructions.md#common-pitfalls--workarounds) in copilot-instructions.md
|
||
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for detailed solutions
|
||
- [GitHub Issues](https://github.com/alshedivat/al-folio/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](.github/instructions/markdown-content.instructions.md) |
|
||
| YAML config (`_config.yml`, `_data/`) | [yaml-configuration.instructions.md](.github/instructions/yaml-configuration.instructions.md) |
|
||
| BibTeX (`_bibliography/`) | [bibtex-bibliography.instructions.md](.github/instructions/bibtex-bibliography.instructions.md) |
|
||
| Liquid templates (`_includes/`, `_layouts/`) | [liquid-templates.instructions.md](.github/instructions/liquid-templates.instructions.md) |
|
||
| JavaScript (`_scripts/`) | [javascript-scripts.instructions.md](.github/instructions/javascript-scripts.instructions.md) |
|
||
|
||
## Auto-Loaded Context
|
||
|
||
The following files are automatically available to you in this agent context:
|
||
|
||
- [`.github/copilot-instructions.md`](.github/copilot-instructions.md) – Primary technical reference
|
||
- [`.github/instructions/*.md`](.github/instructions/) – Code-specific instruction files (loaded when editing relevant file types)
|
||
|
||
Other files need to be accessed explicitly.
|
||
|
||
## What NOT to Commit
|
||
|
||
**Always obey [`.gitignore`](.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`.
|