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

3.2 KiB

Raw Permalink Blame History

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

Create new file in _includes/mycomponent.liquid
Use Liquid syntax for conditionals, loops, and variable output
Call it from templates: {% include mycomponent.liquid %}
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:

Prettier format check:

npx prettier _includes/ _layouts/ --check
npx prettier . --write  # Fix formatting

Build test:

docker compose down
docker compose up
# Wait 30 seconds, check for errors in output
# No "Unknown tag" messages should appear

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

3.2 KiB Raw Permalink Blame History Unescape Escape