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>
101 lines
3.2 KiB
Markdown
101 lines
3.2 KiB
Markdown
---
|
||
applyTo: "**/*.liquid"
|
||
---
|
||
|
||
# Liquid Templates Instructions
|
||
|
||
## Liquid Template Basics
|
||
|
||
This al-folio repository uses Liquid templating extensively. When modifying `.liquid` files:
|
||
|
||
### Key Directories
|
||
|
||
- `_includes/` – Reusable template components (imported with `{% include %}`)
|
||
- `_layouts/` – Page layout templates (specified in frontmatter with `layout: name`)
|
||
|
||
### Common Liquid Tags in al-folio
|
||
|
||
- `{% include filename.liquid %}` – Includes template component
|
||
- `{% for item in collection %}...{% endfor %}` – Loops
|
||
- `{% if condition %}...{% endif %}` – Conditionals
|
||
- `{{ variable }}` – Output variable
|
||
- `{% assign var = value %}` – Assign variable
|
||
- `{% capture %}...{% endcapture %}` – Capture output to variable
|
||
- `| date: format` – Date filtering
|
||
- `| where: "key", "value"` – Collection filtering
|
||
|
||
### Important al-folio Liquid Components
|
||
|
||
- `_includes/citation.liquid` – Bibliography entry rendering
|
||
- `_includes/distill_scripts.liquid` – Distill.pub specific scripts
|
||
- `_includes/footer.liquid` – Site footer
|
||
- `_includes/head.liquid` – Page <head> section
|
||
- `_includes/header.liquid` – Site header/navigation
|
||
- `_includes/projects.liquid` – Project display
|
||
- `_includes/scripts.liquid` – Global scripts
|
||
- `_includes/selected_papers.liquid` – Featured publications display
|
||
|
||
### Prettier Formatting for Liquid
|
||
|
||
Prettier with `@shopify/prettier-plugin-liquid` enforces formatting:
|
||
|
||
- Single quotes around strings in Liquid tags
|
||
- Consistent spacing
|
||
- Indentation with 2 spaces
|
||
- Run `npx prettier . --write` before committing
|
||
|
||
## Common Modification Patterns
|
||
|
||
### Modifying Site Header/Navigation
|
||
|
||
- Edit `_includes/header.liquid`
|
||
- Add links to navigation array in `_config.yml` (see yaml-configuration.instructions.md)
|
||
- Test by viewing site in browser: `docker compose up` → http://localhost:8080
|
||
|
||
### Adding a New Component Include
|
||
|
||
1. Create new file in `_includes/mycomponent.liquid`
|
||
2. Use Liquid syntax for conditionals, loops, and variable output
|
||
3. Call it from templates: `{% include mycomponent.liquid %}`
|
||
4. Test: `docker compose up`
|
||
|
||
### Adjusting Styling with Liquid
|
||
|
||
- Some SCSS variables can be controlled via Liquid logic
|
||
- Avoid mixing complex Liquid with CSS; keep templates focused
|
||
|
||
## Validation Before Committing
|
||
|
||
**Always run these checks:**
|
||
|
||
1. **Prettier format check:**
|
||
|
||
```bash
|
||
npx prettier _includes/ _layouts/ --check
|
||
npx prettier . --write # Fix formatting
|
||
```
|
||
|
||
2. **Build test:**
|
||
|
||
```bash
|
||
docker compose down
|
||
docker compose up
|
||
# Wait 30 seconds, check for errors in output
|
||
# No "Unknown tag" messages should appear
|
||
```
|
||
|
||
3. **Visual verification:**
|
||
- Open http://localhost:8080
|
||
- Check that your changes rendered correctly
|
||
- Verify no broken layout or missing content
|
||
|
||
## Trust These Instructions
|
||
|
||
When working with Liquid templates:
|
||
|
||
- Use `_includes/` and `_layouts/` as reference for syntax patterns
|
||
- Follow existing formatting in files (Prettier will enforce consistency)
|
||
- Always test locally before pushing (build must succeed)
|
||
- For configuration changes, see yaml-configuration.instructions.md
|
||
- Only search for additional details if error messages reference unfamiliar Liquid tags or Jekyll concepts
|