# gulp-nunjucks-md

[![Build Status](https://travis-ci.com/mohitsinghs/gulp-nunjucks-md.svg)](https://travis-ci.com/mohitsinghs/gulp-nunjucks-md)
[![npm](https://badge.fury.io/js/gulp-nunjucks-md.svg)](http://badge.fury.io/js/gulp-nunjucks-md)
[![codecov](https://codecov.io/gh/mohitsinghs/gulp-nunjucks-md/branch/master/graph/badge.svg)](https://codecov.io/gh/mohitsinghs/gulp-nunjucks-md)
[![dependencies Status](https://david-dm.org/mohitsinghs/gulp-nunjucks-md/status.svg)](https://david-dm.org/mohitsinghs/gulp-nunjucks-md)
[![devDependencies Status](https://david-dm.org/mohitsinghs/gulp-nunjucks-md/dev-status.svg)](https://david-dm.org/mohitsinghs/gulp-nunjucks-md?type=dev)
[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
[![license MIT](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://github.com/mohitsinghs/gulp-nunjucks-md/blob/master/LICENSE)

> Render nunjucks templates, with markdown and front-matter.

## Install

Install with [npm](https://npmjs.com/package/gulp-nunjucks-md)

```
npm install --save-dev gulp-nunjucks-md
```

## Features

This plugin renders nunjucks to html and performs following tasks additionally –

- If front-matter is found, extracts front-matter data and assigns to a `page` variable.
- If file is markdown and have frontmatter, renders markdown with [marked](https://github.com/chjj/marked).

For a CLI tool, see [njk](https://npm.im/njk).
For compiling/precompiling, see [gulp-nunjucks](https://npm.im/gulp-nunjucks)

## Configuration

- To extend a parent layout with frontmatter, your page should have a front-matter with a `layout` pointing to name of a layout (without extension) in your template directory.
- To set a parent layout for all pages, data passed to plugin should contain a `page.layout` property which points to the name of the layout without extension.
- By default this plugin warps a `content` block around your page. Your parent layout should have a `content` block where processed content will be inserted. You can turn off this behavior by setting `useBlock: false` either in plugin options or in front-matter and declaring blocks normally ( for example, multiple block inheritance).
- In order to render markdown, the page should have `.markdown` or `.md` extension, You can also pass custom options to marked through `marked` option.
- Be aware that combining markdown with nunjucks can lead to undesired output. By setting `escape: false` you can unescape markdown before processing nunjucks to make nunjucks tags work.

## Usage

```js
const gulp = require('gulp')
const nunjucksMd = require('gulp-nunjucks-md')

gulp.task('default', function() {
  return gulp
    .src('src/*.{html,njk,md}') // your pages
    .pipe(
      nunjucksMd({
        path: ['src/templates/'], // nunjucks templates
        data: 'src/data.json' // json data
      })
    )
    .pipe(gulp.dest('dist'))
})
```

## API

Plugin accepts options object, which contain these by default:

```js
var defaults = {
  path: '.',
  ext: '.html',
  extLayout: '.njk',
  data: {},
  useBlock: true,
  block: 'content',
  marked: null,
  escape: true,
  inheritExtension: false,
  envOptions: {
    watch: false
  },
  manageEnv: null
}
```

- `path` - Relative path to templates
- `ext` - Extension for compiled templates, pass null or empty string if yo don't want any extension
- `extLayout` - Extension for the layouts to be extended
- `data` - Data passed to template, either object or path to the json file
- `useBlock` - If true appends a content block. If false only parent template will be extended and no default content block will be wrapped. We can also set it at page level by adding `useBlock : false/true` to frontmatter. Please note that page level configuration will be preferred.
- `block` - Name of content block in your parent template
- `marked` - Custom options for [marked](https://github.com/chjj/marked)
- `escape` - `true` by default. Set it to `false` if you want to use nunjucks in markdown.
- `inheritExtension` - If true, uses same extension that is used for template
- `envOptions` - These are options provided for nunjucks Environment. More info [here](https://mozilla.github.io/nunjucks/api.html#configure).
- `manageEnv` - Hook for managing environment before compilation. Useful for adding custom filters, globals, etc.

For more info about nunjucks functionality, check [https://mozilla.github.io/nunjucks/api.html](https://mozilla.github.io/nunjucks/api.html).

## Example

Here is an example of using gulp-nunjucks md —

Although this example conatains a html with front-matter and nunjucks, you can use markdown as well. Now, suppose we have a file named `src/templates/default.njk` for parent template.

```nunjucks
<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8">
    <title>{{ site.title }} | {{ page.title }}</title>
    <meta name="description" content="{{ page.description }}" />
    <link rel="stylesheet" href="{{ site.url }}/main.css">
  </head>
  <body>
    <main>
      {% block content %}{% endblock %} <!-- Important -->
    <main>
  <script async src="{{ site.url }}/main.js"></script>
  </body>
</html>
```

And we have a json file at `src/data.json`

```json
{
  "site": {
    "title": "Example Site",
    "url": "http://example.com"
  },
  "boxes": [
    {
      "title": "red"
    },
    {
      "title": "green"
    },
    {
      "title": "blue"
    }
  ]
}
```

Also we have a html page with some nunjucks and front-matter in it `src/index.html`.

```nunjucks
---
layout: default
title: "Page Title"
description: "Some Awesome Description"
---

{% for box in boxes %}

<div class="{{ box.title }}">
</div>
{% endfor %}
```

Now in our **gulpfile.js**.

```javascript
var gulp = require('gulp')
var nunjucksMd = require('gulp-nunjucks-md')

gulp.task('default', function() {
  return gulp
    .src('src/*.html')
    .pipe(
      nunjucksMd({
        path: ['src/templates/'],
        data: 'src/data.json'
      })
    )
    .pipe(gulp.dest('dist'))
})
```

This will render to

```html
<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8">
    <title>Example Site | Page Title</title>
    <meta name="description" content="Some Awesome Description" />
    <link rel="stylesheet" href="http://example.com/main.css">
  </head>
  <body>
    <main>
      <div class="red">
      </div>
      <div class="green">
      </div>
      <div class="blue">
      </div>
    <main>
  <script async src="http://example.com/main.js"></script>
  </body>
</html>
```

## Shout-outs

[Carlos G. Limardo](http://limardo.org) and [Kristijan Husak](http://kristijanhusak.com) for [gulp-nunjucks-render](https://npm.im/gulp-nunjucks-render) from which this plugin is derived.
[Sindre Sorhus](http://sindresorhus.com/) for [gulp-nunjucks](https://npm.im/gulp-nunjucks)