Is there an idiomatic file extension for Jinja templates?

Question

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.

Exurbanite

Side note for others who were found this while searching in the context of HTML: one thing to be careful about is that file extensions have consequences as far as HTML autoescapes are concerned. If you are loading macros for use in an HTML template, {% import "whatever.html" as foo %} will act unsurprisingly while {% import "whatever.jinja" as foo %} will lead autoescapes like > becoming >. I suspect this is part of why a lot of Django and Flask users end up using .html. – Toilet

@Toilet could you elaborate on that? I works fine for me. HTML form the macro is added as working HTML to the template, although I am using .html.j2 as extension for them all. – Peridotite

Answer 1

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.

Interceptor

You're right, I know they don't define a default (and that decision was made with care and thought) but my project requires an explicit extension - I'm asking if there are any unofficial conventions which have emerged (before simply choosing one arbitrarily). – Exurbanite

as far as I know, there is one. Personally, I use html. – Interceptor

if it was there a common extension, developers will tend to implement it in editors since most of those editors are developed by community – Interceptor

I am not working on a web project. Even if I was, html would not be appropriate as again, it does not distinguish between an HTML file with Jinja, and one without (which is what I need to do). – Exurbanite

so I suggest use your own since there is no common one. – Interceptor

I use .jinja2, haha. – Ultima

This answer is outdated. Please refer to answer my @Migwell instead. .jinja2 is pretty much what you should use. – Sensillum

@Sensillum you are confused .jinja2 became .jinja, check the official documentation. – Interceptor

@bigOther well in Pycharm for instance .jinja is not recognized but .jinja2 is. Would you mind linking to the official documentation? – Sensillum

@Sensillum pycharm should follow the new standard by creators, official documentation here: jinja.palletsprojects.com/en/3.0.x/templates/… – Interceptor

I still don't get why it's called jinja2 when the version number is now 3.x 😅 Regardless, the docs say: > 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. – Cargill

Answer 2

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.

Persimmon

Sublime Text users may be interested to learn that it recognises the .j2 extension, and can, for example, detect that *.html.j2 is an HTML jinja template. Very cool. – Maurist

I use the other way round like template.j2.html. Thus it could be syntax highlighted by any editors, but still marked it as being a template. – Transience

Answer 3

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)

Rigveda

I don't see "Jinja 2 Template" or *.jinja2 in my list of file types. I'm running 2018.3 Community Edition with very few extensions/plugins. EDIT: I bet this is specific to Professional Edition: jetbrains.com/help/pycharm/configuring-template-languages.html – Helios

Answer 4

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).

Loving

Answer 5

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

Hallucinogen

Answer 6

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

Korte

Answer 7

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>

Formal

Answer 8

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/

Albertinealbertite

Answer 9

"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.jina

Pitre