gulp-nunjucks-md v2.3.2
gulp-nunjucks-md
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 acontent
block where processed content will be inserted. You can turn off this behavior by settinguseBlock: 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 throughmarked
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 templatesext
- Extension for compiled templates, pass null or empty string if yo don't want any extensionextLayout
- Extension for the layouts to be extendeddata
- Data passed to template, either object or path to the json fileuseBlock
- 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 addinguseBlock : false/true
to frontmatter. Please note that page level configuration will be preferred.block
- Name of content block in your parent templatemarked
- Custom options for markedescape
-true
by default. Set it tofalse
if you want to use nunjucks in markdown.inheritExtension
- If true, uses same extension that is used for templateenvOptions
- 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
5 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago