Simple Language-agnostic Documentation Compiler

This plugin requires Grunt ~0.4.1

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-sildoc --save-dev

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

grunt.loadNpmTasks('grunt-sildoc');

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

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

sildoc is the acronym for Simple Language-agnostic Documentation Compiler (Si.L.Do.C.). Its goal is to make easier the procedure of generating project documentation, by allowing the developer to use Grunt's internal templating processor to process documents with external custom data. This README file itself was generated with this plugin.

If no options are specified, the generated document will be the result of all its source files concatenated in loading order. No data will be available inside the template processor.

In this example, the file dest/document.md is built starting from src/header.md.jst, src/content.md.jst, and src/footer.md.jst.

grunt.initConfig({
  sildoc: {
    options: {},
    files: {
      'dest/document.md': ['src/header.md.jst', 'src/content.md.jst', 'src/footer.md.jst']
    }
  }
})

Please, note that if we had used globbing (such as src/*.jst) as source, the concatenating order would been: content, footer, and header. Therefore, the declaration order of the sources is important, when we don't use a template file.

It's possibile to specify options globally (per task) and/or locally (per target). All the options (except meta and data) can be specified either globally or locally. Instead, meta option can be used only to specify global data (consumed by all the targets), and data option can be used to specify local data (consumed by the specific target only). Inside the template processor, global and local data are mixed together and available via the meta object.

When a template file is specified, all the sources are considered partials and loaded only if their file name follows a simple rule: a leading underscore into the filename (for example, _header.md.jst, _footer.txt, etc.). If the rule isn't satisfied, the file is discarded and a warning is printed out on the console. Inside the template it will be possibile to reference at those partials via the partials object. (Inside this object, the name of the partial is the same of its filename, stripped out of the leading underscore and all the suffixes).

If an index is required, a <%= index %> tag must be defined into the template, at the position where we want it to be inserted. Currently only GitHub Flavoured Markdown indeces are supported. (Github automatically generates the link reference for each heading in document, so the index just targets the link to that reference.)

In this example, the file dest/document.md is built starting from src/_header.md.jst, src/_content.md.jst, and src/_footer.md.jst. The template src/document.md.jst is used.

The file document.md.jst:

<%= partials.header %>
<%= partials.contents %>
<%= partials.footer %>

The file _header.md.jst:

# HEADER

<%= index %>

## Introduction

<%= meta.loremIspum %>

The file _content.md.jst:

## CONTENTS

<% for (var i = 0; i < 10; i++) { %>
    <%= meta.loremIpsum %>
<% } %>

The file _footer.md.jst:

---
<%= meta.name %> - Copyright (c) <%= grunt.template.today('yyyy') %>

The task:

grunt.initConfig({
  sildoc: {
    options: {
      meta: {
        loremIpsum: 'Lorem ipsum dolor sit amet, consectetur adipisicing elit.',
        name: 'document'
      },
      template: 'src/document.md.jst',
      index: 'gfm'
    },
    files: {
      'dest/document.md': ['src/_*.jst']
    }
  }
})

That's what we should obtain as result:

# HEADER

* [Introduction](#introduction)
* [CONTENTS](#contents)

## Introduction

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

## CONTENTS

Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
Lorem ipsum dolor sit amet, consectetur adipisicing elit.

---
document - Copyright (c) 2013

NOTE: due to the recursive nature of the internal template processor, to avoid the unwanted processing of template tags, you MUST insert an exclamation point (!) between the opening angular parenthesis and percent sign (<!%). These forcedly unmanaged tags will be restored to their correct values once the template will be completely processed, just before to write the results on disk.

Any contribution to improve the project and/or expand it is welcome.

If you're interested in contributing to this project, take care to maintain the existing coding style.

The project follows these standard, so please you do it too:

• SemVer for version numbers
• Vandamme for changelog formatting
• EditorConfig for cross-editor configuration

To contribute:

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

See the CHANGELOG file distributed with the project.

Copyright (c) 2012-2013 Marco Trulla.
Released under the MIT license.

See the LICENSE file distributed with the project.