Topolearn

Learn Jinja

Fast, expressive Python template engine for HTML, config files and more

13 lessons · 2 hours · 4 levels · covers Jinja 3.1

Jinja is the template engine behind Flask, Ansible, dbt, Salt and many static site generators. Templates mix text with expressions, filters, loops, inheritance and macros, and are compiled to Python code for speed. Learning it pays off wherever you generate HTML, configuration or code from data.

Sign in free to track progressOfficial docs ↗

Before you start

Jinja builds on these; the tree links to the exact lessons you need.

PythonEssentials level

How deep do you want to go?

1. EssentialsRead and write simple code, do the everyday basics4 lessons · 44 min in total
2. PracticalUse it productively at work, with the usual idioms7 lessons · 1 hour in total
3. AdvancedThe less common features, performance and trade-offs10 lessons · 2 hours in total
4. ExpertInternals and the edge cases experts know13 lessons · 2 hours in total

The Jinja tree

JinjaEnvironment, loaders and renderEnvironment, loadersand renderVariables and expressionsVariables andexpressionsFilters and testsFilters and testsif, for and whitespace controlif, for and whitespacecontrolTemplate inheritanceTemplate inheritanceMacros, include and importMacros, include andimportAutoescaping and safe markupAutoescaping andsafe markupStrings and f-stringsStrings and f-stringsDictionariesDictionariesDefining functionsDefining functions
Essentials and Practical shown (7 of 13 lessons); the full list is below. Click a lesson to read it.

All 13 lessons, in order

Templates and expressions

  1. Environment, loaders and render · Essentials · 10 min

    Create an Environment with a loader, load templates by name and render them with a context of variables.

  2. Variables and expressions · Essentials · 10 min

    Print variables, access attributes and keys, use literals, math, comparisons, string concatenation and inline if expressions.

  3. Filters and tests · Essentials · 12 min

    Transform values with filters like default, join, sort and map, and check values with tests like defined and divisibleby.

Control flow

  1. if, for and whitespace control · Essentials · 12 min

    Use if/elif/else, for loops with the loop variable and else, and strip whitespace with - markers or trim_blocks.

Reuse and safety

  1. Template inheritance · Practical · 12 min

    Build a base layout with blocks, extend it in child templates, call super() and use required and scoped blocks.

  2. Macros, include and import · Practical · 14 min

    Write reusable macros with arguments and caller(), import them from other files, and include partial templates.

  3. Autoescaping and safe markup · Practical · 10 min

    Understand how autoescaping prevents XSS, when to use Markup and |safe, and how to output JSON for scripts.

The Python API

  1. Custom filters, tests and globals · Advanced · 12 min

    Register your own filters, tests and global functions on the Environment, including context-aware ones with pass_context.

  2. Loaders, caching and auto-reload · Advanced · 10 min

    Pick the right loader (FileSystem, Package, Dict, Choice, Prefix), and understand template caching, auto_reload and bytecode caches.

  3. Undefined handling and debugging · Advanced · 8 min

    Choose Undefined, ChainableUndefined, DebugUndefined or StrictUndefined, and find which variables a template needs.

Internals and extending

  1. How templates compile to Python · Expert · 14 min

    See the pipeline from source to tokens, AST and generated Python code, and how blocks, macros and context work at runtime.

  2. The sandboxed environment · Expert · 10 min

    Render templates written by untrusted users with SandboxedEnvironment and understand what it does and doesn't protect.

  3. Writing extensions and async rendering · Expert · 15 min

    Add custom tags with an Extension that parses tokens into AST nodes, use built-in extensions, and render templates asynchronously.