Magic Editor X logo

Magic Editor X

By Schero

Free, MIT-licensed block editor for Strapi 5: live collaboration across servers, version history ..

Latest version

v2.5.0

released November 16, 2026

npm install magic-editor-x

Magic Editor X

Magic Editor X

Block editor for Strapi 5: an Editor.js custom field with Media Library uploads, custom blocks, templates, tables with merged cells, math and footnotes, comments on blocks and on selected text with @mentions, block suggestions, version history, an audit trail, live collaboration across several servers, rendered Content API and GraphQL output, React and Vue components, and optional AI and grammar assistants that use your own provider. Free and open source under the MIT license.

npm license: MIT

Live docs: https://schero94.github.io/Magic-Editor-X/

Contents

Getting started in 3 steps

For editors who open an entry with a Magic Editor X field for the first time:

  1. Write. Click into the field and type. Press + at the start of an empty line, or type /, to add a heading, list, image, table or any other block. Select text to make it bold, add a link or start a comment.
  2. Find the extras. Everything beyond writing is in one place: More tools above the field (Review: comments, history, quality, suggestions; Write: AI, templates, insert from another entry; View: preview, focus, shortcuts). A block's own menu (⋮⋮ next to it) moves, copies or changes that block.
  3. Save. Use Save in the Content Manager as usual. The Magic Editor X panel next to the entry shows who else is editing it, open comments and quality problems. If your browser crashes before you save, the field offers your unsaved changes back the next time you open the entry.

Features

