rc-web@69: Static
rc-web@69: ======
rc-web@69: 
rc-web@69: Markdown and Handlebars static site generator. Transforms files with `.hbs` and `.md` with Handlebars and Markdown respectively.
rc-web@69: 
rc-web@69:     npm install static
rc-web@69: 
rc-web@69: ## Command line interface
rc-web@69: 
rc-web@69:     static source.hbs.html target.html
rc-web@69: 
rc-web@69: ## JavaScript interface
rc-web@69: 
rc-web@69:     var static = require('./static');
rc-web@69:     static.transform('source.hbs.html', function(buffer) {
rc-web@69:       fs.writeFile('target.html', buffer.toString());
rc-web@69:     });
rc-web@69: 
rc-web@69: ## Grunt Interface
rc-web@69: 
rc-web@69: In your `Gruntfile.js`:
rc-web@69: 
rc-web@69:     grunt.loadNpmTasks('static');
rc-web@69: 
rc-web@69: Then in your config, define "static" as a multi task:
rc-web@69: 
rc-web@69:     grunt.initConfig({
rc-web@69:       static: {
rc-web@69:         mySite: {
rc-web@69:           // this file will be included before the
rc-web@69:           // build is run
rc-web@69:           require: ['helpers.js'],
rc-web@69:           build: {
rc-web@69:             // will treat source as a handlebars
rc-web@69:             // template and save at target
rc-web@69:             'target.html': 'source.hbs.html',
rc-web@69:             // process multiple files into a single file
rc-web@69:             'api.html': [
rc-web@69:               'header.hbs.html',
rc-web@69:               'README.md',
rc-web@69:               'footer.html'
rc-web@69:             ],
rc-web@69:             // specify a specific context for the
rc-web@69:             // handlebars template to be run with
rc-web@69:             'target2.html': {
rc-web@69:               file: 'source.hbs.html',
rc-web@69:               context: {
rc-web@69:                 key: 'value'
rc-web@69:               }
rc-web@69:             }
rc-web@69:           }
rc-web@69:         }
rc-web@69:       }
rc-web@69:     });
rc-web@69: 
rc-web@69: In this case, one could invoke: `grunt static:mySite` to run the build.
rc-web@69: 
rc-web@69: `require` accepts an array of files to require before static runs, each file must export a function that will recieve a `static` object:
rc-web@69: 
rc-web@69:     module.exports = function(static) {
rc-web@69: 
rc-web@69:     };
rc-web@69: 
rc-web@69: `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:
rc-web@69: 
rc-web@69:     {
rc-web@69:       file: 'source.hbs.html',
rc-web@69:       context: {
rc-web@69:         key: 'value'
rc-web@69:       }
rc-web@69:     }
rc-web@69: 
rc-web@69: In `source.hbs.html` `{{key}}` would be available.
rc-web@69: 
rc-web@69: ## Example
rc-web@69: 
rc-web@69: A handlebars file similar to this could be used to generate documentation from a README.md file:
rc-web@69: 
rc-web@69:     <ul class="toc">
rc-web@69:       {{#include "README.md" select="h3"}}
rc-web@69:         <li><a href="#{{id}}">{{innerHTML}}</a></li>
rc-web@69:       {{/include}}
rc-web@69:     </ul>
rc-web@69:     <div class="body">
rc-web@69:       {{include "README.md"}}
rc-web@69:     </div>
rc-web@69: 
rc-web@69: ## Handlebars API
rc-web@69: 
rc-web@69: ### include *{{include filename [select=selector]}}*
rc-web@69: 
rc-web@69: 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.
rc-web@69: 
rc-web@69: ## JavaScript API
rc-web@69: 
rc-web@69: ### transform *static.transform(source, callback)*
rc-web@69: 
rc-web@69: Transforms a given file with Handlebars and Markdown if file extensions are present. Calls callback with a buffer containing the transformed file.
rc-web@69: 
rc-web@69: ### handlebars *static.handlebars*
rc-web@69: 
rc-web@69: A reference to the handlebars object static is using. Useful to register new helpers on.
rc-web@69: 
rc-web@69: ### registerAsyncHelper *static.handlebars.registerAsyncHelper(name, callback)*
rc-web@69: 
rc-web@69: 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.
rc-web@69: 
rc-web@69:     static.handlebars.registerAsyncHelper('toc', function(options, callback) {
rc-web@69:       static.transform('README.md', function(html) {
rc-web@69:         static.$(html, function($) {
rc-web@69:           var output = '<ul>';
rc-web@69:           $('h3', function() {
rc-web@69:             output += '<li>' + this.innerHTML + '</li>'
rc-web@69:           });
rc-web@69:           callback(output + '</ul>');
rc-web@69:         });
rc-web@69:       });
rc-web@69:     });
rc-web@69: 
rc-web@69: ### $ *static.$(html, callback)* 
rc-web@69: 
rc-web@69: 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.
rc-web@69: 
rc-web@69: 
rc-web@69:     static.$(html, function($) {
rc-web@69:       $('a').each(...);
rc-web@69:     });
rc-web@69: 
rc-web@69: ### modifyDocumentFragment *static.modifyDocumentFragment(html, callback, next)*
rc-web@69: 
rc-web@69: Similar to `$`, calls `callback` with a `$` cherrio instance. `$` can be modified within the callback. `next` will be called with the resulting HTML.
rc-web@69: 
rc-web@69:     static.modifyDocumentFragment('<ul></ul>', function($) {
rc-web@69:       $('ul').append('<li></li>');
rc-web@69:     }, function(html) {
rc-web@69:       // html === '<ul><li></li></ul>'
rc-web@69:     });
rc-web@69: 
rc-web@69: ### onMarkdown *static.onMarkdown(callback)*
rc-web@69: 
rc-web@69: 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`.
rc-web@69: 
rc-web@69:     static.onMarkdown(function(html, next) {
rc-web@69:       next(html);
rc-web@69:     });
rc-web@69: 
rc-web@69: ### addTransform *static.addTransform(fileExtension, callback)*
rc-web@69: 
rc-web@69: Transform files passed to *transform* based on file extension. `callback` recieves:
rc-web@69: - `buffer` - the file buffer
rc-web@69: - `callback` - to be called with the transformed buffer
rc-web@69: - `context` - context if transform was invoked from a handlebars helper
rc-web@69: - `data` - private handlebars data, also contains `file` which is a reference to the current file
rc-web@69: 
rc-web@69: The `html` extension is a noop and is implemented as:
rc-web@69: 
rc-web@69:     static.addTransform('html', function(buffer, next, context, data) {
rc-web@69:       next(buffer);
rc-web@69:     });
rc-web@69: 
rc-web@69: ### config *static.config*
rc-web@69: 
rc-web@69: Defaults to:
rc-web@69:   
rc-web@69:   {
rc-web@69:     addIdsToHeadings: true, //in markdown add ids to h[1-6] tags
rc-web@69:     gfm: true, //github flavored markdown
rc-web@69:     highlight: function(code, lang) {
rc-web@69:       return require('highlight.js').highlight(lang || 'javascript', code).value;
rc-web@69:     }
rc-web@69:   }