Mark­down­ing YAML for Jekyll

While I’m strug­gling to write a lengthy ar­ti­cle, here is a small one, on a lit­tle Jekyll trick I use.

In Jekyll you need to use YAML front mat­ter to add any meta­data to the post or page. Ac­tu­ally, Jekyll “sees” only those files that have the YAML front mat­ter, so it is a some­what im­por­tant thing.

Most of the time this front mat­ter would look like this:

---
lay­out: docs
ti­tle: Re­sources
pre­v_­sec­tion: sites
---

It could seem to be ok. How­ever, as I use Jekyll right on GitHub, my per­fec­tion­ism tells me that the source of all my posts in mark­down should look per­fect when looked at GitHub. And it would ren­der all the mark­down doc­u­ments in­stead of show­ing their con­tent. So, the YAML front mat­ter in that case would look like this:

Bad code

Not that read­able, huh? And the last line sud­denly be­came a header —I don’t think it’s what we could want there.

How­ever, it can be fixed with ease: you just need to add some ex­tra lines in-be­tween:

---

lay­out: docs

ti­tle: Re­sources

pre­v_­sec­tion: sites

---

And this would look so much bet­ter at GitHub:

Good code

In­stead of a use­less header we would get YAML nicely sep­a­rated from con­tent, and every line would be­come a para­graph there.

As most of posts won’t have a lot of meta­data, those ex­tra lines won’t bloat the code. And, in my opin­ion, this code style is also more read­able when you’re work­ing with ac­tual code, so I don’t see any rea­sons why you should­n’t use it all the time for YAML front matters.

The only thing I don’t like there is that YAML is so strict. You can’t add in­dents in the front of data, or use lists with hy­phens here —those could be ren­dered even nicer. Also, if some­one would see any other pos­si­bil­ity to en­hance the read­abil­ity of the YAML front mat­ters —tell me via twit­ter or by is­sues on GitHub.