close

  menu      DavidRodenas
CONTACT  
Main article: grunt-frontmatter »

grunt-frontmatter: extracting yaml

February 09, 2015

Published a grunt task able to extract YAML front-matter from files and integrate all into a single JSON file.

Tags: grunt-frontmatter, front-matter, projects


---
layout: post
title: Blogging Lika a Hacker
---

Here I present a new grunt task (yep, another grunt task), the idea of these task is to extract YAML front-matter from files and put them all into one single JSON file.

For long time I have been using grunt-markdown-to-json in my developments (two examples: one was this web page, another is Wenode). The idea of using this grunt task is to generate JSON data to index files and their metadata so it can be loaded statically by a web app. Example:

    .
    ├── Gruntfile.coffee
    ├── package.json
    └── source
        ├── articles
        │   ├── bellflower.md    <--
        │   ├── fiddler.html     <--
        │   └── healthy.md       <--
        ├── index.html
        ├── styles.css
        └── app.js

so it generates a new file like this:

.
├── Gruntfile.coffee
├── package.json
├── source
└── release
    └── articles.json        <--

What is front-matter?

Last few years front-matter is becoming more popular (specially thanks to tools like Jekyll and Assemble). Front-matter is a ipso-facto standard to add metadata to a text file by using YAML. An example of front-matter would be the following markdown:

  ---
  title: Example
  tags:
      - example
      - has_frontmatter
  ---
  # This is an Example

  And metadata is above

In this case, the metadata for this text file is the following JSON:

{
    "title": "Example",
    "tags": ["example", "has_frontmatter"]
}

All metadata is enclosed between an initial ---\n and the following ---\n. Apps and processes reading such text files must be aware of this special heading and they may skip it.

Status of “grunt-markdown-to-json”

The problem of grunt-markdown-to-json was that it just is a wrapper for npm markdown-to-json . I have found two problems repeateadly since the first time that I have used it:

  • It is unable to create new files if they are required: so, for example, if you remove release directory during clean, and then execute the m2j task, the task fails (this is because it is not using grunt tools),

  • It does not accept markdowns with --- (the <hr> symbol): I usually do not use them but they are part of the markdown definition, so it sort of unexpected. After analysing it, it turns out that it does not allows to use --- because it internally is using npm js-yaml and this package believes that there are two front-matters inside the same file, and it fails.

Another issue, but not as relevant, is that it has no normalized name, so, although the package is called grunt-markdown-to-json , the grunt task is called m2j . It makes it use a little bit confusing, but most important, tools like jit-grunt require manual configuration.

New package “grunt-frontmatter”

I have built grunt-frontmatter, it has almost the same interface that has grunt-markdown-to-json but it assumes nothing about files except that they have a front-matter. Potentially it would work with any text file.


« Back to List