grunt-markdown/README.md

Compile markdown to html. GFM and code highlighting support!

# grunt-markdown

[![Build Status](https://travis-ci.org/treasonx/grunt-markdown.png?branch=master)](https://travis-ci.org/treasonx/grunt-markdown)

This grunt task takes a set of markdown files and converts them to HTML. It supports [GFM](http://github.github.com/github-flavored-markdown/) with code highlighting. The code highlighting is done using [highlight.js](http://softwaremaniacs.org/soft/highlight/en/).

## Getting Started
Install this grunt plugin next to your project's [grunt.js gruntfile](http://gruntjs.com/getting-started) with:

```bash
npm install grunt-markdown --save-dev
```

Then add this line to your gruntfile:

```javascript
grunt.loadNpmTasks('grunt-markdown');
```

## Documentation
Creating a markdown task is simple. For the basic functionality add the following config in your gruntfile:

```javascript
grunt.initConfig({
  markdown: {
    all: {
      files: [
        {
          expand: true,
          src: 'docs/src/*.md',
          dest: 'docs/html/',
          ext: '.html'
        }
      ]
    }
  }
});

```

Here is an example config using all of the options:

```javascript
grunt.initConfig({
  markdown: {
    all: {
      files: [
        {
          expand: true,
          src: 'docs/src/*.md',
          dest: 'docs/html/',
          ext: '.html'
        }
      ],
      options: {
        template: 'myTemplate.jst',
        preCompile: function(src, context) {},
        postCompile: function(src, context) {},
        templateContext: {},
        contextBinder: false,
        contextBinderMark: '@@@',
        autoTemplate: true,
        autoTemplateFormat: 'jst',
        markdownOptions: {
          gfm: true,
          highlight: 'manual',
          codeLines: {
            before: '<span>',
            after: '</span>'
          }
        }
      }
    }
  }
});

```
These are the properties that the `markdown` task accepts:

* `files`: This plugin supports use of the [files API](http://gruntjs.com/configuring-tasks#files) introduced in Grunt 0.4.0. Files may be specified using any one of the [Compact Format](http://gruntjs.com/configuring-tasks#compact-format), [Files Objects Format](http://gruntjs.com/configuring-tasks#files-object-format), or [Files Array Format](http://gruntjs.com/configuring-tasks#files-array-format) (as in the above example).
* `options`: options to be passed to the markdown parser 
    * `template`: If you wish to specify your own html template, use the `template` option. Include the following line: `<%=content%>` where you want the compiled markdown inserted in your template
    * `markdownOptions`: Options passed directly to the markdown parser.
    * `preCompile`: is run before the markdown is compiled
    * `postCompile`: is run after the markdown has been compiled
    * `templateContext`: the default context for template expansion
    * `contextBinder`: this option is useful when we want to bind some parameters directly from markdown files. All data is stored in `templateContext` object.
    * `contextBinderMark`: with this option we can pass any marker between which we can grab your special parameters from markdown templates.
    * `autoTemplate`: if this option is set to true, script will search for template automatically. Template must be placed in this same catalog where markdown files are.
    * `autoTemplateFormat`: the template format when `autoTemplate` is `true`.

### modifying content with preCompile and postCompile

Sometimes there is a need to modify the markdown content prior to compilation.
This is most commonly used to augment the template context with meta data before
expanding the html template. 

#### preCompile

This function is run prior to the compilation of md to html. It has the
following format: 

```javascript
  function(src, context) {
    //do stuff to src and context
    //optionally return the modified src
  }
```

#### postCompile

This function is run after the md has been converted to html. It has the
following format:

```javascript
  function(src, context) {
    //do stuff to src and context
    //optionally return the modified src
  }
```
### templateContext

This object is used to expand your html template. Any data added to this object
will be available in the template using the template syntax `<%=myAttr%>`. 

This can also be a function which is expected to return a context object.

### markdownOptions

Most markdown options are passed as-is to the [marked](https://github.com/chjj/marked) markdown parser. The only option that is processed prior to compiling the markdown is the `highlight` option. If you specify 'auto' or 'manual' the task will handle highlighting code blocks for you using highlight.js. If you pass a custom function as the highlight option it will be used to highlight the code.

* `auto`: Will try to detect the language
* `manual`: will pass the language name from markdown to the highlight function
* `codeLines`: specify text that should wrap code lines

### contextBinder

Below you can see example how to use this option.

```javascript
  markdown: {
    all: {
      files: [
        {
          expand: true,
          src: 'docs/src/*.md',
          dest: 'docs/html/',
          ext: '.html'
        }
      ],
      options: {
        template: 'myTemplate.jst',
        preCompile: function(src, context) {},
        postCompile: function(src, context) {},
        templateContext: {},
        contextBinder: true,
        contextBinderMark: '@@@',
        markdownOptions: {
          gfm: true,
          highlight: 'manual',
          codeLines: {
            before: '<span>',
            after: '</span>'
          }
        }
      }
    }
  }
```

Then inside markdown file we have to put: `<!-- @@@key:value@@@ -->` and it will be equal to:

```javascript
templateContext: {
  key: 'value'
}
```

## License
Copyright (c) 2012-2013 James Morrin
Licensed under the MIT license.