Skip to content

liquid-templates.instructions.md

Latest commit

 

History

History
100 lines (71 loc) · 3.16 KB

liquid-templates.instructions.md

File metadata and controls

100 lines (71 loc) · 3.16 KB
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 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