Fork me on GitHub

grunt-livemd

Generate live-samples from markdown files

With grunt-livemd you can easily generate runtime browser samples from corresponding code-blocks contained in markdown-files.

Supported languages:

In addition to being a simple wrapper for livemd, grunt-livemd also provides a preconfigured html-renderer. When rendered to html, you could either specify a custom lodash-template or use the bundled default one which is designed to resemble github presentation.

Demo

HTML, CSS, Javascript

Click me

<h4 id="click-me">Click me</h4>

h4 {
  color: #0086b3;
}

var el = document.querySelector('#click-me');
el.onclick = function() {
  this.style.color = '#008080'
};

Coffeescript

Click me with coffeescript

<h4 id="click-me-with-coffeescript">Click me with coffeescript</h4>

el = document.querySelector('#click-me-with-coffeescript');
el.onclick = () ->
  this.style.color = '#008080'

SCSS

Styled with SCSS

<h4 id="scss">Styled with SCSS</h4>

@import "bubble.scss";
h4#scss {
  @include bubble(#0086b3, #fff);
}

Less

Styled with Less

<h4 id="less">Styled with Less</h4>

@import "bubble.less";
h4#less {
  .bubble(#0086b3, #fff)
}

Haml

Haml Example

%h4#haml= "Haml Example"

Getting Started

This plugin requires Grunt ~0.4.5

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

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

grunt.loadNpmTasks('grunt-livemd');

The "livemd" task

Overview

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

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

Options

options.layout

Type: String Default value: 'github'

Path to a custom template or a string identifier specifying a bundled layout. Pass in an object containing a template- and data-property to use custom variables inside the template. By default the template has access to the package.json stored in a key pkg.

options.paths

Type: Array Default value: []

Provide an array of include paths to pass to scss and less modules. Path to source is included by default.

options.prefilter

Type: Function Default value: null

Filter the input markdown by providing a function taking the original string as argument and returning the modified string.

options.title

Type: String Default value: ''

Specify the title of a rendered html page. Provide a function to set the title according to source file.

options.wrap

Type: String Default value: '<div class="highlight-example"></div>'

Specify a wrapper for the generated live-samples.

Usage Examples

Default Options

In this example, markdown as well as an html presentation containing live-samples is generated from a README.md-file.

grunt.initConfig({
  livemd: {
    options: {},
    files: {
      'dest/default_options/README.md': ['src/README.md'],
      'dest/default_options/README.html': ['src/README.md']
    },
  },
});

Custom Options

In this example, an html presentation containing live-samples is generated from a markdown-file with custom template and wrapper.

grunt.initConfig({
  livemd: {
    options: {
      wrap: '<div class="live-example"></div>',
      layout: {
        template: 'layout.html',
        data: {
          test: 'This example demonstrates how to use grunt-livemd with a custom template'
        }
      },
      title: function(src) {
        return "Title of " + src;
      }
    },
    files: {
      'dest/custom_options/README.html': ['src/README.md']
    },
  },
});

Advanced Options

This example demonstrates how to strip off unwanted links by making use of a prefilter.

grunt.initConfig({
  livemd: {
    options: {
      options: {
        prefilter: function(string) {
          return string.replace(grunt.config().pkg && grunt.config().pkg.homepage && new RegExp("\\[.*\\]\\(" + grunt.config().pkg.homepage.replace(/[\-\[\]\/\{\}\(\)\*\+\?\.\\\^\$\|]/g, "\\$&") + "\\)", "gi"), "");
        }
      }
    },
    files: {
      'dest/advanced_options/README.html': ['src/README.md']
    },
  },
});

Demo Projects

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History