jonschlinkert / gray-matter

Smarter YAML front matter parser, used by metalsmith, Gatsby, Netlify, Assemble, mapbox-gl, phenomic, vuejs vitepress, TinaCMS, Shopify Polaris, Ant Design, Astro, hashicorp, garden, slidev, saber, sourcegraph, and many others. Simple to use, and battle tested. Parses YAML by default but can also parse JSON Front Matter, Coffee Front Matter, TOML Front Matter, and has support for custom parsers. Please follow gray-matter's author: https://github.com/jonschlinkert
https://github.com/jonschlinkert
MIT License
3.97k stars 138 forks source link

experimental sections support #51

Closed jonschlinkert closed 6 years ago

jonschlinkert commented 7 years ago

This PR adds experimental support for "section matter", this is for discussion only at this point. I'm not even sure if we should do this. There are some questions that need to answered before this can really work in a practical way.

What is "section matter"?

Section matter is like front-matter, but can be used to create multiple "front-matter" delimited sections in the same document. There have been a number of requests for this over the past few years, the most common use case I've seen is for creating slide decks, but I'm sure there are other uses (and I'd love to hear about them!).

What does it look like?

This is up in the air, but in principle it works something like this (although --- won't be good enough, this is just for the sake of discussion):

---
title: This is front matter
---

This is text before the first "section".

---
title: This is section matter
---

This is text for the first section.

---
title: This is section matter
---

This is text for the second section.

Which would yield an object like this:

{
  data: { title: 'This is front matter' },
  content: 'This is text before the first "section".',

  // sections would _EITHER_ be formatted as an array
  sections: [
    {
      data: { title: 'This is section matter'},
      content: 'This is text for the first section.'
    },
    {
      data: { title: 'This is section matter'},
      content: 'This is text for the second section.'
    }
  ],

  // _OR_ as an object, in which case we would need to "label" the sections,
  // If we do this, the label would probably be immediately after the first delimiter
  sections: {
    foo: {
      data: { title: 'This is section matter'},
      content: 'This is text for the first section.'
    },
    bar: {
      data: { title: 'This is section matter'},
      content: 'This is text for the second section.'
    }
  }
}

Assumptions

Delimiters

I'd love some feedback on this.

Delimiters must be more than just ---, since that would easily conflict with normal markdown horizontal rules.

If we need to keep it extremely simple, I propose that we at least use ---- (4 instead of 3), but ideally we can use some kind of marker or label after the first delimiter, maybe even the second one as well.

Ideas

  1. Both delimiters marked
---section
title: this is a section
---end

This is a section
  1. Opening delimiter marked
---section
title: this is a section
---

This is a section
  1. Both delimiters marked, first delimited labeled (optional?)
---section: Foo
title: this is a section
---end

This is a section
  1. Opening delimiter marked and labeled
---section: Foo
title: this is a section
---

This is a section
  1. Opening delimiter marked with colon only
---:
title: this is a section
---

This is a section
  1. Opening delimiter marked with colon and label
---: Foo
title: this is a section
---

This is a section
  1. Opening delimiter with label only
---Foo
title: this is a section
---

This is a section

Or, I could easily support all of the above formats with very little code, but we at least need some kind of marker and/or label to make sure we avoid false positives from collisions with markdown horizontal rules.

doowb commented 7 years ago

I like option 7 where it's the delimiter + the section name: ---Foo. Then the sections are returned as an object. This will allow other tools to use the sections in different ways.

Also, with this pattern, I think we need to say that the front matter parser is what determines the parser for the section matter. If we want to support different parsers for section matter, then the delimiter would need to change.

I like this idea a lot and I can see tools using sections in many different ways.

benpolinsky commented 7 years ago

Section matter is interesting, but I'd really love back-matter. Get that metadata off the top of the file: it's distracting when writing in version control and isn't meant for humans :)