zephraph / nunjucks-markdown Goto Github PK

View Code? Open in Web Editor NEW

49.0 2.0 12.0 40 KB

Markdown extension for Nunjucks. Use your own renderer!

License: MIT License

JavaScript 83.96% HTML 16.04%

nunjucks-markdown's Introduction

nunjucks-markdown

A nunjuck extension that adds a markdown tag. This plugin allows you to choose your own markdown renderer.

Install

npm install nunjucks-markdown --save

Usage

var nunjucks = require('nunjucks'),
    markdown = require('nunjucks-markdown'),
    marked = require('marked');

var env = nunjucks.configure('views');

// The second argument can be any function that renders markdown
markdown.register(env, marked);

Add markdown to your templates

{% markdown %}
Hello World
===========
# Do stuff
{% endmarkdown %}

You can also provide the markdown tag with a template to render

{% markdown "post.md" %}

Note: This method doesn't require a closing tag

As you would expect, you can add tags inside your markdown tag

{% markdown %}
{% include 'post1.md' %}
{% include 'post2.md' %}
{% endmarkdown %}

Using with Gulp

Gulp requires a little more explicit settings than standard npm. See https://mozilla.github.io/nunjucks/api.html#custom-tags

see example-gulpefile.js based on https://gist.github.com/kerryhatcher/1382950af52f3082ecdc668bba5aa11b

var nunjucks = require('nunjucks'),
    markdown = require('nunjucks-markdown'),
    marked = require('marked'),
    gulpnunjucks = require('gulp-nunjucks');
    
var templates = 'src/templates'; //Set this as the folder that contains your nunjuck files

var env = new nunjucks.Environment(new nunjucks.FileSystemLoader(templates));

// The second argument can be any function that renders markdown
markdown.register(env, marked);

gulp.task('pages', function() {
    // Gets .html files. see file layout at bottom
    return gulp.src([templates + '/*.html', templates + '/**/*.html'])
        // Renders template with nunjucks and marked
        .pipe(gulpnunjucks.compile("", {env: env}))
        // output files in dist folder
        .pipe(gulp.dest(dist))
});

Markdown Options

Nunjucks-markdown doesn't require you to use any particular markdown renderer. If you were to use marked here's a good example of how it could be configured.

var marked = require('marked');

marked.setOptions({
  renderer: new marked.Renderer(),
  gfm: true,
  tables: true,
  breaks: false,
  pedantic: false,
  sanitize: true,
  smartLists: true,
  smartypants: false
});

markdown.register(env, marked);

For more information configuration options, checkout marked.

nunjucks-markdown's People

Contributors

Stargazers

Watchers

Forkers

garygreen tedw nicolasartman kevinmpowell kerryhatcher caseyy haavardb jgerigmeyer zomars khawkins98 lfdebrux

nunjucks-markdown's Issues

Prevent parsing nunjucks content from markdown file

Here is my files:

index.html

{% markdown 'README.md' %}

README.md

some markdown content
...
{% include  'anything' %}
...

nunjucks-markdown parse the include tag inside README.md file which is not expected.

I just wondering if there is another way to do that to me.

Clean up and reorganize tests

Our tests are a bit of a mess. We should clean them up, add better patterns, etc.

Incorrectly treating HTML inside a MD file as indented

As per subject, the HTML from within the MD file is recognised as indented, even though it isn't.

When the view renders, it renders as a code block.

Markdown file:

A paragraph

<div class="adam">Boom</div>

Nunjucks file:

{% markdown %}{% include "./README.md" %}{% endmarkdown %}

The paragraph is correctly marked up as such. But the HTML (<div class="adam">) is converted into code (HTML source below):

<p>Here&#39;s where the timeline readme goes.</p>
<p>&lt;div class=&quot;adam&quot;&gt;Boom&lt;/div&gt;
</p>

Indentation causing clipping when using {% include %}

I'm having a similar issue as reported here: #4 (comment)

But it only occurs when I use the {% include 'file.md' %} method. I'm actually seeing different bugs with the first and second lines of the included file depending on the indentation of the call.

Example:

{% markdown %}
{% include 'file.md' %}
# YES
{% endmarkdown %}

{% markdown %}
  {% include 'file.md' %}
  # NO, first line of 'file.md' becomes wrapped in <pre><code> tags, 
  # subsequent lines are fine
{% endmarkdown %}

  {% markdown %}
  {% include 'file.md' %}
  # NO, first line of 'file.md' renders fine, second line has first four 
  # characters trimmed
  {% endmarkdown %}

  {% markdown %}
    {% include 'file.md' %}
    # NO, first and second line errors are BOTH present with 
    # this syntax 
  {% endmarkdown %}

