In your models

django-bleach provides three ways of creating bleached output. The simplest way of including user-editable HTML content that is automatically sanitised is by using the BleachField model field:

# in app/

from django import models
from django_bleach.models import BleachField

class Post(models.Model):

    title = models.CharField()
    content = BleachField()

BleachField takes the following arguments, to customise the output of bleach.

See the bleach documentation for their use:

  • allowed_tags
  • allowed_attributes
  • allowed_styles
  • allowed_protocols
  • strip_tags
  • strip_comments

In addition to the bleach-specific arguments, the BleachField model field accepts all of the normal field attributes. Behind the scenes, it is a TextField, and accepts all the same arguments as TextField.

The field does not specify any formfield to use, and falls back on the default CharField and Textarea used by TextFields. You must override the form field or widget yourself if you need something different.

In your forms

A BleachField form field is provided. This field sanitises HTML input from the user, and presents safe, clean HTML to your Django application. This is where most of the work is done. Usually you will want to use a BleachField model field, as opposed to the form field, but if you want, you can just use the form field. One possible use case for this set up is to force user input to be bleached, but allow administrators to add any content they like via another form (e.g. the admin site):

# in app/

from django import forms
from django_bleach.forms import BleachField

from app.models import Post

class PostForm(forms.ModelForm):
    class Meta:
        model = Post

        fields = ['title', 'content']

    content = BleachField()

The BleachField form field takes exactly the same arguments as the BleachField model field above.

In your templates

If you have a piece of content from somewhere that needs to be printed in a template, you can use the bleach filter:

{% load bleach_tags %}

{{ some_unsafe_content|bleach }}

It uses the ALLOWED_TAGS setting in your application, or optionally, bleach can pass tags:

{% load bleach_tags %}

{{ some_unsafe_content|bleach:"p,span" }}

If you have content which doesn’t contain HTML, but contains links or email addresses, you can also use the bleach_linkify filter to convert content to links:

{% load bleach_tags %}

{{ some_safe_content|bleach_linkify }}