annotate node_modules/static/README.md @ 101:52e44ee1c791 tip master

enabled all scores in autostart script

Static
======

Markdown and Handlebars static site generator. Transforms files with `.hbs` and `.md` with Handlebars and Markdown respectively.

    npm install static

## Command line interface

    static source.hbs.html target.html

## JavaScript interface

    var static = require('./static');
    static.transform('source.hbs.html', function(buffer) {
      fs.writeFile('target.html', buffer.toString());
    });

## Grunt Interface

In your `Gruntfile.js`:

    grunt.loadNpmTasks('static');

Then in your config, define "static" as a multi task:

    grunt.initConfig({
      static: {
        mySite: {
          // this file will be included before the
          // build is run
          require: ['helpers.js'],
          build: {
            // will treat source as a handlebars
            // template and save at target
            'target.html': 'source.hbs.html',
            // process multiple files into a single file
            'api.html': [
              'header.hbs.html',
              'README.md',
              'footer.html'
            ],
            // specify a specific context for the
            // handlebars template to be run with
            'target2.html': {
              file: 'source.hbs.html',
              context: {
                key: 'value'
              }
            }
          }
        }
      }
    });

In this case, one could invoke: `grunt static:mySite` to run the build.

`require` accepts an array of files to require before static runs, each file must export a function that will recieve a `static` object:

    module.exports = function(static) {

    };

`build` accepts a hash of target file: source file pairs to process. If an array of source files is specified each one will be processed individually and concatenated. If compiling with handlebars an object may be passed that should be in this format:

    {
      file: 'source.hbs.html',
      context: {
        key: 'value'
      }
    }

In `source.hbs.html` `{{key}}` would be available.

## Example

A handlebars file similar to this could be used to generate documentation from a README.md file:

    <ul class="toc">
      {{#include "README.md" select="h3"}}
        <li><a href="#{{id}}">{{innerHTML}}</a></li>
      {{/include}}
    </ul>
    <div class="body">
      {{include "README.md"}}
    </div>

## Handlebars API

### include *{{include filename [select=selector]}}*

Include a file. If `select` is specified a block must be passed. The block will be called once for each selected node (with the context set to the node) from the file and the resulting HTML will be embedded.

## JavaScript API

### transform *static.transform(source, callback)*

Transforms a given file with Handlebars and Markdown if file extensions are present. Calls callback with a buffer containing the transformed file.

### handlebars *static.handlebars*

A reference to the handlebars object static is using. Useful to register new helpers on.

### registerAsyncHelper *static.handlebars.registerAsyncHelper(name, callback)*

Just like `Handlebars.registerHelper` but async. `callback` recieves arguments to the helper (if any) followed by an options object, followed by a callback. Call the callback with your generated output instad of returning.

    static.handlebars.registerAsyncHelper('toc', function(options, callback) {
      static.transform('README.md', function(html) {
        static.$(html, function($) {
          var output = '<ul>';
          $('h3', function() {
            output += '<li>' + this.innerHTML + '</li>'
          });
          callback(output + '</ul>');
        });
      });
    });

### $ *static.$(html, callback)* 

Create a DOM window and jQuery object from the specified HTML. `callback` recieves a `$` cherrio instance. The `select` argument to `include` is implemented with this.


    static.$(html, function($) {
      $('a').each(...);
    });

### modifyDocumentFragment *static.modifyDocumentFragment(html, callback, next)*

Similar to `$`, calls `callback` with a `$` cherrio instance. `$` can be modified within the callback. `next` will be called with the resulting HTML.

    static.modifyDocumentFragment('<ul></ul>', function($) {
      $('ul').append('<li></li>');
    }, function(html) {
      // html === '<ul><li></li></ul>'
    });

### onMarkdown *static.onMarkdown(callback)*

Called anytime after `transform` transforms a markdown document. `callback` is called with the generated HTML and a `next` function that must be called with the modified HTML. Pairs well with `modifyDocumentFragment`.

    static.onMarkdown(function(html, next) {
      next(html);
    });

### addTransform *static.addTransform(fileExtension, callback)*

Transform files passed to *transform* based on file extension. `callback` recieves:
- `buffer` - the file buffer
- `callback` - to be called with the transformed buffer
- `context` - context if transform was invoked from a handlebars helper
- `data` - private handlebars data, also contains `file` which is a reference to the current file

The `html` extension is a noop and is implemented as:

    static.addTransform('html', function(buffer, next, context, data) {
      next(buffer);
    });

### config *static.config*

Defaults to:
  
  {
    addIdsToHeadings: true, //in markdown add ids to h[1-6] tags
    gfm: true, //github flavored markdown
    highlight: function(code, lang) {
      return require('highlight.js').highlight(lang || 'javascript', code).value;
    }
  }