Se você está começando com Django, uma coisa fica clara rápido: templates crescem.
Header, footer, menu, mensagens, cards… tudo se repete.

No começo, copiar e colar parece normal.
Depois de alguns arquivos, vira um problema.

É exatamente aqui que entra o {% include %}.

Neste artigo, vou te explicar de forma simples e prática o que é {% include %}, quando usar e como evitar erros comuns.
Tudo com exemplos reais de projeto.

O que é {% include %} no Django

O {% include %} é uma tag do Django Template Language (DTL) usada para reutilizar trechos de HTML em vários templates.

Na prática, ele:

  • Insere um template dentro de outro

  • No ponto exato onde a tag aparece

  • Sem duplicar código

Pense assim:
É como um “copiar e colar” inteligente, organizado e profissional.

Quando você altera o arquivo incluído, todos os lugares que usam o include são atualizados.

Por que usar {% include %} desde o começo

Comparação visual entre HTML repetitivo e desorganizado versus templates Django bem estruturados usando componentes reutilizáveis. A imagem reforça a importância de evitar duplicação e adotar boas práticas desde o início do projeto.

Em projetos reais, não usar include vira dívida técnica.

Usar {% include %} ajuda a:

  • Evitar duplicação de código

  • Manter templates menores e legíveis

  • Separar responsabilidades visuais

  • Facilitar manutenção

  • Escalar o projeto com organização

Na prática, o erro acontece quando você ignora isso no início.
Depois, dá muito mais trabalho refatorar.

Quer se aprofundar no assunto e ter um material completo para consulta?
Faça o download do PDF gratuito e tenha acesso a um guia prático e direto ao ponto.
Baixar PDF agora

Estrutura de templates recomendada

Uma estrutura simples e profissional costuma seguir este padrão:

 
templates/ ├── base.html ├── pages/ │ ├── home.html │ └── post_detail.html └── includes/ ├── header.html ├── footer.html ├── navbar.html ├── messages.html └── pagination.html

Regra de ouro

Tudo que é reutilizável vai para templates/includes/.

Header aparece em todas as páginas? Include.
Footer também? Include.
Card de post se repete? Include.

Exemplo básico de {% include %}

Vamos ao exemplo mais simples possível.

1. Template incluído

templates/includes/header.html

 
<header> <h1>Meu Blog Profissional</h1> </header>

2. Template principal

templates/base.html

 
<!DOCTYPE html> <html lang="pt-br"> <head> <meta charset="UTF-8"> <title>{% block title %}Blog{% endblock %}</title> </head> <body> {% include "includes/header.html" %} <main> {% block content %}{% endblock %} </main> </body> </html>

O conteúdo de header.html será renderizado exatamente onde o include está.

Simples, limpo e organizado.

Como o contexto funciona no {% include %}

Ilustração didática mostrando como um template principal compartilha automaticamente variáveis com templates incluídos. Demonstra de forma simples como o Django facilita a reutilização de código sem configurações complexas.

Aqui está um detalhe importante que muita gente não entende no começo.

O template incluído herda automaticamente o contexto do template atual.

Exemplo na view

 
def home(request): return render(request, "pages/home.html", { "user_name": "Tiago" })

Template incluído

templates/includes/header.html

 
<header> <p>Olá, {{ user_name }}</p> </header>

Isso funciona sem nenhuma configuração extra.

Na prática, o erro acontece quando o dev acha que precisa “reenviar” variáveis.
Na maioria dos casos, não precisa.

Passando variáveis manualmente para o include

Quando você quer criar componentes reutilizáveis, passar variáveis é comum.

Você faz isso com with.

Exemplo

 
{% include "includes/card.html" with title="Post Destaque" %}

Template incluído

templates/includes/card.html

 
<div class="card"> <h2>{{ title }}</h2> </div>

Esse padrão é muito usado para:

  • Cards

  • Alertas

  • Blocos de conteúdo

  • Componentes visuais reutilizáveis

Na prática, testei e funcionou assim em projetos reais.

Isolando o contexto com only (uso avançado)

Em projetos maiores, o contexto pode ficar confuso.

Para evitar conflitos, você pode usar only.

 
{% include "includes/card.html" with title="Post" only %}

O template incluído só enxerga as variáveis passadas explicitamente.

Isso é útil quando:

  • Existem variáveis com o mesmo nome

  • Você quer mais previsibilidade

  • O projeto começa a crescer

Não é obrigatório no início, mas é bom conhecer.

{% include %} vs {% extends %}

Essa comparação é obrigatória.

{% include %} {% extends %}
Reutiliza pedaços Herda layout inteiro
Componentes Estrutura base
Pode aparecer várias vezes Usado uma vez
Header, footer, cards base.html

Nunca confunda os dois.

  • extends define a estrutura da página

  • include monta os componentes dentro dela

Erros comuns ao usar {% include %}

1. Colocar lógica pesada no template

Exemplo ruim:

 
{% if user.is_authenticated and user.profile.is_admin %}

Boa prática:
A lógica deve vir da view, não do template.

O template só exibe o que já foi decidido.

2. Includes gigantes

Se o include vira quase uma página inteira, algo está errado.

Nesse caso, você deveria:

  • Usar {% extends %}

  • Ou quebrar em mais componentes

Include é para pedaços, não para páginas completas.

Exemplo real: mensagens do Django

Esse padrão aparece em praticamente todo projeto profissional.

Template incluído

templates/includes/messages.html

 
{% if messages %} <ul class="messages"> {% for message in messages %} <li class="{{ message.tags }}"> {{ message }} </li> {% endfor %} </ul> {% endif %}

Uso no base.html

 
{% include "includes/messages.html" %}

Dessa forma, qualquer página pode exibir mensagens sem repetir código.

Na prática, esse foi o comportamento que observei em projetos reais.

Boas práticas profissionais (resumo final)

Visual profissional apresentando um checklist de organização, com pasta includes/, componentes reutilizáveis, nomes claros de arquivos e templates pequenos. A imagem transmite maturidade técnica, padrão profissional e facilidade de manutenção em projetos Django.

Para fechar, guarde isso:

  • Crie uma pasta templates/includes/

  • Use {% include %} apenas para componentes reutilizáveis

  • Prefira passar variáveis com with

  • Evite lógica complexa em templates

  • Combine {% include %} com {% extends %}

  • Use nomes claros como navbar.html, footer.html, messages.html

Se você aprender isso cedo, seus templates vão ficar mais limpos, profissionais e fáceis de manter.