uhop / grunt-slice-front

Slices a Markdown file in segments separating a front matter in YAML, generates HTML, and applies a template to the result. Useful to generate web pages.

grunt-slice-front

Slices a Markdown file in segments separating a front matter in YAML, generates HTML, and applies a template to the result. Useful to generate web pages.

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-slice-front --save-dev

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

grunt.loadNpmTasks('grunt-slice-front');

The "slice_front" task

Overview

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

grunt.initConfig({
  slice_front: {
    plain: {
      options: {
        markdownItOptions: {
          html: true,
          linkify: true
        },
        templateParams: {
          title: "Demo"
        }
      },
      src:  "tests/demo.md",
      dest: "tests/demo-plain.html"
    }
  }
});

Documentation

Please consult Wiki.

Grunt Options

{
	// options.splitter is a regex that separates the sections of the markdown document.
	splitter:     /^(?:\-(?:\s*\-){2,})|(?:_(?:\s*_){2,})|(?:\*(?:\s*\*){2,})\s*$/gm,

	// options.templateFile is, unsurprisingly, a path to the template file.
	templateFile: path.resolve(__dirname, "../resources/template.jst"),

	// options.templateOptions is a Lodash.template options object. See https://lodash.com/docs#template.
	templateOptions = {},

	// options.templateParams is an arbitrary hash of task-wide variables, made available to the template as params.
	templateParams  = {},

	// options.markdownItOptions is a hash of MarkdownIt options.
	markdownItOptions = {
		typographer: true,
		html:        true
	}
}

Template Variables

The task exposes three different variables to the template file:

• page is a hash of all the YAML variables.
• body is an array of the markdown content and each item in the array a string of converted HTML.
• params is a hash of the data in options.templateParams.

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

• 1.0.4 Refreshed dependencies.
• 1.0.3 Bugfix by @lukehler to support embedded folders, and reduce dependencies.
• 1.0.2 Switched to js-yaml from yaml. Less plugins included by default. New version.
• 1.0.1 Fixed task's name. Made almost all plugins optional.
• 1.0.0 Started by cloning grunt-slice-markdown 0.3.2.

License

BSD

grunt-slice-front's Issues

The task fails on directory creation

While trying to dynamically map all files in a source directory to a clean destination directory, I was found that the task would fail, since it tries to open any files in subdirectories without first creating the those subdirectories.

Here's a quick test configuration you could add to the Gruntfile, just to illustrate. You'll see the task fail as it tries to write to tests/dynamic.

// Read all files from a source directory (tests/) and write the results to a new directory (tests/dynamic/)
dynamic: {
  options: {
    templateFile: "tests/trivial/trivial.html.jst",
    templateParams: {
      title: "Dynamic demo"
    }
  },
  // dynamically mapping files, so it's not just reading demo.md, but also subpage/demo.md, as well.
  files: [
    {
      expand: true,
      cwd: "tests/",
      src:  [
        "*.md",
        "**/*.md"
      ],
      dest: "tests/dynamic/",
      ext: ".html"
    }
  ]
}

The same issue becomes really relevant if you have a task that takes the following:

• src/index.md
• src/about/index.md

... and tries to write the results to a clean destination folder:

• dest/index.html
• dest/about/index.html

Using grunt.file instead of fs resolves this pretty tidily without introducing any new dependencies. I'll get a pull request underway, if you're interested.