❤
npm
Sign UpSign In

This package has been deprecated

Author message:

This package is no longer maintained. https://npm.im/njk is a cli tool and better alternative of it with more features.

gulp-nunjucks-md

2.3.2 • Public • Published

gulp-nunjucks-md

Build Status npm codecov dependencies Status devDependencies Status JavaScript Style Guide license MIT

Render nunjucks templates, with markdown and front-matter.

Install

Install with npm

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.

For a CLI tool, see njk. For compiling/precompiling, see 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

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:

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
  • 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.
  • 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.

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.

<!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

{
  "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.

---
layout: default
title: "Page Title"
description: "Some Awesome Description"
---
 
{% for box in boxes %}
 
<div class="{{ box.title }}">
</div>
{% endfor %}

Now in our gulpfile.js.

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

<!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 and Kristijan Husak for gulp-nunjucks-render from which this plugin is derived. Sindre Sorhus for gulp-nunjucks

Readme

Keywords

Package Sidebar

Install

npm i gulp-nunjucks-md

Repository

github.com/mohitsinghs/gulp-nunjucks-md

Homepage

github.com/mohitsinghs/gulp-nunjucks-md

Weekly Downloads

4

Version

2.3.2

License

MIT

Unpacked Size

33.4 kB

Total Files

40

Last publish

Collaborators

  • npm
Try on RunKit
Report malware