Instruction file imported from MiguelClaramunt/miguelclaramunt.github.io (.github/instructions/liquid-templates.instructions.md). Copyright stays with the author.

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 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:

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

2. Build test:

   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