Selecting an editor

Add the editor’s package to INSTALLED_APPS and point TEXT_EDITOR at its RTEConfig path:

INSTALLED_APPS = [
    ...,
    "djangocms_text.contrib.text_ckeditor4",
    ...,
]
TEXT_EDITOR = "djangocms_text.contrib.text_ckeditor4.ckeditor4"

Global editor configuration

The TEXT_EDITOR setting points to a RTEConfig object. The following attributes are available:

• name (str) — The name of the RTE configuration.

• config (str) — The configuration string.

• js (Iterable[str]) — JavaScript files to include.

• css (dict) — CSS files to include.

• admin_css (Iterable[str]) — CSS files for the admin interface only.

• inline_editing (bool) — Whether to enable inline editing.

• child_plugin_support (bool) — Whether to support child plugins.

• configuration (dict) — Frontend-specific options.

• additional_context (dict) — Additional context to pass to the editor.

The default configuration is:

DEFAULT_EDITOR = RTEConfig(
    name="tiptap",
    config="TIPTAP",
    js=("djangocms_text/bundles/bundle.tiptap.min.js",),
    css={"all": ("djangocms_text/css/bundle.tiptap.min.css",)},
    admin_css=("djangocms_text/css/tiptap.admin.css",),
    inline_editing=True,
    child_plugin_support=True,
    configuration={},  # see below
)

Use admin_css to include CSS files loaded into the dialog window, e.g. to declare custom colors or other styles.

Frontend-specific configuration

Frontend-specific options live in the configuration property of the RTEConfig. The contents depend on the rich text editor frontend (TipTap, CKEditor 4, etc.).

The preferred way to set them is via TEXT_EDITOR_SETTINGS, which mirrors RTEConfig.configuration. For backwards compatibility with djangocms-text-ckeditor, CKEDITOR_SETTINGS is also forwarded to the frontend (even when the frontend is not CKEditor 4).

Example TipTap configuration (matches the defaults):

DEFAULT_EDITOR.configuration = {
    "inlineStyles": [  # Styles menu, by default contains some rarer styles
        { "name": 'Small', "element": 'small' },
        { "name": 'Kbd', "element": 'kbd' },
        { "name": 'Var', "element": 'var' },
        { "name": 'Samp', "element": 'samp' },
    ],
    "blockStyles": [],
    # Block styles menu, e.g., for paragraphs; empty by default.
    # Example: [{"name": "Lead", "element": "p", "attributes": {"class": "lead"}}]
    # Styles for p and h1-h6 set the attributes on the element itself;
    # styles for container elements (div, section, ...) wrap the selected blocks.
    "textColors": {  # Colors offered for the text color menu - the keys are CSS classes
        'text-primary': {"name": "Primary"},
        'text-secondary': {"name": "Secondary"},
        'text-success': {"name": "Success"},
        'text-danger': {"name": "Danger"},
        'text-warning': {"name": "Warning"},
        'text-info': {"name": "Info"},
        'text-light': {"name": "Light"},
        'text-dark': {"name": "Dark"},
        'text-body': {"name": "Body"},
        'text-muted': {"name": "Muted"},
    },
    "tableClasses": "table",  # classes added to new tables
}

Three ways to configure the classes added to new tables:

# Option 1: modify the default editor configuration in place
from djangocms_text.editors import DEFAULT_EDITOR
DEFAULT_EDITOR.configuration["tableClasses"] = "table ui"

# Option 2: offer a list of named choices
from djangocms_text.editors import DEFAULT_EDITOR
DEFAULT_EDITOR.configuration["tableClasses"] = [
    ["table", _("Default")],
    ["table table-striped", _("Striped")],
]

# Option 3: use TEXT_EDITOR_SETTINGS in settings.py
TEXT_EDITOR_SETTINGS = {
    "tableClasses": "table ui",
}

Security and resource limits

The link picker resolves django CMS pages by default. Additional model types must be explicitly allowlisted, registered with Django’s admin, implement get_absolute_url(), and grant the requesting user view permission:

TEXT_LINKABLE_MODELS = ("cms.page", "news.article")

Embedded base64 images are decoded with Pillow and re-encoded before the configured TEXT_SAVE_IMAGE_FUNCTION receives them. The default limits are 5 MiB of decoded data and 25 million pixels; deployments can lower them:

TEXT_SAVE_IMAGE_MAX_BYTES = 2 * 1024 * 1024
TEXT_SAVE_IMAGE_MAX_PIXELS = 12_000_000

Inline editing

Inline editing lets editors click a text plugin and change its contents directly in django CMS edit mode. The editor appears around the text field, and changes are saved as soon as the field loses focus.

Inline editing wraps the HTML in a <div> in edit mode, which may interact with site CSS that uses direct child selectors.

Inline editing is enabled by default. To disable it:

TEXT_INLINE_EDITING = False

When enabled, a toolbar toggle lets users switch inline editing on and off for the current session. If only text changes, editing continues seamlessly. If a text-enabled plugin was added, changed, or removed, the page refreshes to update the page tree and re-render the affected plugins.

