Using Mustache and Grunt for documentation.

Share on FacebookShare on Google+Tweet about this on TwitterShare on Reddit

I recently got tasked to document some databases for a project I’m working on.  I happen to enjoy writing documentation, so I thought it would be no big deal.  How wrong I was.  There’s so many tables, and all of them are filled with columns that lack comments.  It’s my job to find out what all of them do, and document them.  My initial thought was to create a markdown document and capture all of the data in some tables.  As I started to do that, I was really pleased with the result.  Beautifully rendered tables that accurately describe what column does what, how it’s formatted, and why we need it.

Unfortunately, my extremely manual documentation process doesn’t scale.  When I realized that several tables all share the same column name, I started to wonder “what happens if I make a typo and then copy and paste it everywhere throughout my documentation?”.  I started to think of ways to centralize the content, while still being able to keep my content in markdown.  The solution I came up with was Mustache and Grunt.

The first thing I did was break out my project into three folders: templates, data, and final.

  • Templates would hold all of my source documents written in markdown.
  • Data would contain a number of JSON files that contain the actually content I’m documenting.
  • Final contains the rendered output from Grunt.

After that, I created a Gruntfile, and put the following into it:

I’m manually defining the files I want to render in the files array, and I’ve also set it up to watch the templates and data folder for changes, and when they are detected, re-render the content.  I’ve also defined a directory for it to look for partials in.  Partials let me define things like a header globally and include them in multiple files.

My content.json file looks something like this:

You can see I’ve created an object with two properties, column 1, and column 2.  Both are reformatted for markdown (I’m making a table with three columns).  You could probably make this more robust by making column1 and object, and assigning your properties to it, but for me, this was good enough.

Now in my markdown, all I have to do to create a table is:

Now when I run grunt, it will watch both folders and render my markdown out anytime I make a change.  This allowed me to create accurate documentation without having to manually copy and paste over and over.  I hope someone else finds this useful as well.

Leave a Reply

Your email address will not be published. Required fields are marked *