Rework <frontmatter> syntax rules
Opened this issue · 4 comments
Please confirm that you have searched existing issues in the repo
Yes, I have searched the existing issues
Any related issues?
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
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)
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>
)
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.