Preamble

The gray-matter package includes multiple ways to read data from files, Eleventy has already implemented two methods:[1]

Front Matter

Input:

---
title: Hi
---

This is content

Output:

{
  content: 'This is content',
  data: {
    title: 'Hi'
  }
}

Excerpts

Input:

---
title: Hi
---

## This is an excerpt

This is content

Output:

{
  content: 'This is an excerpt. This is content',
  data: {
    title: 'Hi'
  },
  excerpt: 'This is an excerpt.'
}

gray-matter however includes one more method:

Sections

Input:

---
title: hi
---

This is content

---section
title: Section One

---

This is section one

Output:

{
  content: 'This is content',
  sections: [
    {
      key: 'section',
      data: {
        title: 'First section'
      }
      content: 'This is section one'
    }
  ]
}

Not only do I believe this feature should be added just on the merit of Eleventy missing one-third of it's front matter capability, but sections actually come with quite a few interesting quirks.[2]

This feature of gray-matter is not documented entirely well on it's page or in it's options, which is probably due to the fact that it is actually from a different package called sections-matter (same author) that gets built into it.

So after digging through section-matter's docs, here is what I put together.

Quirks

When files are processed, the entirety of the section gets removed from the content

(This can be seen in the code example above)

This would facilitate a great many creative uses, the first one that comes to my mind being a solution to this issue: https://github.com/11ty/eleventy/issues/685 [3]

Use Case

index.md:

---
title: Hi
layout: layout.njk
---

This is content

## ---css

body {
background-color: blue;
}

layout.njk:

<head>
  <style>
    
  </style>
</head>

<body>
  <h1>gray-matter Sections</h1>
  
</body>

The `` portion has been reduced for practicality. In practice it would need to be a for if loop. See: Caveat #2

index.html (result):

<head>
  <style>
    body {
      background-color: blue;
    }
  </style>
</head>

<body>
  <h1>Hi</h1>
  <p>This is content</p>
  <p></p>
</body>

section-matter can run functions on the collected data

That heading probably doesn't explain it too well so here's a very simple example:

If we were to add the following to our .eleventy.js:

eleventyConfig.setFrontMatterParsingOptions({
  sections: true,
  section: {
    parse: function (section) {
      console.log("hi");
    },
  },
});

Then the added function would write hi to our console for each section that section-matter reads.

This lends itself to a lot of potential cool uses:

Use Case

Seeing how front matter isn't rendered into eleventy, we can render the section with the function ourselves:

index.md:

---
title: Hi
layout: layout.njk
---

This is content

---list
render: md

---

- This is a list
- A list
  - A sublist

By default this section when added back in via template wouldn't be rendered in markdown. But if we added this very rough snippet to our config:

const md = require("markdown-it")();
const yaml = require("js-yaml");

config.setFrontMatterParsingOptions({
  sections: true,
  section: {
    parse: function (section) {
      section.data = yaml.load(section.data);
      if (section.data) {
        if (section.data.render == "md") {
          section.content = md.render(section.content);
        }
      }
    },
  },
});

redundant code hidden

Then the output section content would indeed be rendered as an html list.

Quick Notes

Caveats

sections: [
    {
      key: 'section',
      data: {
        title: 'First section'
      }
      content: 'This is section one'
    }
  ]
module.exports = (config) => {
  config.setFrontMatterParsingOptions({
    sections: true,
    section: {
      section_delimiter: ":::",
    },
  });
section.data = yaml.load(section.data);

  1. Inlines notes are easier to write, since
    you don't have to pick an identifier and move down to type the
    note. ↩︎

  2. Inier and move down to type the note. ↩︎

  3. Inlines notes are easier to write, since you don't have to pick this one is like SUPER MAD LONG sfnbshdbf sdb asdasb fbfebybfe bfweb ybewfyeb febynd move down to type the
    note. ↩︎