django-prose-editor

Prose editor for the Django admin based on ProseMirror and Tiptap. Announcement blog post.

About rich text editors

Copied from the django-content-editor documentation.

We have been struggling with rich text editors for a long time. To be honest, I do not think it was a good idea to add that many features to the rich text editor. Resizing images uploaded into a rich text editor is a real pain, and what if you’d like to reuse these images or display them using a lightbox script or something similar? You have to resort to writing loads of JavaScript code which will only work on one browser. You cannot really filter the HTML code generated by the user to kick out ugly HTML code generated by copy-pasting from word. The user will upload 10mb JPEGs and resize them to 50x50 pixels in the rich text editor.

All of this convinced me that offering the user a rich text editor with too much capabilities is a really bad idea. The rich text editor in FeinCMS only has bold, italic, bullets, link and headlines activated (and the HTML code button, because that’s sort of inevitable – sometimes the rich text editor messes up and you cannot fix it other than going directly into the HTML code. Plus, if someone really knows what they are doing, I’d still like to give them the power to shot their own foot).

If this does not seem convincing you can always add your own rich text plugin with a different configuration (or just override the rich text editor initialization template in your own project). We do not want to force our world view on you, it’s just that we think that in this case, more choice has the bigger potential to hurt than to help.

Installation

The first step is to ensure that you have an activated virtualenv for your current project, using something like . .venv/bin/activate.

Install the package into your environment:

pip install django-prose-editor

To include nh3 as optional dependency for sanitized HTML, install the extra "sanitize":

pip install django-prose-editor[sanitize]

Add django_prose_editor to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "django_prose_editor",
]

Add the importmap by adding the js_asset.context_processors.importmap context processor and inserting {{ importmap }} somewhere in your base template, above all other scripts.

Replace models.TextField with ProseEditorField where appropriate:

from django_prose_editor.fields import ProseEditorField

class Project(models.Model):
    description = ProseEditorField()

Note! No migrations will be generated when switching from and to models.TextField. That's by design. Those migrations are mostly annoying.

Security

ProseMirror does a really good job of only allowing content which conforms to a particular scheme. Of course users can submit what they want, they are not constrainted by the HTML widgets you're using. You should still always sanitize the HTML submitted on the server side. A good way to do this is by using the sanitize argument to the ProseEditorField. You can use the following snippet to always pass HTML through nh3:

from django_prose_editor.sanitized import SanitizedProseEditorField

description = SanitizedProseEditorField()

Install django-prose-editor with the extra "sanitize" to use SanitizedProseEditorField.

Convenience

Sometimes it may be useful to show an excerpt of the HTML field; the ProseEditorField automatically adds a get_*_excerpt method to models which returns the truncated and stripped beginning of your HTML field's content. The name would be Project.get_description_excerpt in the example above.

Customization

The editor can be customized in two ways: by using the config parameter to include/exclude specific extensions, or by creating custom presets.

Simple Customization with Config

For basic customization, you can use the config parameter to specify which extensions should be enabled:

from django_prose_editor.fields import ProseEditorField

class Article(models.Model):
    content = ProseEditorField(
        config={
            "types": [
                "bold",
                "italic",
                "strike",
                "bulletList",
                "orderedList",
                "horizontalRule",
                "link",
                "table",  # Enables full table support
            ],
            "history": True,
            "html": True,
            "typographic": True,
        }
    )

Extension names use camelCase format (e.g., bold, italic, bulletList, horizontalRule), following the naming convention used by Tiptap. The following legacy names are still supported for backward compatibility, but are deprecated:

• ProseMirror node names: bullet_list → bulletList, ordered_list → orderedList, horizontal_rule → horizontalRule
• ProseMirror mark names: strong → bold, em → italic, strikethrough → strike

Available extension types include:

• Text formatting: bold, italic, strike, subscript, superscript, underline (all enabled by default)
• Lists: bulletList, orderedList (enabled by default)
• Structure: blockquote, heading, horizontalRule (enabled by default)
• Links: link (enabled by default)
• Tables: table (opt-in only, not enabled by default)

Advanced Customization with Presets

For more advanced customization, you can create custom presets by adding additional assets to load:

from js_asset import JS

DJANGO_PROSE_EDITOR_PRESETS = {
    "announcements": [
        JS("prose-editors/announcements.js", {"type": "module"}),
    ],
}

The preset can be selected when instantiating the field:

