15

When working with Nunjucks templates which requite rendering or compilation is there a standard naming convention to be used to have them processed? i.e. file.nunjucks, file.nunjucks.html, or file.njs etc.

I know that when working with other template languages it's common to use their name as the extension such as file.liquid, file.ejs, etc, but I've not seen much in reference to Nunjucks.

ianyoung
  • 2,863
  • 4
  • 26
  • 31

2 Answers2

21

I personally prefer the extension '.njk', its also something that they have as an example on the Nunjucks docs.

File Extensions

Although you are free to use any file extension you wish for your Nunjucks template files, the Nunjucks community has adopted .njk.

If you are developing tools or editor syntax helpers for Nunjucks, please include recognition of the .njk extension.

Community
  • 1
  • 1
t. Macleod Sawyer
  • 310
  • 2
  • 4
7

Jon Buckley's nunjucks plugin for wintersmith supports template naming convention

*.html
*.nunjucks

See https://github.com/jbuck/wintersmith-nunjucks/issues/8 for proof

So this naming convention is common everywhere wintersmith site generator is used. Especially the *.html seems to be fairly common also elsewhere.

Nunjucks's own documentation uses the *.html in examples of using {% include ..%} and {% extends ..%} tags and it says

...overview of the templating features available in nunjucks. Nunjucks is essentially a port of jinja2, so you can read their docs if you find anything lacking here...

and jinja's own documentation in turn says

...A template is simply a text file. It can generate any text-based format (HTML, XML, CSV, LaTeX, etc.). It doesn’t have a specific extension, .html or .xml are just fine...

My in-house site generator applies the nunjucks preprocessor also to files with extensions: *.md, *.markdown, *.htm, *.html, *.php, *.css, *.js, .htaccess but it can not be considered "common convention".

It might be possible to find out nunjuck's usage statistics and examples of used naming conventions using Google or GitHub or Wolfram Alpha computational knowledge engine or IBM Watson Analytics service...

I think that you can use any naming convention as long as you are able to refactor (rename) it anytime later

xmojmr
  • 8,073
  • 5
  • 31
  • 54
  • Thanks for the example. Would you say this is a common convention that is followed? Can you think of any other examples? – ianyoung Oct 11 '14 at 20:12
  • @Ian see my edited answer for little bit more, but you can get only broad answer to a broad question. Do you have some concrete nunjucks use-case on your mind? Do you have a code base to maintain or are you starting from scratch? What is the estimated site's size (in number of nunjucks-ed files)? – xmojmr Oct 12 '14 at 06:55
  • 1
    Thanks @xmojmr. In this particular case I'm looking to use [gulp-nunjucks](https://www.npmjs.org/package/gulp-nunjucks) or [gulp-nunjucks-render](https://www.npmjs.org/package/gulp-nunjucks-render). It doesn't seem right to give them the .html extension as they rely on template rendering and will eventually be converted into .html files. I know most template languages use a specific extension such as .liquid but I haven't really come across any kind of convention for Nunjucks yet so was hoping to at least try and find some patterns if not solid conventions. – ianyoung Oct 13 '14 at 15:17
  • @Ian in that case you may get some better answer if you add this info to your original question + add the **[gulp](http://stackoverflow.com/questions/tagged/gulp)** tag. The tag has 198 followers.. – xmojmr Oct 13 '14 at 15:55
  • I think the extra specificity warrants a new question (although because it's specific I doubt I'll get any response). In this case I think you've given me enough info for me to accept this answer and I think .nunjucks seems to be a solid convention as long as the template parser is expecting it. Thanks for you help. – ianyoung Oct 13 '14 at 16:45
  • I actually posted [another gulp related question](http://stackoverflow.com/questions/26315911/providing-data-models-to-use-in-gulp-nunjucks-templates) in association with Gulp and Nunjucks at the same time as this one but it didn't get any response. – ianyoung Oct 13 '14 at 16:46
  • @Ian I don't have any detailed knowledge of the gulp-nunjucks toolkits. But nunjucks itself will eat whatever filename you feed it. And gulp-nunjucks seems to behave the same. In my in-house generator I have 1 input folder with sources with files of various names and extensions (`html.template`, `html`, `ts`, `js`, `styl`, `json`, ...) and then 1 output folder with transformed results with extensions like `html`, `css`, `js`. nunjucks is just a servant doing the transformation when it is told to do so. It is not a master dictator. In my in-house tool I'm am the master dictator :) – xmojmr Oct 13 '14 at 17:00
  • 1
    I guess it will just take some trial and error with the gulp-specific implementations of Nunjucks (and also getting used to Node and Gulp) but I imagine it's all possible one way or another. Thanks for all your help and advice. – ianyoung Oct 14 '14 at 15:09
  • 2
    I think some python projects name their Jinja2 templates as `.j2`, I thought this can be a good extension for the @Ian **gulp** use case – Valerio Jun 17 '15 at 13:18