grunt-makedocs

Create documentation for your design patterns whilst keeping your components completely separate. It uses Markdown for the page content and Mustache for the templates.

Getting Started

This plugin requires Grunt ~0.4.5

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-makedocs --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-makedocs');

The "makedocs" task

Overview

In your project's Gruntfile, add a section named makedocs to the data object passed into grunt.initConfig().

grunt.initConfig({
  makedocs: {
    options: {
      // Task-specific options go here.
    },
    files: {
      // Target-specific file lists and/or options go here.
    },
  },
});

Options

options.nav

Type: function Default value: false

Pass through a function to build a navigation menu from the list of pages. The default is false, which does nothing. The function takes a single argument, which is the array of pages containing the details from the YAML front matter, plus a dest object (the URL the page will be built at) and a content object (the page content). A sample function to create an unordered list of links to pages could be:

function(pages) {
  var navPage = "partials/nav.html";
  var output = '<ul>';
  pages.forEach(page, i) {
    output+= '<li><a href="'+page.dest+'">'+page.title+'</a></li>';
  }
  output+= '</ul>';
  grunt.file.write(navPage, output);
}

options.build

Type: Boolean Default value: false

Passes a build value through to the templates, which can be used to include/omit things for a development/live environment. (Currently used to switch between un-/minified versions of CSS etc.).

options.layoutsDir

Type: String Default value: './layouts'

The layouts directory holds Mustache templates for the pages to use. You can use any of the config that you set out in the YAML front matter. Simple!

options.partialsDir

Type: String Default value: './partials'

The partials directory holds Mustache partials. The makedocs task read this directory (and any subdirectories) and creates Mustache partials for use within your layout templates. Useful for including a common header, footer or menu.

options.componentsDir

Type: String Default value: './components'

Finally, the components directory. This pretty much mirrors my sass directory, as each of my .scss files usually maps on to a single component.

Each of the Mustache templates in here is the markup for a single component. For example, the markup for my buttons is:

<button class="btn btn-TYPE btn-SIZE">BUTTON TEXT<i class="icon-ICON"></i></button>

I have a few different TYPES of buttons and a couple of different SIZEs, and there's an optional ICON that can go before or after the button text.

This is put in to a Mustache template as follows:

<button class="btn{{#type}} btn-{{this}}{{/type}}{{#size}} btn-{{this}}{{/size}}">{{#icon-before}}<i class="icon-{{this}}"></i>{{/icon-before}}{{text}}{{#icon-after}}<i class="icon-{{this}}"></i>{{/icon-after}}</button>

When this is rendered on the page, you pass through an object with the type, size, icon-before or icon-after options, and the template returns clean, properly formatted HTML.

Making Pages

Pages are the meat of the documentation. Add a .md file to the pages directory, add an introduction, describe how you work, what your favourite colour is, anything as long as it's relevant.

At the top of each Markdown page is a YAML front matter section.

---

title: Homepage
category: Components
layout: default
id: homepage

---

The important thing to put in here is layout. This chooses which of the templates in the layout directory you want to use to render your page. If you leave it blank, it will look for one called default.mustache.

The other options are passed to the Mustache template. In my example I'm using {{title}} as the page title and {{id}} as an id attribute on the body tag.

The script tags that call a component function is, so far, the way that I'm calling the individual components to the page.

Atomic Design

Using the priciples of atomic design, you can build up your components as separate entities and then combine them on the page.

Usage Examples

Default Options

This is how my system is set up: I put the layouts, partials and components directories in a src directory, along with a pages directory. The Grunt task reads the whole pages directory to make the documentation in a new docs directory.

grunt.initConfig({
  makedocs: {
    docs: {
      options: {
        layoutsDir: 'src/layouts',
        partialsDir: 'src/partials',
        componentsDir: 'src/components'
      },
      files: [
        {
          expand: true,
          cwd: 'src/pages',
          src: ['*.md'],
          dest: 'docs',
          ext: '.html'
        }
      ]
    }
  }
});

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

(Nothing yet)