text = ProseEditorField(_("text"), preset="announcements")

The editor uses ES modules and importmaps; you can import extensions and utilities from the django-prose-editor/editor module. The importmap support is provided by django-js-asset, check it's README to learn more.

Here's the example:

import {
  // Always recommended:
  Document, Dropcursor, Gapcursor, Paragraph, HardBreak, Text,

  // Add support for a few marks:
  Bold, Italic, Subscript, Superscript, Link,

  // A menu is always nice:
  Menu,

  // Helper which knows how to attach a prose editor to a textarea:
  createTextareaEditor,

  // Helper which runs the initialization on page load and when
  // new textareas are added through Django admin inlines:
  initializeEditors,
} from "django-prose-editor/editor"


// "announcements" is the name of the preset.
const marker = "data-django-prose-editor-announcements"

function createEditor(textarea) {
  if (textarea.closest(".prose-editor")) return
  const config = JSON.parse(textarea.getAttribute(marker))

  const extensions = [
    Document, Dropcursor, Gapcursor, Paragraph, HardBreak, Text,

    Bold, Italic, Subscript, Superscript, Link,

    Menu,
  ]

  return createTextareaEditor(textarea, extensions)
}

initializeEditors(createEditor, `[${marker}]`)

Customization with JavaScript bundlers

If you're using a bundler such as esbuild, rspack or webpack you have to ensure that the django-prose-editor JavaScript library is treated as an external. In the case of rspack this means adding the following lines to your rspack configuration:

module.exports = {
    // ...
    experiments: { outputModule: true },
    externals: {
        "django-prose-editor/editor": "module django-prose-editor/editor",
    },
}

This makes rspack emit ES modules and preserves imports of django-prose-editor/editor in the output instead of trying to bundle the library.

Usage outside the Django admin

The prose editor can easily be used outside the Django admin. The form field respectively the widget includes the necessary CSS and JavaScript:

from django_prose_editor.fields import ProseEditorFormField

class Form(forms.Form):
    text = ProseEditorFormField()

Or maybe you want to use django_prose_editor.widgets.ProseEditorWidget, but why make it more complicated than necessary.

If you're rendering the form in a template you have to include the form media:

<form method="post">
  {{ form.errors }} {# Always makes sense #}
  {{ form.media }}  {# This is the important line! #}
  {{ form.as_div }}
  <button type="submit">send</button>
</form>

Note that the form media isn't django-prose-editor specific, that's a Django feature.

The django-prose-editor CSS uses the following CSS custom properties.

• --prose-editor-background
• --prose-editor-foreground
• --prose-editor-border-color
• --prose-editor-active-color
• --prose-editor-disabled-color

If you do not set them, they get their value from the following properties that are defined in the Django admin's CSS:

• --border-color
• --body-fg
• --body-bg
• --primary

You should set these properties with appropriate values to use django-prose-editor outside the admin in your site.

In addition, you may optionally set a --prose-editor-typographic property to control the color of typographic characters when shown.

Development

For the best development experience:

1. Install django-prose-editor in editable mode in your project:

   pip install -e /path/to/django-prose-editor

2. Run yarn && yarn dev in the django-prose-editor directory to watch for asset changes.

When using yarn dev:

• The generated CSS and JavaScript is not minified, making it easier to debug.
• Source maps are generated to help identify exactly where in the source code an error occurs.
• The watcher will rebuild files automatically when you make changes.

Source maps are generated in development mode (yarn dev) for easier debugging, but not included in production builds to keep the package size manageable. The JavaScript in this project is quite extensive, so source maps would significantly increase the distribution size.

The pre-commit configuration includes a hook that prevents committing files with source map references, ensuring that development artifacts don't make it into the repository.

Browser Testing with Playwright

This project uses Playwright for browser-based testing of the prose editor.

To run the browser tests:

1. Install the dependencies:

   pip install -e ".[tests]"
   playwright install

2. Run the tests using tox:

   tox -e playwright

   Or directly with pytest:

   pytest tests/testapp/test_prose_editor_e2e.py -v --browser chromium

Code Style and Linting

This project uses pre-commit hooks to enforce coding style guidelines. We use Ruff for Python linting and formatting, Biome for JavaScript/TypeScript linting and formatting and a few other hooks.

To set up pre-commit using uv:

uv tool install pre-commit
pre-commit install

Pre-commit will automatically check your code for style issues when you commit changes.