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 = const nunjucksMd = gulp
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.
{{ site.title }} | {{ page.title }} {% block content %}{% endblock %} <!-- Important -->
And we have a json file at src/data.json
Also we have a html page with some nunjucks and front-matter in it src/index.html
.
---layout: defaulttitle: "Page Title"description: "Some Awesome Description"--- {% for box in boxes %} <div class="{{ box.title }}"></div>{% endfor %}
Now in our gulpfile.js.
var gulp = var nunjucksMd = gulp
This will render to
Example Site | Page Title
Shout-outs
Carlos G. Limardo and Kristijan Husak for gulp-nunjucks-render from which this plugin is derived. Sindre Sorhus for gulp-nunjucks