By Schero
Free, MIT-licensed block editor for Strapi 5: live collaboration across servers, version history ..
released November 16, 2026
npm install 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.
Live docs: https://schero94.github.io/Magic-Editor-X/
For editors who open an entry with a Magic Editor X field for the first time:
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.
plugin::magic-editor-x.richtext (stored as JSON) for collection types, single types, components and dynamic zones, including localised fields and Draft & Publish.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);toc), synced block that shows shared content edited in one place (synced, see Templates, patterns and synced blocks);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);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);linkTool), person card (personality), call-to-action button (button), raw HTML (raw).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.alignmentTune), text variant call-out / citation / details (textVariant), indent (indentTune).#, -, 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.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.?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.![]() | ![]() |
![]() | ![]() |
![]() | ![]() |
![]() | ![]() |
|
|
|
|
|
|
|
|
|
|
|
|
New in 2.3:
![]() | ![]() |
![]() | ![]() |
![]() | ![]() |
![]() | ![]() |
![]() | ![]() |
![]() | ![]() |
![]() | ![]() |
![]() | ![]() |
![]() | ![]() | ![]() |
New in 2.4:
![]() | ![]() |
![]() | ![]() |
![]() | ![]() |
![]() | ![]() |
![]() | ![]() |
![]() | ![]() |
![]() | ![]() |
![]() | ![]() |
New in 2.5:
![]() | ![]() |
![]() | ![]() |
![]() | ![]() |
![]() | ![]() |
![]() | ![]() |
All screenshots use synthetic data (acceptance host: Strapi 5.61.1).
| Term | Meaning |
|---|---|
| Field | One Magic Editor X attribute of a content type or component. Its value is an Editor.js document. |
| Block | One 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 block | A block type defined in Settings > Magic Editor X > Custom blocks, or in code with the block SDK. Its name becomes the block type. |
| Template | Starting content for a field. Inserting it replaces the field content. |
| Pattern | A group of blocks that editors insert anywhere in a field. |
| Synced block | Shared content edited once in Settings > Magic Editor X > Templates. A field stores only a reference ({ ref }) and shows the current source content. |
| Thread | A 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. |
| Suggestion | One 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 key | A random fieldKey that a value inside a repeatable component or dynamic zone carries, so history, comments and live rooms follow that entry (2.4). |
| Version | A stored copy (snapshot) of one field of one document in one locale, listed in the version history. |
| Room | The live editing session of one field of one document in one locale. A room exists while people edit and for collaboration.roomTtlMinutes afterwards. |
| Viewer | Someone in a room who can read the document but not update it. Viewers see changes live but cannot type. |
| Screen | Where | Who can open it |
|---|---|---|
| Editor field | Content Manager, edit view | Everyone who can read the field. Uploads, version history and the AI assistant need the permissions in Admin API and permissions. |
| Version history | More tools > Version history, for a saved document | access and Content Manager read on the document; saving, naming and restoring need update. The Activity tab needs audit.read. |
| Find and replace | More tools > Find and replace, or Ctrl/Cmd+Shift+F in the editor | Everyone who can read the field; replacing needs update. |
| Quality checks | More tools > Quality checks (the number counts problems) | Everyone who can read the field; the link check needs access. |
| Keyboard shortcuts, focus mode | More tools > Keyboard shortcuts or Focus mode, or Ctrl/Cmd+/ | Everyone who can read the field. |
| Field options | Content-Type Builder, Magic Editor X field, Basic and Advanced settings | Content-Type Builder access (development mode). |
| AI assistant | Inline toolbar (select text), or a block's menu, the block selection bar or Ctrl/Cmd+Shift+G for whole blocks | access and ai.use, when an administrator turned the assistant on. |
| AI for the whole field | More tools > AI for the whole field | access and ai.use, when the owner allowed whole-field AI actions and the field does not turn AI off. |
| Comments panel | More 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 template | More tools > Insert template | access and Content Manager read on the type; "Save content as template" and "Save as pattern" need templates.manage. |
| Preview | More tools > Preview, or Ctrl/Cmd+Alt+P | Everyone who can read the field, read-only users included. |
| Grammar check | More tools > Check grammar | access and grammar.use, when the owner turned LanguageTool on. |
| Suggestions panel | More tools > Suggestions, a block's suggestion marker, or "Review suggestions" under the field | access, suggestions.create or suggestions.review and Content Manager read; accepting and rejecting need suggestions.review and update. |
| Suggest mode | More tools > Suggest changes, or "Suggest changes" under a field you cannot edit | access, suggestions.create and Content Manager read. |
| Mentions and replies | Widget on the admin home page | access and comments.read. |
| Configuration | Settings > Magic Editor X > Configuration | settings.read (view), settings.update (edit). |
| Custom blocks | Settings > Magic Editor X > Custom blocks | custom-blocks.manage. |
| Templates | Settings > Magic Editor X > Templates (templates, patterns and synced blocks, with versions of synced blocks) | templates.manage. |
| Audit trail | Settings > Magic Editor X > Audit trail | audit.read and settings.read. |
| Plugin | Strapi | Node | Notes |
|---|---|---|---|
| 2.x | 5.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.x | 5.x | 22 | No 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.useLegacyMediaLibrary) Editor.js keeps its own file drop.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.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.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.@strapi/plugin-graphql; without it nothing is registered.npm install magic-editor-xEnable 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 developAdd 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).
All keys are optional. Infrastructure options live in config/plugins; the AI provider is edited at runtime in Settings > Magic Editor X > Configuration.
| Key | Type | Default | Effect |
|---|---|---|---|
debug | boolean | false | Writes 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. |
sanitizeOnSave | boolean | true | Normalise and sanitise Magic Editor X values on every Document Service write. Turning this off is not recommended. |
encryptionKey | string (32+ characters) | unset | Key for the stored AI provider key. Prefer the MAGIC_EDITOR_X_ENCRYPTION_KEY environment variable. |
uploads.maxImageBytes | integer | 10485760 (10 MiB) | Largest image accepted by file or URL (hard cap 500 MiB). |
uploads.maxFileBytes | integer | 20971520 (20 MiB) | Largest attachment. |
uploads.maxMediaBytes | integer | 52428800 (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.allowPrivateOrigins | string[] | [] | 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.enabled | boolean | true | Link preview cards. When false, GET /magic-editor-x/link answers 404. |
linkPreview.timeoutMs | integer | 8000 | Time limit for fetching a page (1000 to 30000). |
api.autoParseJSON | boolean | true | Turn 1.x JSON strings into objects in Content API GET responses. |
ai.allowPrivateBaseUrl | boolean | false | Allow AI base URLs on loopback or private networks (for local models). Owner decision; not editable in the admin. |
ai.apiKey | string | unset | Provider key from the environment. When set it wins over a key stored in the settings. |
ai.requestsPerMinute | integer | 20 | AI requests per admin per minute, shared by all processes. |
ai.timeoutMs | integer | 60000 | Time limit for one provider request. |
ai.altText | object | { allowPrivateOrigins: [] } | Alternative text suggestions (2.4); key below. |
ai.altText.allowPrivateOrigins | string[] | [] | 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.allowPrivateBaseUrl | boolean | false | Allow a LanguageTool base URL on loopback or private networks (self-hosted server in the LAN). Owner decision. |
languageTool.requestsPerMinute | integer | 30 | Grammar checks per admin per minute, shared by all processes. |
languageTool.timeoutMs | integer | 20000 | Time limit for one LanguageTool request. |
collaboration.enabled | boolean | true | Live collaboration and its Socket.IO server. |
collaboration.path | string | '/magic-editor-x/realtime' | Socket.IO path on the Strapi HTTP server. |
collaboration.allowedOrigins | string[] | [] | Extra browser origins allowed to open the socket. The admin URL and the server URL are always allowed. |
collaboration.pollIntervalMs | integer | 400 | How often each process reads updates written by other processes (50 to 10000). |
collaboration.roomTtlMinutes | integer | 30 | Keep a room's live state this long after the last person left. |
collaboration.maxMessageBytes | integer | 2097152 (2 MiB) | Largest accepted socket message. |
collaboration.snapshotIntervalMinutes | integer | 10 | Automatic version while people edit live. 0 turns it off. |
collaboration.tokenTtlSeconds | integer | 60 | Lifetime of the one-time token that opens the socket. |
collaboration.maxConnectionsPerAdmin | integer | 20 | Open live sockets per admin across all processes. |
collaboration.maxRoomsPerAdmin | integer | 20 | Different fields one admin may have open live at the same time, across all processes. |
collaboration.revalidateSeconds | integer | 60 | Full permission re-check of open sockets. Role, permission and user changes are applied within about a second anyway. |
collaboration.rateLimit | object | { 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.compaction | object | { 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.maxSnapshotsPerField | integer | 50 | Versions kept per field and locale; older ones are deleted. |
comments.enabled | boolean | true | Block comments in the editor. false hides them and the comment routes answer 404. |
comments.perMinute | integer | 30 | New comments and replies one admin may post per minute, shared by all processes (1 to 1000). |
comments.mentionsPerMinute | integer | 60 | Searches of the @mention picker per admin and minute, shared by all processes (2.4). |
comments.notifications | object | { email: false, emailPerHour: 10 } | Mention e-mails (2.4); keys below. In-app notifications are always on. |
comments.notifications.email | boolean | false | E-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.emailPerHour | integer | 10 | Mention e-mails per recipient and hour. |
suggestions.enabled | boolean | true | Block 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.perMinute | integer | 20 | Times one admin may send suggestions per minute (each send carries 1 to 50 block suggestions), shared by all processes. |
links.urlPattern | string | '' | 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.externalLinks | object | { enabled: false, timeoutMs: 5000, perMinute: 30 } | External link check of the quality panel; keys below. |
qualityChecks.externalLinks.enabled | boolean | false | Lets the quality panel check external links (outgoing requests through the SSRF-protected fetcher; owner opt-in). |
qualityChecks.externalLinks.timeoutMs | integer | 5000 | Time limit per request and per redirect hop (1000 to 15000). |
qualityChecks.externalLinks.perMinute | integer | 30 | External URLs one admin may check per minute, shared by all processes. |
qualityChecks.externalLinks.allowPrivateOrigins | string[] | [] | 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.schedule | object | { 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.enabled | boolean | false | Runs the scheduled check. One process in a cluster runs each check (lease). |
qualityChecks.externalLinks.schedule.rule | string | '0 3 * * *' | Cron rule (in schedule.tz, else server time). |
qualityChecks.externalLinks.schedule.tz | string | unset | IANA time zone of the rule, for example 'Europe/Berlin' (2.4). Checked at startup. |
qualityChecks.externalLinks.schedule.maxUrlsPerRun | integer | 500 | Distinct URLs checked per run (1 to 10000). |
qualityChecks.externalLinks.schedule.perMinute | integer | 60 | Requests per minute for the whole run (1 to 600). |
qualityChecks.externalLinks.schedule.perHostConcurrency | integer | 2 | Requests in flight per host (1 to 8). |
audit.enabled | boolean | true | Records the audit trail (2.4). It holds no content. false stops recording and the extra reads it needs. |
audit.retentionDays | integer | 180 | Days an audit event is kept (0 keeps everything, at most 3660). One process prunes once an hour. |
presence.enabled | boolean | true | The 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.softLock | boolean | false | Asks once per tab before you edit an entry someone else is editing ("Continue editing"). Never blocks anyone (2.5). |
presence.perMinute | integer | 30 | Presence requests per admin per minute, shared by all processes. |
mcp.enabled | boolean | false | Registers 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.enabled | boolean | true | "Insert from another entry" in More tools > Write (2.5). |
reuse.perMinute | integer | 60 | Requests 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.enabled | boolean | true | Keeps 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.ttlHours | integer | 72 | Lifetime of a local draft in hours (1 to 720). |
lazyInit.enabled | boolean | true | Starts 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.marginPx | integer | 800 | Distance 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.
| Name | Required | Default | Effect |
|---|---|---|---|
MAGIC_EDITOR_X_ENCRYPTION_KEY | Only to store an AI or LanguageTool key in the settings | unset | 32 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.
Settings > Magic Editor X > Configuration stores these values in the Strapi store:
| Setting | Default | Range |
|---|---|---|
| Enabled | off | |
| Provider | anthropic | anthropic, openai, openai-compatible |
| Base URL | provider default (https://api.anthropic.com, https://api.openai.com); required for openai-compatible | https, or private hosts when ai.allowPrivateBaseUrl is on |
| Model | claude-opus-5-5 (Anthropic), gpt-6-luna (OpenAI) | letters, digits and ._:/@- |
| API key | none | never returned; changing the provider or base URL requires entering it again |
| Max input characters | 8000 | 200 to 50000 |
| Max output tokens | 4096 | 64 to 16000 |
Send images to the AI provider (ai.allowImages) | off | Allows alternative text suggestions; see AI assistant |
Allow whole-field AI actions (ai.allowFieldActions) | off | Allows 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.
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:
collaboration.revalidateSeconds. An admin who loses update access becomes a viewer; one who loses read access is disconnected.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:
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:
collaboration.path (default /magic-editor-x/realtime) and send them to Strapi.admin.auth.secret, so any process can accept a token issued by another one. All processes must use the same ADMIN_JWT_SECRET.magic_editor_x_collab_updates before it is acknowledged. Other processes read new rows every collaboration.pollIntervalMs and send them to their own sockets.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.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.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.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.
The assistant is off until an administrator turns it on in Settings > Magic Editor X > Configuration and gives it a provider:
| Provider | Request | Default model (2026-11-11) |
|---|---|---|
| Anthropic | POST {base}/v1/messages, headers x-api-key and anthropic-version: 2026-10-21 | claude-opus-5-5 |
| OpenAI | POST {base}/v1/chat/completions, Authorization: Bearer, max_completion_tokens | gpt-6-luna |
| OpenAI-compatible (Ollama, vLLM, LM Studio and similar) | POST {base}/v1/chat/completions, optional bearer key, max_tokens | none; you name the model |
MAGIC_EDITOR_X_ENCRYPTION_KEY or read from ai.apiKey, and it is never sent to the browser or written to logs.ai.allowPrivateBaseUrl: true in config/plugins. Redirects are not followed.ai.requestsPerMinute requests per minute; the counter is shared by all processes.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.
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.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.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.
| Feature | Owner switch | What is sent | Result |
|---|---|---|---|
| Alternative text | Send 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 summarize | Allow 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 sent | More (…) > 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. |
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.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.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.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):
| Setting | Default | Notes |
|---|---|---|
| Turn on the grammar check | off | Nothing is sent while it is off or until an editor starts a check. |
| LanguageTool base URL | empty | Your 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 key | empty | Only 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. |
| Rules | Standard | Standard or Strict (level=picky, adds style rules). |
POST /magic-editor-x/settings/language-tool/test); a test against another URL never receives the stored key.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.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 settings | Values | Effect |
|---|---|---|---|
preset | Basic | full (default), article, basic, minimal | Allowed blocks, inline tools and heading levels, see below. |
linkTargets | Basic | all (default), internal, external, none | Which links are allowed: entries of the site (internal links), web addresses, both or none. Link blocks (linkTool, button, personality) count as web addresses. |
requireAlt | Basic | checkbox | Images need an alternative text or the "decorative image" mark. |
allowedBlocks | Advanced | comma-separated block names, for example paragraph, header, list, image, myHero | Replaces the preset's block list (custom blocks by name). paragraph is always allowed. |
headingLevels | Advanced | 2-4, 2,3, 1, 3-5 | Replaces the preset's heading levels. |
maxBlocks | Advanced | number, empty or 0 = no limit | Block limit, shown in the toolbar (12 / 20 blocks). |
maxCharacters | Advanced | number, empty or 0 = no limit | Visible characters, counted like the toolbar (380 / 400 characters). |
disableAi | Advanced | checkbox | No AI button in this field; the AI route answers 403 for requests from it. |
disableGrammar | Advanced | checkbox | No "Check grammar" button in this field; the grammar route answers 403, so its text is never sent to LanguageTool. |
disableCollaboration | Advanced | checkbox | No live editing in this field (the session route answers 403). |
publishGuard | Advanced | checkbox | Publishing is refused while the quality checks report errors in this field. |
| Preset | Blocks | Inline tools | Headings |
|---|---|---|---|
full | all, custom blocks included | all | H1-H6 |
article | paragraph, 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 article | all | H2-H4 |
basic | paragraph, header, list, quote, image, delimiter | bold, italic, underline, strikethrough, link | H2-H3 |
minimal | paragraph, list | bold, italic, link | none |
How the rules apply:
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.Changing a preset never changes stored content by itself. Turning sanitizeOnSave off also turns the save check off.
| Tool | How |
|---|---|
| More tools menu | The 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 shortcuts | At 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 replace | Magnifier 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 shortcuts | Ctrl/Cmd+/ or More > Keyboard shortcuts: editor, block and inline tool shortcuts and the Markdown shortcuts of this field. |
| Focus mode | More > Focus mode: full screen, narrower text column, other blocks dimmed. Escape leaves. |
| Several selected blocks | Select 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. |
| Counts | Blocks, words, characters and reading time (200 words per minute) in the toolbar, with the field's limits. |
| Alternative text | Image 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 point | Image 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. |
| Mentions | Type @ 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 contents | Block "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 language | The 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 name | The 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. |
| Tables | Header 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. |
| Math | Block "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). |
| Footnotes | Ctrl/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). |
| Preview | Preview 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 direction | The editor gets the content locale as lang (spell checking) and writes right to left for Arabic, Hebrew, Persian, Urdu and other RTL locales. |
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:
| Kind | Stored as | In the editor |
|---|---|---|
| Template | kind: 'template' | "Insert template" replaces the field content (with a confirmation when the field is not empty; Undo brings it back). |
| Pattern | kind: 'pattern' | Inserted after the block you worked on last (or into an empty field). |
| Synced block | kind: '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. |
maxBlocks cuts the list, and every inserted block gets a new id. The dialog says how many blocks were left out or adjusted.rawHtml is disable), never stored as typed.Synced blocks in detail:
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.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".synced (full and article). Blocks of the source that the field does not allow are left out, and the editor says how many.?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).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.
@ 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.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.comments.perMinute per admin, 1000 comments per field and locale, 200 replies per thread, 20 mentions per comment, comments.mentionsPerMinute picker searches per admin.comments.enabled: false hides comments and the routes answer 404.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.
ALREADY_DECIDED). Authors can withdraw their own open suggestions.suggestions.perMinute sends per admin.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. 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 # convertOptions: --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 }).
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.
The seal button opens the quality panel; its number counts problems. It never blocks editing.
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.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.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.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.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).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.
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).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.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.magic_editor_x_audit, not in a content type.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):
presence.enabled, default true). Only admins who can read the entry see the list.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).
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.
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.
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.
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' }],
},
},
},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.inlineScript): Ctrl/Cmd+. and Ctrl/Cmd+Shift+. (footnote markers are not affected).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.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.
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.
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):
| Block | data |
|---|---|
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.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.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.
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, exportjavascript:/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.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.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'.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.
| Option | Values | Effect |
|---|---|---|
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%". |
headingIds | true | false | id="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"). |
blocks | array of defineBlock definitions | Blocks defined in code (see Custom blocks in code (SDK)). |
synced | { [ref]: document | blocks }, a Map, or (ref) => document | blocks | null | Sources 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.
Output for content without math, footnotes, code file names or 2.4 table keys is unchanged.
| Option | Values | Effect |
|---|---|---|
math | (tex, { display }) => MathML string | nodes | Renders 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',
});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> }}
/>;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.enhanceCodeBlocks()); Vue 3.5 or later, also with Nuxt server rendering.renderHtml with set:html, or the components as server-rendered islands, plus the CSS for line numbers and copy buttons).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:
mex | Each Magic Editor X field becomes |
|---|---|
html | The rendered HTML string ('' when empty) |
text | Plain text |
markdown | Markdown |
json | The 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": {}
}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.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.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.html, text and markdown. Heading ids are written in html when the value has a table of contents.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.
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'],
});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).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".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.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.
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.
| Action | Label in Roles | Gates |
|---|---|---|
plugin::magic-editor-x.access | Use 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.collaborate | Edit together in real time | Joining live rooms |
plugin::magic-editor-x.ai.use | Use the AI assistant | AI requests |
plugin::magic-editor-x.custom-blocks.manage | Manage custom blocks | Settings > Custom blocks and its routes |
plugin::magic-editor-x.settings.read | Read settings | Settings > Configuration (read) |
plugin::magic-editor-x.settings.update | Update settings | Saving settings, testing the AI connection |
plugin::magic-editor-x.comments.read | Read block comments | Comment threads in the editor (with Content Manager read on the document) |
plugin::magic-editor-x.comments.write | Write block comments | New threads, replies, resolve and reopen, editing and deleting your own comments (no update right needed) |
plugin::magic-editor-x.comments.moderate | Moderate block comments | Deleting other people's comments |
plugin::magic-editor-x.grammar.use | Use the grammar check (LanguageTool) | The "Check grammar" toolbar button and POST /grammar/check |
plugin::magic-editor-x.templates.manage | Manage templates and block patterns | Settings > 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.read | Read 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.create | Suggest block changes (read access to the entry is enough; withdraw own) | Suggest mode, sending suggestions, withdrawing your own |
plugin::magic-editor-x.suggestions.review | Review block suggestions (accept or reject; needs update access to the entry) | Accepting and rejecting suggestions (with Content Manager update) |
plugin::magic-editor-x.mcp.use | Use the Magic Editor X tools of the MCP server | The 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.
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.
| Method | Path | Actions | Body / query | Response |
|---|---|---|---|---|
| GET | /magic-editor-x/config | access | { data: { collaboration, ai, grammar, uploads, linkPreview, quality, comments, rawHtml, codeBlocks, permissions } } | |
| GET | /magic-editor-x/link | access | ?url= | { success: 1, link, meta } |
| POST | /magic-editor-x/image/byFile | access, upload | multipart image | { success: 1, file: { url, ... } } |
| POST | /magic-editor-x/image/byUrl | access, upload | { url } | { success: 1, file } |
| POST | /magic-editor-x/media/byUrl | access, 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/upload | access, upload | multipart file | { success: 1, file: { url, name, title, size, extension } } |
| GET | /magic-editor-x/content-types | access | { data: [{ uid, kind, displayName, attributes }] } (types you can read) | |
| GET | /magic-editor-x/links/types | access | { data: [{ uid, kind, displayName, localized }] } (API types you can read) | |
| GET | /magic-editor-x/links/search | access (+ 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-blocks | access (?all=true also needs custom-blocks.manage) | ?all=true | { data: [block] } |
| GET | /magic-editor-x/custom-blocks/export | custom-blocks.manage | { data: { format: 'magic-editor-x/custom-blocks', version: 2, exportedAt, blocks } } | |
| POST | /magic-editor-x/custom-blocks/import | custom-blocks.manage | export document | { data: { created: [name], skipped: [{ name, reason }] } } |
| PUT | /magic-editor-x/custom-blocks/order | custom-blocks.manage | { ids } (every block once) | { data: [block] } |
| POST | /magic-editor-x/custom-blocks | custom-blocks.manage | block definition | 201 { data: block } |
| PUT | /magic-editor-x/custom-blocks/:id | custom-blocks.manage | full block definition | { data: block } |
| DELETE | /magic-editor-x/custom-blocks/:id | custom-blocks.manage | { data: { id } } | |
| POST | /magic-editor-x/custom-blocks/:id/duplicate | custom-blocks.manage | 201 { data: block } | |
| GET | /magic-editor-x/templates | access (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/targets | access, templates.manage | { data: [{ uid, displayName, field, preset }] } | |
| PUT | /magic-editor-x/templates/order | access, templates.manage | { ids } | { data: [template] } |
| GET | /magic-editor-x/templates/:id | access | { data: template } (disabled ones only for managers; synced sources always) | |
| GET | /magic-editor-x/templates/:id/usage | access, templates.manage | { data: { entries, fields, templates, complete } } (synced sources: how often they are referenced, counts only) | |
| GET | /magic-editor-x/templates/:id/versions | access, 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/:versionId | access, templates.manage | { data: { ...version, content } } | |
| PUT | /magic-editor-x/templates/:id/versions/:versionId | access, templates.manage | { label } (up to 120 characters, '' or null clears) | { data: version } |
| POST | /magic-editor-x/templates/:id/versions/:versionId/restore | access, templates.manage | { data: template } (saves the source with the version's blocks and name; a new version is stored) | |
| POST | /magic-editor-x/templates | access, templates.manage | { name, description?, kind, blocks, scope, enabled? } | 201 { data: template } |
| PUT | /magic-editor-x/templates/:id | access, templates.manage | full definition | { data: template } |
| DELETE | /magic-editor-x/templates/:id | access, templates.manage | { data: { id } } | |
| POST | /magic-editor-x/templates/:id/duplicate | access, templates.manage | 201 { data: template } (disabled copy) | |
| POST | /magic-editor-x/collaboration/session | access, collaborate | { uid, documentId, locale?, field, initialValue? } | { data: { token, path, canEdit, expiresAt } } |
| GET | /magic-editor-x/history | access | ?uid&documentId&locale&field | { data: [version], meta: { canRestore, canCreate } } |
| GET | /magic-editor-x/history/:id | access | { data: { ...version, content } } | |
| POST | /magic-editor-x/history | access | { 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/:id | access (+ 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/links | access (+ 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-report | access (+ 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-schedule | settings.read | { data: { enabled, scheduled, rule, tz, nextRunAt, maxUrlsPerRun, perMinute, perHostConcurrency, running, lastRun } } (tz, nextRunAt 2.4) | |
| POST | /magic-editor-x/quality/link-schedule/run | settings.read, settings.update | 202 { data: { started: true } }; 409 RUNNING; 400 DISABLED | |
| GET | /magic-editor-x/comments | access, comments.read (+ Content Manager read) | ?uid&documentId&locale&field | { data: [thread], meta: { counts, canWrite, canModerate } } |
| POST | /magic-editor-x/comments | access, 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/replies | access, comments.read, comments.write (+ Content Manager read) | { body } | 201 { data: comment } (reopens a resolved thread) |
| PUT | /magic-editor-x/comments/:id | access, comments.read, comments.write (+ Content Manager read) | { body } | { data: comment }; author only (403) |
| POST | /magic-editor-x/comments/:id/resolve | access, comments.read, comments.write (+ Content Manager read) | { data: { id, status, resolvedAt, resolvedBy } } | |
| POST | /magic-editor-x/comments/:id/reopen | access, comments.read, comments.write (+ Content Manager read) | { data: { id, status, resolvedAt, resolvedBy } } | |
| DELETE | /magic-editor-x/comments/:id | access, comments.read (+ Content Manager read) | { data: { id, removed } }; others' comments need comments.moderate (403) | |
| GET | /magic-editor-x/comments/mentionable | access, 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/notifications | access, 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-all | access, comments.read | { threadIds? } (up to 100; without: all) | { data: { updated } } |
| POST | /magic-editor-x/notifications/:id/read | access, comments.read | { data: { id, read: true } }; 404 for someone else's | |
| POST | /magic-editor-x/notifications/:id/unread | access, comments.read | { data: { id, read: false } }; 404 for someone else's | |
| GET | /magic-editor-x/suggestions | access (+ 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/suggestions | access, 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/accept | access, suggestions.review (+ Content Manager update) | { outdated? } | { data: suggestion } with the cleaned proposed block; 409 ALREADY_DECIDED |
| POST | /magic-editor-x/suggestions/:id/reject | access, suggestions.review (+ Content Manager update) | {} | { data: suggestion }; 409 ALREADY_DECIDED |
| DELETE | /magic-editor-x/suggestions/:id | access, suggestions.create | { data: { id } } (your own open suggestion; 403 otherwise) | |
| POST | /magic-editor-x/ai/:action | access, ai.use | { text, language?, tone?, target: { uid, field } } | { data: { text } }; 403 when the field turns AI off |
| POST | /magic-editor-x/ai/image/alt-text | access, ai.use (+ Media Library read) | { target: { uid, field }, fileId, locale? } | { data: { text } }; 503 unless "Send images" is on |
| POST | /magic-editor-x/ai/field/:action | access, ai.use | { target, segments: [{ blockId, path, html }], language? } | { data: { segments } } or { data: { text } } |
| POST | /magic-editor-x/ai/blocks/:action | access, 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/check | access, grammar.use | { target, segments, locale? } | { data: { language, matches, truncated } } |
| GET | /magic-editor-x/settings | settings.read | { data: { ai, languageTool, environment } } (no secrets) | |
| PUT | /magic-editor-x/settings | settings.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/test | settings.read, settings.update | { ai: {...} } | { data: { ok: true } } |
| POST | /magic-editor-x/settings/language-tool/test | settings.read, settings.update | { languageTool: {...} } | { data: { ok: true } } |
| GET | /magic-editor-x/audit | audit.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/actors | audit.read, settings.read | { data: [{ id, name }] } (people in the trail, up to 200) | |
| POST | /magic-editor-x/presence | access (+ 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-summary | access (+ 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-threads | access, 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-links | access | ?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/types | access | { data: [{ uid, kind, displayName, localized, locales }] }: types with an editor field and an entry you can read (2.5) | |
| GET | /magic-editor-x/reuse/source | access (+ 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-urls | access (+ 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 }
}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:
| Request | When | What is sent |
|---|---|---|
| Link preview, image by URL | An 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 upload | A GET request to the file, its poster and its caption tracks |
| Manual link check | An editor presses "Check links" and qualityChecks.externalLinks.enabled is on | HEAD (or a capped GET) to each external URL of the field |
| Scheduled link check | The cron rule fires and qualityChecks.externalLinks.schedule.enabled is on | HEAD (or a capped GET) to external URLs of all editor fields, within the run's budget |
| AI assistant | An editor runs an action on selected text, after the owner configured a provider | The selected text and a fixed instruction |
| AI alternative text | An 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 field | An editor translates or summarizes and the owner turned on whole-field actions | The 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 provider | The inline text of those blocks |
| Mention e-mail (2.4) | Someone is mentioned and the owner set comments.notifications.email: true | An 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 on | The 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.
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:
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.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.
| Symptom | Cause | Fix |
|---|---|---|
| The field shows "The editor could not be loaded." | The role lacks plugin::magic-editor-x.access, or the server is unreachable | Grant the action; check the server log. |
| No upload or "You do not have permission to upload files" | The role lacks plugin::upload.assets.create | Grant Media Library create to the role. |
| No version history (clock) button | The entry was never saved | Save the entry once. |
| Badge shows "Live editing unavailable" | No collaborate action, no read access to the document, or collaboration.enabled: false | Grant 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 allowed | Allow 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 update | Reload the page. |
| Settings say the API key cannot be stored | MAGIC_EDITOR_X_ENCRYPTION_KEY is missing or shorter than 32 characters | Set the variable and restart, or use ai.apiKey. |
| Settings say the stored key is unreadable | The encryption key changed | Enter the provider key again. |
| AI error "The AI provider rejected the key." | Wrong key for this provider | Enter the key again and use Test connection. |
Startup error [magic-editor-x] invalid configuration for: <key> | Wrong type or range in config/plugins | Fix 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 deep | Send 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 publish | The field has publishGuard and the quality checks report errors | Fix the errors listed in the quality panel (missing alternative texts, empty links). |
400 with details.param: 'mex' from the Content API | mex has another value than html, text, markdown or json, or is repeated | Send one of the four values once. |
?mex=html shows link text without the link | The caller may not read the linked entry, it is missing, or it has no published version | Grant 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 frontend | Without ?mex the API returns only { ref }; the renderers need the sources | Use ?mex= or the GraphQL fields, or pass the sources with the synced render option. |
| "Synced block removed" in the editor | Its source was deleted in Settings > Templates | Delete the block, or insert another synced block. |
| No Comments or Check grammar button | Comments: 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 URL | Grant 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 URL | Enter the base URL and use Test LanguageTool. |
Startup error invalid configuration for: qualityChecks.externalLinks.schedule.enabled | The schedule is on but qualityChecks.externalLinks.enabled is off | Turn on both, or neither. |
Strapi does not start, NAME_TAKEN | A block registered with the SDK has the same name as a Settings custom block | Rename 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 ids | View or compare them; they cannot be restored or changed (409 POSITIONAL_READ_ONLY). |
Content API ?status=published create or update answers 400 QUALITY_GATE | Since 2.4 the publishing guard also checks writes that publish directly | Fix 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_UNSAFE | The 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 entry | The role lacks suggestions.create / suggestions.review, suggestions.enabled is false, or the field is a new section that was never saved | Grant the action, turn the feature on, or save the entry once. |
| Mention e-mails do not arrive | comments.notifications.email is off, the Strapi email plugin has no working provider, or the hourly limit per person was reached | Turn it on, configure the email provider (Settings > Configuration shows whether e-mails are on). |
| Settings > Audit trail answers 403 | Listings across documents need settings.read next to audit.read | Grant both, or use the Activity tab of a field. |
2.5 is a minor release. Stored content, routes and configuration keep working; there are no breaking changes.
npm install magic-editor-x@latest && npm run build.mcp.enabled: true.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:
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.[data-mex-ready="true"] must scroll the field into view first, or run with lazyInit.enabled: false.fieldKey (the value stays null), and discarding a draft whose published version predates 2.4 keeps the keys.2.4 is a minor release. Stored content, routes and configuration keep working; there are no breaking changes.
npm install magic-editor-x@latest && npm run build.suggestions.create, suggestions.review, audit.read. No role gets them automatically.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:
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.@editorjs/table. Stored tables are unchanged, and tables without the new keys render exactly as before.?status=published now run the publishing guard (400 QUALITY_GATE for fields with publishGuard and errors).math keeps working; Settings custom blocks named math from before 2.4 keep their data, and new ones cannot take the name.2.3 is a minor release. Stored content, routes and configuration keep working.
npm install magic-editor-x@latest && npm run build.comments.read, comments.write, comments.moderate, templates.manage, grammar.use.qualityChecks.externalLinks.enabled and qualityChecks.externalLinks.schedule.enabled, plus cron: { enabled: true } in config/server).?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.
2.0 is a major release. Stored content keeps working; routes, permissions and configuration changed. The full guide is in the CHANGELOG. In short:
npm install magic-editor-x@2 && npm run build.enabledTools, linkPreviewTimeout, maxImageSize, maxFileSize, allowedImageTypes, collaboration.wsPath, wsUrl, sessionTTL, allowedAdminRoles, allowedAdminUserIds, cors) and use the new keys above.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.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.
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:integrationdocs/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.
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.
The admin is translated into English, German (formal Sie), French, Spanish and Portuguese.
MIT © 2025-2026 Schero D.
Share your work with the community and get it listed in the Strapi ecosystem for everyone to discover and use.
Submit
