blogdown

Generate HTML with Mustache and Markdown

Blogdown

Generate HTML with Mustache and Markdown

Read the blog post.

  • Provide an easy way to combine Mustache templates with Markdown.
  • Generate static HTML using templates, partials and JSON data.
  • Generate only the files that changed, adding created and modified timestamps.
  • Plain text files only. No database. No setup.
  • Full test coverage

Good enough to give it a shot. Feedback, issues and pull requests welcome.

$ npm install -g blogdown
  • Create src/template.mustache with HTML and a {{{md}}} placeholder somewhere
  • Create src/index.md with Markdown in it
  • Run blogdown from the root of the project directory and inspect the generated site/index.html
  • The template.mustache file in each directory will be used as the mustache template unless an item has a .html or .mustache template defined.
  • The template.json file can be created to inherit JSON properties into each item in the same folder and sub folders
  • A template folder can be created and filled with mustache templates that will be used as partials. Reference the partials with {{>partial-name}}.
  • If JSON files are created in the template folder, the content is merged into the template.json using the file name as the key.

Global configs are stored in a blogdown.json file in the root of your project. The file defines date formats and lists of files.

Blogdown uses moment.js for date formatting. A list of date formats can be configured in the config file:

"dates"   : {
  "long"  : "ddd, DD. MMMM YYYY - HH:mm:ss",
  "short" : "DD.MM.YYYY HH:mm:ss",
  // ...
}

The mustache templates can refer to the dates like this:

  • {{dates.long.created}} for the long format showing the file creation date and time
  • {{dates.long.modified}} for the long format showing the file's last modified date and time
  • {{dates.short.created}}
  • etc ...

You can specify custom lists of files in the global config files:

"lists"      : {
  "articles" : {
    "filter" : "file.path = blog/*",
    "sort"   : "file.created DESC",
    "limit"  : 25
  }
}

An array of items with the configured name will be available in the mustache template:

{{#articles}}
  <a href="{{{file.path}}}"><h3>{{heading}}</h3></a>
  <p>{{tldr}}</p>
{{/articles}}

This will show 25 items from the blog folder ordered newest files first.

By default, items are generated with their file names. If you want to use a different file name, you need to put "file" : { "name" : "different" } in the corresponding .json file.

The model of each item that is passed to Mustache for rendering looks like this:

{
  // File related meta information: 
  file         : {
    path       : 'path/to/file.html',
    name       : 'file',  // without the extension 
    root       : '../..', // relative path to root dir 
    created    : '2013-03-17T22:01:53+01:00',
    modified   : '2013-03-17T22:01:53+01:00',
    active     : true // if this file is currently rendered, otherwise false 
  },
 
  // True if blogdown was called with --publish, otherwise false 
  publish      : true,
 
  // Markdown: 
  md           : '<p>parsed from markdown</p>',
 
  // Formatted dates according to config in "blogdown.json": 
  dates        : {
    article    : {
      created  : 'Sun, 31. March 2013 - 17:24 CET',
      modified : 'Sun, 31. March 2013 - 17:24 CET'
    }
  },
 
  // Lists of items according to config in "blogdown.json": 
  newArticles  : [{ ... }, { ... }],
  coolProjects : [{ ... }, { ... }],
 
  anyProperty  : 'defined in a .json file'
}

To get more information about which templates and items where found and which properties they contained, use --debug (or -d).

$ blogdown --debug
$ blogdown -d

This project was build on top of the hard work of other people:

  • https://github.com/chjj/marked
  • https://github.com/janl/mustache.js
  • https://github.com/timrwood/moment