YAML frontmatter

[sencer]

Highlighting and folding for YAML frontmatter many people using in their markdown files.

[kyoh86]

Why isn't this merged? @tpope

[mjm]

This would be really nice to have. I haven't been able to track down any other support for highlighting this frontmatter correctly in Vim.

[tpope]

The reason it isn't merged is because it isn't Markdown! Every system I've seen that uses YAML frontmatter accepts HTML along side Markdown, yet I don't see support for it in html.vim.

Setting aside semantics, I'm reticent to throw another syntax file into the hairiest syntax highlighter I've ever worked on, and that's before counting the embedded HTML, CSS, JavaScript, and custom highlighted languages in code blocks that I already have to contend with.

I do support frontmatter in vim-liquid, which isn't exactly the right place to put it either, but it is closer to the right abstraction layer, supporting HTML, Markdown, and other markup languages in one go. I think it's common for a lot of these frontmatter using frameworks to pair it with Liquid? Jekyll does so, at least.

[mjm]

Fair enough. After posting that, I found a one-liner to mark that area as comments, which I think is good enough for what I need.

[RichardDooling]

I found this one, which handles both --- and ... in 2nd boundary

syntax include @yaml syntax/yaml.vim
syntax region yamlFrontmatter start=/%^---$/ end=/\v^%(.{3}|-{3})$/ keepend contains=@yaml

[mipmip]

Here's are folding functions for markdown that also folds frontmatter yaml with nested nodes. I glued together code from https://habamax.github.io/2019/03/07/vim-markdown-frontmatter.html and https://github.com/pedrohdz/vim-yaml-folds.

[jdorel]

Isn't this supposed to end with --- ?

[tpope]

This will cause an error if b:markdown_frontmatter isn't defined.

[tkapias]

I corrected this code and added TOML too, I made a pull request to vim/vim #9112 .

I mentioned this place in my commit.

[tkapias]

Following my attempt to PULL this functionality on vim/vim#9112, I come back here to defend the topic of including front matter support with Markdown.

I revised the code since vim/vim#9112, the last version is in these 2 files:

• ftplugin/markdown.vim
• syntax/markdown.vim

Basically, if there is a front matter in the Markdown file, written in YAML (most common) or TOML (competitor), the syntax highlighting and folding adapt to the front matter part without impacting the rest.

The addition of these features has been stagnant since 2018 following the latest reply from @tpope. He suggested I change his mind before experimenting first here.

Basically @tpope had 2 blockers:

1. The syntax file was already complex to maintain. I think that this argument can be dismissed because of the small amount of modification needed at the end.

2. The fact that the front matter would be out of the original scope of Markdown, comparing it to additional embedded semantics.

I think that in the case of Vim this feature is special:

• Technically it is upstream of Markdown and does not mix with it, so it is easy to support without interfering with the core.
• Unlike other features that are often tool specific and require a very custom plugin or pipeline, front matter in Yaml, Toml or Json (let's forget about that one) are common to many tools with a unique implementation for many usages.
• But more deeply, I think there is little use for the vanilla Markdown plugin on Vim without this feature:
  • Developers use a lot of additional features and turn to Vim or VScode a lot, but they have to customize their configuration anyway, there is no unique plugin suitable to cover all the cases. Most of them would be for native front matter support since it doesn't disrupt anything.
  • People who edit vanilla Markdown content frequently do so for note-taking or short texts, in which case, on Vim they quickly find themselves lacking some feature for classification or metadata. Or they work on files that are organized by file system, but that often means they are using a note-taking tool or a dedicated CMS, not Vim.
  • People who write Markdown publications necessarily need features like those offered by exports to Pandoc, the most basic of which is the management of front matter values. And Vim may be the only platform that allows you to easily build a clean and light pipeline for that, but nobody knows that because a lot of poorly designed markdown editors have arrived in the last few years.

I use Markdown for taking notes and writing paper or web publications. In these three cases I use a front matter. I've had to deal with dozens of tools, many features were inconsistent but not this one.

[tpope]

• Technically it is upstream of Markdown and does not mix with it, so it is easy to support without interfering with the core.

Easy to add, not easy to support. You have no idea what the support cost will be, and you won't be the one to pay it. But I'm not even sure "easy to add" is a given, since the very first line of your patch has a syntax error: VimL does not feature a not keyword. This is just the first of many mistakes.

• But more deeply, I think there is little use for the vanilla Markdown plugin on Vim without this feature:

You are writing this on a site that hosts literally millions of README files written in Markdown, not a one of them using frontmatter. What's more, the text field you typed your comment into supports Markdown and I don't see you using any frontmatter. Your whole argument reeks of bad faith.

[tpope]

This assumes the whole file is processed top to bottom, which isn't true.

[tpope]

This should start with markdown. Syntax groups are global.

[tpope]

Let me just add, for those unfamiliar, this feature can be implemented externally in after/syntax/markdown.vim. I'm not standing in the way of anyone who wants to highlight frontmatter.