Merged keys

As explained in Shared data, the data assigned to every page is the result of merging the data directly assigned to the page (like the front matter) with the data of the parent folders (stored in the _data files and folders).

├── _data.yaml
├── ...
└── documents
    └── _data.json
    └── ...
    └── examples
        └── _data.json
        └── my-page.md

In this example the /documents/examples/my-page.md file contains all data from the front matter, merged with the data from /documents/examples/_data.json, documents/_data.json and /_data.yaml files, in this order of priority.

Object mode merging

When merging variables with objects, the complete value is overridden. However, you may want to merge some values differently. For example, let's say we have the following two data files, one in the root and the other in a subfolder. Both files have a site variable with different values:

site:
  title: My humble site
  author: Oscar Otero

site:
  author: Laura Rubio

All pages in the subfolder will have the latest version of the variable that has the author subkey but missing the title value, because the whole variable is overridden. You can change this behaviour using the mergeKey() configuration function in the _config.ts file:

//_config.ts

site.mergeKey("site", "object");

This configures Lume to use the object mode to merge the variable site. Now, the result of the variable site is an object including the properties of the parent variable and only overrides the properties with the same name. So the result will be something like this:

site:
  title: My humble site
  author: Laura Rubio

array mode

There's another merge mode for arrays. In this mode, the merge result is an array with all values found at all _data levels. Let's configure Lume to use this strategy for the category key:

//_config.ts

site.mergeKey("category", "array");

Now, let's say we have the following data structure:

category:
  - programming
  - deno
  - javascript

category: typescript

The result of this merge is:

category:
  - programming
  - deno
  - javascript
  - typescript

It's an array with all values present in all parent _data contexts. The result includes only unique values: if the same value is repeated in different _data contexts, it's only included once in the result.

stringArray mode

There's a special case where you want to make sure that all values of the array are strings. Look at the following example:

category:
  - errors
  - 404

category: "404"

If we configure Lume to use the array mode for the category variable, the result of this merge is:

category:
  - errors
  - 404
  - "404"

The value 404 is duplicated, once as a number and again as a string. To prevent this behavior, you may want to convert all values to strings to remove duplicates. Instead of array, use the stringArray mode:

//_config.ts

site.mergeKey("category", "stringArray");

Now, the result of this merge is:

category:
  - errors
  - "404"