I'm using the grunt-nunjucks-2-html package in a project that has 4 spaces as the indentation method.

Unknown block tag error with gulp-nunjucks-render and nunjucks-markdown

I'm getting this error when using gulp-nunjucks-render:

events.js:160
      throw er; // Unhandled 'error' event
      ^
Template render error: (unknown path) [Line 1, Column 2]
  unknown block tag: markdown
    at Object.exports.prettifyError (/Users/issmbl/htdocs/test-nunjucks-md/node_modules/nunjucks/src/lib.js:34:15)
    at new_cls.render (/Users/issmbl/htdocs/test-nunjucks-md/node_modules/nunjucks/src/environment.js:472:27)
    at new_cls.renderString (/Users/issmbl/htdocs/test-nunjucks-md/node_modules/nunjucks/src/environment.js:328:21)
    at Transform._transform (/Users/issmbl/htdocs/test-nunjucks-md/node_modules/gulp-nunjucks-render/index.js:59:15)
    at Transform._read (/Users/issmbl/htdocs/test-nunjucks-md/node_modules/gulp-nunjucks-render/node_modules/readable-stream/lib/_stream_transform.js:184:10)
    at Transform._write (/Users/issmbl/htdocs/test-nunjucks-md/node_modules/gulp-nunjucks-render/node_modules/readable-stream/lib/_stream_transform.js:172:12)
    at doWrite (/Users/issmbl/htdocs/test-nunjucks-md/node_modules/gulp-nunjucks-render/node_modules/readable-stream/lib/_stream_writable.js:237:10)
    at writeOrBuffer (/Users/issmbl/htdocs/test-nunjucks-md/node_modules/gulp-nunjucks-render/node_modules/readable-stream/lib/_stream_writable.js:227:5)
    at Transform.Writable.write (/Users/issmbl/htdocs/test-nunjucks-md/node_modules/gulp-nunjucks-render/node_modules/readable-stream/lib/_stream_writable.js:194:11)
    at write (/Users/issmbl/htdocs/test-nunjucks-md/node_modules/vinyl-fs/node_modules/readable-stream/lib/_stream_readable.js:623:24)

My Gulp files is as follows:

var gulp = require('gulp');
var nunjucksRender = require('gulp-nunjucks-render');
var markdown = require('nunjucks-markdown');
var marked = require('marked');

marked.setOptions({
    smartypants: false
});

gulp.task('default', function () {
    var env = nunjucksRender.nunjucks.configure(['templates']);
    markdown.register(env, marked);
    
    return gulp.src('templates/*.html')
        .pipe(nunjucksRender())
        .pipe(gulp.dest('dist'));
});

Any suggestions would be greatly appreciated.

Thanks

Refactor markdown tag to enable inner templates

Currently when markdown text is rendered in a tag it's treated like raw data. I'd like to refactor the parser so it handles internal tags.

It'll allow for using templates within markdown as follows:

{% markdown %}{% include "content/readme.md" %}{% endmarkdown %}

jstransformer

Could you add jstransformer for load own markdown renderer? I need CommonMark.

https://github.com/jstransformers/inputformat-to-jstransformer
https://github.com/jstransformers/inputformat-to-jstransformer/blob/master/dictionary.json
https://github.com/jstransformers/jstransformer-commonmark

Thank you

Variables

Looks like nunjucks variables {{ test }} don't resolve inside {% markdown %} content.
Is it a bug or a "feature"? Don't see a reason why they should be disabled...

Indentation prevents processing

Just noticed that if the {% markdown %} block is indented and its contents are indented, it isn't processed and is output as a <pre> tag.

{% markdown %}
# YES
{% endmarkdown %}

{% markdown %}
  # YES
{% endmarkdown %}

  {% markdown %}
  # YES
  {% endmarkdown %}

  {% markdown %}
    # NO
  {% endmarkdown %}

Not the end of the world, but had me confused for a while.

Are there any examples with Markdown parsers other than Marked?

I'm trying to get nunjucks-markdown to work with gulp-nunjucks-renderer and makrdown-it instead of Marked. I would use examples if any where available. They all seem to be based on Marked so whoever wants to use a different parser is on his own.

Does anyone have a working example of using nunjucks-markdown with markdown-it or another parser?

{% markdown "content.md" %}

As suggested by @tedw

Add nunjucks as a peer dependency

Remove nunjucks as a dependency

Knowing what I know now and given the fact that nunjucks is on version 2.0, the direct dependency of nunjucks should be removed. Maybe add it as a peerDependency?