Grunt Highlight Plugin

Over the weekend, in a couple hours, I wrote this grunt plugin for Highlight.js. I know that marked does an excellent job of parsing markdown, and can also use highlight, but I wanted something I could use in assemble for HTML parsing or full css/js files.

This was made much easier thanks to the yeoman-gruntplugin project.

Getting Started

This plugin requires Grunt.

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

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

grunt.loadNpmTasks('grunt-highlight');

The "highlight" task

Overview

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

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

Options

options.lang

Type: Boolean Default value: false

If you know the highlight language, use this.

options.useCheerio

Type: Boolean Default value: true

You target files are HTML and you want to parse over them and highlight code blocks. Turn off for raw code input.

options.selector

Type: Boolean Default value: pre code

This is what cheerio will be looking for as code block in your HTML. Only used when useCheerio is true.

Usage Examples

Default Options

grunt.initConfig({
  highlight: {
    task: {
      options: {},
      files: {
        'dest/out.html': ['src/in.html'],
      }
    }
  }
});

Full Code Files

If you want to highlight an entire file then use the following:

grunt.initConfig({
  highlight: {
    task: {
      options: {
        useCheerio: false,
        lang: 'javascript' // treat the file as a javascript file
      },
      files: {
        'dest/highlighted.html': ['src/bunch-o-javascript.js'],
      }
    }
  }
});

Many Files

grunt.initConfig({
  highlight: {
    scripts: {
      options: {
        useCheerio: false,
        lang: 'javascript'
      },
      files: {
        'javascript.html': ['src/script.js']
      }
    },
    styles: {
      options: {
        useCheerio: false,
        lang: 'css'
      },
      files: {
        'stylesheet.html': ['src/style.css']
      }
    }
  }
});

Check out the project on github.