experimental sections support

jonschlinkert commented

2017-10-19 16:49:03 +00:00

(Migrated from github.com)

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

options.sections must be defined as true (example: matter(string, { sections: true }))
file.sections will be an array or object of "section" objects. Each section object will have a data and content property.
file.contents will contain the text preceding the first section

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

Both delimiters marked

---section
title: this is a section
---end

This is a section

Opening delimiter marked

---section
title: this is a section
---

This is a section

Both delimiters marked, first delimited labeled (optional?)

---section: Foo
title: this is a section
---end

This is a section

Opening delimiter marked and labeled

---section: Foo
title: this is a section
---

This is a section

Opening delimiter marked with colon only

---:
title: this is a section
---

This is a section

Opening delimiter marked with colon and label

---: Foo
title: this is a section
---

This is a section

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.

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](#delimiters), this is just for the sake of discussion): ```html --- 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: ```js { 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 - `options.sections` must be defined as true (example: `matter(string, { sections: true })`) - `file.sections` will be an array or object of "section" objects. Each section object will have a `data` and `content` property. - `file.contents` will contain the text preceding the first section ## 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 ``` 2. Opening delimiter marked ``` ---section title: this is a section --- This is a section ``` 3. Both delimiters marked, first delimited labeled (optional?) ``` ---section: Foo title: this is a section ---end This is a section ``` 4. Opening delimiter marked and labeled ``` ---section: Foo title: this is a section --- This is a section ``` 5. Opening delimiter marked with colon only ``` ---: title: this is a section --- This is a section ``` 6. Opening delimiter marked with colon and label ``` ---: Foo title: this is a section --- This is a section ``` 7. 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

2017-10-19 17:44:21 +00:00

(Migrated from github.com)

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.

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

2017-11-09 21:01:58 +00:00

(Migrated from github.com)

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 :)

Pull request closed

Please reopen this pull request to perform a merge.

Rows
Columns

experimental sections support #51

Assumptions

Delimiters

Pull request closed