Layout System and Templates

**Referenced Files in This Document** - [base.njk](file://src/_includes/layouts/base.njk) - [iaa-base.njk](file://src/_includes/layouts/iaa-base.njk) - [knowledge.njk](file://src/_includes/layouts/knowledge.njk) - [index.njk](file://src/index.njk) - [about.njk](file://src/about.njk) - [capabilities.njk](file://src/capabilities.njk) - [alliance.njk](file://src/alliance.njk) - [alliance-knowledge.njk](file://src/alliance-knowledge.njk) - [media-management.njk](file://src/services/media-management.njk) - [code-of-conduct.njk](file://src/legal/code-of-conduct.njk) - [getting-started.md](file://src/content/knowledge/getting-started.md) - [site.json](file://src/_data/site.json) - [.eleventy.js](file://.eleventy.js)

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 the layout system architecture built with Nunjucks templates. It focuses on three primary layouts:

  • base.njk: The main layout providing global navigation, SEO meta tags, canonical URLs, structured data, and a comprehensive footer.
  • iaa-base.njk: An alliance-specific layout tailored for Invest Australia Alliance pages with distinct branding, navigation, and footer content.
  • knowledge.njk: A specialized layout for knowledge base articles, including breadcrumbs, metadata, tagging, and a back link.

It also covers template inheritance patterns, block definitions, content injection points, page-specific overrides, conditional rendering, integration with the component macro system, SEO optimization, meta tag management, and responsive design integration.

Project Structure

The layout system resides under src/_includes/layouts and is complemented by page templates and data files. Pages declare which layout to use via front matter, and content is injected into the selected layout’s content block.

graph TB
subgraph "Layouts"
B["base.njk"]
I["iaa-base.njk"]
K["knowledge.njk"]
end
subgraph "Pages"
H["index.njk"]
A["about.njk"]
C["capabilities.njk"]
S["services/media-management.njk"]
ALN["alliance.njk"]
AK["alliance-knowledge.njk"]
L["legal/code-of-conduct.njk"]
G["content/knowledge/getting-started.md"]
end
subgraph "Data"
D["site.json"]
end
H --> B
A --> B
C --> B
S --> B
ALN --> I
AK --> B
L --> B
K --> B
G --> K
B --> D
I --> D

Diagram sources

  • [base.njk](file://src/_includes/layouts/base.njk)
  • [iaa-base.njk](file://src/_includes/layouts/iaa-base.njk)
  • [knowledge.njk](file://src/_includes/layouts/knowledge.njk)
  • [index.njk](file://src/index.njk)
  • [about.njk](file://src/about.njk)
  • [capabilities.njk](file://src/capabilities.njk)
  • [alliance.njk](file://src/alliance.njk)
  • [alliance-knowledge.njk](file://src/alliance-knowledge.njk)
  • [media-management.njk](file://src/services/media-management.njk)
  • [code-of-conduct.njk](file://src/legal/code-of-conduct.njk)
  • [getting-started.md](file://src/content/knowledge/getting-started.md)
  • [site.json](file://src/_data/site.json)

Section sources

  • [base.njk](file://src/_includes/layouts/base.njk)
  • [iaa-base.njk](file://src/_includes/layouts/iaa-base.njk)
  • [knowledge.njk](file://src/_includes/layouts/knowledge.njk)
  • [index.njk](file://src/index.njk)
  • [about.njk](file://src/about.njk)
  • [capabilities.njk](file://src/capabilities.njk)
  • [alliance.njk](file://src/alliance.njk)
  • [alliance-knowledge.njk](file://src/alliance-knowledge.njk)
  • [media-management.njk](file://src/services/media-management.njk)
  • [code-of-conduct.njk](file://src/legal/code-of-conduct.njk)
  • [getting-started.md](file://src/content/knowledge/getting-started.md)
  • [site.json](file://src/_data/site.json)

Core Components

  • base.njk: Provides the global HTML shell, SEO meta tags, Open Graph and Twitter Card tags, canonical URL, JSON-LD Organization and optional NewsArticle structured data, navigation, search modal, main content area, and a comprehensive footer with legal links, newsletter signup, and theme toggle.
  • iaa-base.njk: Provides an alliance-focused HTML shell with Invest Australia Alliance branding, simplified navigation, and a dedicated footer with alliance-specific contact and legal links.
  • knowledge.njk: Wraps article content in a knowledge-specific structure with breadcrumbs, title, metadata (date, author, reading time), optional tags, and a back link to the knowledge index.

These layouts are consumed by page templates via front matter layout declarations. Content from page templates is injected into the content block of the chosen layout.

Section sources

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

Architecture Overview

The layout system follows a layered inheritance model:

  • Page templates define layout in front matter.
  • The selected layout renders the global shell and injects page content into the content block.
  • Global data (site.json) supplies metadata for SEO and social tags.
  • Macros are imported and invoked within page templates to compose reusable UI blocks.
sequenceDiagram
participant P as "Page Template (e.g., index.njk)"
participant L as "Layout (base.njk)"
participant D as "Global Data (site.json)"
P->>L : "Declare layout in front matter"
L->>D : "Resolve site.title, site.url, site.email, etc."
L->>L : "Render head : meta, OG, Twitter, canonical, LD+JSON"
L->>L : "Render nav and search modal"
P->>L : "Provide content"
L->>L : "Inject content into main"
L->>L : "Render footer and theme toggle"
L-->>P : "Final HTML output"

Diagram sources

  • [index.njk](file://src/index.njk)
  • [base.njk](file://src/_includes/layouts/base.njk)
  • [site.json](file://src/_data/site.json)

Section sources

  • [index.njk](file://src/index.njk)
  • [base.njk](file://src/_includes/layouts/base.njk)
  • [site.json](file://src/_data/site.json)

Detailed Component Analysis

base.njk: Main Layout

  • Global HTML shell with lang attribute and viewport meta.
  • SEO and social tags:
    • Title and description from page front matter.
    • Canonical URL constructed from site.url and page.url.
    • Open Graph tags for type, url, title, description, image, locale, and site_name.
    • Twitter Card meta tags.
    • Preloaded fonts and Material Symbols.
  • Structured data:
    • JSON-LD Organization schema.
    • Optional JSON-LD NewsArticle schema for post-like pages or news URLs.
  • Navigation and search:
    • Logo and navigation menu with active state helpers.
    • Search modal with keyboard hints and accessibility attributes.
  • Main content area:
    • Content block injection point for page templates.
  • Footer:
    • Multi-column layout with brand, capabilities, explore, and contact sections.
    • Newsletter subscription form powered by ConvertKit.
    • Bottom bar with copyright, legal links, and theme toggle.

Responsive design integration:

  • Viewport meta ensures mobile-friendly scaling.
  • CSS modules under assets/css/modules provide tablet, mobile, and small-mobile breakpoints.

Conditional rendering:

  • GSAP and ScrollTrigger scripts are conditionally included based on current page URL.
  • Theme class defaults to dark mode on body.

Section sources

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

iaa-base.njk: Alliance-Specific Layout

  • Simplified HTML shell optimized for Invest Australia Alliance pages.
  • Title and description tailored to the alliance.
  • Fonts and stylesheets loaded for typography and icons.
  • Navigation:
    • Dual branding link to Ace Strategies and a direct link to the alliance home.
    • Minimal menu with “Alliance” and “Contact.”
  • Footer:
    • Dedicated alliance branding and acknowledgment.
    • Enquiries contact details and legal links.
    • Theme toggle adapted for alliance context.

This layout is ideal for member-only or alliance-centric pages where the Ace Strategies branding is secondary.

Section sources

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

knowledge.njk: Knowledge Base Article Layout

  • Inherits from base.njk via front matter.
  • Article wrapper with data-theme attribute.
  • Breadcrumbs linking to Members Portal and Knowledge Base.
  • Article header with title, metadata (date, author, reading time), and optional tags.
  • Body content area for article markdown.
  • Footer with a back link to the Knowledge Base index.

This layout standardizes article presentation and improves discoverability and navigation within the knowledge base.

Section sources

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

Template Inheritance Patterns and Content Injection

  • Page templates declare a layout in front matter (e.g., layout: base.njk or layout: iaa-base.njk).
  • The selected layout defines blocks and placeholders; page content fills the content block.
  • Example page-to-layout assignments:
    • index.njk → base.njk
    • about.njk → base.njk
    • capabilities.njk → base.njk
    • services/media-management.njk → base.njk
    • alliance.njk → iaa-base.njk
    • alliance-knowledge.njk → base.njk
    • legal/code-of-conduct.njk → base.njk
    • content/knowledge/getting-started.md → knowledge.njk

Section sources

  • [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)
  • [alliance.njk](file://src/alliance.njk)
  • [alliance-knowledge.njk](file://src/alliance-knowledge.njk)
  • [code-of-conduct.njk](file://src/legal/code-of-conduct.njk)
  • [getting-started.md](file://src/content/knowledge/getting-started.md)
  • [knowledge.njk](file://src/_includes/layouts/knowledge.njk)

Block Definitions and Content Injection Points

  • base.njk defines:
    • A content block for page content injection.
    • Head section for SEO and structured data.
    • Body content including navigation, search modal, main content area, and footer.
  • iaa-base.njk defines:
    • A content block for page content injection.
    • Head section for alliance-specific SEO.
    • Body content including alliance navigation and footer.
  • knowledge.njk defines:
    • A content block for article content injection.
    • Article header, body, and footer regions.

Page templates render content inside these blocks, enabling consistent structure and shared functionality across pages.

Section sources

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

Page-Specific Template Overrides

  • Pages override layout selection via front matter:
    • alliance.njk selects iaa-base.njk for alliance-specific presentation.
    • knowledge articles (Markdown) select knowledge.njk for standardized article layout.
  • Pages can override SEO metadata (title, description) and permalink behavior in front matter.

Examples:

  • alliance.njk sets layout: iaa-base.njk and declares title and description for the alliance.
  • getting-started.md sets layout: knowledge.njk and includes front matter for title, date, author, excerpt, and tags_list.

Section sources

  • [alliance.njk](file://src/alliance.njk)
  • [getting-started.md](file://src/content/knowledge/getting-started.md)
  • [knowledge.njk](file://src/_includes/layouts/knowledge.njk)

Conditional Layout Rendering

  • base.njk includes conditional script loading for GSAP and ScrollTrigger based on the current page URL.
  • base.njk conditionally includes a module preload for Three.js on the home page.
  • iaa-base.njk applies a theme-light class on the body element.

These conditions optimize performance and tailor behavior per page.

Section sources

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

Integration with the Component Macro System

  • Pages import and use macros to compose reusable UI blocks:
    • index.njk imports multiple macros (client-marquee, service-capability-card, team-flip-card, news-article-card, testimonial-card, cta-section) and renders carousels and sections.
    • capabilities.njk imports the cta-section macro for call-to-action sections.
    • services/media-management.njk uses breadcrumb navigation and structured content blocks.
  • Macros encapsulate markup and logic, promoting reuse and consistency across pages.

Section sources

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

SEO Optimization and Meta Tag Management

  • Title and description come from page front matter and site metadata.
  • Canonical URL is generated from site.url and page.url.
  • Open Graph tags include type, url, title, description, image, locale, and site_name.
  • Twitter Card meta tags mirror key SEO fields.
  • JSON-LD Organization schema is embedded in the base layout.
  • Optional JSON-LD NewsArticle schema is included for post-like pages or news URLs.
  • Global data (site.json) centralizes contact, social, and branding information used across layouts.

Section sources

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

Responsive Design Integration

  • Viewport meta in base.njk ensures proper scaling on mobile devices.
  • CSS modules under assets/css/modules provide responsive breakpoints and styles for tablets, phones, and smaller screens.
  • Layouts and pages apply data-theme attributes to sections to support theme-aware rendering.

Section sources

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

Dependency Analysis

The layout system depends on:

  • Global data (site.json) for SEO, canonical URLs, and social metadata.
  • Eleventy configuration for template directories and transforms.
  • CSS modules for responsive design and theme toggles.
  • Macros for reusable UI components.
graph LR
S["site.json"] --> B["base.njk"]
S --> I["iaa-base.njk"]
E[".eleventy.js"] --> B
E --> I
M["Macros (imported in pages)"] --> H["index.njk"]
M --> A["about.njk"]
M --> C["capabilities.njk"]
M --> Svc["services/media-management.njk"]
H --> B
A --> B
C --> B
Svc --> B
ALN["alliance.njk"] --> I
AK["alliance-knowledge.njk"] --> B
L["legal/code-of-conduct.njk"] --> B
G["content/knowledge/getting-started.md"] --> K["knowledge.njk"]
K --> B

Diagram sources

  • [site.json](file://src/_data/site.json)
  • [base.njk](file://src/_includes/layouts/base.njk)
  • [iaa-base.njk](file://src/_includes/layouts/iaa-base.njk)
  • [.eleventy.js](file://.eleventy.js)
  • [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)
  • [alliance.njk](file://src/alliance.njk)
  • [alliance-knowledge.njk](file://src/alliance-knowledge.njk)
  • [code-of-conduct.njk](file://src/legal/code-of-conduct.njk)
  • [getting-started.md](file://src/content/knowledge/getting-started.md)
  • [knowledge.njk](file://src/_includes/layouts/knowledge.njk)

Section sources

  • [site.json](file://src/_data/site.json)
  • [base.njk](file://src/_includes/layouts/base.njk)
  • [iaa-base.njk](file://src/_includes/layouts/iaa-base.njk)
  • [.eleventy.js](file://.eleventy.js)
  • [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)
  • [alliance.njk](file://src/alliance.njk)
  • [alliance-knowledge.njk](file://src/alliance-knowledge.njk)
  • [code-of-conduct.njk](file://src/legal/code-of-conduct.njk)
  • [getting-started.md](file://src/content/knowledge/getting-started.md)
  • [knowledge.njk](file://src/_includes/layouts/knowledge.njk)

Performance Considerations

  • Conditional script loading reduces payload on non-home pages.
  • Preloading critical assets (fonts, icons) improves First Contentful Paint.
  • HTML minification transform in production reduces bundle size.
  • Macro usage promotes reuse and reduces duplication across templates.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

  • Missing or incorrect SEO metadata:
    • Verify page front matter includes title and description.
    • Confirm site.json contains correct site.url and related fields.
  • Broken canonical URLs:
    • Ensure page.url is correct and site.url matches deployed domain.
  • Missing structured data:
    • Confirm base layout includes JSON-LD Organization and optional NewsArticle blocks.
  • Incorrect layout rendering:
    • Check front matter layout declaration matches intended layout file.
  • Macro errors:
    • Ensure macros are imported in the page template and invoked with correct parameters.

Section sources

  • [base.njk](file://src/_includes/layouts/base.njk)
  • [site.json](file://src/_data/site.json)
  • [index.njk](file://src/index.njk)

Conclusion

The layout system leverages Nunjucks template inheritance to provide a consistent, SEO-optimized, and responsive foundation across the site. base.njk offers a robust global shell, iaa-base.njk supports alliance-specific needs, and knowledge.njk standardizes article presentation. Combined with macros and centralized data, the system balances flexibility and maintainability while ensuring strong SEO and accessibility outcomes.