search

Milkdown / vscode

MIT License
257 stars 10 forks source link

Enable editing of .md with "front matter" #33

Open shoffmeister opened 2 years ago

shoffmeister commented 2 years ago

Astro (https://astro.build/) is the new hotness in content-rich static site rendering - and they have a concept called "front matter" (https://docs.astro.build/en/guides/markdown-content/) which simply has a "---"-enclosed section at the very top:

---
some: yaml
content: here
---
We now get into markdown territory...

At the moment, milkdown-vscode will corrupt the front matter of any such .md file; the above content will be transformed into

***

some: yaml
content: here
-------------

We now get into markdown territory...

by a roundtrip through milkdown-vscode. It would be quite nice to be able to edit such .md files through milkdown, because Astro itself is all about working inside Visual Studio Code, creating content and implementing site functionality there.

What confuses me a bit is that milkdown suggests that it does gfm-formatted markup (https://github.github.com/gfm/#tables-extension-), and those Astro frontmatter-enriched .md render fine inside the Github renderer (see, for exmple, https://github.com/withastro/astro/blob/main/examples/with-markdown-plugins/src/pages/index.md)

So, in the end, this could possibly be made to work by adjusting the gfm plugin / enabling the gfm?

Perhaps a configuration option on milkdown-vscode along the lines of

Retain front matter in files (yes/no) - Some markdown files may contain a --- ... --- section at the very top - "front matter". If such front matter is present in a markdown file, retain this front matter section unchanged through edits.

?

shoffmeister commented 2 years ago

It just occurred to me that front matter as above can be (re)interpreted as a custom code fence (https://spec.commonmark.org/0.30/#fenced-code-blocks, https://github.github.com/gfm/#fenced-code-blocks) with - being the character used for wrapping the fence block (expanding beyond `` and ~)?

shoffmeister commented 2 years ago

... and just discovered that another static site renderer, Jekyll (https://jekyllrb.com/docs/step-by-step/03-front-matter/), does front matter, too. That renderer also does markdown, so the use case for enabling --- fences would be much broader than just Astro.

For reference, https://jamstack.org/generators/ lists plenty of static site renderers; I'd guess more of these might do front matter, too (with renderer proprietary content that milkdown processing would ignore)