For security, opening a new Text plugin form no longer creates a temporary database record. Save the new Text plugin once before adding inline child plugins such as images or links.

<!-- cms/plugins/text.html -->
<section class="my-text-plugin">
    <div class="cms-content-start">
        {{ body|safe }}
    </div>
</section>

Text-enabled plugins

djangocms-text supports text-enabled plugins (note: not all editor frontends do — see Editors).

To make a plugin available inside Text plugins, set text_enabled = True on its plugin class:

class MyTextPlugin(TextPlugin):
    name = "My text plugin"
    model = MyTextModel
    text_enabled = True

The plugin then appears in the CMS Plugins dropdown (puzzle icon) in the editor and is previewed inline.

Pro-tip: Provide an icon_alt method on the plugin so that, when many text_enabled plugins are available, users get a useful tooltip — for example, the name of the product whose price the plugin shows.

Text-enabled plugins can also have their own icons. Add a text_icon property containing SVG source code:

class MyTextPlugin(TextPlugin):
    name = "My text plugin"
    model = MyTextModel
    text_enabled = True
    text_icon = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm0 18c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8zm-1-13h2v6h-2zm0 8h2v2h-2z"/></svg>'

The icon shows in the CMS plugin pulldown menu and toolbar. To make a text-enabled plugin directly accessible from the editor toolbar, add its name (e.g. "LinkPlugin") to the toolbar configuration.

For more on extending the CMS with plugins, see the django-cms doc.

Default content in placeholders

You can use TextPlugin in default_plugins (see the CMS_PLACEHOLDER_CONF setting docs). TextPlugin requires a single value: body for the default HTML content. To attach default children (e.g. a LinkPlugin), reference them in the body using "%(_tag_child_<order>)s" placeholders:

CMS_PLACEHOLDER_CONF = {
    'content': {
        'name' : _('Content'),
        'plugins': ['TextPlugin', 'LinkPlugin'],
        'default_plugins':[
            {
                'plugin_type':'TextPlugin',
                'values':{
                    'body':'<p>Great websites : %(_tag_child_1)s and %(_tag_child_2)s</p>'
                },
                'children':[
                    {
                        'plugin_type':'LinkPlugin',
                        'values':{
                            'name':'django',
                            'url':'https://www.djangoproject.com/'
                        },
                    },
                    {
                        'plugin_type':'LinkPlugin',
                        'values':{
                            'name':'django-cms',
                            'url':'https://www.django-cms.org'
                        },
                    },
                ]
            },
        ]
    }
}

HTML sanitizer

djangocms-text uses nh3 to sanitize HTML, both for security and to enforce well-formed markup. Sanitization may strip tags useful for some use cases (e.g. iframe).

HTML is sanitized when it is written through Django’s ORM. It is not sanitized again when read from the database; stored values are treated as trusted HTML. Code that writes directly to the database, bypassing the ORM, must therefore sanitize HTML before storing it.

Customize allowed tags and attributes via TEXT_ADDITIONAL_ATTRIBUTES:

TEXT_ADDITIONAL_ATTRIBUTES = {
    'iframe': {'scrolling', 'allowfullscreen', 'frameborder'},
}

The dictionary maps tag names to sets of allowed attribute names.

If you have settings in the older djangocms-text-ckeditor style using both TEXT_ADDITIONAL_TAGS and TEXT_ADDITIONAL_ATTRIBUTES, those will be translated automatically — with a warning from the Django checks framework at server startup.

Note: Some frontend editors pre-sanitize content before sending it to the server, which can render the above settings ineffective.

To disable sanitization entirely, set TEXT_HTML_SANITIZE = False.

Switching from CKEditor 4 to TipTap

When transitioning from CKEditor 4 to TipTap (the new default), keep these points in mind:

• No HTML source editing — TipTap does not support direct HTML source editing. This simplifies the editor for most users but may be a drawback for advanced users or developers who manually edit HTML.

• Loss of non-standard formatting — TipTap stores content in an abstract JSON format and regenerates HTML on edit. Formatting created via CKEditor 4 plugins or manually added HTML classes may not be preserved. This only happens on first edit after migration.

• Keep using CKEditor 4 if needed — If retaining CKEditor 4 behavior is essential, use the CKEditor 4 backend that ships with djangocms-text.

You can continue to use CKEditor 4 for migration compatibility. CKEditor 4 is end-of-life, so TipTap is recommended for new deployments. The bundled integration disables source editing and other unsafe legacy plugins, and its content-filter restrictions cannot be relaxed through editor settings. Compared to djangocms-text-ckeditor, the CKEditor 4 sources have moved to static/djangocms_text/vendor/ckeditor4. Update any custom CKEditor 4 plugins accordingly.

pre-commit hooks

The repo uses pre-commit git hooks to ensure code quality. Install with:

pip install pre-commit
pre-commit install

Building the JavaScript

djangocms-text distributes a JavaScript bundle containing the editor frontends and CMS integration. To rebuild the bundle:

nvm use
npm install
npm run build

Other build scripts:

• npm run build:dev — unminified development build

• npm run watch — rebuild on file changes