grunt-markdown-site

v4.1.0

Published

2 years ago

The easiest way to create a markdown website with grunt

Downloads

0High
0Medium
0Low

juliandoucette

grunt markdown site generator md static website documentation html templates

grunt-markdown-site

The easiest way to create a markdown website with grunt

Overview

Using the site task, you can create a website using markdown from HTML templates

Getting Started

This plugin requires Grunt ~0.4.0

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

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

grunt.loadNpmTasks('grunt-site');

The site task

site: { //site task
  example: { //multi task name (EG: example)
    options: {
      site: {}, //optional global variables available in all templates (EG: site.title, site.url)
      extend: {}, //optional extend the scope object available in all templates (EG: By adding a utility library like momentjs)
      marked: {}, //optional marked options, see https://github.com/chjj/marked for a detailed list of options
      templates: 'src/templates', //required template directory (all partials and templates must be located inside this directory)
      defaultTemplate: 'default.html' //required default template (used whenever "template" is not defined in a markdown document)
    },
    src: 'src/markdown', //required directory that markdown documents will be loaded from
    dest: 'dest' //required directory that html documents will be output to
  }
}

Although it is possible to customize these locations via the site task options, it is recommended that your directory structure looks something like this:

public //dest directory
includes //template directory
content //src directory

Writing markdown

Markdown documents within the site src directory are parsed by marked and yaml-front-matter.

Basic document example

---
title: Example title # example of a property that will be available inside the template as <%= title %> or <%= doc.title %>
template: default.html # optional template property (this will default to the defaultTemplate if not provided)
---

# Example Headline

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Writing templates

Templates (inside the templates directory) are compiled using lodash templates.

Each template is provided the following scope:

//All templates and partials have access to the following properties as globals and via the scope object
var scope = {
  _: _, //lodash utility library
  path: path, //nodejs stdlib path module
  partial: function (template, scope)  //render a template using the passed or default scope (templates are relative to the templates directory)
  //... : ... //All options.extend properties provided inside of Gruntfile
  //... : ... //All yaml-front-matter properties will be available here EG: title
  content: '...', //the HTML content of the document that is currently being rendered,
  doc: document, //the currently rendering document (including all yaml-front-matter and the content property)
  docs: documents, //all site documents: in the same format as document. This is ideal for creating archives, navs, lists, etc
};

Basic template example

default.html

<%= partial('header.ejs') %>
<main>
  <%= content %>
</main>
<%= partial('footer.ejs') %>

header.html

<!DOCTYPE html>
<html>
  <head>
    <title><%= title %></title>
  </head>
  <body>

footer.html

  </body>
</html>

Basic archive example

default.html

<%= partial('header.ejs') %>
<main>
    <h1><%= title %></h1>
    <nav>
        <ul>
            <% _.each(_.where(docs, {"category": "archive"}), function (_doc) { %>
            <li><a href="/<%= _doc.dest %>"><%= _doc.title %></a></li>
            <% }); %>
        </ul>
    </nav>
</main>
<%= partial('footer.ejs') %>

header.html

<!DOCTYPE html>
<html>
  <head>
    <title><%= title %></title>
  </head>
  <body>

footer.html

  </body>
</html>

Exporting

Documents will be excluded from the export proceedure if:

They do not include a title within yaml-front-matter
They define exclude: true within yaml-front-matter

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

grunt-markdown-site

Overview

Getting Started

The site task

Writing markdown

Basic document example

Writing templates

Basic template example

default.html

header.html

footer.html

Basic archive example

default.html

header.html

footer.html

Exporting