Feature request: add syntax-highlighting support for YAML and JSON front-matter

[fusion809]

Hi,

I would like to request that this Atom package be given syntax-highlighting support for YAML and JSON front matter (as asciidoc can be used to write posts for Hexo, the static site generator written in JavaScript and Hexo uses YAML/JSON front matter). You could use the existing language-json and language-yaml packages to provide this capability and just set patterns to invoke these two packages, when appropriate. Like YAML front-matter for Hexo has the example format:

---
title:   "Free Operating Systems: A Comparison and Overview"
date:    2016-04-19 +1000
layout:  post

---

Thanks for your time, Brenton

[mojavelinux]

This is supported by Asciidoctor, so we should include it.

Is there anyway to tell the grammar to only match something at the beginning of the file? I guess we could check the language-gfm or language-markup grammars to see how it is handled there.

PR welcome!

[nicorikken]

That doesn't seem to hard: https://github.com/atom/language-gfm/blob/8f6dd61ea3e3254dc5429856727b3078163468d1/grammars/gfm.cson#L257-L269 Copy paste really.

[ldez]

It's an open block or an another mysterious block ?

[nicorikken]

The Asciidoctor user manual seems to be somewhat hesitant in defining the proper grammar, using 'typically' and 'e.g.':

Many static site generators (i.e., Jekyll, Middleman, Awestruct) rely on "front matter" added to the top of the document to determine how to render the content. Front matter typically starts on the first line of a file and is bounded by block delimiters (e.g., ---).

Copying the GFM solution probably covers more than 99% of the cases 😉

[nicorikken]

3 dashes, so no open block

[mojavelinux]

Correct, it is not an open block. In fact, it's not really an AsciiDoc block at all. It is a block that is skimmed off of the top of the document before the AsciiDoc processor sees the source (i.e., an external preprocessor).

It does look a lot like an open block, but with 3 dashes. The content is YAML (or JSON, though most implementations I've seen are YAML).

The only trick to getting this right is that it must be only permitted at the top of the document. That means in the top-level grammar, we need to look for it before blocks. It might even be necessary to add another level of nesting so that we look for "front matter" then "document" where "document" is the current grammar.

[nicorikken]

Can we use the \A selector like GFM does, to only match at the beginning of the document? Still conflicts should be avoided. If I find the time I can prototype.

[ldez]

\Amatch the beginning of string. It's linked to multi-lines support, no matchers for position in the document.

If we do this feature, we can capture only a block beginning and ending with ---

[mojavelinux]

Actually, if you use begin, then \\A does seem to match the beginning of the document only. I tried a sample Markdown document that uses the gfm grammar. If you move the front matter block down by one line, it stops highlighting it.

Here's how it is defined there:

  {
    'begin': '\\A---$'
    'end': '^(---|\\.\\.\\.)$'
    'captures':
      '0':
        'name': 'comment.hr.gfm'
    'name': 'front-matter.yaml.gfm'
    'patterns': [
      {
        'include': 'source.yaml'
      }
    ]
  }

(I don't know why end also include three dots. We should only use ^---$).

We should use the same names as we do for a source block of type YAML.

[mojavelinux]

Basically, front matter is a special form of:

[source, yaml]
----
name: value
----

Except it uses three instead of four delimiters, no attribute list and must be at the start of the file.

[ldez]

conflicts with horizontal rules...

[mojavelinux]

Yes, but the match should win if it is listed first. No?

[ldez]

Tests saves my life! :heart:

See #106

[mojavelinux]

I :heart: to :ear: that!

[nicorikken]

The work of @ldez just got merged, to be released in the upcoming release.

[nicorikken]

@fusion809 Can you check back in now, or after the release, to see if this works for your use-case?

[fusion809]

Just gave it a go and it's doing as intended thanks.