Every feature is available in every installation. There is nothing to activate, no tiers and no usage limits. The plugin makes outgoing requests only for link previews, images and media by URL, the external link check and the AI provider and LanguageTool server the owner configured, and only when someone uses one of these features (see Security and privacy). Mention e-mails, when the owner turns them on, go through your own Strapi email plugin.

  • Custom field plugin::magic-editor-x.richtext (stored as JSON) for collection types, single types, components and dynamic zones, including localised fields and Draft & Publish.
  • Block tools (block name in brackets, the same names 1.x used):
    • text: paragraph (paragraph), heading H1 to H6 (header), list with nesting, ordered and unordered (list), checklist (checklist), quote (quote), warning (warning), alert in eight colours (alert), collapsible toggle (toggle), delimiter (delimiter), table with header row and column, alignment, merged cells and a caption (table), formula in TeX (math, 2.4);
    • structure: table of contents built from the headings, with stable anchors (toc), synced block that shows shared content edited in one place (synced, see Templates, patterns and synced blocks);
    • code: plain code (code), code with syntax highlighting and an optional file name (codeFlask; Prism with plain text, JavaScript, TypeScript, JSX, TSX, JSON, HTML/XML, CSS, SCSS, Shell, Python, PHP, Ruby, Java, Kotlin, Swift, C#, C, C++, Go, Rust, SQL, GraphQL, YAML, Markdown, Dockerfile and diff);
    • media: image upload by file or URL into the Media Library (image, with alternative text and a focal point), picking images from the Media Library (mediaLib, inserts image blocks), image by URL without upload (simpleImage), gallery of Media Library images as grid or carousel (gallery), video and audio from the Media Library with captions and WebVTT tracks (video, audio), file attachments (attaches), embeds such as YouTube, Vimeo, CodePen, GitHub, Figma and others (embed);
    • other: link preview card (linkTool), person card (personality), call-to-action button (button), raw HTML (raw).
  • Inline tools: bold, italic, link with target and rel (hyperlink, with a built-in picker that links an entry of your content types, see Internal links), mention of an entry (mention, Ctrl/Cmd+Shift+2, or type @), inline formula (inlineMath, Ctrl/Cmd+Shift+E), footnote (footnote, Ctrl/Cmd+Alt+F), marker, underline, strikethrough, inline code, tooltip, and the AI assistant when it is enabled.
  • Block tunes: alignment (alignmentTune), text variant call-out / citation / details (textVariant), indent (indentTune).
  • Field presets: per field in the Content-Type Builder: allowed blocks and heading levels, character and block limits, required alternative text, allowed links, AI and live collaboration on or off, publishing guard. Enforced on every save and over the live channel, not only in the editor. See Field presets.
  • Writing: Markdown shortcuts (#, -, 1., [], >, ```, ---, **bold**, _italic_, ~~strike~~, `code`), find and replace, keyboard shortcut help, focus mode, actions for several selected blocks, counts with reading time, a rendered preview of the field (Ctrl/Cmd+Alt+P), undo and redo, drag and drop, full screen. The field toolbar shows undo, redo, a More tools menu and full screen; everything else is in the menu. See Writing tools.
  • Templates, patterns and synced blocks: reusable starting content and block sequences per field or preset, inserted from the editor toolbar, and synced blocks that every field shows from one source. See Templates, patterns and synced blocks.
  • Comments: threads on single blocks or on selected text, with replies, resolve and reopen, @mentions of colleagues, a "Mentions and replies" widget on the admin home page and optional e-mails, for editors and read-only reviewers, with their own permissions. See Comments.
  • Suggestions: reviewers propose block changes in a separate copy of the field; editors accept or reject each one. See Suggestions.
  • Paste and import: Word, Google Docs, LibreOffice, web pages and Markdown become real blocks (tables keep merged cells, header cells and alignment; videos and audio from the web are copied into the Media Library); a CLI migrates Strapi Blocks, Markdown and HTML fields. See Paste, import and migration.
  • Media: alternative text and "decorative image" on image blocks and gallery images, a focal point that frontends keep visible when they crop; images keep their Media Library id and responsive formats.
  • Quality checks: accessibility lint (alternative texts, heading order, link texts, table headers, contrast of custom colours, videos without captions, empty tables of contents), a link check and an optional scheduled check of every external link, with an optional publishing guard. See Quality checks.
  • Renderers, schema and types: magic-editor-x/render (HTML, plain text, Markdown; framework-free and XSS-safe), React and Vue components (magic-editor-x/react, magic-editor-x/vue), guides for React, Vue/Nuxt and Astro, magic-editor-x/schema (JSON Schema) and magic-editor-x/types (TypeScript). See Rendering content.
  • Content API and GraphQL output: ?mex=html|text|markdown|json on Content API requests and <field>Rendered / <field>Resolved in GraphQL, with internal links, mentions, embedded entries, media and synced blocks resolved with the caller's permissions. See Content API and GraphQL output.
  • Custom blocks: define your own blocks in Settings: simple blocks with fields (text, textarea, URL, number, select, checkbox, image, colour) and an optional HTML template, or embedded-entry blocks that link an entry of another content type. Import and export as JSON. Blocks that need code (own editor UI, strict data rules, own output) are defined once with the block SDK; see Custom blocks in code (SDK).
  • Version history: named versions, a word-level comparison with the current content (tune changes shown as "Alignment: left → center"), restore of the whole field or a single block; automatic versions during live sessions. Fields inside repeatable components and dynamic zones have their own history (2.4). Synced block sources keep versions too.
  • Audit trail: who changed which field, version, comment, template or setting, and when, with counts and block ids but never the content. See Audit trail.
  • Live collaboration: several admins edit the same field at the same time with character-level merging, presence avatars and read-only viewers. Works with several Node processes behind a load balancer without sticky sessions.
  • AI assistant: improve, fix grammar, shorten, expand, summarize, simplify, translate, change tone and continue writing, using Anthropic, OpenAI or any OpenAI-compatible server (for example a local model) with your own key, on selected text or on chosen blocks. Optional, each behind its own owner switch: alternative text suggestions for images and translate or summarize a whole field. See AI assistant.
  • Grammar check: spelling and grammar of a whole field with a LanguageTool server (self-hosted or hosted), off until the owner turns it on. See Grammar check (LanguageTool).
  • Entry panel (2.5): a Magic Editor X panel next to every entry shows who else is editing it, open comment threads and quality problems per field; optional soft lock that asks once before you edit an entry someone else is editing. Homepage widgets "My open threads" and "Broken links".
  • Unsaved work is kept (2.5): unsaved field content stays in your browser and is offered back after a reload, crash, closed tab or ended session.
  • Reuse (2.5): insert blocks from another entry, field or language with a preview, and copy blocks between fields with everything they contain.
  • Many fields (2.5): fields start only when they come near the screen, so long entries open fast.
  • Colours from your palette (2.5): text colour and highlight from named tokens you define (no free colours, no inline styles), superscript and subscript, and inline annotations such as abbreviations. All off until a field turns them on.
  • Private upload providers (2.5): files of private storage (for example a private S3 bucket) are signed on every read and never stored signed. Drop files onto a field to upload and insert them.
  • Tools for AI clients (2.5): optional tools, preset schemas and a content guide for Strapi's MCP server.
  • Strapi-native admin: built with the Strapi Design System, light and dark mode, keyboard accessible, admin in English, German, French, Spanish and Portuguese.
  • Safe content: every value is normalised and sanitised on the server when it is saved, from the Content Manager, the Content API or code.
  • Strapi AI translations and Releases: Strapi's AI translation sends only the text of Magic Editor X fields and rebuilds other locales from the source structure; Releases show entries the publishing guard would refuse as not ready. See Strapi AI translations and Releases.

Screenshots

Editor in the Content Manager, light modeEditor in dark mode
Two admins editing the same fieldVersion history dialog
AI assistant dialogSettings, configuration page
Settings, custom blocks listCustom block form

| Field presets in the Content-Type Builder | Content that does not match its field settings | | Find and replace | Quality checks and link check | | Version comparison with per-block restore | Image block with alternative text | | Actions for several selected blocks | Keyboard shortcuts |

New in 2.3:

Comments panel with an open thread and its reply, a resolved thread whose block was removed, and a comment marker next to a blockComments panel in dark mode
Insert a template or pattern dialog with a search, the pattern Release notes and its rendered previewSettings, Templates: patterns and a template with where they are offered, on/off switches and row actions
The field as a rendered preview: heading, list, code with line numbers, table, image and quoteA synced block Opening hours in the editor with the Edit source and Detach buttons
Gallery block in grid layout with two columns: three images with alternative texts, captions and focal pointsVideo block with title, poster image and an English captions track, and an audio block
Focal point picker: the point marked on the image, its position in percent and a Reset focal point buttonTable of contents block with its settings and the live list of headings, and two mention chips in the text
Code block with the language Python and line numbersEditor tool of a block defined in code with title, text, link and tone fields
Quality panel with the last scheduled link check: one broken link with status 404Image block with an AI suggestion for the alternative text and the Use suggestion and Dismiss buttons
AI for the whole field dialog: translation into German, a note on what is sent and a preview per textGrammar check panel with two LanguageTool issues and suggested replacements
Editor on a 390 px wide screenComments panel on a 390 px wide screenPreview on a 390 px wide screen

New in 2.4:

The field toolbar with undo, redo, the More tools menu and full screenThe More tools menu grouped into Review, Write and View
Table with a header row and a header column, right-aligned numbers, a merged cell, a caption and the table toolbarThe same table in dark mode on a 390 px wide screen
A math block with its TeX source, style select and rendered formula, and two inline formulasThree numbered footnote markers in the text and the footnote list under the field
Comments panel with a thread on selected text, a mention of a colleague and the highlighted passages in the textMentions and replies widget on the admin home page with one unread mention
Suggestions panel with a changed, an outdated, a new and a removed block, each with Accept and RejectSuggest mode: the field is a separate copy with Stop suggesting and Send 1 suggestion
AI for the chosen blocks: translation into German with a word diff and Apply to blocksSettings, Audit trail: filters and a list of events with who changed what and how many blocks
Versions of a synced block source with a comparison against the current content and RestoreSettings, Configuration: the scheduled link check with its time zone, next run and the Run now button
Typing @ in a paragraph opens entry suggestions at the caretCode block with the file name config/plugins.js above the code

New in 2.5:

The Magic Editor X entry panel: Editing now with a colleague, open comments and quality per fieldThe entry panel in dark mode on a 390 px wide screen
Admin home with the My open threads and Broken links widgetsRestore notice: unsaved changes found, with Restore and Discard
Insert from another entry: entry, field and a preview of the blocks with checkboxesMore tools with Insert from another entry in the Write group
The Colour menu with palette tokens and highlightsSettings: the colour palette with the CSS to copy and contrast warnings
Dropping an image onto a fieldA field whose images come from private storage

All screenshots use synthetic data (acceptance host: Strapi 5.61.1).

Core concepts

TermMeaning
FieldOne Magic Editor X attribute of a content type or component. Its value is an Editor.js document.
BlockOne entry of the document's blocks array, for example a paragraph or an image. Each block has an id, a type (the block name) and data.
Custom blockA block type defined in Settings > Magic Editor X > Custom blocks, or in code with the block SDK. Its name becomes the block type.
TemplateStarting content for a field. Inserting it replaces the field content.
PatternA group of blocks that editors insert anywhere in a field.
Synced blockShared content edited once in Settings > Magic Editor X > Templates. A field stores only a reference ({ ref }) and shows the current source content.
ThreadA comment and its replies on one block, or on a passage of text in one block, of one field, document and locale. Threads are not part of the field value.
SuggestionOne proposed change of one block (changed, new or removed), waiting for an editor to accept or reject it. Suggestions are not part of the field value.
Field keyA random fieldKey that a value inside a repeatable component or dynamic zone carries, so history, comments and live rooms follow that entry (2.4).
VersionA stored copy (snapshot) of one field of one document in one locale, listed in the version history.
RoomThe live editing session of one field of one document in one locale. A room exists while people edit and for collaboration.roomTtlMinutes afterwards.
ViewerSomeone in a room who can read the document but not update it. Viewers see changes live but cannot type.

Screens

ScreenWhereWho can open it
Editor fieldContent Manager, edit viewEveryone who can read the field. Uploads, version history and the AI assistant need the permissions in Admin API and permissions.
Version historyMore tools > Version history, for a saved documentaccess and Content Manager read on the document; saving, naming and restoring need update. The Activity tab needs audit.read.
Find and replaceMore tools > Find and replace, or Ctrl/Cmd+Shift+F in the editorEveryone who can read the field; replacing needs update.
Quality checksMore tools > Quality checks (the number counts problems)Everyone who can read the field; the link check needs access.
Keyboard shortcuts, focus modeMore tools > Keyboard shortcuts or Focus mode, or Ctrl/Cmd+/Everyone who can read the field.
Field optionsContent-Type Builder, Magic Editor X field, Basic and Advanced settingsContent-Type Builder access (development mode).
AI assistantInline toolbar (select text), or a block's menu, the block selection bar or Ctrl/Cmd+Shift+G for whole blocksaccess and ai.use, when an administrator turned the assistant on.
AI for the whole fieldMore tools > AI for the whole fieldaccess and ai.use, when the owner allowed whole-field AI actions and the field does not turn AI off.
Comments panelMore tools > Comments (shows the open-thread count), a block's comment marker, or Comment on selected text (Ctrl/Cmd+Alt+M)access, comments.read and Content Manager read on the document; writing and mentioning need comments.write, deleting others' comments comments.moderate.
Insert templateMore tools > Insert templateaccess and Content Manager read on the type; "Save content as template" and "Save as pattern" need templates.manage.
PreviewMore tools > Preview, or Ctrl/Cmd+Alt+PEveryone who can read the field, read-only users included.
Grammar checkMore tools > Check grammaraccess and grammar.use, when the owner turned LanguageTool on.
Suggestions panelMore tools > Suggestions, a block's suggestion marker, or "Review suggestions" under the fieldaccess, suggestions.create or suggestions.review and Content Manager read; accepting and rejecting need suggestions.review and update.
Suggest modeMore tools > Suggest changes, or "Suggest changes" under a field you cannot editaccess, suggestions.create and Content Manager read.
Mentions and repliesWidget on the admin home pageaccess and comments.read.
ConfigurationSettings > Magic Editor X > Configurationsettings.read (view), settings.update (edit).
Custom blocksSettings > Magic Editor X > Custom blockscustom-blocks.manage.
TemplatesSettings > Magic Editor X > Templates (templates, patterns and synced blocks, with versions of synced blocks)templates.manage.
Audit trailSettings > Magic Editor X > Audit trailaudit.read and settings.read.

Compatibility

PluginStrapiNodeNotes
2.x5.38 or later (acceptance host: Strapi 5.61.1; 2.5 also checked on 5.62.0)22.12 or later (22 or 24)SQLite, PostgreSQL and MySQL/MariaDB through the Strapi database connection. Acceptance runs used SQLite and PostgreSQL 16.
1.x5.x22No longer developed.
  • engines.node is >=22.12.0 <=26.x.x (2.5 declares the floor that sanitize-html 2.18 already required since 2.4.0); the 2.3 to 2.5 test runs used Node 22.23.1.
  • The admin uses the React, React Router, react-intl, styled-components and Design System versions of the Strapi admin (React 18, Design System 2.2.4 in Strapi 5.61, 2.3.1 in 5.62).
  • Dropping files onto a field uses the Media Library drop zone that Strapi registers from 5.61; with an older Strapi or the legacy Media Library (useLegacyMediaLibrary) Editor.js keeps its own file drop.
  • Console messages you may see in the admin that come from Strapi itself, not from the plugin: the useRBAC deprecation warning, React Router future-flag warnings, the styled-components attribute prop warning, and the upgrade check to api.github.com when outgoing requests are blocked.
  • The editor uses Editor.js 2.31.7. Editor.js 2.32.0 is still a release candidate on npm (2.32.0-rc.3 on the next tag, checked 2026-11-12) and is not used. Why the plugin stays on Editor.js is explained in docs/engine-decision.md.
  • Formulas are rendered with Temml 0.14 (MIT), loaded by the admin only when a field shows math.
  • magic-editor-x/react works with React 18 and 19 (peer ^18.0.0 || ^19.0.0), in the browser and in server rendering, including React Server Components.
  • magic-editor-x/vue needs Vue 3.5 or later (optional peer ^3.5.0; it is never installed by the plugin).
  • magic-editor-x/render and magic-editor-x/blocks have no dependencies and no Node built-ins, so they run in Node, browsers and edge runtimes.
  • The GraphQL fields need @strapi/plugin-graphql; without it nothing is registered.

Install

npm install magic-editor-x

Enable the plugin in config/plugins.ts (or config/plugins.js):

export default ({ env }) => ({
  'magic-editor-x': {
    enabled: true,
    config: {
      // optional, see Configuration
    },
  },
});

Then rebuild the admin and restart:

npm run build
npm run develop

Add the field in the Content-Type Builder: Add another field > Custom > Magic Editor X. In its settings you can set a placeholder, a preset and the other field presets, and a minimum height (120 to 2000 px).

After the first start, Super Admins can use everything. Other roles need the plugin actions listed in Admin API and permissions (Settings > Administration Panel > Roles > Plugins > Magic Editor X).

Configuration

Reference

All keys are optional. Infrastructure options live in config/plugins; the AI provider is edited at runtime in Settings > Magic Editor X > Configuration.

KeyTypeDefaultEffect
debugbooleanfalseWrites debug log lines (never content or personal data).
rawHtml'sanitize' | 'allow' | 'disable''sanitize'Raw HTML block on save: sanitize removes scripts, event handlers, iframes and unsafe URLs; allow stores the HTML as typed; disable empties it.
sanitizeOnSavebooleantrueNormalise and sanitise Magic Editor X values on every Document Service write. Turning this off is not recommended.
encryptionKeystring (32+ characters)unsetKey for the stored AI provider key. Prefer the MAGIC_EDITOR_X_ENCRYPTION_KEY environment variable.
uploads.maxImageBytesinteger10485760 (10 MiB)Largest image accepted by file or URL (hard cap 500 MiB).
uploads.maxFileBytesinteger20971520 (20 MiB)Largest attachment.
uploads.maxMediaBytesinteger52428800 (50 MiB)Largest video or audio file copied from a pasted URL (POST /magic-editor-x/media/byUrl, 2.4; hard cap 200 MiB). WebVTT tracks are capped at 512 KiB.
uploads.allowPrivateOriginsstring[][]Exact origins (for example http://media.intranet.example.test:9000) that images and media by URL may fetch although they resolve to a private address (2.4). Redirects from them are never followed. At most 20.
linkPreview.enabledbooleantrueLink preview cards. When false, GET /magic-editor-x/link answers 404.
linkPreview.timeoutMsinteger8000Time limit for fetching a page (1000 to 30000).
api.autoParseJSONbooleantrueTurn 1.x JSON strings into objects in Content API GET responses.
ai.allowPrivateBaseUrlbooleanfalseAllow AI base URLs on loopback or private networks (for local models). Owner decision; not editable in the admin.
ai.apiKeystringunsetProvider key from the environment. When set it wins over a key stored in the settings.
ai.requestsPerMinuteinteger20AI requests per admin per minute, shared by all processes.
ai.timeoutMsinteger60000Time limit for one provider request.
ai.altTextobject{ allowPrivateOrigins: [] }Alternative text suggestions (2.4); key below.
ai.altText.allowPrivateOriginsstring[][]Exact origins of private image storage (for example a MinIO host in your network) that alt text suggestions may read images from. One DNS lookup, pinned connection, no redirects; link-local and cloud metadata addresses are refused even when listed. At most 20, checked at startup.
languageTool.allowPrivateBaseUrlbooleanfalseAllow a LanguageTool base URL on loopback or private networks (self-hosted server in the LAN). Owner decision.
languageTool.requestsPerMinuteinteger30Grammar checks per admin per minute, shared by all processes.
languageTool.timeoutMsinteger20000Time limit for one LanguageTool request.
collaboration.enabledbooleantrueLive collaboration and its Socket.IO server.
collaboration.pathstring'/magic-editor-x/realtime'Socket.IO path on the Strapi HTTP server.
collaboration.allowedOriginsstring[][]Extra browser origins allowed to open the socket. The admin URL and the server URL are always allowed.
collaboration.pollIntervalMsinteger400How often each process reads updates written by other processes (50 to 10000).
collaboration.roomTtlMinutesinteger30Keep a room's live state this long after the last person left.
collaboration.maxMessageBytesinteger2097152 (2 MiB)Largest accepted socket message.
collaboration.snapshotIntervalMinutesinteger10Automatic version while people edit live. 0 turns it off.
collaboration.tokenTtlSecondsinteger60Lifetime of the one-time token that opens the socket.
collaboration.maxConnectionsPerAdmininteger20Open live sockets per admin across all processes.
collaboration.maxRoomsPerAdmininteger20Different fields one admin may have open live at the same time, across all processes.
collaboration.revalidateSecondsinteger60Full permission re-check of open sockets. Role, permission and user changes are applied within about a second anyway.
collaboration.rateLimitobject{ sessionsPerMinute: 60, updatesPer10s: 300, bytesPer10s: 8388608 }Session tokens per admin and minute (shared by all processes), updates and update bytes per socket in 10 seconds.
collaboration.compactionobject{ enabled: true, idleSeconds: 60, minBytes: 262144, ratio: 4, checkIntervalSeconds: 30 }Rebuilds an idle room whose live state is ratio times larger than a fresh copy (and at least minBytes) as a new generation, once across all processes. Open editors switch without reconnecting; edits that had not reached the server yet are kept. Bounds: idleSeconds 15 to 86400, minBytes 1 KiB to 512 MiB, ratio 1.5 to 1000, checkIntervalSeconds 1 to 3600.
history.maxSnapshotsPerFieldinteger50Versions kept per field and locale; older ones are deleted.
comments.enabledbooleantrueBlock comments in the editor. false hides them and the comment routes answer 404.
comments.perMinuteinteger30New comments and replies one admin may post per minute, shared by all processes (1 to 1000).
comments.mentionsPerMinuteinteger60Searches of the @mention picker per admin and minute, shared by all processes (2.4).
comments.notificationsobject{ email: false, emailPerHour: 10 }Mention e-mails (2.4); keys below. In-app notifications are always on.
comments.notifications.emailbooleanfalseE-mail people when they are mentioned, through the Strapi email plugin. The e-mail names who mentioned them and the entry, never the comment text.
comments.notifications.emailPerHourinteger10Mention e-mails per recipient and hour.
suggestions.enabledbooleantrueBlock suggestions (2.4). The UI appears only for roles with suggestions.create or suggestions.review, which no role has until you grant them. false hides them and the routes answer 404.
suggestions.perMinuteinteger20Times one admin may send suggestions per minute (each send carries 1 to 50 block suggestions), shared by all processes.
links.urlPatternstring''href of internal links, for example '/{locale}/{collection}/{slug}' or 'https://www.example.com/{collection}/{documentId}'. Placeholders: {documentId}, {locale}, {slug}, {collection}, {singular}. Empty means '/{collection}/{documentId}'. See Internal links.
qualityChecks.externalLinksobject{ enabled: false, timeoutMs: 5000, perMinute: 30 }External link check of the quality panel; keys below.
qualityChecks.externalLinks.enabledbooleanfalseLets the quality panel check external links (outgoing requests through the SSRF-protected fetcher; owner opt-in).
qualityChecks.externalLinks.timeoutMsinteger5000Time limit per request and per redirect hop (1000 to 15000).
qualityChecks.externalLinks.perMinuteinteger30External URLs one admin may check per minute, shared by all processes.
qualityChecks.externalLinks.allowPrivateOriginsstring[][]Exact origins (for example an intranet host) that the link checks may reach although they resolve to a private address. Redirects from them are never followed.
qualityChecks.externalLinks.scheduleobject{ enabled: false, rule: '0 3 * * *', maxUrlsPerRun: 500, perMinute: 60, perHostConcurrency: 2 }Scheduled check of every external link in all editor fields (needs externalLinks.enabled); keys below.
qualityChecks.externalLinks.schedule.enabledbooleanfalseRuns the scheduled check. One process in a cluster runs each check (lease).
qualityChecks.externalLinks.schedule.rulestring'0 3 * * *'Cron rule (in schedule.tz, else server time).
qualityChecks.externalLinks.schedule.tzstringunsetIANA time zone of the rule, for example 'Europe/Berlin' (2.4). Checked at startup.
qualityChecks.externalLinks.schedule.maxUrlsPerRuninteger500Distinct URLs checked per run (1 to 10000).
qualityChecks.externalLinks.schedule.perMinuteinteger60Requests per minute for the whole run (1 to 600).
qualityChecks.externalLinks.schedule.perHostConcurrencyinteger2Requests in flight per host (1 to 8).
audit.enabledbooleantrueRecords the audit trail (2.4). It holds no content. false stops recording and the extra reads it needs.
audit.retentionDaysinteger180Days an audit event is kept (0 keeps everything, at most 3660). One process prunes once an hour.
presence.enabledbooleantrueThe Magic Editor X entry panel shows who else has the entry open (2.5). Names only, never e-mail addresses. Works without live collaboration.
presence.softLockbooleanfalseAsks once per tab before you edit an entry someone else is editing ("Continue editing"). Never blocks anyone (2.5).
presence.perMinuteinteger30Presence requests per admin per minute, shared by all processes.
mcp.enabledbooleanfalseRegisters the Magic Editor X tools, preset schemas and content guide with Strapi's MCP server. Strapi's own server.mcp.enabled must be on too (2.5).
reuse.enabledbooleantrue"Insert from another entry" in More tools > Write (2.5).
reuse.perMinuteinteger60Requests of "Insert from another entry" per admin per minute.
palette.colors{ name, label, light, dark }[][]Named text colours editors may pick in fields with "Text colour and highlight" (2.5). name becomes the class mex-color-<name>; light/dark are hex colours for the editor display and the contrast check. At most 24.
palette.highlights{ name, label, light, dark }[][]Named highlight colours (<mark>, class mex-highlight-<name>), same rules (2.5). Optional palette.background and palette.text ({ light, dark }) set the page colours the contrast check compares with.
drafts.enabledbooleantrueKeeps unsaved field content in the admin's browser (IndexedDB) and offers it back after a reload, crash, closed tab or ended session: one notice with Restore or Discard (2.5). Removed on save, discard, expiry and logout.
drafts.ttlHoursinteger72Lifetime of a local draft in hours (1 to 720).
lazyInit.enabledbooleantrueStarts the editor and the live room of a field only when it comes near the screen or gets focus; until then the saved content is shown (2.5).
lazyInit.marginPxinteger800Distance above and below the screen at which a field starts (0 to 10000 CSS pixels).

The validator rejects wrong types and ranges at startup and names the key, never the value. Keys from 1.x that no longer exist are ignored with a warning; see Migrating from 1.x.

Environment variables

NameRequiredDefaultEffect
MAGIC_EDITOR_X_ENCRYPTION_KEYOnly to store an AI or LanguageTool key in the settingsunset32 or more characters. Encrypts the AI provider key and the LanguageTool key (AES-256-GCM). Without it the settings page cannot store a key; you can still pass one with ai.apiKey. Generate one with node -e "console.log(require('crypto').randomBytes(32).toString('base64'))". Keep it stable: a different key makes a stored provider key unreadable, and the settings page then asks you to enter it again.

The plugin also uses Strapi's own admin.auth.secret (ADMIN_JWT_SECRET) to sign collaboration tokens. Every process of a cluster must use the same value.

AI settings (admin)

Settings > Magic Editor X > Configuration stores these values in the Strapi store:

SettingDefaultRange
Enabledoff
Provideranthropicanthropic, openai, openai-compatible
Base URLprovider default (https://api.anthropic.com, https://api.openai.com); required for openai-compatiblehttps, or private hosts when ai.allowPrivateBaseUrl is on
Modelclaude-opus-5-5 (Anthropic), gpt-6-luna (OpenAI)letters, digits and ._:/@-
API keynonenever returned; changing the provider or base URL requires entering it again
Max input characters8000200 to 50000
Max output tokens409664 to 16000
Send images to the AI provider (ai.allowImages)offAllows alternative text suggestions; see AI assistant
Allow whole-field AI actions (ai.allowFieldActions)offAllows translate and summarize of a whole field

The same page has a Grammar check (LanguageTool) section; see Grammar check (LanguageTool). It also shows the scheduled link check (rule, time zone, next run, last run, and Run now for admins with settings.update), the private image origins for alt text and whether mention e-mails are on, all read-only.

Live collaboration

When a document has been saved once, the editor joins the room of its field. Everyone with Content Manager read access to that document, locale and field and the collaborate action can join; people with update access can type, others watch as viewers.

How it works:

  • Conflict-free structure. The field is shared as a Yjs document in which every block has a stable id and every part of its data has its own shared type: texts merge character by character, and every table cell, list item, checklist entry, tune (alignment, text variant, indent) and custom block field is merged separately. Two people can edit different cells of one table, different items of one list, or the text and the alignment of one paragraph at the same time and both changes are kept. When two people change the same number, switch or option at the same moment, one value wins on every screen. The stored Editor.js JSON does not change.
  • Presence. Avatars with first name and last initial (never e-mail addresses), coloured carets and selections of the others in the text, a coloured marker at the block someone is editing and an "away" state after a minute without activity or when the tab is hidden. Joins and leaves are announced politely to screen readers. Colours follow the light and dark theme; the caret does not blink when reduced motion is requested.
  • Connection state in the toolbar: Connecting, Syncing, Live, Reconnecting, Offline, View only, or Live editing unavailable.
  • Offline and reconnects. You can keep typing while the connection is gone. Unsent changes are kept, sent again after the reconnect and merged with what others did meanwhile, without duplicates. Reconnects use exponential backoff with jitter and a new one-time token; waking a laptop or returning to a tab reconnects at once. Closing the tab leaves the room immediately.
  • Undo and redo (toolbar, Cmd/Ctrl+Z, Shift+Cmd/Ctrl+Z) only revert your own changes, never what others typed (the last 200 steps).
  • Saving. Changes made by others become part of your form. Save, publish and discard work as usual. Version history restores into the live room, so everyone sees the restored content. Each locale has its own room.
  • Permissions are checked when you join, re-checked within about a second when roles, permissions or users change (on every process), and every collaboration.revalidateSeconds. An admin who loses update access becomes a viewer; one who loses read access is disconnected.
  • Nothing typed is lost. Edits are stored in the database before they are confirmed. When a room is cleaned up collaboration.roomTtlMinutes after the last person left and contains edits nobody saved, a version is created first, so they can be restored from the history.

Limits:

  • A new entry that has not been saved yet has no room. A new section in a repeatable component or dynamic zone gets its room, history and comments after the entry is saved once; until then the toolbar says so.
  • Text formatting (bold, links, …) is part of the text; two people formatting the same word at the same moment can produce nested tags, which the sanitiser keeps valid.
  • Up to 5000 blocks per field (the stored-content limit); rooms above 64 MiB of history refuse further edits until they are compacted.

Running several instances

Collaboration works with several Node processes and several machines that share one database, for example Railway with 2 replicas and pm2 with 4 processes each, behind a load balancer without sticky sessions. No Redis is needed.

How it works:

  • The browser connects with the WebSocket transport only. A WebSocket connection is one long-lived request, so it does not need sticky routing. Your proxy must allow WebSocket upgrades on collaboration.path (default /magic-editor-x/realtime) and send them to Strapi.
  • The session token is signed with a key derived from admin.auth.secret, so any process can accept a token issued by another one. All processes must use the same ADMIN_JWT_SECRET.
  • Every update is written to the table magic_editor_x_collab_updates before it is acknowledged. Other processes read new rows every collaboration.pollIntervalMs and send them to their own sockets.
  • Presence is stored in magic_editor_x_collab_presence with heartbeats; leases and one-time keys in magic_editor_x_locks. Seeding a room, compaction, automatic versions and cleanup each run once across all processes.
  • Every process keeps the active rooms in memory, checks every update before it is stored (only the structures the editor uses, every dependency present, every touched block valid within the content limits) and relays it.
  • Clients resynchronise their state every 20 seconds and after each reconnect, so a process restart or deploy loses nothing that was acknowledged.
  • Permission changes set a signal in magic_editor_x_locks that every process checks every second. Session, AI, link check, comment and grammar check rate limits are counted in magic_editor_x_counters, so they apply to the whole cluster.
  • Every process fires the scheduled link check; a one-time key and a lease in magic_editor_x_locks let exactly one process run it. Its results are stored in magic_editor_x_link_fields and magic_editor_x_link_urls.
  • Comments are read from the database (polled every 15 seconds while the field is visible, 8 seconds with the panel open), so they appear on every process.

The plugin creates these tables on startup. They are not content types, so Strapi's schema sync leaves them alone. Comments, templates and versions are content types of the plugin, hidden from the Content Manager.

Behind a proxy, also set server.proxy in config/server (koa: true and the number of trusted hops in maxIpsCount) so Strapi sees the real client address.

The acceptance run with several processes is described in CONTRIBUTING.md.

AI assistant

The assistant is off until an administrator turns it on in Settings > Magic Editor X > Configuration and gives it a provider:

ProviderRequestDefault model (2026-11-11)
AnthropicPOST {base}/v1/messages, headers x-api-key and anthropic-version: 2026-10-21claude-opus-5-5
OpenAIPOST {base}/v1/chat/completions, Authorization: Bearer, max_completion_tokensgpt-6-luna
OpenAI-compatible (Ollama, vLLM, LM Studio and similar)POST {base}/v1/chat/completions, optional bearer key, max_tokensnone; you name the model
  • The key stays on the server. It is encrypted at rest with MAGIC_EDITOR_X_ENCRYPTION_KEY or read from ai.apiKey, and it is never sent to the browser or written to logs.
  • The selected text (with its inline formatting) and a fixed instruction are sent to the provider. Nothing else from the document is sent. The text is never logged.
  • Base URLs must be public https URLs. Loopback and private hosts are allowed only with ai.allowPrivateBaseUrl: true in config/plugins. Redirects are not followed.
  • Input is limited by "Max input characters", output by "Max output tokens". Each admin can send ai.requestsPerMinute requests per minute; the counter is shared by all processes.
  • The answer is sanitised to the inline tags the editor uses before it reaches the browser. The admin reviews the suggestion and chooses Replace selection; nothing changes before that.

AI for chosen blocks (2.4)

Select blocks and choose AI for the chosen blocks in the selection bar, or open a block's menu and choose AI assistant, to rewrite, shorten, translate or change the tone of just those blocks (Ctrl/Cmd+Shift+G opens it for the selected blocks or the block with the caret). Only their text is sent, with its inline formatting and links; block ids, types, settings, images and URLs stay in the browser. You see the changes as a word diff before you apply them, and one Undo reverts them.

  • Uses the same switch, permission (ai.use), rate limit and "Max input characters" as the assistant for selected text; it does not need "Allow whole-field AI actions". Fields with disableAi answer 403.
  • The answer must return every text it was sent, exactly once, or nothing changes (502 BAD_RESPONSE). Each text is sanitised to the inline tools the field allows, and links that were not in the original are removed. When the blocks changed while the assistant worked, the dialog says so and applies nothing.
  • Since 2.4 the assistant for selected text works the same way: the suggestion is limited to the field's inline tools, links the selection did not hold are removed, the dialog shows a word diff, and formatting the selection crossed is kept.

Alternative text and whole-field actions

Two more AI features use the same provider, key and rate limit. Each has its own switch in Settings > Magic Editor X > Configuration, off by default, with a note that says what is sent. Fields with disableAi answer 403 for both. Results are suggestions: the server never writes content.

FeatureOwner switchWhat is sentResult
Alternative textSend images to the AI provider (ai.allowImages)One Media Library image (the largest stored size with a long edge up to 1568 px and at most 3.5 MB; JPEG, PNG, GIF or WebP) and the content language"Suggest alternative text" on image blocks and on every gallery image; plain text up to 150 characters that the editor reviews and uses with "Use suggestion". Needs Media Library read on the file (404 otherwise).
Translate or summarizeAllow whole-field AI actions (ai.allowFieldActions)The inline text of every block in the field, with its formatting and links. Images, files and other block data are not sentMore (…) > AI for the whole field. A translation is shown as a preview and replaces the texts in place (blocks, ids and settings stay; one undo step); a summary can be copied or inserted as a paragraph.
  • Local files are read only from the public/uploads folder; remote files (for example a cloud upload provider) are fetched through the same SSRF-protected fetcher as link previews. The image type is taken from the file's bytes.
  • Upload providers on a private network (for example MinIO or S3-compatible storage inside your network) need their exact origin in ai.altText.allowPrivateOrigins (2.4). The host is resolved once and the connection is pinned to that address, redirects are never followed (also not to the same origin), and link-local and cloud metadata addresses stay refused even when listed. Settings > Configuration shows the list read-only.
  • A translation must return every text it was sent, exactly once, or nothing changes (502 BAD_RESPONSE); each text is sanitised again and links that were not in the original are removed. Fields over "Max input characters" answer 413.
  • POST /magic-editor-x/ai/image/alt-text answers 503 IMAGES_DISABLED while images are off; POST /magic-editor-x/ai/field/:action answers 503 FIELD_ACTIONS_DISABLED while field actions are off.

Grammar check (LanguageTool)

Editors with grammar.use can check the spelling and grammar of a whole field with "Check grammar" in the editor toolbar. Issues are highlighted in the text; a suggested replacement is applied only when the flagged text is still there and lies in one piece of text (not across formatting or a line break). The check is not AI: disableAi does not affect it. To keep a field's text away from LanguageTool, turn on disableGrammar in its field settings: the field shows no "Check grammar" button and POST /magic-editor-x/grammar/check answers 403 for it, so nothing from it is sent.

It is off until an owner configures it in Settings > Magic Editor X > Configuration > Grammar check (LanguageTool):

SettingDefaultNotes
Turn on the grammar checkoffNothing is sent while it is off or until an editor starts a check.
LanguageTool base URLemptyYour own server or a hosted service, for example https://languagetool.example.com; requests go to <base URL>/v2/check. Public https only, unless languageTool.allowPrivateBaseUrl is on.
User name, API keyemptyOnly for hosted accounts. The key is encrypted with MAGIC_EDITOR_X_ENCRYPTION_KEY (own key derivation), never returned, and must be entered again when the base URL or user name change.
RulesStandardStandard or Strict (level=picky, adds style rules).
  • Test LanguageTool checks a fixed sample sentence (POST /magic-editor-x/settings/language-tool/test); a test against another URL never receives the stored key.
  • What is sent: the plain text of every block in the field and the language of the content locale (en becomes en-US, de de-DE, pt pt-PT; without a locale auto). Up to 60,000 characters per check in requests of at most 20,000; longer fields answer 413. At most 500 issues are shown.
  • languageTool.requestsPerMinute limits checks per admin, shared by all processes; languageTool.timeoutMs limits one request.

Field presets

Each Magic Editor X field can have its own rules, set in the Content-Type Builder (field settings). They are stored as custom field options in the schema and enforced in three places with the same code (shared/presets.mjs): the editor offers only what the field allows, the realtime server refuses new blocks a preset does not allow, and every write (Content Manager, Content API, imports, code) is checked by the Document Service middleware.

Option (options.*)Where in the field settingsValuesEffect
presetBasicfull (default), article, basic, minimalAllowed blocks, inline tools and heading levels, see below.
linkTargetsBasicall (default), internal, external, noneWhich links are allowed: entries of the site (internal links), web addresses, both or none. Link blocks (linkTool, button, personality) count as web addresses.
requireAltBasiccheckboxImages need an alternative text or the "decorative image" mark.
allowedBlocksAdvancedcomma-separated block names, for example paragraph, header, list, image, myHeroReplaces the preset's block list (custom blocks by name). paragraph is always allowed.
headingLevelsAdvanced2-4, 2,3, 1, 3-5Replaces the preset's heading levels.
maxBlocksAdvancednumber, empty or 0 = no limitBlock limit, shown in the toolbar (12 / 20 blocks).
maxCharactersAdvancednumber, empty or 0 = no limitVisible characters, counted like the toolbar (380 / 400 characters).
disableAiAdvancedcheckboxNo AI button in this field; the AI route answers 403 for requests from it.
disableGrammarAdvancedcheckboxNo "Check grammar" button in this field; the grammar route answers 403, so its text is never sent to LanguageTool.
disableCollaborationAdvancedcheckboxNo live editing in this field (the session route answers 403).
publishGuardAdvancedcheckboxPublishing is refused while the quality checks report errors in this field.
PresetBlocksInline toolsHeadings
fullall, custom blocks includedallH1-H6
articleparagraph, header, list, checklist, quote, warning, alert, toggle, code, codeFlask, delimiter, toc, synced, table, embed, image (and the Media Library picker), gallery, video, audio, linkTool, attaches, button, and code-registered blocks that list articleallH2-H4
basicparagraph, header, list, quote, image, delimiterbold, italic, underline, strikethrough, linkH2-H3
minimalparagraph, listbold, italic, linknone

How the rules apply:

  • Editor: blocks that are not allowed leave the toolbox, the conversion menu and paste handling; heading levels and inline tools are limited; Markdown shortcuts and pasted content follow the preset (a pasted H1 becomes the nearest allowed level, a table becomes text). Existing content that no longer fits is kept, listed under "Field settings" in the quality panel with Fix automatically (changes heading levels, turns blocks that are not allowed into paragraphs, removes links that are not allowed), and a note under the field says that saving fails until it is fixed.
  • Save: a value that breaks a rule is refused with 400 ValidationError, details.code: 'PRESET_VIOLATION', details.violations: [{ field, code, blockId, index, params }] (codes BLOCK_NOT_ALLOWED, HEADING_LEVEL, LINK_NOT_ALLOWED, ALT_REQUIRED, TOO_MANY_BLOCKS, TOO_MANY_CHARACTERS) and details.errors with the field path, so the Content Manager shows the reason on the field. Errors carry rule codes and block ids only, never content. Inline formatting a preset leaves out (for example a marker in a basic field) is removed on save; the text stays.
  • Live editing: the server refuses updates that add a block type or heading level the preset does not allow (blocks that existed before stay editable). Limits and alternative texts are checked on save only, so typing is never refused half-way.

Changing a preset never changes stored content by itself. Turning sanitizeOnSave off also turns the save check off.

Writing tools

ToolHow
More tools menuThe field toolbar shows undo, redo, More tools and full screen. More tools groups the other tools: Review (comments, version history, suggestions, quality checks), Write (suggest changes, AI for the whole field, check grammar, find and replace, insert template) and View (preview, focus mode, keyboard shortcuts). Entries appear only where they can work (permission, settings, field options); counts show in the menu, and a tool that changes the view (preview, focus mode) adds a visible way back to the bar. Keyboard shortcuts are unchanged.
Markdown shortcutsAt the start of an empty paragraph: # to ###### + Space (heading), -, * or + + Space (bulleted list), 1. + Space (numbered list, other numbers set the start), [] or [x] + Space (checklist), > + Space (quote), ``` (optionally with a language) + Enter (code block), --- + Enter (delimiter). While typing: **bold**, __bold__, *italic*, _italic_, ~~strike~~, `code`. Never inside code, raw HTML or tables; only blocks and marks the field allows.
Find and replaceMagnifier button or Ctrl/Cmd+Shift+F. Searches every text block, list item, table cell, caption and code block; keeps formatting; match case, whole words, regular expressions (off by default, patterns up to 200 characters). Enter / Shift+Enter move between matches, the current match is highlighted. Replacements are normal edits (undo, collaboration). A match cannot span differently formatted text.
Keyboard shortcutsCtrl/Cmd+/ or More > Keyboard shortcuts: editor, block and inline tool shortcuts and the Markdown shortcuts of this field.
Focus modeMore > Focus mode: full screen, narrower text column, other blocks dimmed. Escape leaves.
Several selected blocksSelect across blocks (Shift+Arrow at a block edge, Ctrl/Cmd+A twice, or drag across blocks): move up or down, duplicate, copy as Markdown, delete, convert to text, heading, list or quote.
CountsBlocks, words, characters and reading time (200 words per minute) in the toolbar, with the field's limits.
Alternative textImage and image-by-URL blocks and every gallery image: "Alternative text" field (prefilled from the Media Library) and "Decorative image (no alternative text)". Required when the field has requireAlt. With the AI image switch on, "Suggest alternative text" (see AI assistant).
Focal pointImage blocks and gallery images: "Set focal point", then click or tap the image, or use the arrow keys (1 %, Shift for 10 %); Reset clears it. Frontends keep this point visible when they crop the image.
MentionsType @ at the start of a word in a text block: entry suggestions open at the caret (arrow keys, Enter inserts, Tab switches the content type, Escape closes and keeps the text). An e-mail address such as name@example.test never opens it. Or select text and press the Mention button or Ctrl/Cmd+Shift+2: the internal-link picker opens with the selection as search text. The picked entry becomes a chip with its title. Backspace or Delete removes the whole chip. Offered when the field allows links to entries (linkTargets all or internal).
Table of contentsBlock "Table of contents": title, heading levels (from, to) and list style. The editor shows a live preview from the headings; frontends build the list when they render.
Code languageThe code block's language select lists 27 languages (one list for the editor, highlighting and renderers). A language the list does not have (from older or imported content) is kept and highlighted as plain text.
Code file nameThe highlighted code block (codeFlask) has an optional file name above the code (plain text, up to 200 characters). Renderers show it as a caption; Markdown writes it as ```js title="name". The plain code block has no file name.
TablesHeader row and header column, alignment per column, merged cells and a caption. Select cells with Shift+click (or drag) and merge them, or use merge right/down and split from one cell. Tab and Shift+Tab move between cells (Tab in the last cell adds a row), Enter moves down, Shift+Enter is a line break, Alt+F10 opens the table toolbar. Pasting tab-separated text from a spreadsheet fills the cells; pasting a table from Word or a web page keeps merged cells, header cells and alignment. Tables saved before 2.4 stay exactly as they were.
MathBlock "Math": TeX source, display or inline style and a live preview with parser errors. Inline formulas: select text and press Ctrl/Cmd+Shift+E, or press it at the caret. The API and the renderers output MathML (see Rendering content).
FootnotesCtrl/Cmd+Alt+F adds a footnote at the caret and opens its note (bold, italic and links as the field allows). Notes live in their marker, so copying, moving, undo and deleting keep marker and note together. Footnotes are numbered in reading order and listed under the field (go to, edit, remove).
PreviewPreview button or Ctrl/Cmd+Alt+P: the field rendered with magic-editor-x/react as a frontend would show it (code line numbers on). Embeds appear as labelled links, links do not navigate, raw HTML only when the field allows it and after a second sanitising pass. The editor stays open in the background, so collaborators' edits show up live.
Language and directionThe editor gets the content locale as lang (spell checking) and writes right to left for Arabic, Hebrew, Persian, Urdu and other RTL locales.

Templates, patterns and synced blocks

Settings > Magic Editor X > Templates (permission templates.manage) holds three kinds of reusable content, each with a name, an optional description, its blocks (edited in an embedded editor), a scope and an on/off switch:

KindStored asIn the editor
Templatekind: 'template'"Insert template" replaces the field content (with a confirmation when the field is not empty; Undo brings it back).
Patternkind: 'pattern'Inserted after the block you worked on last (or into an empty field).
Synced blockkind: 'synced'Inserted as a reference. The field stores { type: 'synced', data: { ref } } and shows the current content of the source; a change to the source appears in every field that uses it.
  • Scope: every Magic Editor X field, or only fields with chosen presets and chosen fields. The "Insert template" dialog lists the enabled entries whose scope covers the field (searchable, with a preview).
  • Field rules apply: blocks the field's preset does not allow are left out, heading levels and links are fixed like "Fix automatically", maxBlocks cuts the list, and every inserted block gets a new id. The dialog says how many blocks were left out or adjusted.
  • Saving from the editor: managers can save the whole field ("Save content as template" in the dialog) or the selected blocks ("Save as pattern" in the block selection bar).
  • Limits: 1 to 200 blocks and 256 KiB per entry, at most 500 entries. Blocks are cleaned with the same sanitiser as field values on every write; raw HTML is sanitised (or emptied when rawHtml is disable), never stored as typed.

Synced blocks in detail:

  • In the editor a synced block shows "Synced block:" with the source name and the rendered source. Edit source (only with templates.manage) opens it in Settings; Detach replaces the reference with a copy of the blocks, which then become normal content of the field (one undo step). A deleted source shows "Synced block removed" and renders nothing.
  • A source cannot contain another synced block, and its kind cannot change (400). Turning a source off only stops offering it for insertion; fields that reference it keep showing it.
  • Sources have no Draft & Publish and are not localised: a saved change is live in published API output at once. Old versions of a field store the reference only, so they show the current source.
  • Settings shows how often a source is used (entries, fields, templates and patterns; GET /magic-editor-x/templates/:id/usage, counts only). The count reads the stored data, so it includes changes made through the Content API, scripts or imports; on very large sites it stops after 200,000 rows or 20 seconds and says "at least".
  • Versions of synced blocks (2.4): every save of a source keeps a version (name, blocks, who saved it). The source's edit view in Settings lists them with a preview, a comparison with the content in the form, rename and Restore (with a confirmation; restoring saves the source again as a new version). Deleting a source deletes its versions. Templates and patterns have no versions.
  • Synced blocks are offered only where the field's preset allows synced (full and article). Blocks of the source that the field does not allow are left out, and the editor says how many.
  • Without ?mex, the Content API returns the stored reference. With ?mex, GraphQL …Rendered/…Resolved or the renderers' synced option, the source blocks are expanded in place (see Content API and GraphQL output).

Comments

Reviewers and editors can discuss single blocks or a passage of text without changing the content. More tools > Comments shows the number of open threads and opens the panel; each block with open threads gets a marker at its end.

  • Start a thread on a chosen block, reply, resolve and reopen; edit or delete your own comments (deletion asks for confirmation). Resolved threads are hidden until you choose "Show resolved threads". A thread whose block was deleted stays readable and can be resolved.
  • Comments on selected text (2.4): select text and choose Comment in the inline toolbar, or press Ctrl/Cmd+Alt+M. Read-only reviewers get a floating Comment button next to the selection. Magic Editor X highlights the passage and keeps the thread on it while people edit, also during live editing (the anchor follows the text in the live room, then its quoted text). When the passage is gone the thread says "Text changed" and stays on its block. Ctrl/Cmd+Alt+N jumps to the next open comment, with Shift to the previous one. Browsers without the CSS Custom Highlight API show no highlight; threads and markers still work.
  • Mentions (2.4): type @ in a comment to mention a colleague. The list offers only people who can read the field, by name (never e-mail addresses). The server checks every mention again and drops people without access. Mentioned people, and the other people in a thread when someone replies, see it in the comments panel ("You were mentioned", "New reply") and in the Mentions and replies widget on the admin home page, which links to the thread. With comments.notifications.email: true they also get an e-mail through your Strapi email plugin (in English, at most emailPerHour per person). The e-mail names who mentioned them and the entry title when they may read it, never the comment text.
  • Comments are plain text (up to 4000 characters; control, bidi-override and zero-width characters are removed). They are never part of the field value, the version history or the Content API.
  • Permissions: comments.read to see threads and notifications (plus Content Manager read on the document, locale and field), comments.write to comment, reply, mention, resolve, reopen and edit or delete your own (no update right needed, so read-only reviewers can comment), comments.moderate to delete other people's comments or a thread with their replies.
  • New comments appear for others within about 15 seconds (8 seconds with the panel open), on every process of a cluster.
  • Limits: comments.perMinute per admin, 1000 comments per field and locale, 200 replies per thread, 20 mentions per comment, comments.mentionsPerMinute picker searches per admin.
  • Fields inside repeatable components and dynamic zones have comments since 2.4. Threads written there before 2.4 were stored by position: they move to their entry when their block proves it, otherwise they are listed read-only under "Older comments saved by position".
  • Deleting a document locale deletes its comments and notifications. Deleting an admin keeps their comments and shows them as "Deleted user", and deletes the notifications addressed to them. comments.enabled: false hides comments and the routes answer 404.

Suggestions

Give a role Suggest block changes (suggestions.create) and its members can choose Suggest changes (More tools, or the button under a field they cannot edit), even in fields they cannot edit. Their edits stay in a separate copy of the field until they send them: nothing reaches the form, the live room or other people before that. Each changed, new or removed block becomes one suggestion, with an optional note. Editors with Review block suggestions (suggestions.review) accept or reject them in the Suggestions panel (More tools > Suggestions, or a block's suggestion marker). Accepted changes go into the field like any edit, as one undo step and live for collaborators; save the entry to keep them.

  • The panel shows each suggestion as a word diff against the block as it is now, with author, time and note. A suggestion whose block changed since it was made is marked "Outdated" and asks before it replaces the newer text. Accept all accepts the suggestions that are not outdated.
  • One decision wins: when two reviewers decide the same suggestion, the second gets "Someone else already decided this suggestion" (409 ALREADY_DECIDED). Authors can withdraw their own open suggestions.
  • Suggestions are block level. Editor.js keeps no change marks in its data, so character-level track changes are not possible; moving blocks is not a suggestion. In the copy, AI, uploads, the Media Library and the footnote dialog are not available.
  • Suggested blocks are cleaned with the field's sanitiser and checked against its preset when they are sent; an accepted change is checked again when the entry is saved. At most 50 per send, 500 open per field and locale, suggestions.perMinute sends per admin.
  • Accepting needs suggestions.review and update access to the document; suggesting needs Content Manager read only. No role has either action after an update, so nothing appears until you grant them. suggestions.enabled: false turns the feature off.

Review workflows are not supported. Strapi's review workflows (stages, required stage before publishing) need a Strapi Enterprise or Growth plan: in Strapi 5.61 @strapi/review-workflows registers its routes, services and Document Service middleware only when that feature is active, so a stage change cannot be checked end to end on a Community Edition host. A hook that refuses a stage change while the quality checks fail could not be tested, so 2.4 ships none. The plugin's own publishing guard (publishGuard) and Releases readiness work without it.

Paste, import and migration

Paste. Pasting from Word, Google Docs, LibreOffice, web pages (two or more blocks) or Markdown text creates real blocks: headings, nested lists, checklists, quotes, code, tables, links, bold, italic, underline and strikethrough. Styles, classes, comments and scripts are removed; the clipboard HTML is parsed into an inert document and never attached to the page. Images from the web are copied into the Media Library through the same SSRF-protected path as "image by URL" (at most 10 per paste) when you may upload; images Word keeps on your disk (file:) cannot be pasted and are counted in a message. Since 2.4, pasted <video> and <audio> elements with an http(s) source become video and audio blocks when the field allows them and you may upload: the file, its poster and its WebVTT tracks are copied into the Media Library (POST /magic-editor-x/media/byUrl, at most 3 per paste, up to uploads.maxMediaBytes; the server checks the file's first bytes against the type). Tables keep merged cells, header cells, alignment and the caption. Blocks the field does not allow become paragraphs. Ctrl/Cmd+Shift+V pastes plain text. Pastes into code, raw HTML and table cells are not changed.

Migrate an existing field. Add a Magic Editor X field next to the old one, then run from the project root (the old field is kept):

npx magic-editor-x migrate --uid api::article.article --from body --to content            # dry run, writes nothing
npx magic-editor-x migrate --uid api::article.article --from body --to content --apply    # convert

Options: --format auto|blocks|markdown|html (auto: Blocks fields as Strapi Blocks, Rich text as Markdown, text and string as HTML when they contain tags, else Markdown, JSON as Strapi Blocks or Editor.js), --locale <code> or --locale '*' (all locales), --overwrite (replace a target that already has content), --batch 50, --limit <n>, --json (machine-readable report on stdout; Strapi's own log lines go to stderr), --out report.json. Re-running skips converted documents (idempotent). The report counts scanned, converted, skipped and failed documents and lists lossy conversions (for example a skipped image) by document id and note, never content. Drafts are converted; publish afterwards. The same is available in code: strapi.plugin('magic-editor-x').service('migrate').run({ uid, from, to, format, locale, dryRun, overwrite }).

Version history

The clock button opens the versions of the field (per document and locale). Save current version stores the editor content, optionally with a name ("Before legal review", up to 120 characters); the pencil renames a version. Open a version with the eye button: Preview shows it, Changes compares it with the current editor content: added, removed, moved and changed blocks, changes marked word by word (<ins>/<del> with text labels, not colour alone), formatting-only changes and tune changes in words ("Alignment: left → center", "Indent: 0 → 1"; tunes that differ only in key order are not reported). A synced block appears as "Synced block" with its source name. Restore this block puts a single block back (at its old place, or over the current block); Restore replaces the whole field. Save the entry to keep a restore. Automatic versions are taken during live sessions (collaboration.snapshotIntervalMinutes).

Since 2.4, fields inside repeatable components and dynamic zones have their own history: their values carry a fieldKey, so versions follow the entry when entries are moved, added or removed. Versions saved by position before 2.4 move to their entry when their block ids prove it; the others are listed read-only under "Older versions saved by position" (view and compare, no restore). Admins with audit.read also see an Activity tab with the field's audit trail. Editor.js writes default settings (alignment left, no indent) into every block it saves; since 2.4 these no longer count as a change, so live sessions without edits leave no new version.

Quality checks

The seal button opens the quality panel; its number counts problems. It never blocks editing.

  • Accessibility lint (shared/quality.mjs): images and gallery images without alternative text (an error when the field has requireAlt, otherwise a warning; decorative images are fine), skipped heading levels, more than one H1, empty headings, empty links (error), link texts such as "click here", "hier", "cliquez ici", "aquí", "clique aqui" (English, German, French, Spanish, Portuguese), tables without a header row or header column, empty header cells (table-empty-header, warning), formulas that do not parse (math-invalid, warning), empty footnotes (footnote-empty, warning), custom-block colour pairs below 4.5:1, videos without a captions or subtitles track (video-no-captions, warning) and a table of contents without headings in its level range (toc-no-headings, warning). Click an issue to jump to its block.
  • Field settings: content that breaks the field's preset, with automatic fixes.
  • Check links (POST /magic-editor-x/quality/links): internal links and mentions (entries you cannot read answer "Not checked", so nothing is revealed; "Not published" for drafts of Draft & Publish types), Media Library files of image, gallery, video and audio blocks (needs Media Library read) and, only when qualityChecks.externalLinks.enabled is true, external links through the SSRF-protected fetcher (public addresses only, pinned DNS, redirects re-checked, HEAD then a capped GET, rate limited per admin across processes, cached for 10 minutes). URLs are never logged.
  • Scheduled link check (opt-in): with qualityChecks.externalLinks.enabled and qualityChecks.externalLinks.schedule.enabled, a cron job (schedule.rule, server time, default 03:00 every day) scans every editor field of every api:: type (top level, components, dynamic zones; drafts and published versions; all locales) and checks up to maxUrlsPerRun external URLs, least recently checked first, at perMinute requests per minute and perHostConcurrency per host. In a cluster one process runs each check. The quality panel shows the last result for the field ("Scheduled check": broken links with their status for the draft and the published version; Enter on a link moves to its block), and Settings > Configuration shows the rule, the time zone, the next run and the last run, with Run now for admins with settings.update (POST /magic-editor-x/quality/link-schedule/run; it shows when a run is still going). Set schedule.tz (an IANA name such as 'Europe/Berlin') to run the rule in that zone instead of server time. URLs not checked within the budget keep their earlier result. Strapi's docs ask hosts to set cron: { enabled: true } in config/server; set it when you turn the schedule on. The plugin refuses to start when the schedule is on and externalLinks.enabled is off.
  • Private hosts: qualityChecks.externalLinks.allowPrivateOrigins lists exact origins (for example https://intranet.example.test) that both link checks may reach although they resolve to a private address. Redirects from them are not followed.
  • Publishing guard: with the field option publishGuard, publishing a document whose field has errors answers 400 details.code: 'QUALITY_GATE' with details.issues: [{ field, rule, blockId, locale? }] and details.errors for the form. Warnings never block. Since 2.4 the guard also runs when a document is created or updated directly as published (Content API ?status=published, strapi.documents().create/update({ status: 'published' })); such writes skipped it before. Releases show entries the guard refuses as not ready (see Strapi AI translations and Releases).

Audit trail

Settings > Magic Editor X > Audit trail lists who changed what and when: per editor field (created, updated, published, unpublished, discarded, deleted, with the number of added, removed, changed and moved blocks), versions (saved, restored, renamed), AI actions, comments and mentions, suggestions, templates and synced blocks, settings, link check runs and Strapi AI translations. Filter by event, person, content type, document and date.

  • No content: an event holds its type, the target (content type, document, locale, field), counts, up to 20 block ids and identifiers, the person and the time. Never text, e-mail addresses, IP addresses or tokens.
  • Who can read it: audit.read. The Settings page and listings across documents also need settings.read. The Activity tab in a field's version history shows that field's events and needs audit.read plus Content Manager read on the document (404 otherwise).
  • Retention: audit.retentionDays (180 by default; 0 keeps everything). One process prunes once an hour. Deleting an admin keeps their events and shows them as "Deleted user". audit.enabled: false stops recording.
  • Coverage: field changes are recorded from the Document Service, so the Content Manager, the Content API, imports and code are all covered; writes around it (db.query, raw SQL) are not. Content API writes are recorded without a person. With Strapi's Enterprise audit logs available, the events are also sent there.
  • The events are stored in the table magic_editor_x_audit, not in a content type.

Working together and reusing content (2.5)

Entry panel and who is editing

Every entry with a Magic Editor X field gets a Magic Editor X panel in the Content Manager (in the actions drawer on narrow screens):

  • Editing now lists the other admins who have the entry open, with names only. It works across several server processes and also without live collaboration (presence.enabled, default true). Only admins who can read the entry see the list.
  • Comments shows the open threads per field; Show opens that field's comments.
  • Quality shows issues and broken links per field of the saved draft; Check opens that field's quality panel.
  • Soft lock (presence.softLock: true, off by default): when someone else is editing, a dialog says so once per tab and you choose Continue editing. Nobody is ever locked out.

The admin home can show My open threads (threads you started or were mentioned in) and Broken links (entries you can read with broken links from the scheduled link check).

Unsaved changes

While a field has unsaved changes, Magic Editor X keeps them in your browser (IndexedDB, drafts.enabled, default true). After a reload, a crash, a closed tab or an ended session the field shows "Unsaved changes from … were found." Choose Restore (one Undo reverts it) or Discard. If the saved content changed in the meantime, the notice says so and never restores automatically. Local drafts are removed when you save, discard, after drafts.ttlHours (72) and when you log out. While a field is live in a collaboration room the room keeps your edits, so nothing is stored locally; a draft is kept only during connection gaps. Strapi does not tell the browser when a session will end, so there is no countdown; the local draft covers that case.

Insert from another entry and copy blocks

More tools > Insert from another entry copies blocks from any entry, field or language you can read: choose the entry (type, language and field are preselected and hidden when there is only one choice), tick the blocks in the preview and choose Insert N blocks. The source is the entry as last saved. Blocks the field does not allow are listed with the reason. Every inserted block gets a new id, so comments and suggestions stay with the source; synced blocks stay synced; images keep their Media Library file.

Copy blocks between fields, entries and browser tabs with Ctrl/Cmd+C (after selecting blocks) or Copy block in the block menu, and paste with Ctrl/Cmd+V: custom blocks, blocks registered in code and alignment are kept. Turn the dialog off with reuse.enabled: false.

Long entries

Editors start when a field comes within lazyInit.marginPx (800 px) of the screen or gets focus; until then the field shows its saved content. With 20 fields plus a dynamic zone, 4 editors and live connections start instead of 20 and the page has fewer than 40 % of the DOM nodes. Turn it off with lazyInit.enabled: false.

Colours, superscript, subscript and annotations

Define a palette in the plugin configuration and turn the tools on per field in the Content-Type Builder (Advanced settings > Extra formatting). All of them are off by default.

// config/plugins.js
'magic-editor-x': {
  config: {
    palette: {
      colors: [{ name: 'accent', label: 'Accent', light: '#b3261e', dark: '#ffb4ab' }],
      highlights: [{ name: 'note', label: 'Note', light: '#fff3b0', dark: '#5c4a00' }],
    },
  },
},
  • Text colour and highlight (inlineColors): one Colour button (Ctrl/Cmd+Shift+7) with your tokens. Content stores the token name (<span data-mex-color="accent">, <mark data-mex-highlight="note">), never a colour or a style; the renderers add the classes mex-color-<name> and mex-highlight-<name>, which your site styles. Settings > Magic Editor X > Configuration shows the CSS to copy and lists combinations below 4.5:1 contrast; the quality rule color-contrast flags them in fields.
  • Superscript and subscript (inlineScript): Ctrl/Cmd+. and Ctrl/Cmd+Shift+. (footnote markers are not affected).
  • Inline annotations (inlineAnnotations, a comma list): the built-in abbreviation (Ctrl/Cmd+Shift+9) renders <abbr title="…">. Register your own in code with registerInlineAnnotation (magic-editor-x/blocks, see Custom blocks in code (SDK)), for example a glossary term whose definition is looked up when content is read.

Private upload providers and dropped files

With a private upload provider (isPrivate(), for example a private S3 bucket), Magic Editor X stores each Media Library file with its id and its unsigned URL and signs it fresh on every Content API, GraphQL and ?mex= read and in the editor. Content saved before 2.5 is updated once at startup; run npx magic-editor-x media-file-ids to see what would change and --apply to run it again. Public providers are not affected.

On Strapi 5.61 and later, drag images, videos or audio files onto a field: they are uploaded to the Media Library and inserted as blocks. Older Strapi versions keep the previous behaviour.

Tools for AI clients (MCP)

With mcp.enabled: true and Strapi's own MCP server on (server.mcp.enabled), Magic Editor X adds the tools mex_from_markdown, mex_from_html, mex_validate and mex_render, one JSON Schema resource per preset and the prompt mex_content_guide. They only convert and check content; they read and write no entries. The admin token of the AI client needs the action plugin::magic-editor-x.mcp.use.

Data format

The field stores an Editor.js document as JSON:

{
  "time": 1762866000000,
  "version": "2.31.7",
  "blocks": [
    { "id": "kq1x9w0abc", "type": "header", "data": { "text": "Release notes", "level": 2 } },
    {
      "id": "kq1x9w0abd",
      "type": "paragraph",
      "data": { "text": "Read the <a href=\"https://example.test\">guide</a>." },
      "tunes": { "alignmentTune": { "alignment": "left" } }
    }
  ]
}

A value inside a repeatable component or a dynamic zone also carries a top-level fieldKey (2.4): 16 to 32 characters A-Z a-z 0-9 _ -, set by the plugin when the value is saved. It keeps version history, comments and live editing with that entry when entries are moved, added or removed, and survives publish, discard draft, "Fill in from another locale" and duplication. Keep it when you write such values through the API; values without it get a new key (an entry sent with its component id keeps the stored key). Renderers ignore it. Top-level fields and fields in single components never have one.

Data of each block type as stored after sanitising (shared/sanitize-policy.mjs):

Blockdata
paragraph{ text } (inline HTML)
header{ text, level: 1-6 }
list{ style: 'ordered' | 'unordered' | 'checklist', meta?: { start?, counterType? }, items: [{ content, meta?, items: [...] }] }
checklist{ items: [{ text, checked }] }
quote{ text, caption, alignment: 'left' | 'center' }
warning{ title, message }
alert{ type: 'primary' | 'secondary' | 'info' | 'success' | 'warning' | 'danger' | 'light' | 'dark', align: 'left' | 'center' | 'right', message }
toggle{ text, status: 'open' | 'closed', fk?, items } (the next items blocks are its content)
code{ code } (plain text)
codeFlask{ code, language, showlinenumbers?, filename? } (filename 2.4: plain text, max 200 characters, stored only when set)
raw{ html } (see rawHtml)
table{ withHeadings, stretched, content: string[][], headerColumn?, align?, merges?, caption? } (2.4 keys, stored only when set: headerColumn: true; align: per column 'left' | 'center' | 'right' | null; merges: [{ row, col, rowspan, colspan }] (max 1000, covered cells ''); caption inline HTML, max 4000. At most 500 rows and 100 columns)
math (2.4){ tex, display } (tex plain-text TeX, max 10000; display: false = text style)
image{ file: { url, mime?, alt?, width?, height?, size?, formats?, id?, documentId? }, caption, withBorder, withBackground, stretched, decorative?, focalPoint? } (id/documentId reference the Media Library file, formats its responsive sizes; decorative: true = intentionally empty alternative text; focalPoint: { x, y } from 0 to 1, two decimals)
gallery (2.3){ images: [{ file, caption, decorative?, focalPoint? }] (at most 50), layout: 'grid' | 'carousel', columns: 1-6 (default 3), caption } (file like the image block; entries without a URL or with a non-image MIME type are dropped)
video (2.3){ file: { url, id?, documentId?, mime?, name?, hash?, ext?, width?, height?, size? }, poster?, title, caption, loop, muted, tracks } (file must be video/*; poster an image file; no autoplay)
audio (2.3){ file, title, caption, loop, tracks } (file must be audio/*)
video/audio tracks[{ file, kind: 'captions' | 'subtitles' | 'descriptions' | 'chapters', srclang, label, default? }] (at most 8, WebVTT files only, at most one default)
toc (2.3){ title, minLevel: 1-6 (default 2), maxLevel: 1-6 (default 4), style: 'ordered' | 'unordered' } (only the settings are stored; the entries are built from the headings when rendering)
synced (2.3){ ref } (the documentId of a synced source, or '' when invalid; nothing else is stored)
simpleImage{ url, caption, withBorder, withBackground, stretched, alt?, decorative? }
linkTool{ link, meta: { title, description, site_name?, image?: { url } } }
attaches{ file: { url, name?, extension?, size?, title? }, title }
embed{ service, source, embed, width?, height?, caption } (embed is always https)
personality{ name, description, link, photo }
button{ text, link, style, openInNewTab }
delimiter{}
custom simple block{ content, <field values>, blockType: 'simple', blockName }
custom embedded-entry block{ entry: { id, documentId, title, <display fields> }, contentType, displayMode }
block defined in code (SDK)the keys of its schema, in declaration order (see Custom blocks in code (SDK))

Blocks toc, gallery, video, audio, synced (2.3) and math (2.4) also store _mex: 1, the built-in marker. Before 2.3 a custom block could have one of these names; its stored data has neither the marker nor exactly the built-in keys, so it stays custom block data everywhere (sanitising, editor tool, renderers, API output) and is never rewritten. Write the marker (or exactly the keys listed above) when you create these blocks through the API. New custom blocks cannot use these names or mention. A block registered in code with the block SDK may still be named math, so 2.3 hosts that registered one keep starting.

Inline HTML may contain b, strong, i, em, u, s, mark, code, a (href, target, rel, title, and for internal links data-mex-uid, data-mex-document-id, data-mex-locale, plus data-mex-mention="true" for mentions), br, span (class cdx-tooltip with data-tooltip, or data-mex-math="true" around inline TeX, 2.4), sub and sup (data-mex-footnote="<id>" and data-mex-note="<note HTML>" for a footnote, 2.4; the note follows the same inline rules, without footnotes). Links allow http, https, mailto, tel and relative URLs. Escape plain-text fields (code, personality, button.text, link card text) when you render them.

The link tool (CMD+K) has a Link to an entry button: choose a content type, search by title (arrow keys move through the results, Enter picks, Escape closes) and the selected text becomes a link to that entry. The picker lists only the content types and entries you can read in the Content Manager, with its conditions and field permissions. The link is stored as plain HTML:

<a
  href="/articles/x7k2m9q4p1v8"
  data-mex-uid="api::article.article"
  data-mex-document-id="x7k2m9q4p1v8"
  data-mex-locale="en"
  >our guide</a
>
  • href is always a normal URL, so every frontend can render the link as it is. It is built on the server from links.urlPattern when the link is inserted: {documentId}, {locale} (empty for types without i18n; empty path segments are removed), {slug} (the first uid attribute of the type, or the documentId when there is none), {collection} (plural API name) and {singular} (singular API name). Values are URL-encoded. The pattern must be a site-relative path or an http(s) URL with a fixed host. Without a pattern the link is /{collection}/{documentId}.
  • data-mex-uid, data-mex-document-id and data-mex-locale identify the entry, so a frontend can resolve the current URL itself (for example when a slug changed after the link was inserted). They are kept only when they are valid and only on <a>; a link whose address you edit by hand becomes a normal link.
  • Mentions are internal links with data-mex-mention="true"; their text is the entry title at the time of insertion. Everything above applies to them (presets, link check, resolveHrefs, API output); renderers add class="mex-mention", and the links resolver receives mention: true.
  • Links follow slug changes because the entry reference is stored, not only the URL: render with renderHtml(value, { links: ({ uid, documentId, locale, href }) => urlFor(uid, documentId, locale) }) (see Rendering content), or in server code await strapi.plugin('magic-editor-x').service('links').resolveHrefs(value, { status: 'published' }), which re-renders every internal href from links.urlPattern and the entry's current slug (one query per type and locale; links to deleted entries keep their stored href; it does not check admin permissions, so use it for content the caller may already see).

Tunes are stored per block in tunes: alignmentTune: { alignment }, textVariant: '' | 'call-out' | 'citation' | 'details', indentTune: { indentLevel }.

The Content API returns the object as stored. Entries saved with 1.x may still contain a JSON string until they are saved again; with api.autoParseJSON (default) the plugin parses such strings in Content API GET responses.

Rendering content

npm i magic-editor-x also gives you a framework-free renderer (ESM and CommonJS, no dependencies, no Node built-ins, so it runs in Node, browsers and edge runtimes), a JSON Schema and TypeScript types:

import { renderHtml, renderText, renderMarkdown } from 'magic-editor-x/render';

const html = renderHtml(entry.body, {
  links: ({ uid, documentId, locale, href }) => `/${locale}/articles/${slugs.get(documentId)}`, // internal links follow slug changes
  media: (file) => file, // refresh Media Library files by file.id / file.documentId if you like
  overrides: { myHero: (block, h) => `<section class="hero">${h.escape(block.data.title)}</section>` },
});
const text = renderText(entry.body); // search index, meta description
const markdown = renderMarkdown(entry.body); // feeds, LLM context, export
  • Safe by default: stored inline HTML is re-parsed and only the editor's own tags and attributes survive (entities are decoded before URL checks, javascript:/data: links are dropped, target="_blank" gets rel="noopener noreferrer"), so the output is safe even for content that did not pass the server sanitiser. Raw HTML blocks are left out unless you pass rawHtml: 'allow' together with your own sanitizeRaw function. Embeds become iframes (sandbox, loading="lazy", referrerpolicy) only for embedHosts (default: YouTube, youtube-nocookie, Vimeo player, CodePen, Twitch, Figma, Miro); other embeds become links.
  • Output: HTML elements with stable mex- classes (tunes as mex-align-*, mex-variant-*, mex-indent-N), images with srcset from the Media Library formats, width, height and lazy loading (imageSizes, default 100vw), decorative images with alt="", toggles as <details>. Custom blocks render as <div class="mex-block mex-<name>" data-mex-block> with escaped values unless you pass an override. Markdown is CommonMark plus GFM tables and task lists; plain text uses blank lines between blocks.
  • Deterministic: the same value always gives the same string.
  • Schema: magic-editor-x/schema is a JSON Schema (draft 2020-12) of the stored value with one data schema per block type; validate content in CI. Types: import type { MagicEditorXData, MagicEditorXBlock } from 'magic-editor-x/types'.

Options added in 2.3

All are off or neutral by default, so renderHtml output for existing content is the same as in 2.2 unless the value has a table of contents.

OptionValuesEffect
code{ lineNumbers?: boolean | 'block', copyButton?: boolean | { label, copiedLabel, failedLabel } }Line numbers (<span class="mex-code-line"> per line, numbers from CSS counters; 'block' follows the block's own setting) and a copy button with a polite status region. Call enhanceCodeBlocks() in the browser to wire the buttons of server-rendered HTML.
focalPoint'data' (default) | 'style'data-mex-focal-x/data-mex-focal-y on <img> (no inline style, works under a strict CSP), or also style="object-position:X% Y%".
headingIdstrue | falseid="mex-h-<blockId>" on headings. Default: only when the value has a toc block. The anchor is the block id, so it survives text edits, reordering and translated locales.
toc{ label? }aria-label of a table of contents without a title (default "Table of contents").
blocksarray of defineBlock definitionsBlocks defined in code (see Custom blocks in code (SDK)).
synced{ [ref]: document | blocks }, a Map, or (ref) => document | blocks | nullSources of synced blocks. Without it, or for an unknown ref, a synced block renders nothing. The copies are cleaned and rendered like any block, and a table of contents lists their headings.

New block output: gallery as <figure class="mex-gallery mex-gallery-<layout> mex-gallery-cols-<n>"> with a list of figures, video and audio as <figure class="mex-video">/<figure class="mex-audio"> with native controls and <track> elements (never autoplay), the table of contents as <nav class="mex-toc"> with nested ol/ul links to the heading ids, mentions as <a class="mex-mention">. Markdown output of a table of contents links to GitHub-style slugs of the heading text, because Markdown pipelines assign heading ids themselves.

Options added in 2.4

Output for content without math, footnotes, code file names or 2.4 table keys is unchanged.

OptionValuesEffect
math(tex, { display }) => MathML string | nodesRenders formulas. The result goes through a MathML allow-list (no links, styles, ids, event handlers or HTML). Without it, or when it fails, the TeX is written escaped between \( \) or \[ \], so client-side KaTeX or Temml can pick it up.
footnotes{ label?, backLabel?, prefix? }Footnote list heading (default "Footnotes"), back-link label (default "Back to reference {n}") and id prefix (default mex-). Markers become numbered links; the list follows the content as <section class="mex-footnotes">.

magic-editor-x/math exports renderMath(tex, { display }) (MathML string or null, Temml with trust: false), checkMath(tex, { display }) and MATH_SETTINGS; pass it as the math option: renderHtml(value, { math: renderMath }). ?mex=html|text|markdown and the GraphQL …Rendered fields render MathML this way and give each value its own footnote id prefix.

New output: tables with <caption>, <th scope="col|row">, colspan/rowspan and mex-align-<value> classes (Markdown: a GFM alignment row; merged cells cannot be expressed there, so the text stays in the first cell); code with a file name as <figure class="mex-code-figure"><figcaption class="mex-code-filename">; math as <span class="mex-math"> or <div class="mex-math mex-math-display">; in Markdown, math as $…$ / $$…$$ and footnotes as GFM [^n]. Renderers that do not know the 2.4 table keys still show a full grid.

renderTree(value, options) returns the same output as plain nodes ({ type: 'element', tag, attrs, children }, { type: 'text', value }) for your own serialiser; serializeNodes(nodes) turns them into the renderHtml string.

import { renderHtml } from 'magic-editor-x/render';

const html = renderHtml(entry.body, {
  synced: (ref) => sources.get(ref) ?? null, // sources you loaded, for example from ?mex=json
  code: { lineNumbers: 'block', copyButton: true },
  focalPoint: 'style',
});

React and Vue components

magic-editor-x/react and magic-editor-x/vue export MagicEditorXContent, built on the same render tree as renderHtml: text stays text, URLs are validated, and dangerouslySetInnerHTML/innerHTML is used only for raw HTML blocks you opt in to with rawHtml: 'allow' and sanitizeRaw.

import { MagicEditorXContent } from 'magic-editor-x/react';

<MagicEditorXContent
  value={article.content}
  options={{ code: { lineNumbers: 'block', copyButton: true } }}
  components={{ paragraph: ({ children }) => <div className="lead">{children}</div> }}
/>;
  • Props: value, options (every option above) and components (per block type, receives { block, helpers, children }; children is the default output). Vue also takes scoped slots block-<type>, which win over components.
  • React 18 and 19, server rendering and React Server Components (the copy button needs a client component or enhanceCodeBlocks()); Vue 3.5 or later, also with Nuxt server rendering.
  • Guides: React, Vue and Nuxt, Astro (renderHtml with set:html, or the components as server-rendered islands, plus the CSS for line numbers and copy buttons).

Content API and GraphQL output

Without extra parameters the Content API returns the stored value, as in 2.2. Add ?mex= to a GET request to get the field rendered or resolved instead:

mexEach Magic Editor X field becomes
htmlThe rendered HTML string ('' when empty)
textPlain text
markdownMarkdown
jsonThe stored document with resolved references (internal links, media, synced blocks)
GET /api/articles/k9d2w4xq8m1n0p3r5t7v9b1c?mex=text
Authorization: Bearer <API token>
{
  "data": {
    "documentId": "k9d2w4xq8m1n0p3r5t7v9b1c",
    "title": "Release notes",
    "body": "Release notes\n\nRead our guide.\n\nShared footer"
  },
  "meta": {}
}
  • Works on GET requests of Content API routes of api:: content types (find, findOne and custom GET actions of the same controller), for fields at the top level, in components, in dynamic zones and in populated relations, in the flat and the Strapi-Response-Format: v4 response. Admin and plugin routes and error responses are never changed. Any other value answers 400 (details.param: 'mex'). mex is registered with Strapi's contentAPI.addQueryParams, so it also passes with api.rest.strictParams: true.
  • References are resolved with the caller's own permissions (API token or users-permissions role): a target entry is read only when the caller has find on its type, Media Library files only with the upload plugin's find, and every row goes through Strapi's output sanitising. Published versions are used unless the request asks for status=draft.
  • Internal links and mentions get the href from links.urlPattern with the current slug; a resolved mention shows the entry's current title. A link the caller may not see, or that points to a missing or draft-only entry, is removed and only its text stays. Embedded entries (custom blocks) get the live display fields, or entry: null. Media Library files get their current URL and formats. Synced blocks are expanded with the containing field's sanitiser and preset; json output marks the copied blocks with syncedFrom.
  • Raw HTML blocks are left out of html, text and markdown. Heading ids are written in html when the value has a table of contents.
  • Bounds: 500 distinct references and 5 seconds per response; at most 100 distinct synced sources per response. References over the limit stay unresolved.

GraphQL (when @strapi/plugin-graphql is installed): for every Magic Editor X attribute body of an api:: content type or component in the schema, the plugin adds bodyRendered(format: MagicEditorXFormat = HTML): String (HTML, TEXT, MARKDOWN) and bodyResolved: JSON, with the same resolution and permissions. Fields that are private, disabled through shadowCRUD, or that would clash with an existing attribute name are skipped.

query {
  articles {
    title
    bodyRendered(format: HTML)
  }
}

In server code, strapi.plugin('magic-editor-x').service('references').transform(items, { format, auth, status }) gives the same output.

Custom blocks in code (SDK)

When a block needs real code (its own editor UI, strict data rules or frontend output you control), define it once with defineBlock from magic-editor-x/blocks and use the definition on the server, in the admin and in your frontend:

import { defineBlock } from 'magic-editor-x/blocks';

export const calloutCard = defineBlock({
  name: 'calloutCard',
  title: 'Callout card',
  schema: {
    title: { type: 'text', max: 120 },
    body: { type: 'inline', max: 2000 },
    link: { type: 'url' },
    tone: { type: 'enum', values: ['info', 'success', 'warning'] },
  },
  presets: ['article'],
});
  • Server: call strapi.plugin('magic-editor-x').service('blocks').register(calloutCard) in your app's register(). Every save cleans the block with its schema (unknown keys dropped, values bounded, URLs and inline HTML through the same policies as built-in blocks); presets, live collaboration, ?mex= and GraphQL use it without further wiring. A Settings custom block with the same name stops Strapi from starting (NAME_TAKEN).
  • Admin: in src/admin/app.js, call app.getPlugin('magic-editor-x').apis.registerBlock({ definition, tool, title?, icon?, i18n?, inlineToolbar?, shortcut? }); apis.createReactTool(Component) turns a React component into an Editor.js tool. Settings > Custom blocks lists code blocks read-only under "Defined in code".
  • Frontend: pass blocks: [calloutCard] to renderHtml, renderText, renderMarkdown or the React/Vue components; give the definition a render, text or markdown function for your own output, or get a neutral default.
  • Field types: text, inline, url, enum, number, boolean, array, object. blockJsonSchema(definition) returns the JSON Schema of the stored shape.

The full guide with the admin tool, field types and security notes is docs/guides/custom-blocks-sdk.md.

Strapi AI translations and Releases

Both run only when your Strapi plan includes the feature; on a Community Edition host the plugin's hooks stay inactive.

AI translations. Strapi 5.61's AI translation (i18n) sends every localised attribute of a new or changed default-locale entry to its provider and writes the answer into the other locales. For a Magic Editor X field that was the whole stored JSON, and the answer replaced it: in tests a provider emptied the field or changed formulas and code, and block ids, URLs and footnotes were sent. Since 2.4, inside such a job only the inline texts of each field go to the provider (links as placeholders), and the other locale's value is rebuilt from the source structure, taking only the translated text. Formulas, code, tables, files, URLs, internal links and footnote ids stay as in the source; positional fields keep their own fieldKey. When a text comes back with links or formulas that do not match, the source text is kept. When the source value cannot be found, the write fails with 400 AI_TRANSLATION_UNSAFE and Strapi marks that locale as failed. The audit trail records ai.localize per field. Other writes (Content Manager, Content API, "Fill in from another locale") are never touched.

Releases. Strapi's Releases check entries with its own validator, which accepts any JSON. An entry the publishing guard would refuse showed as ready, and publishing the release then failed as a whole. Since 2.4 such entries show as "Not ready to publish" until the errors in guarded fields are fixed; warnings never block and drafts are never checked. The same check now covers writes that publish directly with status: 'published' (Content API ?status=published), which skipped the guard before. Preset violations are not part of the readiness check because every save already refuses them.

Admin API and permissions

Permissions

ActionLabel in RolesGates
plugin::magic-editor-x.accessUse the editor (uploads, link previews, custom blocks, version history)Editor configuration, link previews, uploads (with the Media Library permission), content type list, internal-link search, custom block list, templates offered in a field, version history, link check, collaboration, comment, grammar and AI routes
plugin::magic-editor-x.collaborateEdit together in real timeJoining live rooms
plugin::magic-editor-x.ai.useUse the AI assistantAI requests
plugin::magic-editor-x.custom-blocks.manageManage custom blocksSettings > Custom blocks and its routes
plugin::magic-editor-x.settings.readRead settingsSettings > Configuration (read)
plugin::magic-editor-x.settings.updateUpdate settingsSaving settings, testing the AI connection
plugin::magic-editor-x.comments.readRead block commentsComment threads in the editor (with Content Manager read on the document)
plugin::magic-editor-x.comments.writeWrite block commentsNew threads, replies, resolve and reopen, editing and deleting your own comments (no update right needed)
plugin::magic-editor-x.comments.moderateModerate block commentsDeleting other people's comments
plugin::magic-editor-x.grammar.useUse the grammar check (LanguageTool)The "Check grammar" toolbar button and POST /grammar/check
plugin::magic-editor-x.templates.manageManage templates and block patternsSettings > Magic Editor X > Templates (templates, patterns and synced blocks, usage counts, synced block versions), "Save content as template" and "Save as pattern" in the editor, "Edit source" on synced blocks
plugin::magic-editor-x.audit.readRead the audit trail (who changed what and when)The Activity tab of a field (with Content Manager read), Settings > Audit trail (with settings.read)
plugin::magic-editor-x.suggestions.createSuggest block changes (read access to the entry is enough; withdraw own)Suggest mode, sending suggestions, withdrawing your own
plugin::magic-editor-x.suggestions.reviewReview block suggestions (accept or reject; needs update access to the entry)Accepting and rejecting suggestions (with Content Manager update)
plugin::magic-editor-x.mcp.useUse the Magic Editor X tools of the MCP serverThe MCP tools, resources and prompt; the admin token that calls Strapi's /mcp needs this action (2.5)

Uploads also need the Media Library action plugin::upload.assets.create. Version history and collaboration also apply the Content Manager permissions of the document: read access (including conditions such as "is creator", locale and field permissions) to list versions and join a room, update access to save versions, restore and type. A document you cannot read answers 404, the same as a document that does not exist.

Super Admins have all actions. The access action keeps its 1.x id, so roles that had it keep using the editor. The 2.4 actions (audit.read, suggestions.create, suggestions.review) are not given to any other role automatically.

Routes

All routes are admin routes served at /magic-editor-x/... and need an admin session (Authorization: Bearer <admin JWT>). There are no Content API routes; the Content API output of your own types is described in Content API and GraphQL output. Errors use the Strapi envelope { "data": null, "error": { "status", "name", "message", "details" } }; validation errors carry details.fieldErrors keyed by field path. Editor.js tool routes answer { "success": 0, "message" } on errors, as the tools expect.

MethodPathActionsBody / queryResponse
GET/magic-editor-x/configaccess{ data: { collaboration, ai, grammar, uploads, linkPreview, quality, comments, rawHtml, codeBlocks, permissions } }
GET/magic-editor-x/linkaccess?url={ success: 1, link, meta }
POST/magic-editor-x/image/byFileaccess, uploadmultipart image{ success: 1, file: { url, ... } }
POST/magic-editor-x/image/byUrlaccess, upload{ url }{ success: 1, file }
POST/magic-editor-x/media/byUrlaccess, upload{ url, kind: 'video' | 'audio' | 'track' }{ success: 1, file: { url, id, documentId, name, mime, ext, hash, size } }; 413 too large, 415 type or file signature, 429 more than 3 downloads at once (2.4)
POST/magic-editor-x/file/uploadaccess, uploadmultipart file{ success: 1, file: { url, name, title, size, extension } }
GET/magic-editor-x/content-typesaccess{ data: [{ uid, kind, displayName, attributes }] } (types you can read)
GET/magic-editor-x/links/typesaccess{ data: [{ uid, kind, displayName, localized }] } (API types you can read)
GET/magic-editor-x/links/searchaccess (+ Content Manager read)?uid=api::x.y&q=&locale=&page= (q up to 100 characters){ data: [{ documentId, uid, locale, title, href, status? }], meta: { pagination } } (up to 20 readable entries; unknown or unreadable type 404)
GET/magic-editor-x/custom-blocksaccess (?all=true also needs custom-blocks.manage)?all=true{ data: [block] }
GET/magic-editor-x/custom-blocks/exportcustom-blocks.manage{ data: { format: 'magic-editor-x/custom-blocks', version: 2, exportedAt, blocks } }
POST/magic-editor-x/custom-blocks/importcustom-blocks.manageexport document{ data: { created: [name], skipped: [{ name, reason }] } }
PUT/magic-editor-x/custom-blocks/ordercustom-blocks.manage{ ids } (every block once){ data: [block] }
POST/magic-editor-x/custom-blockscustom-blocks.manageblock definition201 { data: block }
PUT/magic-editor-x/custom-blocks/:idcustom-blocks.managefull block definition{ data: block }
DELETE/magic-editor-x/custom-blocks/:idcustom-blocks.manage{ data: { id } }
POST/magic-editor-x/custom-blocks/:id/duplicatecustom-blocks.manage201 { data: block }
GET/magic-editor-x/templatesaccess (all=true: templates.manage)?uid&field or ?all=true{ data: [template] } (enabled templates offered in the field; unknown or unreadable field 404)
GET/magic-editor-x/templates/targetsaccess, templates.manage{ data: [{ uid, displayName, field, preset }] }
PUT/magic-editor-x/templates/orderaccess, templates.manage{ ids }{ data: [template] }
GET/magic-editor-x/templates/:idaccess{ data: template } (disabled ones only for managers; synced sources always)
GET/magic-editor-x/templates/:id/usageaccess, templates.manage{ data: { entries, fields, templates, complete } } (synced sources: how often they are referenced, counts only)
GET/magic-editor-x/templates/:id/versionsaccess, templates.manage{ data: [{ id, version, trigger, label, name, createdAt, createdBy, blockCount }] } (synced sources only, newest first; 2.4)
GET/magic-editor-x/templates/:id/versions/:versionIdaccess, templates.manage{ data: { ...version, content } }
PUT/magic-editor-x/templates/:id/versions/:versionIdaccess, templates.manage{ label } (up to 120 characters, '' or null clears){ data: version }
POST/magic-editor-x/templates/:id/versions/:versionId/restoreaccess, templates.manage{ data: template } (saves the source with the version's blocks and name; a new version is stored)
POST/magic-editor-x/templatesaccess, templates.manage{ name, description?, kind, blocks, scope, enabled? }201 { data: template }
PUT/magic-editor-x/templates/:idaccess, templates.managefull definition{ data: template }
DELETE/magic-editor-x/templates/:idaccess, templates.manage{ data: { id } }
POST/magic-editor-x/templates/:id/duplicateaccess, templates.manage201 { data: template } (disabled copy)
POST/magic-editor-x/collaboration/sessionaccess, collaborate{ uid, documentId, locale?, field, initialValue? }{ data: { token, path, canEdit, expiresAt } }
GET/magic-editor-x/historyaccess?uid&documentId&locale&field{ data: [version], meta: { canRestore, canCreate } }
GET/magic-editor-x/history/:idaccess{ data: { ...version, content } }
POST/magic-editor-x/historyaccess{ uid, documentId, locale?, field, content, label? }201 new version, 200 with meta.created: false when unchanged (a label then names the latest version)
PUT/magic-editor-x/history/:idaccess (+ Content Manager update){ label } (up to 120 characters, '' or null clears){ data: version }; 403 for read-only access, 404 without read access
POST/magic-editor-x/quality/linksaccess (+ Content Manager read per type, Media Library read){ internal?: [{ uid, documentId, locale? }] (max 100), media?: [id] (max 100), external?: [url] (max 20) }{ data: { internal: [{ uid, documentId, locale, status }], media: [{ id, status }], external: [{ url, status, code? }] } }; 429 above qualityChecks.externalLinks.perMinute
GET/magic-editor-x/quality/link-reportaccess (+ Content Manager read on the field)?uid&documentId&locale&field{ data: { enabled, lastRun, draft, published } } (last scheduled check of the field)
GET/magic-editor-x/quality/link-schedulesettings.read{ data: { enabled, scheduled, rule, tz, nextRunAt, maxUrlsPerRun, perMinute, perHostConcurrency, running, lastRun } } (tz, nextRunAt 2.4)
POST/magic-editor-x/quality/link-schedule/runsettings.read, settings.update202 { data: { started: true } }; 409 RUNNING; 400 DISABLED
GET/magic-editor-x/commentsaccess, comments.read (+ Content Manager read)?uid&documentId&locale&field{ data: [thread], meta: { counts, canWrite, canModerate } }
POST/magic-editor-x/commentsaccess, comments.read, comments.write (+ Content Manager read){ uid, documentId, locale?, field, fieldKey?, blockId, body (1-4000), excerpt?, anchor?, mentions? } (anchor: { path, start, end, quote: { exact, prefix, suffix } } for a comment on selected text; mentions: up to 20 ids from /comments/mentionable)201 { data: thread }, meta.droppedMentions; 429 above comments.perMinute
POST/magic-editor-x/comments/:id/repliesaccess, comments.read, comments.write (+ Content Manager read){ body }201 { data: comment } (reopens a resolved thread)
PUT/magic-editor-x/comments/:idaccess, comments.read, comments.write (+ Content Manager read){ body }{ data: comment }; author only (403)
POST/magic-editor-x/comments/:id/resolveaccess, comments.read, comments.write (+ Content Manager read){ data: { id, status, resolvedAt, resolvedBy } }
POST/magic-editor-x/comments/:id/reopenaccess, comments.read, comments.write (+ Content Manager read){ data: { id, status, resolvedAt, resolvedBy } }
DELETE/magic-editor-x/comments/:idaccess, comments.read (+ Content Manager read){ data: { id, removed } }; others' comments need comments.moderate (403)
GET/magic-editor-x/comments/mentionableaccess, comments.read, comments.write (+ Content Manager read)?uid&documentId&locale&field&fieldKey?&q? (q up to 50 characters){ data: [{ id, name }] } (up to 8 people who can read the field; opaque ids, never e-mail addresses); 429 above comments.mentionsPerMinute
GET/magic-editor-x/notificationsaccess, comments.read?page&pageSize&unread (pageSize 1-50, default 10){ data: [{ id, kind: 'mention' | 'reply', read, createdAt, threadId, actor, snippet, excerpt, target }], meta: { unread, pagination } } (your own, only for entries you can still read)
POST/magic-editor-x/notifications/read-allaccess, comments.read{ threadIds? } (up to 100; without: all){ data: { updated } }
POST/magic-editor-x/notifications/:id/readaccess, comments.read{ data: { id, read: true } }; 404 for someone else's
POST/magic-editor-x/notifications/:id/unreadaccess, comments.read{ data: { id, read: false } }; 404 for someone else's
GET/magic-editor-x/suggestionsaccess (+ suggestions.create or suggestions.review, Content Manager read)?uid&documentId&locale&field&fieldKey?&status (open default, or all){ data: [suggestion], meta: { counts: { open, accepted, rejected }, canCreate, canReview, fieldKey } }
POST/magic-editor-x/suggestionsaccess, suggestions.create (+ Content Manager read){ uid, documentId, locale?, field, fieldKey?, note?, suggestions: [1-50 of { op: 'update', blockId, proposed, baseHash } | { op: 'insert', blockId, afterBlockId, proposed } | { op: 'delete', blockId, baseHash }] }201 { data: [suggestion], meta: { created, updated } }; 400 PRESET_VIOLATION, TOO_MANY_SUGGESTIONS; 429 above suggestions.perMinute
POST/magic-editor-x/suggestions/:id/acceptaccess, suggestions.review (+ Content Manager update){ outdated? }{ data: suggestion } with the cleaned proposed block; 409 ALREADY_DECIDED
POST/magic-editor-x/suggestions/:id/rejectaccess, suggestions.review (+ Content Manager update){}{ data: suggestion }; 409 ALREADY_DECIDED
DELETE/magic-editor-x/suggestions/:idaccess, suggestions.create{ data: { id } } (your own open suggestion; 403 otherwise)
POST/magic-editor-x/ai/:actionaccess, ai.use{ text, language?, tone?, target: { uid, field } }{ data: { text } }; 403 when the field turns AI off
POST/magic-editor-x/ai/image/alt-textaccess, ai.use (+ Media Library read){ target: { uid, field }, fileId, locale? }{ data: { text } }; 503 unless "Send images" is on
POST/magic-editor-x/ai/field/:actionaccess, ai.use{ target, segments: [{ blockId, path, html }], language? }{ data: { segments } } or { data: { text } }
POST/magic-editor-x/ai/blocks/:actionaccess, ai.use{ target: { uid, field }, segments: [{ blockId, path, html }] (1-200), language?, tone? } (improve, shorten, translate, tone){ data: { segments } }; 403 disableAi, 413, 502 BAD_RESPONSE, 503 DISABLED (2.4)
POST/magic-editor-x/grammar/checkaccess, grammar.use{ target, segments, locale? }{ data: { language, matches, truncated } }
GET/magic-editor-x/settingssettings.read{ data: { ai, languageTool, environment } } (no secrets)
PUT/magic-editor-x/settingssettings.read, settings.update{ ai: { enabled, provider, baseUrl, model, maxInputChars, maxOutputTokens, allowImages?, allowFieldActions?, apiKey? }, languageTool?: { enabled, baseUrl, username, level, apiKey? } }{ data: { ai, languageTool, environment } }
POST/magic-editor-x/settings/ai/testsettings.read, settings.update{ ai: {...} }{ data: { ok: true } }
POST/magic-editor-x/settings/language-tool/testsettings.read, settings.update{ languageTool: {...} }{ data: { ok: true } }
GET/magic-editor-x/auditaudit.read (field: + Content Manager read, 404; all documents: + settings.read, 403)?uid&documentId&locale&field&fieldKey&actor&event&from&to&page&pageSize (pageSize 1-100, default 25){ data: [event], meta: { scope: 'field' | 'global', enabled, pagination } }, newest first (2.4)
GET/magic-editor-x/audit/actorsaudit.read, settings.read{ data: [{ id, name }] } (people in the trail, up to 200)
POST/magic-editor-x/presenceaccess (+ Content Manager read){ uid, documentId, locale?, tabId, idle?, leave? }{ data: { enabled, softLock, canEdit, editors: [{ id, name, color, idle, live }] } }; names only (2.5)
GET/magic-editor-x/entry-summaryaccess (+ Content Manager read)?uid&documentId&locale{ data: { fields, comments, quality, links } }: open threads, issues and broken links per readable field (2.5)
GET/magic-editor-x/widgets/open-threadsaccess, comments.read?pageSize (1 to 20){ data: [{ threadId, started, mentioned, excerpt, updatedAt, target }], meta: { more } } (2.5 homepage widget)
GET/magic-editor-x/widgets/broken-linksaccess?pageSize (1 to 20){ data: [{ problems, target }], meta: { enabled, lastRun, more, truncated } } (2.5 homepage widget; entries you can read)
GET/magic-editor-x/reuse/typesaccess{ data: [{ uid, kind, displayName, localized, locales }] }: types with an editor field and an entry you can read (2.5)
GET/magic-editor-x/reuse/sourceaccess (+ Content Manager read on document, locale and field)?uid&documentId&locale&field{ data: { uid, documentId, locale, title, status: 'draft', fields: [{ field, fieldKey, preset, blockCount, truncated, blocks }] } } (2.5)
POST/magic-editor-x/media/signed-urlsaccess (+ Content Manager read when target is sent){ target?, urls: string[1..100] }{ data: { private, urls: { <url>: <signed url> } } } (2.5, private upload providers)

upload means plugin::upload.assets.create.

Fields inside repeatable components and dynamic zones (2.4): GET /history, POST /history, GET /comments, POST /comments, GET /comments/mentionable, GET /suggestions, POST /suggestions, POST /collaboration/session and GET /quality/link-report accept an optional fieldKey next to field, and GET /history and GET /comments return meta.fieldKey. Writes for such a field whose stored value has no key yet answer 409 FIELD_KEY_REQUIRED (save the entry once); versions and threads saved by position before 2.4 that could not be mapped to an entry are listed under meta.positionalVersions / meta.positionalThreads and answer 409 POSITIONAL_READ_ONLY to changes. AI actions: improve, grammar, shorten, expand, summarize, simplify, translate (with language), tone (with tone), continue. Provider problems answer with name: 'AIProviderError' and details.code (DISABLED, NOT_CONFIGURED, NO_API_KEY, AUTH_FAILED, PROVIDER_RATE_LIMIT, TIMEOUT, REFUSED, PROVIDER_ERROR). Too long text answers 413, too many requests 429.

Example: save a version.

POST /magic-editor-x/history
Authorization: Bearer <admin JWT>
Content-Type: application/json

{ "uid": "api::article.article", "documentId": "k9d2w4xq8m1n0p3r5t7v9b1c", "locale": "en", "field": "body",
  "content": { "blocks": [{ "id": "a1", "type": "paragraph", "data": { "text": "Hello" } }] } }
{
  "data": {
    "id": "s8f2k1x0w9q7e5r3t1y6u4i2",
    "version": 3,
    "trigger": "manual",
    "createdAt": "2026-11-11T09:30:00.000Z",
    "createdBy": "Anna Beispiel",
    "stats": { "blocks": 1, "words": 1, "characters": 5 },
    "restorable": true
  },
  "meta": { "created": true }
}

Security and privacy

  • Stored content: every Magic Editor X value is normalised and sanitised on save by a Document Service middleware (Content Manager, Content API, imports and code). Unknown keys of known block types are dropped, URLs are checked, inline HTML is limited to the tags above and the raw HTML block follows rawHtml. Values over 5 MiB, with more than 5000 blocks or nested deeper than 24 levels are rejected with 400, never truncated. The admin sanitises again before rendering (DOMPurify with the same rules).

  • Outgoing requests: the plugin sends nothing on its own; there is no telemetry. What leaves the server, and when:

    RequestWhenWhat is sent
    Link preview, image by URLAn editor adds a link card or an image by URL (linkPreview.enabled for link cards)A GET request to that URL
    Video and audio by URL (2.4)An editor pastes a video or audio element and may uploadA GET request to the file, its poster and its caption tracks
    Manual link checkAn editor presses "Check links" and qualityChecks.externalLinks.enabled is onHEAD (or a capped GET) to each external URL of the field
    Scheduled link checkThe cron rule fires and qualityChecks.externalLinks.schedule.enabled is onHEAD (or a capped GET) to external URLs of all editor fields, within the run's budget
    AI assistantAn editor runs an action on selected text, after the owner configured a providerThe selected text and a fixed instruction
    AI alternative textAn editor asks for a suggestion and the owner turned on "Send images to the AI provider"One image file (at most 1568 px on the long edge, 3.5 MB) and the content language
    AI for the whole fieldAn editor translates or summarizes and the owner turned on whole-field actionsThe inline text of every block in the field (no images, files or other block data)
    AI for chosen blocks (2.4)An editor runs an action on chosen blocks, after the owner configured a providerThe inline text of those blocks
    Mention e-mail (2.4)Someone is mentioned and the owner set comments.notifications.email: trueAn e-mail through your Strapi email plugin: who mentioned you, the entry title, an admin link
    Grammar check (LanguageTool)An editor presses "Check grammar" and the owner turned LanguageTool onThe plain text of every block in the field and its language, to the configured LanguageTool server

    Link previews, images and media by URL and the link checks only fetch public http(s) addresses: the host is resolved once, every address must be public, the connection is pinned to that address, redirects are re-checked (at most 3), and size, type and time are limited. AI and LanguageTool base URLs must be public https URLs unless ai.allowPrivateBaseUrl or languageTool.allowPrivateBaseUrl is on; origins on private networks need qualityChecks.externalLinks.allowPrivateOrigins (link checks), uploads.allowPrivateOrigins (images and media by URL) or ai.altText.allowPrivateOrigins (alt text images); redirects from them are never followed.

  • Uploads are checked by their first bytes (not by the file name or the browser's MIME type) and stored through the Media Library with the admin as creator.

  • Collaboration: tokens are signed, bound to admin, document, locale and field, expire after collaboration.tokenTtlSeconds and work once on any process; the socket accepts the admin and server origins and collaboration.allowedOrigins and only clients of the current protocol; every update is checked (allowed structures only, no prototype keys, dependencies present, touched blocks valid) before it is stored or relayed, and a socket that keeps sending invalid updates is closed; names and colours of other people come from the server, never from a client; remote content is sanitised before the editor renders it; updates, sessions, sockets and rooms per admin are rate limited; viewers cannot write. See docs/security-audit-2.1.md.

  • Field presets are enforced on the server (save middleware and realtime guard), not only in the editor; see Field presets.

  • Paste, import and rendering: pasted and imported HTML/Markdown is parsed into an inert document and rebuilt from the editor's own tags only, then sanitised again on save; magic-editor-x/render re-parses stored inline HTML and never trusts it. The link check fetches external URLs only when the owner turns it on, through the SSRF-protected fetcher, rate limited, without logging URLs. See docs/security-audit-2.2.md.

  • Content API and GraphQL output (2.3): ?mex= and the GraphQL fields resolve internal links, mentions, embedded entries, media and synced blocks with the caller's own permissions (find on the target type, upload find for media), read published versions unless the request asks for drafts, and pass every row through Strapi's output sanitising. Targets the caller may not read are handled like missing ones, so the output reveals neither their existence nor their titles or slugs. Without ?mex the response is the stored value, which still carries stored hrefs and embedded-entry snapshots, as in 2.2.

  • React and Vue components (2.3) use the same render tree as renderHtml; text is rendered as text and raw HTML only through your sanitizeRaw. The XSS corpus is rendered through all three outputs in the tests.

  • Comments, templates and synced blocks (2.3): comment routes check the plugin actions and Content Manager read on the document, locale and field (404 otherwise); admin ids are never returned; comment text is plain text. Templates and synced sources are cleaned with the field sanitiser on every write and filtered by the field preset when inserted or expanded; a synced source cannot contain another synced block. Synced sources have no Draft & Publish, so an edit is live in published output at once.

  • 2.4 surfaces: field keys come from the server, are checked against the stored draft and never decide access on their own; legacy rows are mapped only on block-id evidence and are otherwise read-only. Table merges, alignment and captions are validated and bounded on save and on the live channel. Math is rendered by Temml with trust: false and every renderer passes MathML through an allow-list (no links, styles, ids or event handlers); footnote notes follow the inline policy. Comment anchors, mentions and notifications are checked server-side (Content Manager read on the field for every mentioned person, ids only in notification rows, e-mails without comment text and with header-safe names). Suggestions are sanitised and preset-checked, decided once (conditional updates) and need update access to accept. The audit trail holds no content. AI translations by Strapi receive only text. See docs/security-audit-2.4.md.

  • Secrets: the AI key and the LanguageTool key are encrypted with AES-256-GCM (random IV, versioned format, separate key derivation per purpose) and never returned. Changing the AI provider or base URL, or the LanguageTool base URL or user name, requires entering the key again, so a stored key cannot be sent to another host.

  • Logs contain operation names and error codes only, never content, URLs with queries, tokens, user ids or email addresses.

  • Stored data: custom block definitions, versions (field content and the admin who saved it), live rooms (Yjs updates, removed collaboration.roomTtlMinutes after the last person left), presence rows (admin display name, colour, caret position; removed when the socket closes or after missed heartbeats), comments (text, author id and display name; deleted with the document locale, anonymised when the admin is deleted), templates, patterns and synced sources (with the creator's display name) and their versions (with the saver's name), suggestions (proposed blocks, author and decider names; deleted with the document locale, anonymised when the admin is deleted), notifications (ids only), the audit trail (event, target, counts, block ids, admin id and name; pruned after audit.retentionDays) and, with the scheduled link check, the external URLs of editor fields with their last status.

  • Reviews: docs/security-audit-2.4.md covers every 2.4 surface (findings MEX-24-01 to MEX-24-18), docs/security-audit-2.3.md every 2.3 surface (MEX-23-01 to MEX-23-15), each with controls, tests and residual risks.

  • Content Security Policy: Editor.js and the Design System add inline styles, which Strapi's default style-src 'unsafe-inline' allows. The socket connects to the same origin as the admin, which connect-src 'self' covers; add the wss: origin only when the admin runs on another host. Embeds and external images in the editor preview need frame-src and img-src sources; see Content Security Policy below.

Report vulnerabilities privately through GitHub security advisories on the repository.

Content Security Policy

Strapi's default admin CSP (strapi::security) has no frame-src, so embed iframes fall back to default-src 'self', and its img-src allows only 'self', data:, blob: and market-assets.strapi.io. YouTube, Vimeo and the other embeds, and images from other hosts (for example link preview images), are therefore blocked in the editor preview. The stored content is not affected and your frontend has its own CSP.

The plugin never changes the CSP. Instead:

  • Settings > Magic Editor X > Configuration shows a "Content Security Policy" notice when sources are missing: what is blocked and the exact config/middlewares.js snippet, with a copy button. The server reads the effective strapi::security configuration once at startup (string and object entries, useDefaults, frame-src, child-src, default-src, img-src) and returns it in GET /magic-editor-x/settings as data.environment.csp ({ active, frameSrcMissing, imgSrcMissing, snippet }). Only CSP sources are returned; browsers receive them in every response header anyway.
  • In the editor, a blocked embed or image is replaced by a placeholder inside the block ("This embed is blocked by your Content Security Policy.") with a link to the settings page for admins who can read the settings. The block data is saved unchanged.

The snippet for Strapi's defaults (merge it into your existing strapi::security entry and keep your other directives, for example the hosts of your upload provider; Strapi merges arrays with its defaults by position):

// config/middlewares.js
module.exports = [
  // ...other middlewares
  {
    name: 'strapi::security',
    config: {
      contentSecurityPolicy: {
        useDefaults: true,
        directives: {
          'frame-src': [
            "'self'",
            'https://www.youtube.com',
            'https://player.vimeo.com',
            'https://platform.twitter.com',
            'https://www.instagram.com',
            'https://codepen.io',
            'https://imgur.com',
            'https://assets.pinterest.com',
            'https://miro.com',
            'https://www.figma.com',
            'https://www.facebook.com',
          ],
          'img-src': ["'self'", 'data:', 'blob:', 'https://market-assets.strapi.io', 'https:'],
        },
      },
    },
  },
  // ...other middlewares
];

Add only the services you use. Instead of https: in img-src you can list your image hosts; the notice then counts external images as allowed. GitHub gist embeds load a data: iframe that inherits the admin CSP and needs a remote script, so they stay blocked under a strict policy, and Imgur's embed URL uses http:, which an https admin blocks as mixed content.

Troubleshooting

SymptomCauseFix
The field shows "The editor could not be loaded."The role lacks plugin::magic-editor-x.access, or the server is unreachableGrant the action; check the server log.
No upload or "You do not have permission to upload files"The role lacks plugin::upload.assets.createGrant Media Library create to the role.
No version history (clock) buttonThe entry was never savedSave the entry once.
Badge shows "Live editing unavailable"No collaborate action, no read access to the document, or collaboration.enabled: falseGrant the action or check the Content Manager permissions.
Badge stays at "Connecting" or "Reconnecting"The proxy does not forward WebSocket upgrades on collaboration.path, or the origin is not allowedAllow upgrades on the path; add the admin origin to collaboration.allowedOrigins when the admin runs on another host.
"Reload the page to keep editing live"The browser still runs the admin of an older version after an updateReload the page.
Settings say the API key cannot be storedMAGIC_EDITOR_X_ENCRYPTION_KEY is missing or shorter than 32 charactersSet the variable and restart, or use ai.apiKey.
Settings say the stored key is unreadableThe encryption key changedEnter the provider key again.
AI error "The AI provider rejected the key."Wrong key for this providerEnter the key again and use Test connection.
Startup error [magic-editor-x] invalid configuration for: <key>Wrong type or range in config/pluginsFix the named key (see the reference table).
400 "A Magic Editor X field contains invalid content"The value is not editor JSON, too large or too deepSend an Editor.js object within the limits.
400 "A Magic Editor X field does not match its field settings"The content breaks the field's preset (details.violations lists rule codes and block ids)Open the quality panel of the field and use Fix automatically, or change the content or the field options.
400 "Quality checks failed for a Magic Editor X field" on publishThe field has publishGuard and the quality checks report errorsFix the errors listed in the quality panel (missing alternative texts, empty links).
400 with details.param: 'mex' from the Content APImex has another value than html, text, markdown or json, or is repeatedSend one of the four values once.
?mex=html shows link text without the linkThe caller may not read the linked entry, it is missing, or it has no published versionGrant find on the target type to the token or role, publish the entry, or request status=draft where appropriate.
A synced block renders nothing in my frontendWithout ?mex the API returns only { ref }; the renderers need the sourcesUse ?mex= or the GraphQL fields, or pass the sources with the synced render option.
"Synced block removed" in the editorIts source was deleted in Settings > TemplatesDelete the block, or insert another synced block.
No Comments or Check grammar buttonComments: the role lacks comments.read, comments.enabled is false, or the entry was never saved. Grammar: the role lacks grammar.use, or LanguageTool is off or has no base URLGrant the action, save the entry once, or turn the feature on.
"Alternative text suggestions are turned off.""Send images to the AI provider" is off (503 IMAGES_DISABLED)Turn it on in Settings > Magic Editor X > Configuration, if you accept that images are sent.
"The grammar check is not configured yet."LanguageTool is on but has no base URLEnter the base URL and use Test LanguageTool.
Startup error invalid configuration for: qualityChecks.externalLinks.schedule.enabledThe schedule is on but qualityChecks.externalLinks.enabled is offTurn on both, or neither.
Strapi does not start, NAME_TAKENA block registered with the SDK has the same name as a Settings custom blockRename one of them.
"Save the entry once to turn on history and comments for this section."A new section in a repeatable component or dynamic zone has no fieldKey yet (409 FIELD_KEY_REQUIRED from the API)Save the entry.
"Older versions saved by position" or "Older comments saved by position"Rows from before 2.4 that could not be matched to one entry by their block idsView or compare them; they cannot be restored or changed (409 POSITIONAL_READ_ONLY).
Content API ?status=published create or update answers 400 QUALITY_GATESince 2.4 the publishing guard also checks writes that publish directlyFix the errors in the guarded field, or save as draft and publish after fixing.
A Strapi AI translation of one locale failed with AI_TRANSLATION_UNSAFEThe source value of a Magic Editor X field could not be matched (for example more repeatable entries than the source has)Align the entries with the source locale and translate again, or fill the locale by hand.
No Suggest changes or Suggestions entryThe role lacks suggestions.create / suggestions.review, suggestions.enabled is false, or the field is a new section that was never savedGrant the action, turn the feature on, or save the entry once.
Mention e-mails do not arrivecomments.notifications.email is off, the Strapi email plugin has no working provider, or the hourly limit per person was reachedTurn it on, configure the email provider (Settings > Configuration shows whether e-mails are on).
Settings > Audit trail answers 403Listings across documents need settings.read next to audit.readGrant both, or use the Activity tab of a field.

Upgrading from 2.4

2.5 is a minor release. Stored content, routes and configuration keep working; there are no breaking changes.

  1. Update and rebuild the admin: npm install magic-editor-x@latest && npm run build.
  2. Nothing else is required. New features are off by default or appear only when they are relevant: the entry panel shows only when there is something to show, local drafts only when there is something to restore, colours and annotations only in fields that turn them on, MCP only with mcp.enabled: true.
  3. Optional: presence.softLock: true, a palette, the new action plugin::magic-editor-x.mcp.use for admin tokens of AI clients (no role gets it automatically).

What changes for existing data and clients:

  • With a private upload provider, media in Magic Editor X values gets a fileId once at startup (migration 2.5.0-media-file-ids, idempotent; npx magic-editor-x media-file-ids [--apply]) and Content API output carries freshly signed URLs. Stored values never contain signatures.
  • Fields start when they come near the screen. Scripts and tests that wait for [data-mex-ready="true"] must scroll the field into view first, or run with lazyInit.enabled: false.
  • Mention e-mails use the recipient's admin language.
  • A field emptied and saved keeps its fieldKey (the value stays null), and discarding a draft whose published version predates 2.4 keeps the keys.
  • Editor.js stays at 2.31.7.

Upgrading from 2.3

2.4 is a minor release. Stored content, routes and configuration keep working; there are no breaking changes.

  1. Update and rebuild the admin: npm install magic-editor-x@latest && npm run build.
  2. Grant the new actions to roles that need them: suggestions.create, suggestions.review, audit.read. No role gets them automatically.
  3. Optional: comments.notifications.email: true (needs a working Strapi email provider), qualityChecks.externalLinks.schedule.tz, uploads.allowPrivateOrigins, ai.altText.allowPrivateOrigins. The audit trail is on by default (audit.enabled, 180 days); set audit.enabled: false if you do not want it.

What changes for existing data and clients:

  • Values inside repeatable components and dynamic zones get a fieldKey the next time they are saved. API clients that write such values should send the key back (or send the component id); otherwise each write gives them a new key and their history, comments and live room start fresh.
  • Versions and comments that 2.3 stored for such fields by position are mapped to their entry when their block ids prove it, the first time someone opens that field's history or comments. The rest stay readable but read-only. Nothing is deleted.
  • Tables use the plugin's own table tool instead of @editorjs/table. Stored tables are unchanged, and tables without the new keys render exactly as before.
  • Content API writes with ?status=published now run the publishing guard (400 QUALITY_GATE for fields with publishGuard and errors).
  • A block registered in code with the name math keeps working; Settings custom blocks named math from before 2.4 keep their data, and new ones cannot take the name.
  • Editor.js stays at 2.31.7.

Upgrading from 2.2

2.3 is a minor release. Stored content, routes and configuration keep working.

  1. Update and rebuild the admin: npm install magic-editor-x@latest && npm run build.
  2. Grant the new actions to roles that need them: comments.read, comments.write, comments.moderate, templates.manage, grammar.use.
  3. Optional: turn on the AI image and whole-field switches and LanguageTool in Settings, and the scheduled link check (qualityChecks.externalLinks.enabled and qualityChecks.externalLinks.schedule.enabled, plus cron: { enabled: true } in config/server).
  4. Optional: use ?mex= or the GraphQL fields, or the React and Vue components, in your frontend.

A custom block named toc, gallery, video, audio, synced or mention that you created before 2.3 keeps working as a custom block, with its stored data unchanged; new custom blocks cannot use these names.

Migrating from 1.x

2.0 is a major release. Stored content keeps working; routes, permissions and configuration changed. The full guide is in the CHANGELOG. In short:

  1. Update the package and rebuild the admin: npm install magic-editor-x@2 && npm run build.
  2. Remove 1.x configuration keys (enabledTools, linkPreviewTimeout, maxImageSize, maxFileSize, allowedImageTypes, collaboration.wsPath, wsUrl, sessionTTL, allowedAdminRoles, allowedAdminUserIds, cors) and use the new keys above.
  3. Grant the new actions to your roles: collaborate, ai.use, custom-blocks.manage, settings.read, settings.update. Collaboration grants from 1.x are replaced by Content Manager permissions; Strapi drops the old tables on the first start.
  4. If you used the AI assistant, configure your own provider in Settings > Magic Editor X > Configuration.
  5. If your raw HTML blocks need scripts or iframes, set rawHtml: 'allow'.

On the first start the plugin converts 1.x versions that only contained collaboration state and cleans custom block icons and templates. Both run once across all processes.

Development and tests

npm ci
npm run lint
npm run format:check
npm test                  # unit tests, no Strapi host needed
npm run bench             # performance benchmark (500 to 5000 blocks) against fixed budgets
npm run build             # admin and server bundles, then a runtime check
npm run verify
MEX_HOST_URL=http://127.0.0.1:1421 MEX_CREDS=/path/to/creds.json npm run test:integration

docs/engine-decision.md records why the plugin stays on Editor.js for 2.x. CONTRIBUTING.md explains the isolated acceptance host, the integration suite on SQLite and PostgreSQL and the multi-process acceptance run. AGENTS.md is the contract for coding agents.

Maintenance status

Actively maintained. Releases are made with semantic-release from main; every release runs lint, tests, build, package verification and a production dependency audit first. Supported line: Strapi 5.

Languages

The admin is translated into English, German (formal Sie), French, Spanish and Portuguese.

License

MIT © 2025-2026 Schero D.

Submit your content

Share your work with the community and get it listed in the Strapi ecosystem for everyone to discover and use.

Submit
Submit your content