Template Syntax and Logic Operations

**Referenced Files in This Document** - [base.njk](file://src/_includes/layouts/base.njk) - [index.njk](file://src/index.njk) - [about.njk](file://src/about.njk) - [capabilities.njk](file://src/capabilities.njk) - [media-management.njk](file://src/services/media-management.njk) - [code-of-conduct.njk](file://src/legal/code-of-conduct.njk) - [alliance.njk](file://src/alliance.njk) - [news.njk](file://src/news.njk) - [team.njk](file://src/team.njk) - [service-capability-card.njk](file://src/_includes/macros/service-capability-card.njk) - [cta-section.njk](file://src/_includes/macros/cta-section.njk) - [news-article-card.njk](file://src/_includes/macros/news-article-card.njk) - [testimonial-card.njk](file://src/_includes/macros/testimonial-card.njk) - [team-flip-card.njk](file://src/_includes/macros/team-flip-card.njk) - [site.json](file://src/_data/site.json) - [homepage.json](file://src/_data/homepage.json) - [capabilitiesPage.json](file://src/_data/capabilitiesPage.json) - [about.json](file://src/_data/about.json)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction

This document explains Nunjucks template syntax and logic operations used across the platform. It covers variable interpolation, conditional statements, loops, filters (including safe, replace, default), and custom macros. It also documents template logic patterns such as page URL detection, content rendering, dynamic navigation highlighting, and dynamic content injection. Practical examples demonstrate conditional asset loading, dynamic navigation highlighting, and content-specific rendering. Finally, it includes debugging techniques, common syntax errors, and performance considerations for template processing.

Project Structure

The platform uses a layered Nunjucks setup:

  • Layouts define shared HTML scaffolding and navigation.
  • Pages import macros to render reusable UI blocks.
  • Data files supply structured content for interpolation.
  • Collections and front matter provide runtime data for loops and conditionals.
graph TB
subgraph "Layouts"
L_base["base.njk"]
end
subgraph "Pages"
P_home["index.njk"]
P_about["about.njk"]
P_caps["capabilities.njk"]
P_news["news.njk"]
P_team["team.njk"]
P_alliance["alliance.njk"]
P_media["media-management.njk"]
P_legal["code-of-conduct.njk"]
end
subgraph "Macros"
M_card["service-capability-card.njk"]
M_cta["cta-section.njk"]
M_news["news-article-card.njk"]
M_testimonial["testimonial-card.njk"]
M_team["team-flip-card.njk"]
end
subgraph "Data"
D_site["site.json"]
D_home["homepage.json"]
D_caps["capabilitiesPage.json"]
D_about["about.json"]
end
P_home --> L_base
P_about --> L_base
P_caps --> L_base
P_news --> L_base
P_team --> L_base
P_alliance --> L_base
P_media --> L_base
P_legal --> L_base
P_home -. imports .-> M_card
P_home -. imports .-> M_cta
P_home -. imports .-> M_testimonial
P_home -. imports .-> M_team
P_about -. imports .-> M_cta
P_news -. imports .-> M_news
P_news -. imports .-> M_cta
P_home -. uses .-> D_home
P_caps -. uses .-> D_caps
P_about -. uses .-> D_about
P_alliance -. uses .-> D_site
P_news -. uses .-> D_site
P_team -. uses .-> D_site
P_media -. uses .-> D_site
P_legal -. uses .-> D_site

Diagram sources

  • [base.njk](file://src/_includes/layouts/base.njk)
  • [index.njk](file://src/index.njk)
  • [about.njk](file://src/about.njk)
  • [capabilities.njk](file://src/capabilities.njk)
  • [news.njk](file://src/news.njk)
  • [team.njk](file://src/team.njk)
  • [alliance.njk](file://src/alliance.njk)
  • [media-management.njk](file://src/services/media-management.njk)
  • [code-of-conduct.njk](file://src/legal/code-of-conduct.njk)
  • [service-capability-card.njk](file://src/_includes/macros/service-capability-card.njk)
  • [cta-section.njk](file://src/_includes/macros/cta-section.njk)
  • [news-article-card.njk](file://src/_includes/macros/news-article-card.njk)
  • [testimonial-card.njk](file://src/_includes/macros/testimonial-card.njk)
  • [team-flip-card.njk](file://src/_includes/macros/team-flip-card.njk)
  • [site.json](file://src/_data/site.json)
  • [homepage.json](file://src/_data/homepage.json)
  • [capabilitiesPage.json](file://src/_data/capabilitiesPage.json)
  • [about.json](file://src/_data/about.json)

Section sources

  • [base.njk](file://src/_includes/layouts/base.njk)
  • [index.njk](file://src/index.njk)
  • [about.njk](file://src/about.njk)
  • [capabilities.njk](file://src/capabilities.njk)
  • [news.njk](file://src/news.njk)
  • [team.njk](file://src/team.njk)
  • [alliance.njk](file://src/alliance.njk)
  • [media-management.njk](file://src/services/media-management.njk)
  • [code-of-conduct.njk](file://src/legal/code-of-conduct.njk)
  • [service-capability-card.njk](file://src/_includes/macros/service-capability-card.njk)
  • [cta-section.njk](file://src/_includes/macros/cta-section.njk)
  • [news-article-card.njk](file://src/_includes/macros/news-article-card.njk)
  • [testimonial-card.njk](file://src/_includes/macros/testimonial-card.njk)
  • [team-flip-card.njk](file://src/_includes/macros/team-flip-card.njk)
  • [site.json](file://src/_data/site.json)
  • [homepage.json](file://src/_data/homepage.json)
  • [capabilitiesPage.json](file://src/_data/capabilitiesPage.json)
  • [about.json](file://src/_data/about.json)

Core Components

  • Layouts: Centralized HTML scaffolding and navigation. Dynamic navigation highlighting uses page URL checks. Conditional assets load based on current route.
  • Pages: Compose content via loops over collections and data, and import macros for reusable UI.
  • Macros: Encapsulate rendering logic and accept parameters, including optional defaults.
  • Data: JSON files supply structured content for interpolation and conditional rendering.

Key template constructs demonstrated:

  • Variable interpolation: Embedding data fields into HTML attributes and content.
  • Conditionals: If/else branching for optional content and conditional asset loading.
  • Loops: Iterating over arrays and collections to render repeated UI blocks.
  • Filters: Built-ins like safe, replace, default; plus date formatting via macros.
  • Macros: Parameterized rendering with optional defaults and conditional branches.

Section sources

  • [base.njk](file://src/_includes/layouts/base.njk)
  • [index.njk](file://src/index.njk)
  • [about.njk](file://src/about.njk)
  • [capabilities.njk](file://src/capabilities.njk)
  • [news.njk](file://src/news.njk)
  • [team.njk](file://src/team.njk)
  • [alliance.njk](file://src/alliance.njk)
  • [media-management.njk](file://src/services/media-management.njk)
  • [code-of-conduct.njk](file://src/legal/code-of-conduct.njk)
  • [service-capability-card.njk](file://src/_includes/macros/service-capability-card.njk)
  • [cta-section.njk](file://src/_includes/macros/cta-section.njk)
  • [news-article-card.njk](file://src/_includes/macros/news-article-card.njk)
  • [testimonial-card.njk](file://src/_includes/macros/testimonial-card.njk)
  • [team-flip-card.njk](file://src/_includes/macros/team-flip-card.njk)
  • [site.json](file://src/_data/site.json)
  • [homepage.json](file://src/_data/homepage.json)
  • [capabilitiesPage.json](file://src/_data/capabilitiesPage.json)
  • [about.json](file://src/_data/about.json)

Architecture Overview

The template architecture follows a layout-per-page pattern with shared macros and data-driven content.

sequenceDiagram
participant Browser as "Browser"
participant Eleventy as "Eleventy Build"
participant Layout as "base.njk"
participant Page as "index.njk"
participant Macro as "service-capability-card.njk"
Browser->>Eleventy : Request / (index)
Eleventy->>Page : Resolve front matter and collections
Page->>Layout : Render with layout : base.njk
Layout-->>Browser : HTML with navigation and placeholders
Page->>Macro : Invoke card(service) per capability
Macro-->>Page : Rendered HTML for each service
Page-->>Browser : Complete HTML

Diagram sources

  • [base.njk](file://src/_includes/layouts/base.njk)
  • [index.njk](file://src/index.njk)
  • [service-capability-card.njk](file://src/_includes/macros/service-capability-card.njk)

Section sources

  • [base.njk](file://src/_includes/layouts/base.njk)
  • [index.njk](file://src/index.njk)
  • [service-capability-card.njk](file://src/_includes/macros/service-capability-card.njk)

Detailed Component Analysis

Layout and Navigation Highlighting

  • Dynamic navigation highlighting uses the current page URL to apply an active class to the matching link.
  • Conditional asset loading occurs based on the current URL (e.g., loading ScrollTrigger on non-home pages, modulepreload on home).

Practical patterns:

  • Compare page.url against known routes to set active state.
  • Load scripts/styles conditionally to optimize performance.

Section sources

  • [base.njk](file://src/_includes/layouts/base.njk)

Home Page Composition

  • Imports multiple macros to render marquees, cards, carousels, and CTAs.
  • Uses loops over collections and data arrays to render services, testimonials, team members, and news.
  • Demonstrates conditional content rendering and safe HTML insertion.

Patterns:

  • Loop over collections for dynamic content.
  • Import and invoke macros with parameters.
  • Use safe filter for trusted HTML content.

Section sources

  • [index.njk](file://src/index.njk)

About Page Rendering

  • Splits hero titles into words and conditionally styles the first or last word.
  • Iterates over paragraphs and accordion items, conditionally rendering lists and links.
  • Uses replace and safe filters to inject highlighted spans into headings.

Patterns:

  • String manipulation via split and replace.
  • Conditional rendering inside loops.
  • Safe insertion for highlighted markup.

Section sources

  • [about.njk](file://src/about.njk)

Capabilities Page Logic

  • Builds alternating content blocks using loop indices to decide image placement.
  • Renders process steps in a grid with numbered items.
  • Uses a macro to render a call-to-action section with optional highlight replacement.

Patterns:

  • Even/odd logic via loop.index to alternate layout.
  • Grid rendering with consistent structure.
  • Macro invocation with optional parameters.

Section sources

  • [capabilities.njk](file://src/capabilities.njk)

Service Detail Page (Media Management)

  • Renders hero content, intro paragraphs, capability cards, and dark-themed sections.
  • Uses replace and safe filters to highlight text in CTAs.

Patterns:

  • Paragraph iteration for long-form content.
  • Card-based rendering with iconography.
  • Highlighted CTAs via filter chaining.

Section sources

  • [media-management.njk](file://src/services/media-management.njk)

News Page Composition

  • Imports polling bar, news article cards, newsletter signup, and CTA macros.
  • Renders a filtering UI and dynamically filters news items client-side.
  • Uses date formatting via a macro and safe insertion for expanded content.

Patterns:

  • Macro composition for modular sections.
  • Client-side filtering with DOM manipulation.
  • Safe insertion for rich content.

Section sources

  • [news.njk](file://src/news.njk)

Team Page Rendering

  • Iterates over team member collection items to render profiles.
  • Uses safe filter for profile bio content.

Patterns:

  • Collection iteration with conditional image fallbacks.
  • Safe insertion for markdown-rendered bio content.

Section sources

  • [team.njk](file://src/team.njk)

Alliance Page Content

  • Uses a dedicated layout and renders marquee, advantages, services, timeline, and partner index.
  • Imports marquee macro and iterates over data arrays.

Patterns:

  • Dedicated layout for specialized content.
  • Structured grid and timeline rendering.

Section sources

  • [alliance.njk](file://src/alliance.njk)

Legal Document Page

  • Renders a static document page using layout inheritance.
  • Inserts email from site data into a contact link.

Patterns:

  • Static content rendering with layout reuse.
  • Data interpolation for contact information.

Section sources

  • [code-of-conduct.njk](file://src/legal/code-of-conduct.njk)

Macros and Filters

Macro: Service Capability Card

  • Accepts a service object and renders a card with image, title, body, and link.
  • Uses default filter for optional class field.
classDiagram
class ServiceCapabilityCard {
+card(service)
}

Diagram sources

  • [service-capability-card.njk](file://src/_includes/macros/service-capability-card.njk)

Section sources

  • [service-capability-card.njk](file://src/_includes/macros/service-capability-card.njk)

Macro: Call-to-Action Section

  • Accepts parameters for title, subtitle, button text, URL, theme, and highlight text.
  • Applies replace + safe to highlight a substring in the title when provided.
classDiagram
class CTASection {
+section(title, buttonText="Contact us today", buttonUrl="/contact/", subtitle="", theme="dark", highlightText="")
}

Diagram sources

  • [cta-section.njk](file://src/_includes/macros/cta-section.njk)

Section sources

  • [cta-section.njk](file://src/_includes/macros/cta-section.njk)

Macro: News Article Card

  • Renders either a carousel card or a grid article depending on variant.
  • Uses date formatting macro and safe insertion for content.
classDiagram
class NewsArticleCard {
+card(item, variant="carousel")
}

Diagram sources

  • [news-article-card.njk](file://src/_includes/macros/news-article-card.njk)

Section sources

  • [news-article-card.njk](file://src/_includes/macros/news-article-card.njk)

Macro: Testimonial Card

  • Renders a testimonial quote with author and role.
  • Supports a case study variant with different markup.
classDiagram
class TestimonialCard {
+card(quote, author, role, isCaseStudy=false)
}

Diagram sources

  • [testimonial-card.njk](file://src/_includes/macros/testimonial-card.njk)

Section sources

  • [testimonial-card.njk](file://src/_includes/macros/testimonial-card.njk)

Macro: Team Flip Card

  • Renders a flip card with front/back content for team profiles.
classDiagram
class TeamFlipCard {
+card(item)
}

Diagram sources

  • [team-flip-card.njk](file://src/_includes/macros/team-flip-card.njk)

Section sources

  • [team-flip-card.njk](file://src/_includes/macros/team-flip-card.njk)

Data Sources and Interpolation

  • Site metadata (title, URL, phone, email, address, social) is interpolated across layouts and pages.
  • Page-specific content (hero, headings, CTAs) is loaded from JSON data files and interpolated into templates.
  • Collections (team members, news) are looped over to render dynamic content.

Examples of interpolation patterns:

  • Embedding site fields into meta tags, canonical URLs, and contact links.
  • Using page data to populate hero content and CTAs.
  • Rendering collection items with safe insertion for markdown content.

Section sources

  • [site.json](file://src/_data/site.json)
  • [homepage.json](file://src/_data/homepage.json)
  • [capabilitiesPage.json](file://src/_data/capabilitiesPage.json)
  • [about.json](file://src/_data/about.json)

Dependency Analysis

Template dependencies are primarily import-based and data-driven:

  • Pages depend on layouts for structure and on macros for UI.
  • Macros depend on data passed as parameters.
  • Data files are consumed by pages and macros.
graph LR
P_home["index.njk"] --> L_base["base.njk"]
P_about["about.njk"] --> L_base
P_caps["capabilities.njk"] --> L_base
P_news["news.njk"] --> L_base
P_team["team.njk"] --> L_base
P_alliance["alliance.njk"] --> L_base
P_media["media-management.njk"] --> L_base
P_legal["code-of-conduct.njk"] --> L_base
P_home -. imports .-> M_card["service-capability-card.njk"]
P_home -. imports .-> M_cta["cta-section.njk"]
P_home -. imports .-> M_testimonial["testimonial-card.njk"]
P_home -. imports .-> M_team["team-flip-card.njk"]
P_about -. imports .-> M_cta
P_news -. imports .-> M_news["news-article-card.njk"]
P_news -. imports .-> M_cta
P_home -. uses .-> D_home["homepage.json"]
P_caps -. uses .-> D_caps["capabilitiesPage.json"]
P_about -. uses .-> D_about["about.json"]
P_alliance -. uses .-> D_site["site.json"]
P_news -. uses .-> D_site
P_team -. uses .-> D_site
P_media -. uses .-> D_site
P_legal -. uses .-> D_site

Diagram sources

  • [base.njk](file://src/_includes/layouts/base.njk)
  • [index.njk](file://src/index.njk)
  • [about.njk](file://src/about.njk)
  • [capabilities.njk](file://src/capabilities.njk)
  • [news.njk](file://src/news.njk)
  • [team.njk](file://src/team.njk)
  • [alliance.njk](file://src/alliance.njk)
  • [media-management.njk](file://src/services/media-management.njk)
  • [code-of-conduct.njk](file://src/legal/code-of-conduct.njk)
  • [service-capability-card.njk](file://src/_includes/macros/service-capability-card.njk)
  • [cta-section.njk](file://src/_includes/macros/cta-section.njk)
  • [news-article-card.njk](file://src/_includes/macros/news-article-card.njk)
  • [testimonial-card.njk](file://src/_includes/macros/testimonial-card.njk)
  • [team-flip-card.njk](file://src/_includes/macros/team-flip-card.njk)
  • [site.json](file://src/_data/site.json)
  • [homepage.json](file://src/_data/homepage.json)
  • [capabilitiesPage.json](file://src/_data/capabilitiesPage.json)
  • [about.json](file://src/_data/about.json)

Section sources

  • [base.njk](file://src/_includes/layouts/base.njk)
  • [index.njk](file://src/index.njk)
  • [about.njk](file://src/about.njk)
  • [capabilities.njk](file://src/capabilities.njk)
  • [news.njk](file://src/news.njk)
  • [team.njk](file://src/team.njk)
  • [alliance.njk](file://src/alliance.njk)
  • [media-management.njk](file://src/services/media-management.njk)
  • [code-of-conduct.njk](file://src/legal/code-of-conduct.njk)
  • [service-capability-card.njk](file://src/_includes/macros/service-capability-card.njk)
  • [cta-section.njk](file://src/_includes/macros/cta-section.njk)
  • [news-article-card.njk](file://src/_includes/macros/news-article-card.njk)
  • [testimonial-card.njk](file://src/_includes/macros/testimonial-card.njk)
  • [team-flip-card.njk](file://src/_includes/macros/team-flip-card.njk)
  • [site.json](file://src/_data/site.json)
  • [homepage.json](file://src/_data/homepage.json)
  • [capabilitiesPage.json](file://src/_data/capabilitiesPage.json)
  • [about.json](file://src/_data/about.json)

Performance Considerations

  • Conditional asset loading: Defer heavy libraries (e.g., ScrollTrigger) on non-home pages; preload critical modules on the home page.
  • Minimize unsafe HTML: Use the safe filter only for trusted content to avoid XSS and reduce parsing overhead.
  • Efficient loops: Prefer server-side loops over client-side DOM manipulation where possible; keep macro invocations lightweight.
  • Data locality: Keep large datasets in data files and pass only necessary fields to macros to reduce template complexity.
  • Filter usage: Use filters judiciously; complex chained filters (e.g., replace + safe) should be reserved for small, controlled inputs.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

  • Unexpected HTML in output: Verify the safe filter is applied only to trusted content. Confirm the content source and sanitization pipeline.
  • Navigation not highlighting: Ensure page.url comparisons match the exact route used in the template. Check trailing slashes and case sensitivity.
  • Macro parameters missing: Confirm macro signatures and default values. Use optional parameters with sensible defaults.
  • Date formatting errors: Ensure the date formatting macro is imported and invoked with a valid date value.
  • Conditional asset loading not working: Verify the page URL check logic and script/modulepreload directives are placed in the correct scope.

Section sources

  • [base.njk](file://src/_includes/layouts/base.njk)
  • [index.njk](file://src/index.njk)
  • [about.njk](file://src/about.njk)
  • [capabilities.njk](file://src/capabilities.njk)
  • [news.njk](file://src/news.njk)
  • [team.njk](file://src/team.njk)
  • [alliance.njk](file://src/alliance.njk)
  • [media-management.njk](file://src/services/media-management.njk)
  • [code-of-conduct.njk](file://src/legal/code-of-conduct.njk)
  • [service-capability-card.njk](file://src/_includes/macros/service-capability-card.njk)
  • [cta-section.njk](file://src/_includes/macros/cta-section.njk)
  • [news-article-card.njk](file://src/_includes/macros/news-article-card.njk)
  • [testimonial-card.njk](file://src/_includes/macros/testimonial-card.njk)
  • [team-flip-card.njk](file://src/_includes/macros/team-flip-card.njk)
  • [site.json](file://src/_data/site.json)
  • [homepage.json](file://src/_data/homepage.json)
  • [capabilitiesPage.json](file://src/_data/capabilitiesPage.json)
  • [about.json](file://src/_data/about.json)

Conclusion

The platform leverages Nunjucks to compose flexible, data-driven pages with shared layouts and reusable macros. Core logic patterns include URL-based navigation highlighting, conditional asset loading, dynamic content injection via loops and macros, and careful use of filters for safe HTML and text transformations. Following the documented patterns and troubleshooting tips will help maintain consistency, readability, and performance across templates.