# Magic Editor X > Strapi 5 plugin (npm: magic-editor-x, plugin id: magic-editor-x, MIT) that adds an Editor.js custom field `plugin::magic-editor-x.richtext` with Media Library uploads, custom blocks (Settings or code), tables with merged cells, math (MathML) and footnotes, templates, patterns and synced blocks, comments on blocks and selected text with @mentions and notifications, block suggestions, version history, an audit trail, live collaboration across several Node processes, rendered Content API and GraphQL output, React and Vue components, and optional AI (Anthropic, OpenAI or an OpenAI-compatible server) and LanguageTool assistants that use the owner's servers. Key facts for code generation: - The field stores an Editor.js object `{ time, blocks: [{ id, type, data, tunes? }], version }`. Entries saved with 1.x may hold a JSON string until saved again; the Content API parses it when `api.autoParseJSON` is on (default). - Block names: paragraph, header, list, checklist, quote, warning, alert, toggle, code, codeFlask, delimiter, table, embed, raw, image, simpleImage, linkTool, attaches, personality, button, since 2.3 gallery, video, audio, toc, synced, and since 2.4 math, plus custom block names (Settings or the block SDK). Tunes: alignmentTune, textVariant, indentTune. The README lists the `data` of each block. - 2.3 data: `image.data.focalPoint` and gallery images `{ x, y }` (0 to 1); `gallery` `{ images: [{ file, caption, decorative?, focalPoint? }], layout: grid|carousel, columns, caption }`; `video` `{ file, poster?, title, caption, loop, muted, tracks }`; `audio` `{ file, title, caption, loop, tracks }`; tracks are WebVTT `{ file, kind, srclang, label, default? }`; `toc` `{ title, minLevel, maxLevel, style }` (entries are built from headings at render time, anchors `mex-h-`); `synced` `{ ref }` (documentId of a synced source); mentions are internal links ``. - 2.4 data: `table` adds optional `headerColumn: true`, `align: ('left'|'center'|'right'|null)[]`, `merges: [{ row, col, rowspan, colspan }]` (covered cells `''`) and `caption`; `math` `{ tex, display, _mex: 1 }`; `codeFlask.filename` (plain text); inline math `TeX`; footnotes ``. Values of editor fields inside repeatable components and dynamic zones carry a top-level `fieldKey` (16-32 URL-safe characters); keep it when writing such values through the API (or send the component `id`). - Values are normalised and sanitised on every Document Service write; invalid or oversized values (over 5 MiB, 5000 blocks or depth 24) answer 400. - Inline HTML may contain b, strong, i, em, u, s, mark, code, a, br, span (cdx-tooltip, inline math), sub, sup (footnotes). Escape plain-text fields when rendering, or use the renderers. - Admin routes only, under `/magic-editor-x`, each gated by `admin::hasPermissions` with `plugin::magic-editor-x.access|collaborate|ai.use|custom-blocks.manage|settings.read|settings.update|comments.read|comments.write|comments.moderate|grammar.use|templates.manage|audit.read|suggestions.create|suggestions.review`. Version history, collaboration, comments, suggestions, field audit listings and the link report also check Content Manager read/update permissions per document, locale and field; denied answers 404. Positional fields take an optional `fieldKey` next to `field`; writes without a stored key answer 409 `FIELD_KEY_REQUIRED`. - Route groups: config, link preview, uploads (`/image/byFile`, `/image/byUrl`, `/file/upload`, `/media/byUrl`), content types, internal-link search, custom blocks, templates (`/templates`, `/templates/targets`, `/templates/order`, `/templates/:id`, `/templates/:id/usage`, `/templates/:id/duplicate`, `/templates/:id/versions`, `/templates/:id/versions/:versionId`, `/templates/:id/versions/:versionId/restore`), collaboration session, history, quality (`/quality/links`, `/quality/link-report`, `/quality/link-schedule`, `/quality/link-schedule/run`), comments (`/comments`, `/comments/:id`, `/comments/:id/replies`, `/comments/:id/resolve`, `/comments/:id/reopen`, `/comments/mentionable`), notifications (`/notifications`, `/notifications/read-all`, `/notifications/:id/read`, `/notifications/:id/unread`), suggestions (`/suggestions`, `/suggestions/:id/accept`, `/suggestions/:id/reject`, `DELETE /suggestions/:id`), AI (`/ai/:action`, `/ai/image/alt-text`, `/ai/field/:action`, `/ai/blocks/:action`), `/grammar/check`, audit (`/audit`, `/audit/actors`), settings (`/settings`, `/settings/ai/test`, `/settings/language-tool/test`). The README has the full table. - Content API output (2.3, opt-in per request): `?mex=html|text|markdown|json` on GET requests of `api::` content types replaces every Magic Editor X value with the rendered string or the resolved document; other values answer 400. Registered with `strapi.contentAPI.addQueryParams`, so it works with `strictParams`. Internal links, mentions, embedded entries, Media Library files and synced blocks are resolved with the caller's permissions (`find` on the target type, upload `find` for media), published versions unless `status=draft`; unreadable targets become plain text or `null`. Bounds: 500 references and 5 s per response. - GraphQL (with `@strapi/plugin-graphql`): for each Magic Editor X attribute `x`, `xRendered(format: MagicEditorXFormat = HTML): String` (HTML, TEXT, MARKDOWN) and `xResolved: JSON`, same resolution. - Collaboration: `POST /magic-editor-x/collaboration/session` returns a one-time signed token; Socket.IO on `collaboration.path` with the WebSocket transport only; handshake `auth: { token, protocol: 3 }`; events `mx:welcome`, `mx:sync`, `mx:update`, `mx:resync`, `mx:presence`, `mx:cursor`, `mx:role`, `mx:error`. Block data is structured in Yjs (schema 3: maps, arrays, texts per field), so concurrent edits of different cells, items, tunes and fields merge. Works without sticky sessions; all processes share the database and `ADMIN_JWT_SECRET`. - AI: `POST /magic-editor-x/ai/:action` with `{ text, language?, tone?, target: { uid, field } }`; actions improve, grammar, shorten, expand, summarize, simplify, translate, tone, continue. 2.3: `POST /magic-editor-x/ai/image/alt-text` (needs the owner setting `ai.allowImages`) and `POST /magic-editor-x/ai/field/translate|summarize` (needs `ai.allowFieldActions`). The key never reaches the browser; fields with `disableAi` answer 403; results are suggestions, the server never writes content. - 2.4 AI: `POST /magic-editor-x/ai/blocks/improve|shorten|translate|tone` with `{ target, segments: [{ blockId, path, html }] (1-200), language?, tone? }` sends only the chosen blocks' text. Strapi's own i18n AI translation receives only the inline text of Magic Editor X fields; the target locale is rebuilt from the source structure (400 `AI_TRANSLATION_UNSAFE` when it cannot be). - Grammar: `POST /magic-editor-x/grammar/check` with `grammar.use`, sent to the LanguageTool server configured in Settings (off by default); 403 for fields with `disableGrammar`. - Field presets are custom field options (`preset` full|article|basic|minimal, `allowedBlocks`, `headingLevels`, `maxBlocks`, `maxCharacters`, `requireAlt`, `linkTargets` all|internal|external|none, `disableAi`, `disableGrammar`, `disableCollaboration`, `publishGuard`), enforced on save (400 `PRESET_VIOLATION`) and on the live channel. - 2.5 admin routes: `POST /magic-editor-x/presence`, `GET /magic-editor-x/entry-summary`, `GET /magic-editor-x/widgets/open-threads`, `GET /magic-editor-x/widgets/broken-links` (entry panel, homepage widgets), `GET /magic-editor-x/reuse/types` and `GET /magic-editor-x/reuse/source` (insert from another entry; Content Manager read on the source), `POST /magic-editor-x/media/signed-urls` (private upload providers). Config `presence`, `drafts`, `lazyInit`, `reuse`, `palette`, `mcp`; action `plugin::magic-editor-x.mcp.use`. - 2.5 data: inline ``, ``, ``, ``, `="…">` (field options `inlineColors`, `inlineScript`, `inlineAnnotations`); media file slots carry `fileId` with private upload providers (never a signed URL). - 2.5 MCP (with `mcp.enabled` and Strapi's `server.mcp.enabled`, admin token with `mcp.use`): tools `mex_from_markdown`, `mex_from_html`, `mex_validate`, `mex_render`, resources `magic-editor-x://presets//schema`, prompt `mex_content_guide`. - Render stored values with `magic-editor-x/render` (`renderHtml`, `renderText`, `renderMarkdown`, `renderTree`, `serializeNodes`, `enhanceCodeBlocks`; options `links`, `media`, `overrides`, `embedHosts`, `imageSizes`, `rawHtml` + `sanitizeRaw`, since 2.3 `code`, `focalPoint`, `headingIds`, `toc`, `blocks`, `synced`, and since 2.4 `math` (pass `renderMath` from `magic-editor-x/math`) and `footnotes`); validate with `magic-editor-x/schema` (JSON Schema 2020-12); types in `magic-editor-x/types`. - Components: `magic-editor-x/react` and `magic-editor-x/vue` export `MagicEditorXContent` (props `value`, `options`, `components`; Vue also scoped slots `block-`). React 18 or 19; Vue `^3.5.0` is an optional peer. Guides: docs/guides/react.md, vue-nuxt.md, astro.md. - Block SDK: `defineBlock` from `magic-editor-x/blocks`; register on the server with `strapi.plugin('magic-editor-x').service('blocks').register(def)` in `register()`, in the admin with `app.getPlugin('magic-editor-x').apis.registerBlock({ definition, tool })`, render with the `blocks` option. Guide: docs/guides/custom-blocks-sdk.md. - Migrate fields: `npx magic-editor-x migrate --uid api::x.y --from old --to new [--apply]` (Strapi Blocks, Markdown, HTML; dry run by default). - Quality checks: `shared/quality.mjs` lint, `POST /magic-editor-x/quality/links`, an opt-in scheduled external link check (`qualityChecks.externalLinks.schedule`), publish guard via `publishGuard` (400 `QUALITY_GATE`; since 2.4 also for `?status=published` writes and Releases readiness). Versions can be named (`PUT /magic-editor-x/history/:id`). - Comments (2.4): `POST /magic-editor-x/comments` accepts `anchor` (`{ path, start, end, quote: { exact, prefix, suffix } }` for selected text) and `mentions` (ids from `GET /comments/mentionable`). Suggestions: `suggestions.create` to propose block changes, `suggestions.review` (+ update) to accept or reject. Audit trail: `GET /magic-editor-x/audit` with `audit.read`, ids and counts only, never content. - Editor.js stays at 2.31.7 (2.32.0 is a release candidate); see docs/engine-decision.md. ## Docs - [README](https://github.com/Schero94/Magic-Editor-X/blob/main/README.md): install, configuration, collaboration on several instances, AI provider, grammar check, templates, comments, suggestions, audit trail, data format, rendering, Content API and GraphQL output, routes, permissions, security, migration - [Custom blocks in code](https://github.com/Schero94/Magic-Editor-X/blob/main/docs/guides/custom-blocks-sdk.md), [React](https://github.com/Schero94/Magic-Editor-X/blob/main/docs/guides/react.md), [Vue and Nuxt](https://github.com/Schero94/Magic-Editor-X/blob/main/docs/guides/vue-nuxt.md), [Astro](https://github.com/Schero94/Magic-Editor-X/blob/main/docs/guides/astro.md): guides - [AGENTS.md](https://github.com/Schero94/Magic-Editor-X/blob/main/AGENTS.md): exact API contract, collaboration protocol, collaboration document model, rules for coding agents - [llms-full.txt](https://schero94.github.io/Magic-Editor-X/llms-full.txt): README and AGENTS.md in one file ## Optional - [CHANGELOG](https://github.com/Schero94/Magic-Editor-X/blob/main/CHANGELOG.md): versions and the migration guide from 1.x - [Security review 2.5](https://github.com/Schero94/Magic-Editor-X/blob/main/docs/security-audit-2.5.md), [2.4](https://github.com/Schero94/Magic-Editor-X/blob/main/docs/security-audit-2.4.md) and [2.3](https://github.com/Schero94/Magic-Editor-X/blob/main/docs/security-audit-2.3.md): findings and controls of the new surfaces - [Engine decision](https://github.com/Schero94/Magic-Editor-X/blob/main/docs/engine-decision.md): why the plugin stays on Editor.js for 2.x - [CONTRIBUTING](https://github.com/Schero94/Magic-Editor-X/blob/main/CONTRIBUTING.md): acceptance host, integration tests, multi-process acceptance