Rework <frontmatter> syntax rules

[ang-zeyu]

Please confirm that you have searched existing issues in the repo

Yes, I have searched the existing issues

Any related issues?

1753, #2187, #1251

What is the area that this feature belongs to?

Author Usability

Is your feature request related to a problem? Please describe.

Been thinking of this for a while. I think the above 2 more recent linked issues solidify the use case even further.

Not sure if there was any reason for the choice of <frontmatter> as frontmatter syntax.

This type of syntax is overwhelmingly common in SSGs.

// start of page, nothing should preceed it
---
... frontmatter ...
---

... content ...

Describe the solution you'd like

Propose switching to the above syntax. Feature set wise (thinking about overriding of frontmatter properties) there shouldn't be an issue in preserving things. But it is a breaking change and migration work will again be needed.

Benefits:

• Overwhelmingly more conventional, and simpler to type.
• Because <frontmatter> is HTML, it can only be extracted after processing nunjucks + markdown. This makes frontmatter properties unavailable to nj + md processing and very difficult for HTML processing. It is only being used currently for post processing. Example use cases is in linked issues. Some things we can make available with this change are:
  • Make frontmatter properties of the page available as nunjucks variables.
  • Make frontmatter properties of all pages available during processing to all pages (because we can now separate extracting frontmatter from nj->md->HTML)

Cons:

• Breaking change, migration work again needed. (convert <frontmatter> to ---\n...\n--- syntax)
• Can't think of anything otherwise.

On frontmatter merging:

• We support merging <frontmatter> currently from <include>s. (honestly not too sure on the use cases for this)
• There shouldn't be any issue preserving this (<include>-ing an page will include its frontmatter properties)
• But some refactoring on author end may be required in the case the <frontmatter> was <include>-ed via a specific #hash (new syntax only supports 1 frontmatter per file, at the top of the page)

Describe alternatives you've considered

No response

Additional context

No response

[ang-zeyu]

I think this has been the case since day 1 of markbind. My guess is just that --- ... --- wasn't all that common back then.

@damithc do you have any thoughts or context on this?

@tlylt, I thought through #1753 abit more with #2187. Would having frontmatter and frontmatter tags of all pages available as nunjucks variables solve #1753? (filter the pages you want based on page frontmatter tags)

[tlylt]

Is this issue related to https://github.com/MarkBind/markbind/issues/1851? https://github.com/MarkBind/markbind/pull/2145 is completed to add --- as an alternative frontmatter.

Not sure if there was any reason for the choice of as frontmatter syntax. I think this has been the case since day 1 of markbind. My guess is just that --- ... --- wasn't all that common back then.

https://github.com/MarkBind/markbind/issues/1851#issuecomment-1081805682

[ang-zeyu]

completely forgot about that.. 🤦‍♂️ this would just be for deprecating the HTML version.

We support merging <frontmatter> currently from <include>s. (honestly not too sure on the use cases for this)

Specifically, we can support something like

---
mergeWith: someOtherFile1.md, someOtherFile2.md, ...
---

<include>-ing frontmatter will however have to go. (and <include omitFrontmatter>)

[ang-zeyu]

this would just be for deprecating the HTML version.

I looked at the MR a bit closer, the syntax would be the same but the implementation should be moved from markdown to a preprocessing step before nunjucks.