CODEWITHSUNDEEP
pythontemplatesfile-extensionjinja2
Chris Tonkinson
Chris Tonkinson

Reputation: 14459

Is there an idiomatic file extension for Jinja templates?

I need to programatically distinguish between Jinja template files, other template files (such as ERB), and template-less plain text files.

According to Jinja documentation:

A Jinja template doesn’t need to have a specific extension: .html, .xml, or any other extension is just fine.

But what should I use when an explicit extension is required? .py is misleading, and any search including the words "jinja" and "extension" are badly searchwashed by discussion around Jinja Extensions.

I could easily dictate a project-wide convention (.jnj or .ja come to mind) but this is for open source so I don't want to buck the trend if there's already established practice somewhere.

EDIT 1: Again, I understand that the Jinja project — purposefully — does not define a default file extension. I'm asking if there are any unofficial conventions that have emerged for circumstances where one is desired for some project-specific reason.

EDIT 2: Clarification: This is not for HTML content.

Upvotes: 128

Views: 60997

Answers (9)

user8395964
user8395964

Reputation: 142

"i like other way: *.j2.html ... syntax highlight by any editor"
- @Andor at comment

  • In vscodium, i used extension samuelcolvin.jinjahtml ,
  • which provides syntax highlighting for not just the html, but also for the embedded templates as well
  • on saving a blank file (on os win 10) with language-mode as jinja-html shows extensions as *.jinja;*.jinja2;*.j2;*.html.j2.
  • and likewise *.xml.j2;*.xml.jinja;*.xml.jinja2 for jinja-xml (in-case u want to hint about use of xhtml)
  • j2 would be not informative enough, and as many have said above, now even contradictory as well

so, my choice too would be .html.jinja and .xhtml.jijna

Also, github also recognised this and performs highlight for both the html and jinja. Whereas with .jinja.html, it only does html's syntax highlighting.

Upvotes: 0

Assem
Assem

Reputation: 12077

2021 update:: Jinja now officially recommends using the extension .jinja. See docs

2020 update: Things changed since I wrote this answer, .jinja2 and .j2 are trending.

Jinja Authors did not define a default extension. Most of Jinja template editors like TextMate extension, Emacs extension, and PyCharm mention no default extension to enforce Jinja highlighting.

Django already had a request for setting such a default extension, which ended up as a wontfix issue after some debate. I quote from the closing message:

Filetype detection based on extension is flawed for the very reasons described in these comments, so you have to do some internal inspection, just like MIME type detection works.

I suggest that you should use your own since there is no common one.

Upvotes: 84

Johnride
Johnride

Reputation: 8736

Ansible uses the .j2 extension.

I couldn't find a definitive documentation about that precise point but we see occurences of the .j2 extension in many places of their documentation :

If you look for .j2 in the following pages you'll see many occurences :

https://docs.ansible.com/ansible/latest/collections/ansible/builtin/template_module.html https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html

This is the convention that I use for other projects as well, except django templates.

Upvotes: 53

Wojciech Jakubas
Wojciech Jakubas

Reputation: 1673

As mentioned on official webpage, file extension does not matter but for syntax highlighting some IDEs will work with .jinja. This is also the case for latest Jinja 3.0 version.

Template File Extension As stated above, any file can be loaded as a template, regardless of file extension. Adding a .jinja extension, like user.html.jinja may make it easier for some IDEs or editor plugins, but is not required. Autoescaping, introduced later, can be applied based on file extension, so you’ll need to take the extra suffix into account in that case.

Another good heuristic for identifying templates is that they are in a templates folder, regardless of extension. This is a common layout for projects.

You can check latest version here: https://jinja.palletsprojects.com/en/3.0.x/templates/

Upvotes: 1

Migwell
Migwell

Reputation: 20107

IntelliJ's PyCharm uses .jinja2 as their pattern for recognizing Jinja2 templates. For that reason I use the same (and recommend others do so too)

pycharm filetypes

Upvotes: 27

geerlingguy
geerlingguy

Reputation: 4802

I wanted to add an additional answer in 2020, as recently the Jinja2 project decided to drop the '2' from the name... meaning it's now just "Jinja".

Ansible still uses .j2 in a lot of documentation, but seeing as the official Jinja template engine documentation now recommends .jinja if you want to use something other than non-Jinja-specific file extensions (see docs here, or when the change was added), I think people will start moving that way (and dropping the use of .j2 or .jinja2).

Upvotes: 19

rd2
rd2

Reputation: 331

Just FYI - Johnride above mentioned about Ansible using .j2 as their convention for template file which is correct, just pointing out the "best practices" documented they have now put out, which mentions:

templates end in .j2

Upvotes: 13

Kiran Jonnalagadda
Kiran Jonnalagadda

Reputation: 2826

I use .html.jinja2, .js.jinja2, .css.jinja2 etc to indicate that (a) it's a Jinja2 template, and (b) will compile into a HTML, JS or CSS file. I like the .j2 choice in Ansible, but IMO using .jinja2 makes it easier for a new contributor to guess what templating language is being used.

For Flask users, since auto-escaping is nice to have:

def _select_jinja_autoescape(filename):
    """
    Returns `True` if autoescaping should be active for the given template name.
    """
    if filename is None:
        return False
    return filename.endswith(('.html', '.htm', '.xml', '.xhtml',
        '.html.jinja', '.html.jinja2', '.xml.jinja', '.xml.jinja2',
        '.xhtml.jinja', '.xhtml.jinja2'))

app.jinja_env.autoescape = _select_jinja_autoescape

Upvotes: 10

elemel21
elemel21

Reputation: 21

I use .jnj extension - and for syntax highlighting and for snippets in vim I just copied, renamed and tweaked settings for twig.

When I need some settings for html (like commenting, tag balancing, indenting etc) in jinja template, I also have a function set a time ago to work with PHP and WordPress - it toggles to html and back to previous filetype:

let g:my_file_type = 0

function! ToggleFileType()
  if g:my_file_type == 0
      set ft=html
      let g:my_file_type = 1
  else
      filetype detect
      let g:my_file_type = 0
  endif
endfunction

And it is bound to F12 key with nmap <silent> <F12> :call ToggleFileType()<CR>

Upvotes: 2

Related Questions