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.
Answers:
2021 update:: Jinja now officially recommends using the extension .jinja. check docs
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 Vim extension, TextMate extension, Emacs extension, and PyCharm mention no default extension to enforce Jinja highlighting.
Django had already a similar debate about setting a default extension, and ended as a wontfix issue. 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.
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>
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 :
http://docs.ansible.com/ansible/template_module.html
http://docs.ansible.com/ansible/playbooks_intro.html
This is the convention that I use for other projects as well, except django templates.
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
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
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)
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).
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/
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.
2021 update:: Jinja now officially recommends using the extension .jinja. check docs
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 Vim extension, TextMate extension, Emacs extension, and PyCharm mention no default extension to enforce Jinja highlighting.
Django had already a similar debate about setting a default extension, and ended as a wontfix issue. 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.
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>
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 :
http://docs.ansible.com/ansible/template_module.html
http://docs.ansible.com/ansible/playbooks_intro.html
This is the convention that I use for other projects as well, except django templates.
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
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
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)
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).
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/