Jinja Cursor Rules for AI

jinja.mdc

---
description: This rule explains Jinja template syntax and best practices for Python web applications.
globs: **/*.html
alwaysApply: false
---

# Jinja rules

- Use template inheritance:

```html
{# base.html #}
<!DOCTYPE html>
<html>
<head>
  <title>{% block title %}Default Title{% endblock %}</title>
</head>
<body>
  {% block content %}{% endblock %}
</body>
</html>
```

- Use include for components:

```html
{% include "components/user_card.html" %}
```

- Use macros for reusable functions:

```html
{% macro input(name, value='', type='text') %}
  <input type="{{ type }}" name="{{ name }}" value="{{ value }}">
{% endmacro %}
```

- Use control structures:

```html
{% if user.is_authenticated %}
  <p>Welcome, {{ user.username }}!</p>
{% else %}
  <p>Please log in.</p>
{% endif %}
```

- Use filters to format data:

```html
<p>{{ text|truncate(30) }}</p>
<p>{{ date|strftime('%B %d, %Y') }}</p>
```

- Use set for local variables:

```html
{% set navigation = [('Home', '/'), ('About', '/about')] %}
```

- Use whitespace control:

```html
{% for item in items -%}
  {{ item }}
{%- endfor %}
```

Jinja templating is a powerful Python templating engine commonly used in web frameworks like Flask and Django. This rule provides essential syntax patterns and best practices for Jinja template development to help you create clean, maintainable, and efficient web templates.

What this rule does

The Jinja rule provides a comprehensive guide to Jinja template syntax and patterns for Python web applications. It covers fundamental concepts including template inheritance, components, macros, control structures, and formatting options. This rule helps standardize template development and promotes best practices within your project.

Key Jinja concepts

Template inheritance

Template inheritance allows you to build a base "skeleton" template with common elements (header, navigation, footer) that child templates can extend and override specific blocks:

<!-- In a base template, you define blocks that child templates can fill -->
{% block content %}{% endblock %}

<!-- In child templates, you extend and customize -->
{% extends "base.html" %}
{% block content %}
  <h1>Page specific content</h1>
{% endblock %}

This approach reduces duplication and creates a consistent structure across multiple pages.

Components and reusability

The rule emphasizes several methods for creating reusable template components:

Includes - For embedding template fragments:

{% include "components/user_card.html" %}

Macros - For template functions with parameters:

{% macro input(name, value='', type='text') %}
  <input type="{{ type }}" name="{{ name }}" value="{{ value }}">
{% endmacro %}

<!-- Later used as -->
{{ input('username', type='email') }}

Data manipulation

Jinja provides powerful ways to handle data:

Control structures for conditionals and loops
Filters to format and transform data inline
Set statements for local variables
Whitespace control to manage output formatting

Using Jinja in Cursor

The Jinja rule (jinja.mdc) is designed to assist you when working with Jinja templates in your Python web projects.

This rule is configured as an "Auto Attached" rule that automatically activates when you're working with HTML files, thanks to its glob pattern (**/*.html). When you open or create an HTML file in your project, Cursor will intelligently apply this rule's context to the AI, ensuring you receive Jinja-aware assistance.

This means the AI will:

Understand Jinja syntax in your HTML files
Provide appropriate suggestions based on Jinja best practices
Help you implement template inheritance, macros, and other Jinja patterns correctly

You can also manually invoke this rule at any time by typing @jinja in the Cmd-K command palette or AI chat, which is helpful when working with files that might contain Jinja but don't match the HTML extension pattern.

Usage tips

Whitespace management

Use Jinja's whitespace control modifiers (-) to create cleaner HTML output by stripping unnecessary whitespace:

{% for item in items -%}
  {{ item }}
{%- endfor %}

Leverage filters effectively

Jinja's filters are powerful for formatting and transforming data directly in templates:

<!-- Limit text length -->
{{ long_description|truncate(100) }}

<!-- Format dates -->
{{ created_at|strftime('%B %d, %Y') }}

<!-- Escape content -->
{{ user_input|escape }}

Organize complex templates

For larger applications:

Break your templates into logical components
Use clear naming conventions for blocks
Consider organizing macros into separate files that can be imported

By following these Jinja best practices, you'll create more maintainable and efficient templates for your Python web applications.

Cursor Rules for Jinja