static

    2.0.0 • Public • Published

    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; } }

    Keywords

    none

    Install

    npm i static

    DownloadsWeekly Downloads

    706

    Version

    2.0.0

    License

    none

    Last publish

    Collaborators

    • syntacticx
    • kpdecker
    • eastridge