Working with Data in Nunjucks Components

During the build, Metalsmith reads all JSON files from lib/data/ and makes them available in templates via the data object.

The loading function (from metalsmith.js):

const getGlobalMetadata = () => {
  const dataDir = path.join(thisDirectory, 'lib', 'data');

  const processDirectory = (dirPath, relativePath = '') => {
    const files = fs.readdirSync(dirPath);
    const result = {};

    files.forEach(file => {
      const filePath = path.join(dirPath, file);
      const stat = fs.statSync(filePath);

      if (stat.isDirectory()) {
        // Recursively process subdirectories
        result[file] = processDirectory(filePath);
      } else if (file.endsWith('.json')) {
        // Load JSON file
        const fileName = file.replace('.json', '');
        const fileContents = fs.readFileSync(filePath, 'utf8');
        result[fileName] = JSON.parse(fileContents);
      }
    });

    return result;
  };

  return processDirectory(dataDir);
};

This recursively loads all JSON files and creates a nested object structure that mirrors your directory structure.

The maps component demonstrates data-driven architecture. Map markers are stored in JSON files, while the page only references which data to use.

Data file (lib/data/maps/london-landmarks.json):

{
  "latitude": 51.509865,
  "longitude": -0.118092,
  "zoom": 10,
  "markers": [
    {
      "latitude": 51.509865,
      "longitude": -0.118092,
      "title": "London",
      "icon": "award",
      "content": {
        "title": "London",
        "body": "Political and cultural center...",
        "link": "https://en.wikipedia.org/wiki/London"
      }
    },
    {
      "latitude": 51.483334,
      "longitude": -0.604167,
      "title": "Windsor Castle",
      "icon": "home",
      "content": {
        "title": "Windsor Castle",
        "body": "Royal residence in Berkshire...",
        "link": "https://en.wikipedia.org/wiki/Windsor_Castle"
      }
    }
  ]
}

Page frontmatter (just references the data):

sections:
  - sectionType: maps
    mapProvider: leaflet
    mapData: london-landmarks
    height: 600px

The maps component loads data.maps['london-landmarks'] and renders all markers.

Follow these patterns for maintainable data files:

1. Include IDs for filterable lists:

[
  {
    "id": "item-1",
    "title": "First Item",
    "content": "..."
  }
]

2. Group related data:

{
  "settings": {
    "zoom": 10,
    "center": [51.5, -0.1]
  },
  "markers": [...]
}

3. Keep metadata with content:

{
  "title": "London Landmarks",
  "description": "Famous locations in London",
  "lastUpdated": "2025-09-20",
  "markers": [...]
}

4. Use consistent naming:

• Arrays: plural names (markers, items, logos)
• Objects: singular names (config, settings, metadata)
• Booleans: is/has prefix (isActive, hasIcon)

Understanding when to use data files vs. Metalsmith collections:

Use data files when:

• Content doesn't need its own page (logos, awards, markers)
• Data is reused across multiple pages
• Content is structured lists or configuration
• You need to filter/select subsets

Use collections when:

• Each item needs its own page (blog posts)
• You need pagination
• Items should appear in navigation/sitemap

Example combinations:

• Blog posts: Collection (each post is a page)
• Author info: Data file (reused across posts)
• Tags: Data file (list of valid tags)
• Comments: Data file (associated with posts)

There's one important detail about how components access data: Nunjucks macro scope isolation.

When section components are rendered via {% include %} statements inside a macro, template-level variables like data aren't automatically available. The solution is a context object that explicitly passes required data through the render chain.

How it works in sections-renderer.njk:

{# Build context object with all data needed by components #}
{% set context = {
  data: data,
  collections: collections,
  collection: collection,
  urlPath: urlPath,
  crumbs: navigation.breadcrumbs
} %}

{% for section in sections %}
  {{ renderSection(section, context) }}
{% endfor %}

Then in render-section.njk:

{% macro renderSection(section, context) %}
  {# Extract context properties for use in included templates #}
  {% set data = context.data %}
  {% set collections = context.collections %}
  {% set urlPath = context.urlPath %}

  {% include "components/sections/" + section.sectionType + "/" + section.sectionType + ".njk" ignore missing %}
{% endmacro %}

This pattern makes data flow explicit and keeps components portable. The same component works in Metalsmith, Eleventy, or any SSG that implements the same context interface.

Which components need context?

Check each component's manifest.json for a context array:

{
  "name": "podcast",
  "type": "section",
  "context": ["data.podcasts"],
  "requires": ["ctas", "commons"]
}

Components without a context field are self-contained and only need their frontmatter section data. Components with context requirements need those properties passed through the render chain.

Context Properties Reference

Data Properties - These access external JSON data files:

Site Properties - These provide site-wide or page-specific information:

Adding Context for New Components

When you install a component that requires context:

1. Check the component's manifest.json for a context array
2. Ensure your sections-renderer.njk includes that property in the context object
3. Ensure your render-section.njk extracts it before the {% include %}

Most components are self-contained and work out of the box without any context configuration. Components like text-only, hero, accordion, banner, cards-list, and most partials only need their frontmatter section data.

If you're using these components with Eleventy instead of Metalsmith, the data loading works differently but the component code stays the same.

The challenge: Eleventy's global data files are accessed by filename. A file at src/_data/podcasts.json becomes podcasts in templates, not data.podcasts. But components expect the data.* namespace.

The solution: Create a nested data folder inside _data:

src/_data/
└── data/                    # This folder name becomes the namespace
    ├── site.json            # Accessed as data.site
    ├── author.json          # Accessed as data.author
    ├── maps/
    │   └── london.json      # Accessed as data.maps.london
    └── podcasts/
        └── show-1.json      # Accessed as data.podcasts['show-1']

Eleventy automatically creates nested objects from folder structure. By putting your data files inside _data/data/, everything becomes available under data.* - exactly what the components expect.

No code changes needed: The same component templates work in both Metalsmith and Eleventy because they both access data.podcasts, data.maps, etc. The only difference is where you put the JSON files:

This is why components are portable across static site generators - they use a consistent data interface regardless of how each SSG loads that data.