Configuring CKEditor in Drupal for Rich Content Editing
CKEditor remains the default rich text editor inside Drupal core and continues to evolve with each release. Site builders who configure it well save their editorial teams hours of frustration every week, and the payoff is consistent formatting across thousands of pages.
This article walks through the practical side of CKEditor configuration in modern Drupal 10 or 11 installs. Whether you manage a council website in Brisbane, a national publication out of Sydney, or an internal portal for an Adelaide-based logistics firm, the same fundamentals apply. The aim is a tidy toolbar, sensible text formats, media handling that just works, and HTML filtering that keeps the editorial workflow clean without locking your content producers out of features they actually need.
Getting CKEditor 5 Running in Modern Drupal
Drupal 10.1 and later ship with CKEditor 5 already integrated into the editor module, replacing the older CKEditor 4 stack that depended on a separately maintained contrib project. The first step on a fresh build is to enable the Editor and CKEditor 5 modules through the Extend page, then confirm a default text format such as Basic HTML or Restricted HTML is available under Configuration > Content authoring > Text formats and editors.
Once enabled, the editor configuration lives in YAML files inside your config sync directory rather than in a sprawling admin form. Editing these files directly is the recommended path for development teams running on Australian infrastructure, since it lets you commit toolbar changes alongside code reviews. Site editors then see those settings reflected in their browser the next time they save a piece of content. Permissions matter here too, because the "Use any text format" right must be granted thoughtfully. Most Australian government builds draw a line between an editor role for the marketing team and an author role for general staff, with separate format access for each.
Building a Useful Toolbar Layout
A toolbar that throws every available button at your editors does them no favours. The aim is a layout that matches the workflow, with the most-used controls on the first row and the occasional ones tucked away. Drupal splits the toolbar into an "active" row and a disabled group, and dragging items between them is how you curate the experience.
For most content teams working in Australian English, the essentials are bold, italic, link, bulleted and numbered lists, blockquote, heading levels two and three, and source. Headings deserve careful thought because accessibility audits under the WCAG 2.2 guidelines, which the Digital Transformation Agency references for federal sites, often flag skipped heading levels. A toolbar that exposes a single heading dropdown is usually safer than one that lists every available level. Drupal agencies in Melbourne and Sydney frequently ship a curated default and let editors request additions through a lightweight change request rather than exposing full customisation in production.
Configuring Text Formats and Editor Roles
Text formats are the bridge between the toolbar you build and the HTML your site actually stores. Drupal offers three out of the box: Restricted HTML, Basic HTML, and Full HTML. Each one pairs with a CKEditor 5 configuration, and the format's HTML filter rules decide what tags and attributes survive the round trip from editor to database.
A practical pattern on Australian government projects is to create a fourth format, often called "Marketing" or "News release", that grants the editor role access to embed iframes for approved video hosts and pull in pull-quote styling. Restricting the allowed HTML tags at the format level is far cleaner than relying on editor-side discipline. If your team regularly references third-party instructional content such as a motorbike dashcam installation guide alongside news pieces, you will need to weigh whether that link should be allowed as plain anchor text only, or if the format should permit a richer embed. The choice usually comes down to trust: any iframe-capable format must be locked behind a role with editorial accountability, never assigned to anonymous contributors.
Custom Styles, Embeds and Source Code Blocks
CKEditor 5's style buttons go beyond simple bold and italic. Through the Source editing plugin and the General HTML Support feature, you can allow custom elements such as <aside>, <figure>, or <mark> while keeping everything filtered through Drupal's HTML purifier. The General HTML Support panel under each text format accepts a JSON-style list of allowed tags and attributes, giving you surgical control without touching contrib modules.
For tech-heavy sites run from Brisbane or Canberra, code blocks matter. The Code block plugin provides a monospaced container with syntax highlighting when paired with a front-end theme that ships highlight.js or Prism. Embedding media from YouTube or Vimeo is handled by the Media Embed plugin, which sends oEmbed requests through Drupal's Media module and stores a reference rather than the original embed code. That means removing a video later does not leave orphan iframes behind in the database, which is a quiet but recurring maintenance win on long-running publication sites across the country.
Image Handling Through the Media Library
Image upload inside CKEditor 5 is routed through the Media library rather than dropped into the body field directly. Clicking the image icon opens a modal where editors can pick from existing media, upload new files, or reuse an entity already stored in the system. For sites that publish a handful of hero images per week, this is a clear upgrade over the older inline file approach.
To make it work smoothly, the Image media type needs to be configured with a sensible max file size and an allowed extensions list. Australian editorial teams often publish images straight from a Sydney photo shoot in large JPEG, so server-side limits around five to ten megabytes per upload prevent surprise quota issues. Alt text fields should be mandatory at the media type level rather than relying on editor habit, since missing alt text is one of the most common findings in the accessibility audits run by states like Victoria and NSW.
Source View and HTML Filtering Best Practices
The source button inside CKEditor 5 is genuinely powerful and equally risky. When toggled on, editors see the raw HTML their content produces, which lets them tweak attributes, paste tables from spreadsheets, or clean up weird formatting. It also exposes the underlying markup to mistakes that the toolbar would otherwise prevent.
The recommended approach is to allow Source editing only in text formats assigned to senior roles, never in the default format handed to new content authors. Drupal South Pacific sessions frequently emphasise this point, and most Australian agencies follow the same pattern. Combine Source editing with General HTML Support that explicitly lists allowed tags, and consider a hook_update or a small custom module that warns site admins when a format with Source access gets assigned to a low-trust role. Logging changes to filtered HTML through watchdog gives editors a paper trail for post-publication corrections as well.
CKEditor 4 vs CKEditor 5 Configuration Compared
The migration from CKEditor 4 to 5 was not a simple swap. The plugin architecture, configuration format, and filtering model all changed, and the comparison below maps the most common differences for teams still running hybrid sites or planning an upgrade window.
| Area | CKEditor 4 (Drupal 7/9 era) | CKEditor 5 (Drupal 10+) |
|---|---|---|
| Config location | Admin UI form per text format | YAML files in config sync |
| Plugin model | Separate contrib plugins | First-party plugins plus General HTML Support |
| HTML filtering | Per-format allowed tags list | HTMLPurifier plus GHS allowed tags |
| Media embedding | ckeditor_media_embed contrib | Media embed via Media module |
| Source editing | Always available | Per-format toggle, opt-in |
| Toolbar model | Single row with groups | Multiple rows, active vs disabled |
| Custom styles | Styles dropdown with classes | Style buttons with allowed elements |
| Legacy upgrade path | N/A | Continued support until Drupal 11 EOL |
For Australian sites still on Drupal 9, the upgrade checklist should include auditing every CKEditor 4 contrib plugin in use, mapping it to a CKEditor 5 equivalent, and rehearsing the migration on a staging environment before AEST business hours. A freeze on content publication over a weekend is usually enough, particularly if the team schedules it around the Anzac Day or Melbourne Cup long weekends where publishing volume is naturally lower.