Django IncludeContents

Component-like Django template tags with HTML syntax support. Full feature parity between Django templates and Jinja2.

Features

🧩 Component Templates: Create reusable template components with isolated contexts
📝 HTML Syntax: Use familiar HTML-like syntax for components (<include:my-card>)
🎯 Props System: Define required and optional props with validation
🎨 Advanced Styling: Conditional classes, extended classes, and CSS utilities
🔀 Conditional Wrapping: Clean conditional HTML wrapper syntax with {% wrapif %}
🎭 Icon System: SVG sprite generation from Iconify icons and local SVG files (<icon:home>)

Quick Start

Installation

pip install django-includecontents

Setup

Choose your template engine:

Django Templates

Replace your Django template backend in settings.py:

TEMPLATES = [
    {
        'BACKEND': 'includecontents.django.DjangoTemplates',
        # ... rest of your template config
    },
]

Jinja2

Add the Jinja2 extension in settings.py:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.jinja2.Jinja2',
        'OPTIONS': {
            'extensions': [
                'includecontents.jinja2.IncludeContentsExtension',
            ],
        },
    },
]

See Jinja2 Setup for complete instructions.

Create a Component

templates/components/welcome-card.html

{# props title, subtitle="" #}
<div class="card">
    <h2>{{ title }}</h2>
    {% if subtitle %}<p>{{ subtitle }}</p>{% endif %}
    <div class="content">{{ contents }}</div>
</div>

Use the Component

<include:welcome-card title="Hello World" subtitle="Getting started">
    <p>Your component content goes here!</p>
</include:welcome-card>

Result

<div class="card">
    <h2>Hello World</h2>
    <p>Getting started</p>
    <div class="content">
        <p>Your component content goes here!</p>
    </div>
</div>

Template Tag Syntax

If you prefer traditional Django template syntax:

{% load includecontents %}
{% includecontents "components/welcome-card.html" title="Hello World" subtitle="Getting started" %}
    <p>Your component content goes here!</p>
{% endincludecontents %}

Documentation

📚 Full Documentation

Getting Started - Installation and setup
Jinja2 Setup - Jinja2 template engine setup
Quick Start Guide - Get started in 5 minutes
HTML Components - Modern component syntax
Best Practices - Building great components

Examples

Named Content Blocks

<include:article title="My Article">
    <content:header>
        <h1>Article Title</h1>
        <p>By {{ author }}</p>
    </content:header>
    
    <p>Main article content...</p>
    
    <content:sidebar>
        <h3>Related Links</h3>
    </content:sidebar>
</include:article>

Conditional Wrapping

{% load includecontents %}
{% wrapif user.is_authenticated %}
    <a href="/profile" class="user-link">
        {% contents %}Welcome, {{ user.name }}{% endcontents %}
    </a>
{% endwrapif %}

Modern JavaScript Framework Integration

<!-- Vue.js and Alpine.js attributes work seamlessly -->
<include:button @click="handleClick()" :disabled="isLoading">
    Submit
</include:button>

<include:modal x-on:click="open = false" x-show="open">
    Modal content
</include:modal>

<!-- Nested attributes for complex components -->
<include:form inner.class="form-control" button.@click="submit()">
    Form content
</include:form>

Dynamic Components

<include:button variant="primary" {disabled} class:loading="{{ is_processing }}">
    {% if is_processing %}Processing...{% else %}Submit{% endif %}
</include:button>

Icons

# settings.py
STATICFILES_FINDERS = [
    'includecontents.icons.finders.IconSpriteFinder',  # Must be first for icons
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
]

INCLUDECONTENTS_ICONS = {
    'icons': [
        'mdi:home',        # Use as <icon:home>
        'tabler:user',     # Use as <icon:user>
        'icons/logo.svg'   # Use as <icon:logo>
    ]
}

Note: Icon names auto-generate from config: 'mdi:home' → <icon:home>, 'icons/logo.svg' → <icon:logo>

<icon:home class="w-6 h-6" />
<icon:user class="avatar" use.role="img" />
<icon:logo class="brand" />

Requirements

Python: 3.8+
Django: 3.2+

License

MIT License. See LICENSE for details.

Contributing

Contributions welcome! Please see our GitHub Issues for bug reports and feature requests.

Support

Release files for django-includecontents 4.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for django-includecontents 4.0.2
File	Size	Uploaded
django_includecontents-4.0.2.tar.gz	133.1 kB	Aug 23, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for django-includecontents 4.0.2
File	Interpreter	ABI	Platform	Reset
django_includecontents-4.0.2-py3-none-any.whl 64.7 kB Aug 23, 2026	Python 3	none	any	Details

Total release size:197.8 kB

Release files / django_includecontents-4.0.2.tar.gz

Download URL	django_includecontents-4.0.2.tar.gz
Size	133.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`ec7fbb506a6ba97aa5aec9d5f456582a12c06693ad88c021c48135b6599d5633`
BLAKE2b-256 checksum How to use checksums	`9ae8003b4c200bca58cf5ee520396dbf65d809de91ec88345e88810e0b9bf5d3`
Upload date	Aug 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`pdm/2.28.2 CPython/3.12.3 Linux/6.17.0-1022-azure`

Release files / django_includecontents-4.0.2-py3-none-any.whl

Download URL	django_includecontents-4.0.2-py3-none-any.whl
Size	64.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`cb6e9917c4ab9a73ae0a94c66c66b25c068031c0a919588f69b2a870203b31b4`
BLAKE2b-256 checksum How to use checksums	`785f2098c0afea000af84f4dddb3c83de61db36bd312dda619c761c6a70f147b`
Upload date	Aug 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`pdm/2.28.2 CPython/3.12.3 Linux/6.17.0-1022-azure`