node package manager
It’s your turn. Help us improve JavaScript. Take the 2017 JavaScript Ecosystem Survey »


{{md}} NPM version

Convert markdown to HTML. Use wildcard (glob) patterns for files. Like Assemble itself, this helper will automatically determine the correct context to use, or a context may be explicitly passed in as a second parameter.

If you find a bug or have a feature request, please create an issue.


Install with npm:

npm i handlebars-helper-md --save-dev`

Install with bower:

bower install handlebars-helper-md --save-dev`

Register the helper

The easiest way to register the helper with Assemble is to add the module to devDependencies and keywords in your project's package.json:

  "devDependencies": {
    "handlebars-helper-md": "*"
  "keywords": [

Alternatively, to register the helper explicitly in the Gruntfile:

  assemble: {
    options: {
      // the 'handlebars-helper-md' npm module must also be listed in 
      // devDependencies for assemble to automatically resolve the helper 
      helpers: ['handlebars-helper-md', 'foo/*.js']
    files: {
      'dist/': ['src/templates/*.hbs']

Usage Examples

With the helper registered, you may now begin using it in your templates:

{{md 'foo'}}

Gruntfile configuration

assemble: {
  options: {
    partials: ['test/fixtures/includes/*.md'],
  files: {
    'dest/': ['src/*.{hbs,md}']

Optionally pass in a context as the second parameter:

{{md 'foo' bar}}

Wildcard patterns

Globbing patterns may also be used:

{{md 'chapter-*' bar}}

Set marked.js options in the Gruntfile

assemble: {
  options: {
    // marked.js options 
    marked: {
      sanitize: true,
      // see test/fixtures/render/heading.tmpl 
      headings: 'anchors.tmpl'
    partials: ['includes/*.md'],
  files: {
    'dest/': ['src/*.{hbs,md}']


Like Assemble itself, this helper attempts to automatically determine the correct context to use based on the data supplied, but a context can be explicitly passed as a second parameter.

This is how data is merged into the context, in order of precedence:

  1. given context : a context explicitly passed as a second parameter, e.g. {{md 'foo' bar}}, will win over other contexts.
  2. YAML front matter : YAML front matter of the markdown file
  3.[name] : JSON/YAML data file defined in Assemble with a basename matching the name of the markdown file, e.g {{md 'foo'}} matches foo.json
  4. this : A context of this likely means either YAML front matter of the "inheriting" page, the inheriting layout, block expression, or "parent" helper wrapping this helper
  5. Assemble options : Custom properties defined in Assemble options
  6. : Data from (e.g. pkg: grunt.file.readJSON('package.json'))

Related projects

Besides the handlebars-helpers library, which contains more than 120 helpers, Here are some related projects you might be interested in from the Assemble core team.

  • banners: Reusable banners for Node.js projects.
  • fs-utils: File utils from Grunt.js. This is temporary, we'll switch to grunt-file when it's published.
  • glob-object: Globbing for objects and properties.
  • glob-utils: Globbing utilities for Grunt.js and node.js projects.
  • grunt-helpers: Utils for grunt.js projects.
  • grunt-init-helper-mod: Grunt init template for creating a new helper module.
  • handlebars-helper-aggregate: {{aggregate}} handlebars helper. inlines content from multiple files optionally using wildcard (globbing/minimatch) patterns. uses YAML front matter as context for each file. optionally pass in a sorting function.
  • handlebars-helper-autolink: {{autolink}} handlebars helper. Generate relative links from the "current page" to other dest pages.
  • handlebars-helper-br: {{br}} Handlebars helper. Adds <br> tags to generated HTML. Great for prototyping.
  • handlebars-helper-compose: {{compose}} handlebars helper. Similar to {{aggregate}}, but this is a block expression helper that inlines content from multiple files differently, extracting YAML front matter to pass to context for each file. Optionally use wildcard (globbing/minimatch) patterns. Accepts compare function as 3rd parameter for sorting inlined files.
  • handlebars-helper-condense: Remove extra newlines from HTML content.
  • handlebars-helper-disqus: {{disqus}} Handlebars helper. Simplifies adding Disqus comments to your site.
  • handlebars-helper-eachitems: {{eachItems}} handlebars helper.
  • handlebars-helper-ghbtns: {{ghbtn}} handlebars helper. Add github buttons ( to your site.
  • handlebars-helper-include: Handlebars helper, alternative to built-in partials. Similar to handlebars-helper-partial, but this helper will allow wildcard (glob) patterns. Like Assemble itself, this helper will automatically determine the correct context to use, or a context may be explicitly passed in as a second parameter.
  • handlebars-helper-isActive: {{isactive}} handlebars helper. Adds an 'active' class to the 'current page'. Class can be customized.
  • handlebars-helper-jade: {{jade}} handlebars helper, for converting basic Jade templates to HTML.
  • handlebars-helper-less: {{less}} handlebars helper. This helper allows you to use LESS inside style tags in your HTML. By default, the resulting CSS will be rendered inside the <style>...</style> tags of the rendered HTML, but you may alternatively define a destination path using the dest hash option of the helper.
  • handlebars-helper-lorem: {{lorem}} handlebars helper, for generating lorem lorem placeholder text.
  • handlebars-helper-minify: {{minify}} handlebars helper, for minification of HTML with html-minifier.
  • handlebars-helper-moment: {{moment}} handlebars helper. Combines the powers of Assemble, Handlebars.js and Moment.js into a great helper to master time.
  • handlebars-helper-not: {{not}} handlebars helper. Conditionally render a block if the condition is false. This block helper is really just a semantic alternative to {{isnt}}
  • handlebars-helper-paginate: {{paginate}} handlebars helper. Made for Assemble, the static site generator for Node.js, Grunt.js and Yeoman.
  • handlebars-helper-partial: Handlebars helper, alternative to built-in partials. Like Assemble itself, this helper will automatically determine the correct context to use, or a context may be explicitly passed in as a second parameter.
  • handlebars-helper-pkg: {{pkg}} handlebars helper, for retrieving a value from your project's package.json
  • handlebars-helper-post: {{post}} handlebars helper, for including a post, or a list of posts.
  • handlebars-helper-prettify: {{prettify}} handlebars helper, for formatting ("beautifying") HTML, CSS and JavaScript.
  • handlebars-helper-process: {{process}} handlebars helper, for processing raw templates in included content, with the correct context
  • handlebars-helper-rel: Handlebars helper for generating a relative link from the current page to the specified page.
  • handlebars-helper-repeat: {{repeat}} handlebars helper, for duplicating a block of content n times.
  • handlebars-helper-slugify: Convert strings into URL slugs.
  • handlebars-helper-track: {{track}} handlebars helper. Simplify the process of adding Google analytics tracking codes to your web projects.
  • handlebars-helper-twitter: Add {{tweet}} and {{follow}} buttons using handlebars helpers.
  • handlebars-helper-uml: Embed UML diagrams in your handlebars template using
  • lodash-mixin-safename: Get a safe variable name from a given string.
  • logger: Logging utilities for Node.js projects.
  • matchkeys: Return an array of resolved filepaths for specified npm module dependencies. Minimatch patterns can be used.
  • meta: General planning around helpers. Also the place to make requests and suggestions.
  • node-name: Basic utility methods for transforming and handling file paths.
  • sort-object: Sort the keys in an object.
  • strip-yfm: Strip YAML front matter from files.
  • utils: Library of javascript utils
  • utils-compare: Utility compare function, accepts two objects (a,b) and returns 1 if a >= b otherwise -1.
  • utils-concat-array: Takes a string and an array of strings and concatenates the first string to each string in the array.
  • utils-update: Update the properties on an object with the properties from another object.
  • yfm: Helpers and examples for extracting, parsing, and passing context from YAML front matter into your templates. Useful if you need custom programming beyond what Assemble offers by default.

Visit for more information about Assemble plugins.


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, and build the documentation with grunt-readme.


Jon Schlinkert

Brian Woodward


Copyright (c) 2014 Jon Schlinkert, contributors. Released under the MIT license

This file was generated by grunt-readme on Wednesday, February 5, 2014.