Vincent Durmont

« Back

April 7, 2014

Compile your Markdown with Grunt

These days, I spend a lot of time writing documentation and procedures in order to share my knowledge of Ubleam's system and help the team handling the servers when my contract will be over.

I decided to use markdown since I think the syntax is really easy to learn (anyone will be able to edit my work) and it compiles to HTML (providing a good way to visualize the content).

The drawback is that even if a lot of text editors handle the markdown compilation, I would have to make sure that my HTML files were updated each time I made a modification in a markdown.

Then I discovered grunt-markdown.

grunt-markdown is a lightweight Grunt module that enables you to compile markdown to HTML.

My file structure looks like it:

./
  Gruntfile.js
  package.json
  file1.md
  file2.md
  file3.md
  ...
  html/
    file1.html
    file2.html
    file3.html
    ...

The package.json is:

{
  "name": "mydocumentation",
  "private": true,
  "version": "0.0.1",
  "description": "My documentation.",
  "author": "Vincent DURMONT <vdurmont@gmail.com>",
  "devDependencies": {
    "grunt": "0.4.4",
    "grunt-markdown": "0.5.0"
  }
}

Don't forget to run npm install in order to retrieve the dependencies.

Then, I simply defined a task in the Gruntfile.js:

module.exports = function (grunt) {
  grunt.initConfig({
    pkg: grunt.file.readJSON("package.json"),
    markdown: {
      all: {
        files: [
          {
            expand: true,
            src: "./*.md",
            dest: "html/",
            ext: ".html",
          },
        ],
      },
    },
  });

  grunt.loadNpmTasks("grunt-markdown");
  grunt.registerTask("default", ["markdown:all"]);
};

Finally, a simple:

grunt

in the root directory will generate all my HTML files. Easy!

Check out grunt-markdown on Github.