magic-editor-x 2.3.0 → 2.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +87 -0
- package/README.md +299 -142
- package/dist/admin/AuditPage-C2u6z4aN.js +381 -0
- package/dist/admin/AuditPage-guB0SiGS.mjs +381 -0
- package/dist/admin/{ConfigurationPage-C-UktL1x.js → ConfigurationPage-D6uya-J1.js} +228 -13
- package/dist/admin/{ConfigurationPage-BxLHIQdo.mjs → ConfigurationPage-DiEpF1Rr.mjs} +222 -7
- package/dist/admin/ConfirmAction-CUhpngYU.js +71 -0
- package/dist/admin/ConfirmAction-CZjpduc3.mjs +72 -0
- package/dist/admin/{CustomBlocksPage-D8aMbVXc.mjs → CustomBlocksPage-Byt10-6c.mjs} +6 -4
- package/dist/admin/{CustomBlocksPage-CxcTfdOT.js → CustomBlocksPage-DP3h_wNd.js} +21 -19
- package/dist/admin/MentionsWidget-C2OCAmqq.js +227 -0
- package/dist/admin/MentionsWidget-sMkM9mHX.mjs +225 -0
- package/dist/admin/{TemplatesPage-Hn6gyu2l.js → TemplatesPage-DrSJdteI.js} +313 -17
- package/dist/admin/{TemplatesPage-jhYi6Zdf.mjs → TemplatesPage-Yp4OqFE2.mjs} +305 -9
- package/dist/admin/{ConfirmAction-DuQwvRYi.mjs → api-2ZRpHM3d.mjs} +19 -70
- package/dist/admin/{ConfirmAction-zLuIFj8t.js → api-bix9RLLI.js} +19 -70
- package/dist/admin/auditText-DIIYVR6k.mjs +110 -0
- package/dist/admin/auditText-DUhWu2Nx.js +109 -0
- package/dist/admin/comments-C7P41lan.js +86 -0
- package/dist/admin/comments-hfIbLQNO.mjs +87 -0
- package/dist/admin/{de-BMY2LBaa.mjs → de-BNPIGqhs.mjs} +41 -2
- package/dist/admin/{de-2Ie5jy7j.js → de-BhhGss1l.js} +41 -2
- package/dist/admin/{de-DOiGaTNX.mjs → de-CKz6CG3V.mjs} +191 -5
- package/dist/admin/{de-C3AsGauQ.js → de-CbBDnXeT.js} +140 -1
- package/dist/admin/{de-BUS1hUw0.mjs → de-DiCZrmH8.mjs} +140 -1
- package/dist/admin/{de-B1X46JJZ.js → de-zcV8D7nt.js} +191 -5
- package/dist/admin/{en-Ah-Cw0Wd.js → en-B9ApE1y1.js} +41 -2
- package/dist/admin/{en-CDg_18Bt.js → en-BMWhILnj.js} +191 -5
- package/dist/admin/{en-BkEjpC3i.js → en-CpehF0Kv.js} +140 -1
- package/dist/admin/{en-GCzgS9Aw.mjs → en-DCPMqFIa.mjs} +140 -1
- package/dist/admin/{en-CU6UzV4g.mjs → en-cYzqbASF.mjs} +191 -5
- package/dist/admin/{en-CvFiqti2.mjs → en-gFLeK9Ng.mjs} +41 -2
- package/dist/admin/{es-DbKHZz5l.mjs → es-BmwBgEgz.mjs} +41 -2
- package/dist/admin/{es-Cr8JH85N.js → es-C0W31rl8.js} +41 -2
- package/dist/admin/{es-BCpJmUEM.js → es-CQPh8PXw.js} +191 -5
- package/dist/admin/{es-C4pEnDRv.js → es-CawpzwyC.js} +140 -1
- package/dist/admin/{es-DHBBZKl2.mjs → es-Chs37IBR.mjs} +140 -1
- package/dist/admin/{es-BmfffNM2.mjs → es-DCamt1ek.mjs} +191 -5
- package/dist/admin/{fr-DQJ_7aq5.mjs → fr-CMWBNE5D.mjs} +41 -2
- package/dist/admin/{fr-C2aLSwEu.js → fr-COOsqexl.js} +140 -1
- package/dist/admin/{fr-Dvq4xk2e.mjs → fr-Dp5-XP29.mjs} +140 -1
- package/dist/admin/{fr-ZcN0yM_2.js → fr-DpC44Ol8.js} +191 -5
- package/dist/admin/{fr-OJ4VW1kh.js → fr-iGeIfEcU.js} +41 -2
- package/dist/admin/{fr-DZd2XJP6.mjs → fr-oW0t8bT5.mjs} +191 -5
- package/dist/admin/{index-Cm-fFUhE.js → index-64wc26Bl.js} +13851 -6746
- package/dist/admin/{index-XgfwqLfV.mjs → index-BVjf1gVC.mjs} +13788 -6682
- package/dist/admin/{index-BHBRr562.js → index-D6Z7i8ba.js} +1003 -53
- package/dist/admin/{index-CQk1XeNb.mjs → index-D_Fv8Non.mjs} +1032 -82
- package/dist/admin/index.js +2 -1
- package/dist/admin/index.mjs +3 -2
- package/dist/admin/math-CIQ4Z_mY.mjs +47 -0
- package/dist/admin/math-vsK_06ZR.js +49 -0
- package/dist/admin/{pt-D0I0_JYs.js → pt-BHmXk2d9.js} +41 -2
- package/dist/admin/{pt-CImqDnLB.js → pt-Bo0Pm_Pt.js} +191 -5
- package/dist/admin/{pt-CilDggGF.mjs → pt-DALDvfBn.mjs} +140 -1
- package/dist/admin/{pt-BSLzA17U.mjs → pt-DFNgZ5_k.mjs} +41 -2
- package/dist/admin/{pt-DX0OAIoL.js → pt-DXy7G1x7.js} +140 -1
- package/dist/admin/{pt-C3UdeIpd.mjs → pt-uGpfRQLC.mjs} +191 -5
- package/dist/admin/{useT-D3sM9Zf7.js → useT-BXJLIPN4.js} +1 -1
- package/dist/admin/{useT-CmaeZbCr.mjs → useT-CLPhBmBC.mjs} +1 -1
- package/dist/blocks/index.d.mts +2 -0
- package/dist/blocks/index.d.ts +2 -0
- package/dist/blocks/index.js +13 -2
- package/dist/blocks/index.mjs +13 -2
- package/dist/math/index.d.mts +27 -0
- package/dist/math/index.d.ts +27 -0
- package/dist/math/index.js +164 -0
- package/dist/math/index.mjs +134 -0
- package/dist/react/index.js +673 -91
- package/dist/react/index.mjs +673 -91
- package/dist/render/index.d.mts +26 -0
- package/dist/render/index.d.ts +26 -0
- package/dist/render/index.js +779 -106
- package/dist/render/index.mjs +779 -106
- package/dist/server/index.js +10419 -4103
- package/dist/server/index.mjs +10419 -4103
- package/dist/vue/index.js +673 -91
- package/dist/vue/index.mjs +673 -91
- package/package.json +8 -2
- package/schema/magic-editor-x.schema.json +127 -2
- package/types/blocks.d.ts +2 -0
- package/types/index.d.ts +42 -0
- package/types/math.d.ts +27 -0
- package/types/render.d.ts +26 -0
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# Magic Editor X
|
|
6
6
|
|
|
7
|
-
Block editor for Strapi 5: an [Editor.js](https://editorjs.io/) custom field with Media Library uploads, custom blocks, templates,
|
|
7
|
+
Block editor for Strapi 5: an [Editor.js](https://editorjs.io/) 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.
|
|
8
8
|
|
|
9
9
|
[](https://www.npmjs.com/package/magic-editor-x)
|
|
10
10
|
[](./LICENSE)
|
|
@@ -28,16 +28,20 @@ Live docs: <https://schero94.github.io/Magic-Editor-X/>
|
|
|
28
28
|
- [Writing tools](#writing-tools)
|
|
29
29
|
- [Templates, patterns and synced blocks](#templates-patterns-and-synced-blocks)
|
|
30
30
|
- [Comments](#comments)
|
|
31
|
+
- [Suggestions](#suggestions)
|
|
31
32
|
- [Paste, import and migration](#paste-import-and-migration)
|
|
32
33
|
- [Version history](#version-history)
|
|
33
34
|
- [Quality checks](#quality-checks)
|
|
35
|
+
- [Audit trail](#audit-trail)
|
|
34
36
|
- [Data format](#data-format)
|
|
35
37
|
- [Rendering content](#rendering-content)
|
|
36
38
|
- [Content API and GraphQL output](#content-api-and-graphql-output)
|
|
37
39
|
- [Custom blocks in code (SDK)](#custom-blocks-in-code-sdk)
|
|
40
|
+
- [Strapi AI translations and Releases](#strapi-ai-translations-and-releases)
|
|
38
41
|
- [Admin API and permissions](#admin-api-and-permissions)
|
|
39
42
|
- [Security and privacy](#security-and-privacy)
|
|
40
43
|
- [Troubleshooting](#troubleshooting)
|
|
44
|
+
- [Upgrading from 2.3](#upgrading-from-23)
|
|
41
45
|
- [Upgrading from 2.2](#upgrading-from-22)
|
|
42
46
|
- [Migrating from 1.x](#migrating-from-1x)
|
|
43
47
|
- [Development and tests](#development-and-tests)
|
|
@@ -47,33 +51,36 @@ Live docs: <https://schero94.github.io/Magic-Editor-X/>
|
|
|
47
51
|
|
|
48
52
|
## Features
|
|
49
53
|
|
|
50
|
-
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 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](#security-and-privacy)).
|
|
54
|
+
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](#security-and-privacy)). Mention e-mails, when the owner turns them on, go through your own Strapi email plugin.
|
|
51
55
|
|
|
52
56
|
- **Custom field** `plugin::magic-editor-x.richtext` (stored as JSON) for collection types, single types, components and dynamic zones, including localised fields and Draft & Publish.
|
|
53
57
|
- **Block tools** (block name in brackets, the same names 1.x used):
|
|
54
|
-
- text: paragraph (`paragraph`), heading H1 to H6 (`header`), list with nesting, ordered and unordered (`list`), checklist (`checklist`), quote (`quote`), warning (`warning`), alert in eight colours (`alert`), collapsible toggle (`toggle`), delimiter (`delimiter`), table (`table`);
|
|
58
|
+
- text: paragraph (`paragraph`), heading H1 to H6 (`header`), list with nesting, ordered and unordered (`list`), checklist (`checklist`), quote (`quote`), warning (`warning`), alert in eight colours (`alert`), collapsible toggle (`toggle`), delimiter (`delimiter`), table with header row and column, alignment, merged cells and a caption (`table`), formula in TeX (`math`, 2.4);
|
|
55
59
|
- structure: table of contents built from the headings, with stable anchors (`toc`), synced block that shows shared content edited in one place (`synced`, see [Templates, patterns and synced blocks](#templates-patterns-and-synced-blocks));
|
|
56
|
-
- code: plain code (`code`), code with syntax highlighting (`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);
|
|
60
|
+
- code: plain code (`code`), code with syntax highlighting and an optional file name (`codeFlask`; Prism with plain text, JavaScript, TypeScript, JSX, TSX, JSON, HTML/XML, CSS, SCSS, Shell, Python, PHP, Ruby, Java, Kotlin, Swift, C#, C, C++, Go, Rust, SQL, GraphQL, YAML, Markdown, Dockerfile and diff);
|
|
57
61
|
- media: image upload by file or URL into the Media Library (`image`, with alternative text and a focal point), picking images from the Media Library (`mediaLib`, inserts `image` blocks), image by URL without upload (`simpleImage`), gallery of Media Library images as grid or carousel (`gallery`), video and audio from the Media Library with captions and WebVTT tracks (`video`, `audio`), file attachments (`attaches`), embeds such as YouTube, Vimeo, CodePen, GitHub, Figma and others (`embed`);
|
|
58
62
|
- other: link preview card (`linkTool`), person card (`personality`), call-to-action button (`button`), raw HTML (`raw`).
|
|
59
|
-
- **Inline tools:** bold, italic, link with target and rel (`hyperlink`, with a built-in picker that links an entry of your content types, see [Internal links](#internal-links)), mention of an entry (`mention`, Ctrl/Cmd+Shift+2), marker, underline, strikethrough, inline code, tooltip, and the AI assistant when it is enabled.
|
|
63
|
+
- **Inline tools:** bold, italic, link with target and rel (`hyperlink`, with a built-in picker that links an entry of your content types, see [Internal links](#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.
|
|
60
64
|
- **Block tunes:** alignment (`alignmentTune`), text variant call-out / citation / details (`textVariant`), indent (`indentTune`).
|
|
61
65
|
- **Field presets:** per field in the Content-Type Builder: allowed blocks and heading levels, character and block limits, required alternative text, allowed links, AI and live collaboration on or off, publishing guard. Enforced on every save and over the live channel, not only in the editor. See [Field presets](#field-presets).
|
|
62
|
-
- **Writing:** Markdown shortcuts (`#`, `-`, `1.`, `[]`, `>`, ` ``` `, `---`, `**bold**`, `_italic_`, `~~strike~~`, `` `code` ``), find and replace, keyboard shortcut help, focus mode, actions for several selected blocks, counts with reading time, a rendered preview of the field (Ctrl/Cmd+Alt+P), undo and redo, drag and drop, full screen. See [Writing tools](#writing-tools).
|
|
66
|
+
- **Writing:** Markdown shortcuts (`#`, `-`, `1.`, `[]`, `>`, ` ``` `, `---`, `**bold**`, `_italic_`, `~~strike~~`, `` `code` ``), find and replace, keyboard shortcut help, focus mode, actions for several selected blocks, counts with reading time, a rendered preview of the field (Ctrl/Cmd+Alt+P), undo and redo, drag and drop, full screen. The field toolbar shows undo, redo, a **More tools** menu and full screen; everything else is in the menu. See [Writing tools](#writing-tools).
|
|
63
67
|
- **Templates, patterns and synced blocks:** reusable starting content and block sequences per field or preset, inserted from the editor toolbar, and synced blocks that every field shows from one source. See [Templates, patterns and synced blocks](#templates-patterns-and-synced-blocks).
|
|
64
|
-
- **
|
|
65
|
-
- **
|
|
68
|
+
- **Comments:** threads on single blocks or on selected text, with replies, resolve and reopen, @mentions of colleagues, a "Mentions and replies" widget on the admin home page and optional e-mails, for editors and read-only reviewers, with their own permissions. See [Comments](#comments).
|
|
69
|
+
- **Suggestions:** reviewers propose block changes in a separate copy of the field; editors accept or reject each one. See [Suggestions](#suggestions).
|
|
70
|
+
- **Paste and import:** Word, Google Docs, LibreOffice, web pages and Markdown become real blocks (tables keep merged cells, header cells and alignment; videos and audio from the web are copied into the Media Library); a CLI migrates Strapi Blocks, Markdown and HTML fields. See [Paste, import and migration](#paste-import-and-migration).
|
|
66
71
|
- **Media:** alternative text and "decorative image" on image blocks and gallery images, a focal point that frontends keep visible when they crop; images keep their Media Library id and responsive formats.
|
|
67
72
|
- **Quality checks:** accessibility lint (alternative texts, heading order, link texts, table headers, contrast of custom colours, videos without captions, empty tables of contents), a link check and an optional scheduled check of every external link, with an optional publishing guard. See [Quality checks](#quality-checks).
|
|
68
73
|
- **Renderers, schema and types:** `magic-editor-x/render` (HTML, plain text, Markdown; framework-free and XSS-safe), React and Vue components (`magic-editor-x/react`, `magic-editor-x/vue`), guides for React, Vue/Nuxt and Astro, `magic-editor-x/schema` (JSON Schema) and `magic-editor-x/types` (TypeScript). See [Rendering content](#rendering-content).
|
|
69
74
|
- **Content API and GraphQL output:** `?mex=html|text|markdown|json` on Content API requests and `<field>Rendered` / `<field>Resolved` in GraphQL, with internal links, mentions, embedded entries, media and synced blocks resolved with the caller's permissions. See [Content API and GraphQL output](#content-api-and-graphql-output).
|
|
70
75
|
- **Custom blocks:** define your own blocks in Settings: simple blocks with fields (text, textarea, URL, number, select, checkbox, image, colour) and an optional HTML template, or embedded-entry blocks that link an entry of another content type. Import and export as JSON. Blocks that need code (own editor UI, strict data rules, own output) are defined once with the block SDK; see [Custom blocks in code (SDK)](#custom-blocks-in-code-sdk).
|
|
71
|
-
- **Version history:** named versions, a word-level comparison with the current content (tune changes shown as "Alignment: left → center"), restore of the whole field or a single block; automatic versions during live sessions.
|
|
76
|
+
- **Version history:** named versions, a word-level comparison with the current content (tune changes shown as "Alignment: left → center"), restore of the whole field or a single block; automatic versions during live sessions. Fields inside repeatable components and dynamic zones have their own history (2.4). Synced block sources keep versions too.
|
|
77
|
+
- **Audit trail:** who changed which field, version, comment, template or setting, and when, with counts and block ids but never the content. See [Audit trail](#audit-trail).
|
|
72
78
|
- **Live collaboration:** several admins edit the same field at the same time with character-level merging, presence avatars and read-only viewers. Works with several Node processes behind a load balancer without sticky sessions.
|
|
73
|
-
- **AI assistant:** improve, fix grammar, shorten, expand, summarize, simplify, translate, change tone and continue writing, using Anthropic, OpenAI or any OpenAI-compatible server (for example a local model) with your own key. Optional, each behind its own owner switch: alternative text suggestions for images and translate or summarize a whole field. See [AI assistant](#ai-assistant).
|
|
79
|
+
- **AI assistant:** improve, fix grammar, shorten, expand, summarize, simplify, translate, change tone and continue writing, using Anthropic, OpenAI or any OpenAI-compatible server (for example a local model) with your own key, on selected text or on chosen blocks. Optional, each behind its own owner switch: alternative text suggestions for images and translate or summarize a whole field. See [AI assistant](#ai-assistant).
|
|
74
80
|
- **Grammar check:** spelling and grammar of a whole field with a LanguageTool server (self-hosted or hosted), off until the owner turns it on. See [Grammar check (LanguageTool)](#grammar-check-languagetool).
|
|
75
81
|
- **Strapi-native admin:** built with the Strapi Design System, light and dark mode, keyboard accessible, admin in English, German, French, Spanish and Portuguese.
|
|
76
82
|
- **Safe content:** every value is normalised and sanitised on the server when it is saved, from the Content Manager, the Content API or code.
|
|
83
|
+
- **Strapi AI translations and Releases:** Strapi's AI translation sends only the text of Magic Editor X fields and rebuilds other locales from the source structure; Releases show entries the publishing guard would refuse as not ready. See [Strapi AI translations and Releases](#strapi-ai-translations-and-releases).
|
|
77
84
|
|
|
78
85
|
## Screenshots
|
|
79
86
|
|
|
@@ -106,42 +113,61 @@ New in 2.3:
|
|
|
106
113
|
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------- |
|
|
107
114
|
|  |  |  |
|
|
108
115
|
|
|
116
|
+
New in 2.4:
|
|
117
|
+
|
|
118
|
+
| | |
|
|
119
|
+
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
120
|
+
|  |  |
|
|
121
|
+
|  |  |
|
|
122
|
+
|  |  |
|
|
123
|
+
|  |  |
|
|
124
|
+
|  |  |
|
|
125
|
+
|  |  |
|
|
126
|
+
|  |  |
|
|
127
|
+
|  |  |
|
|
128
|
+
|
|
109
129
|
All screenshots use synthetic data (acceptance host: Strapi 5.61.1).
|
|
110
130
|
|
|
111
131
|
## Core concepts
|
|
112
132
|
|
|
113
|
-
| Term | Meaning
|
|
114
|
-
| ------------ |
|
|
115
|
-
| Field | One Magic Editor X attribute of a content type or component. Its value is an Editor.js document.
|
|
116
|
-
| 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`.
|
|
117
|
-
| 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`.
|
|
118
|
-
| Template | Starting content for a field. Inserting it replaces the field content.
|
|
119
|
-
| Pattern | A group of blocks that editors insert anywhere in a field.
|
|
120
|
-
| 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.
|
|
121
|
-
| Thread | A comment and its replies on one block of one field, document and locale. Threads are not part of the field value.
|
|
122
|
-
|
|
|
123
|
-
|
|
|
124
|
-
|
|
|
133
|
+
| Term | Meaning |
|
|
134
|
+
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
135
|
+
| Field | One Magic Editor X attribute of a content type or component. Its value is an Editor.js document. |
|
|
136
|
+
| 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`. |
|
|
137
|
+
| 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`. |
|
|
138
|
+
| Template | Starting content for a field. Inserting it replaces the field content. |
|
|
139
|
+
| Pattern | A group of blocks that editors insert anywhere in a field. |
|
|
140
|
+
| 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. |
|
|
141
|
+
| 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. |
|
|
142
|
+
| 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. |
|
|
143
|
+
| 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). |
|
|
144
|
+
| Version | A stored copy (snapshot) of one field of one document in one locale, listed in the version history. |
|
|
145
|
+
| 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. |
|
|
146
|
+
| Viewer | Someone in a room who can read the document but not update it. Viewers see changes live but cannot type. |
|
|
125
147
|
|
|
126
148
|
## Screens
|
|
127
149
|
|
|
128
|
-
| Screen | Where
|
|
129
|
-
| ------------------------------ |
|
|
130
|
-
| Editor field | Content Manager, edit view
|
|
131
|
-
| Version history |
|
|
132
|
-
| Find and replace |
|
|
133
|
-
| Quality checks |
|
|
134
|
-
| Keyboard shortcuts, focus mode | More
|
|
135
|
-
| Field options | Content-Type Builder, Magic Editor X field, Basic and Advanced settings
|
|
136
|
-
| AI assistant | Inline toolbar (select text)
|
|
137
|
-
| AI for the whole field | More
|
|
138
|
-
| Comments panel |
|
|
139
|
-
| Insert template |
|
|
140
|
-
| Preview |
|
|
141
|
-
| Grammar check |
|
|
142
|
-
|
|
|
143
|
-
|
|
|
144
|
-
|
|
|
150
|
+
| Screen | Where | Who can open it |
|
|
151
|
+
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
152
|
+
| 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](#admin-api-and-permissions). |
|
|
153
|
+
| 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`. |
|
|
154
|
+
| 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. |
|
|
155
|
+
| Quality checks | More tools > Quality checks (the number counts problems) | Everyone who can read the field; the link check needs `access`. |
|
|
156
|
+
| Keyboard shortcuts, focus mode | More tools > Keyboard shortcuts or Focus mode, or Ctrl/Cmd+/ | Everyone who can read the field. |
|
|
157
|
+
| Field options | Content-Type Builder, Magic Editor X field, Basic and Advanced settings | Content-Type Builder access (development mode). |
|
|
158
|
+
| 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. |
|
|
159
|
+
| 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. |
|
|
160
|
+
| 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`. |
|
|
161
|
+
| 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`. |
|
|
162
|
+
| Preview | More tools > Preview, or Ctrl/Cmd+Alt+P | Everyone who can read the field, read-only users included. |
|
|
163
|
+
| Grammar check | More tools > Check grammar | `access` and `grammar.use`, when the owner turned LanguageTool on. |
|
|
164
|
+
| 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. |
|
|
165
|
+
| Suggest mode | More tools > Suggest changes, or "Suggest changes" under a field you cannot edit | `access`, `suggestions.create` and Content Manager read. |
|
|
166
|
+
| Mentions and replies | Widget on the admin home page | `access` and `comments.read`. |
|
|
167
|
+
| Configuration | Settings > Magic Editor X > Configuration | `settings.read` (view), `settings.update` (edit). |
|
|
168
|
+
| Custom blocks | Settings > Magic Editor X > Custom blocks | `custom-blocks.manage`. |
|
|
169
|
+
| Templates | Settings > Magic Editor X > Templates (templates, patterns and synced blocks, with versions of synced blocks) | `templates.manage`. |
|
|
170
|
+
| Audit trail | Settings > Magic Editor X > Audit trail | `audit.read` and `settings.read`. |
|
|
145
171
|
|
|
146
172
|
## Compatibility
|
|
147
173
|
|
|
@@ -150,9 +176,10 @@ All screenshots use synthetic data (acceptance host: Strapi 5.61.1).
|
|
|
150
176
|
| 2.x | 5.38 or later (acceptance host: Strapi 5.61.1) | 22 or 24 | SQLite, PostgreSQL and MySQL/MariaDB through the Strapi database connection. Acceptance runs used SQLite and PostgreSQL 16. |
|
|
151
177
|
| 1.x | 5.x | 22 | No longer developed. |
|
|
152
178
|
|
|
153
|
-
- `engines.node` is `>=22.0.0 <=26.x.x`; the 2.3
|
|
179
|
+
- `engines.node` is `>=22.0.0 <=26.x.x`; the 2.3 and 2.4 test runs used Node 22.23.1.
|
|
154
180
|
- The admin uses the React, React Router, react-intl, styled-components and Design System versions of the Strapi admin (React 18, Design System 2.2.4).
|
|
155
|
-
- The editor uses Editor.js 2.31.7. Editor.js 2.32.0 is still a release candidate on npm and is not used.
|
|
181
|
+
- The editor uses Editor.js 2.31.7. Editor.js 2.32.0 is still a release candidate on npm (`2.32.0-rc.3` on the `next` tag, checked 2026-11-12) and is not used. Why the plugin stays on Editor.js is explained in [docs/engine-decision.md](./docs/engine-decision.md).
|
|
182
|
+
- Formulas are rendered with Temml 0.14 (MIT), loaded by the admin only when a field shows math.
|
|
156
183
|
- `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.
|
|
157
184
|
- `magic-editor-x/vue` needs Vue 3.5 or later (optional peer `^3.5.0`; it is never installed by the plugin).
|
|
158
185
|
- `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.
|
|
@@ -202,6 +229,8 @@ All keys are optional. Infrastructure options live in `config/plugins`; the AI p
|
|
|
202
229
|
| `encryptionKey` | string (32+ characters) | unset | Key for the stored AI provider key. Prefer the `MAGIC_EDITOR_X_ENCRYPTION_KEY` environment variable. |
|
|
203
230
|
| `uploads.maxImageBytes` | integer | `10485760` (10 MiB) | Largest image accepted by file or URL (hard cap 500 MiB). |
|
|
204
231
|
| `uploads.maxFileBytes` | integer | `20971520` (20 MiB) | Largest attachment. |
|
|
232
|
+
| `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. |
|
|
233
|
+
| `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. |
|
|
205
234
|
| `linkPreview.enabled` | boolean | `true` | Link preview cards. When `false`, `GET /magic-editor-x/link` answers 404. |
|
|
206
235
|
| `linkPreview.timeoutMs` | integer | `8000` | Time limit for fetching a page (1000 to 30000). |
|
|
207
236
|
| `api.autoParseJSON` | boolean | `true` | Turn 1.x JSON strings into objects in Content API GET responses. |
|
|
@@ -209,6 +238,8 @@ All keys are optional. Infrastructure options live in `config/plugins`; the AI p
|
|
|
209
238
|
| `ai.apiKey` | string | unset | Provider key from the environment. When set it wins over a key stored in the settings. |
|
|
210
239
|
| `ai.requestsPerMinute` | integer | `20` | AI requests per admin per minute, shared by all processes. |
|
|
211
240
|
| `ai.timeoutMs` | integer | `60000` | Time limit for one provider request. |
|
|
241
|
+
| `ai.altText` | object | `{ allowPrivateOrigins: [] }` | Alternative text suggestions (2.4); key below. |
|
|
242
|
+
| `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. |
|
|
212
243
|
| `languageTool.allowPrivateBaseUrl` | boolean | `false` | Allow a LanguageTool base URL on loopback or private networks (self-hosted server in the LAN). Owner decision. |
|
|
213
244
|
| `languageTool.requestsPerMinute` | integer | `30` | Grammar checks per admin per minute, shared by all processes. |
|
|
214
245
|
| `languageTool.timeoutMs` | integer | `20000` | Time limit for one LanguageTool request. |
|
|
@@ -228,6 +259,12 @@ All keys are optional. Infrastructure options live in `config/plugins`; the AI p
|
|
|
228
259
|
| `history.maxSnapshotsPerField` | integer | `50` | Versions kept per field and locale; older ones are deleted. |
|
|
229
260
|
| `comments.enabled` | boolean | `true` | Block comments in the editor. `false` hides them and the comment routes answer 404. |
|
|
230
261
|
| `comments.perMinute` | integer | `30` | New comments and replies one admin may post per minute, shared by all processes (1 to 1000). |
|
|
262
|
+
| `comments.mentionsPerMinute` | integer | `60` | Searches of the @mention picker per admin and minute, shared by all processes (2.4). |
|
|
263
|
+
| `comments.notifications` | object | `{ email: false, emailPerHour: 10 }` | Mention e-mails (2.4); keys below. In-app notifications are always on. |
|
|
264
|
+
| `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. |
|
|
265
|
+
| `comments.notifications.emailPerHour` | integer | `10` | Mention e-mails per recipient and hour. |
|
|
266
|
+
| `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. |
|
|
267
|
+
| `suggestions.perMinute` | integer | `20` | Times one admin may send suggestions per minute (each send carries 1 to 50 block suggestions), shared by all processes. | |
|
|
231
268
|
| `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](#internal-links). |
|
|
232
269
|
| `qualityChecks.externalLinks` | object | `{ enabled: false, timeoutMs: 5000, perMinute: 30 }` | External link check of the quality panel; keys below. |
|
|
233
270
|
| `qualityChecks.externalLinks.enabled` | boolean | `false` | Lets the quality panel check external links (outgoing requests through the SSRF-protected fetcher; owner opt-in). |
|
|
@@ -236,10 +273,13 @@ All keys are optional. Infrastructure options live in `config/plugins`; the AI p
|
|
|
236
273
|
| `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. |
|
|
237
274
|
| `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. |
|
|
238
275
|
| `qualityChecks.externalLinks.schedule.enabled` | boolean | `false` | Runs the scheduled check. One process in a cluster runs each check (lease). |
|
|
239
|
-
| `qualityChecks.externalLinks.schedule.rule` | string | `'0 3 * * *'` | Cron rule (server time).
|
|
276
|
+
| `qualityChecks.externalLinks.schedule.rule` | string | `'0 3 * * *'` | Cron rule (in `schedule.tz`, else server time). |
|
|
277
|
+
| `qualityChecks.externalLinks.schedule.tz` | string | unset | IANA time zone of the rule, for example `'Europe/Berlin'` (2.4). Checked at startup. | |
|
|
240
278
|
| `qualityChecks.externalLinks.schedule.maxUrlsPerRun` | integer | `500` | Distinct URLs checked per run (1 to 10000). |
|
|
241
279
|
| `qualityChecks.externalLinks.schedule.perMinute` | integer | `60` | Requests per minute for the whole run (1 to 600). |
|
|
242
280
|
| `qualityChecks.externalLinks.schedule.perHostConcurrency` | integer | `2` | Requests in flight per host (1 to 8). |
|
|
281
|
+
| `audit.enabled` | boolean | `true` | Records the [audit trail](#audit-trail) (2.4). It holds no content. `false` stops recording and the extra reads it needs. |
|
|
282
|
+
| `audit.retentionDays` | integer | `180` | Days an audit event is kept (0 keeps everything, at most 3660). One process prunes once an hour. |
|
|
243
283
|
|
|
244
284
|
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](#migrating-from-1x).
|
|
245
285
|
|
|
@@ -267,7 +307,7 @@ Settings > Magic Editor X > Configuration stores these values in the Strapi stor
|
|
|
267
307
|
| Send images to the AI provider (`ai.allowImages`) | off | Allows alternative text suggestions; see [AI assistant](#ai-assistant) |
|
|
268
308
|
| Allow whole-field AI actions (`ai.allowFieldActions`) | off | Allows translate and summarize of a whole field |
|
|
269
309
|
|
|
270
|
-
The same page has a **Grammar check (LanguageTool)** section; see [Grammar check (LanguageTool)](#grammar-check-languagetool). It also shows the scheduled link check
|
|
310
|
+
The same page has a **Grammar check (LanguageTool)** section; see [Grammar check (LanguageTool)](#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.
|
|
271
311
|
|
|
272
312
|
## Live collaboration
|
|
273
313
|
|
|
@@ -286,7 +326,7 @@ How it works:
|
|
|
286
326
|
|
|
287
327
|
Limits:
|
|
288
328
|
|
|
289
|
-
- A new entry that has not been saved yet has no room.
|
|
329
|
+
- A new entry that has not been saved yet has no room. A new section in a repeatable component or dynamic zone gets its room, history and comments after the entry is saved once; until then the toolbar says so.
|
|
290
330
|
- Text formatting (bold, links, …) is part of the text; two people formatting the same word at the same moment can produce nested tags, which the sanitiser keeps valid.
|
|
291
331
|
- Up to 5000 blocks per field (the stored-content limit); rooms above 64 MiB of history refuse further edits until they are compacted.
|
|
292
332
|
|
|
@@ -328,6 +368,14 @@ The assistant is off until an administrator turns it on in Settings > Magic Edit
|
|
|
328
368
|
- Input is limited by "Max input characters", output by "Max output tokens". Each admin can send `ai.requestsPerMinute` requests per minute; the counter is shared by all processes.
|
|
329
369
|
- The answer is sanitised to the inline tags the editor uses before it reaches the browser. The admin reviews the suggestion and chooses Replace selection; nothing changes before that.
|
|
330
370
|
|
|
371
|
+
### AI for chosen blocks (2.4)
|
|
372
|
+
|
|
373
|
+
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.
|
|
374
|
+
|
|
375
|
+
- Uses the same switch, permission (`ai.use`), rate limit and "Max input characters" as the assistant for selected text; it does not need "Allow whole-field AI actions". Fields with `disableAi` answer 403.
|
|
376
|
+
- The answer must return every text it was sent, exactly once, or nothing changes (502 `BAD_RESPONSE`). Each text is sanitised to the inline tools the field allows, and links that were not in the original are removed. When the blocks changed while the assistant worked, the dialog says so and applies nothing.
|
|
377
|
+
- Since 2.4 the assistant for selected text works the same way: the suggestion is limited to the field's inline tools, links the selection did not hold are removed, the dialog shows a word diff, and formatting the selection crossed is kept.
|
|
378
|
+
|
|
331
379
|
### Alternative text and whole-field actions
|
|
332
380
|
|
|
333
381
|
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.
|
|
@@ -338,6 +386,7 @@ Two more AI features use the same provider, key and rate limit. Each has its own
|
|
|
338
386
|
| 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. |
|
|
339
387
|
|
|
340
388
|
- Local files are read only from the `public/uploads` folder; remote files (for example a cloud upload provider) are fetched through the same SSRF-protected fetcher as link previews. The image type is taken from the file's bytes.
|
|
389
|
+
- Upload providers on a private network (for example MinIO or S3-compatible storage inside your network) need their exact origin in `ai.altText.allowPrivateOrigins` (2.4). The host is resolved once and the connection is pinned to that address, redirects are never followed (also not to the same origin), and link-local and cloud metadata addresses stay refused even when listed. Settings > Configuration shows the list read-only.
|
|
341
390
|
- A translation must return every text it was sent, exactly once, or nothing changes (502 `BAD_RESPONSE`); each text is sanitised again and links that were not in the original are removed. Fields over "Max input characters" answer 413.
|
|
342
391
|
- `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.
|
|
343
392
|
|
|
@@ -393,21 +442,26 @@ Changing a preset never changes stored content by itself. Turning `sanitizeOnSav
|
|
|
393
442
|
|
|
394
443
|
## Writing tools
|
|
395
444
|
|
|
396
|
-
| Tool | How
|
|
397
|
-
| ----------------------- |
|
|
398
|
-
|
|
|
399
|
-
|
|
|
400
|
-
|
|
|
401
|
-
|
|
|
402
|
-
|
|
|
403
|
-
|
|
|
404
|
-
|
|
|
405
|
-
|
|
|
406
|
-
|
|
|
407
|
-
|
|
|
408
|
-
|
|
|
409
|
-
|
|
|
410
|
-
|
|
|
445
|
+
| Tool | How |
|
|
446
|
+
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
447
|
+
| 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. |
|
|
448
|
+
| 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. |
|
|
449
|
+
| 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. |
|
|
450
|
+
| Keyboard shortcuts | Ctrl/Cmd+/ or More > Keyboard shortcuts: editor, block and inline tool shortcuts and the Markdown shortcuts of this field. |
|
|
451
|
+
| Focus mode | More > Focus mode: full screen, narrower text column, other blocks dimmed. Escape leaves. |
|
|
452
|
+
| 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. |
|
|
453
|
+
| Counts | Blocks, words, characters and reading time (200 words per minute) in the toolbar, with the field's limits. |
|
|
454
|
+
| 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](#alternative-text-and-whole-field-actions)). |
|
|
455
|
+
| 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. |
|
|
456
|
+
| 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`). |
|
|
457
|
+
| 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. |
|
|
458
|
+
| 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. |
|
|
459
|
+
| 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. |
|
|
460
|
+
| 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. |
|
|
461
|
+
| 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](#rendering-content)). |
|
|
462
|
+
| 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). |
|
|
463
|
+
| 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. |
|
|
464
|
+
| 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. |
|
|
411
465
|
|
|
412
466
|
## Templates, patterns and synced blocks
|
|
413
467
|
|
|
@@ -430,23 +484,39 @@ Synced blocks in detail:
|
|
|
430
484
|
- A source cannot contain another synced block, and its kind cannot change (400). Turning a source off only stops offering it for insertion; fields that reference it keep showing it.
|
|
431
485
|
- Sources have no Draft & Publish and are not localised: a saved change is live in published API output at once. Old versions of a field store the reference only, so they show the current source.
|
|
432
486
|
- Settings shows how often a source is used (entries, fields, templates and patterns; `GET /magic-editor-x/templates/:id/usage`, counts only). The count reads the stored data, so it includes changes made through the Content API, scripts or imports; on very large sites it stops after 200,000 rows or 20 seconds and says "at least".
|
|
487
|
+
- **Versions of synced blocks (2.4):** every save of a source keeps a version (name, blocks, who saved it). The source's edit view in Settings lists them with a preview, a comparison with the content in the form, rename and **Restore** (with a confirmation; restoring saves the source again as a new version). Deleting a source deletes its versions. Templates and patterns have no versions.
|
|
433
488
|
- Synced blocks are offered only where the field's preset allows `synced` (`full` and `article`). Blocks of the source that the field does not allow are left out, and the editor says how many.
|
|
434
489
|
- Without `?mex`, the Content API returns the stored reference. With `?mex`, GraphQL `…Rendered`/`…Resolved` or the renderers' `synced` option, the source blocks are expanded in place (see [Content API and GraphQL output](#content-api-and-graphql-output)).
|
|
435
490
|
|
|
436
491
|
## Comments
|
|
437
492
|
|
|
438
|
-
Reviewers and editors can discuss single blocks without changing the content.
|
|
493
|
+
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.
|
|
439
494
|
|
|
440
495
|
- Start a thread on a chosen block, reply, resolve and reopen; edit or delete your own comments (deletion asks for confirmation). Resolved threads are hidden until you choose "Show resolved threads". A thread whose block was deleted stays readable and can be resolved.
|
|
496
|
+
- **Comments on selected text (2.4):** select text and choose Comment in the inline toolbar, or press Ctrl/Cmd+Alt+M. Read-only reviewers get a floating Comment button next to the selection. Magic Editor X highlights the passage and keeps the thread on it while people edit, also during live editing (the anchor follows the text in the live room, then its quoted text). When the passage is gone the thread says "Text changed" and stays on its block. Ctrl/Cmd+Alt+N jumps to the next open comment, with Shift to the previous one. Browsers without the CSS Custom Highlight API show no highlight; threads and markers still work.
|
|
497
|
+
- **Mentions (2.4):** type `@` in a comment to mention a colleague. The list offers only people who can read the field, by name (never e-mail addresses). The server checks every mention again and drops people without access. Mentioned people, and the other people in a thread when someone replies, see it in the comments panel ("You were mentioned", "New reply") and in the **Mentions and replies** widget on the admin home page, which links to the thread. With `comments.notifications.email: true` they also get an e-mail through your Strapi email plugin (in English, at most `emailPerHour` per person). The e-mail names who mentioned them and the entry title when they may read it, never the comment text.
|
|
441
498
|
- Comments are plain text (up to 4000 characters; control, bidi-override and zero-width characters are removed). They are never part of the field value, the version history or the Content API.
|
|
442
|
-
- Permissions: `comments.read` to see threads (plus Content Manager read on the document, locale and field), `comments.write` to comment, reply, 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.
|
|
499
|
+
- Permissions: `comments.read` to see threads and notifications (plus Content Manager read on the document, locale and field), `comments.write` to comment, reply, mention, resolve, reopen and edit or delete your own (no update right needed, so read-only reviewers can comment), `comments.moderate` to delete other people's comments or a thread with their replies.
|
|
443
500
|
- New comments appear for others within about 15 seconds (8 seconds with the panel open), on every process of a cluster.
|
|
444
|
-
- Limits: `comments.perMinute` per admin, 1000 comments per field and locale, 200 replies per thread.
|
|
445
|
-
-
|
|
501
|
+
- Limits: `comments.perMinute` per admin, 1000 comments per field and locale, 200 replies per thread, 20 mentions per comment, `comments.mentionsPerMinute` picker searches per admin.
|
|
502
|
+
- Fields inside repeatable components and dynamic zones have comments since 2.4. Threads written there before 2.4 were stored by position: they move to their entry when their block proves it, otherwise they are listed read-only under "Older comments saved by position".
|
|
503
|
+
- Deleting a document locale deletes its comments and notifications. Deleting an admin keeps their comments and shows them as "Deleted user", and deletes the notifications addressed to them. `comments.enabled: false` hides comments and the routes answer 404.
|
|
504
|
+
|
|
505
|
+
## Suggestions
|
|
506
|
+
|
|
507
|
+
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.
|
|
508
|
+
|
|
509
|
+
- The panel shows each suggestion as a word diff against the block as it is now, with author, time and note. A suggestion whose block changed since it was made is marked "Outdated" and asks before it replaces the newer text. **Accept all** accepts the suggestions that are not outdated.
|
|
510
|
+
- One decision wins: when two reviewers decide the same suggestion, the second gets "Someone else already decided this suggestion" (409 `ALREADY_DECIDED`). Authors can withdraw their own open suggestions.
|
|
511
|
+
- Suggestions are block level. Editor.js keeps no change marks in its data, so character-level track changes are not possible; moving blocks is not a suggestion. In the copy, AI, uploads, the Media Library and the footnote dialog are not available.
|
|
512
|
+
- Suggested blocks are cleaned with the field's sanitiser and checked against its preset when they are sent; an accepted change is checked again when the entry is saved. At most 50 per send, 500 open per field and locale, `suggestions.perMinute` sends per admin.
|
|
513
|
+
- Accepting needs `suggestions.review` and update access to the document; suggesting needs Content Manager read only. No role has either action after an update, so nothing appears until you grant them. `suggestions.enabled: false` turns the feature off.
|
|
514
|
+
|
|
515
|
+
**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.
|
|
446
516
|
|
|
447
517
|
## Paste, import and migration
|
|
448
518
|
|
|
449
|
-
**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. 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.
|
|
519
|
+
**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.
|
|
450
520
|
|
|
451
521
|
**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):
|
|
452
522
|
|
|
@@ -461,16 +531,28 @@ Options: `--format auto|blocks|markdown|html` (auto: Blocks fields as Strapi Blo
|
|
|
461
531
|
|
|
462
532
|
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`).
|
|
463
533
|
|
|
534
|
+
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](#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.
|
|
535
|
+
|
|
464
536
|
## Quality checks
|
|
465
537
|
|
|
466
538
|
The seal button opens the quality panel; its number counts problems. It never blocks editing.
|
|
467
539
|
|
|
468
|
-
- **Accessibility lint** (`shared/quality.mjs`): images and gallery images without alternative text (an error when the field has `requireAlt`, otherwise a warning; decorative images are fine), skipped heading levels, more than one H1, empty headings, empty links (error), link texts such as "click here", "hier", "cliquez ici", "aquí", "clique aqui" (English, German, French, Spanish, Portuguese), tables without a header row, 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.
|
|
540
|
+
- **Accessibility lint** (`shared/quality.mjs`): images and gallery images without alternative text (an error when the field has `requireAlt`, otherwise a warning; decorative images are fine), skipped heading levels, more than one H1, empty headings, empty links (error), link texts such as "click here", "hier", "cliquez ici", "aquí", "clique aqui" (English, German, French, Spanish, Portuguese), tables without a header row or header column, empty header cells (`table-empty-header`, warning), formulas that do not parse (`math-invalid`, warning), empty footnotes (`footnote-empty`, warning), custom-block colour pairs below 4.5:1, videos without a captions or subtitles track (`video-no-captions`, warning) and a table of contents without headings in its level range (`toc-no-headings`, warning). Click an issue to jump to its block.
|
|
469
541
|
- **Field settings:** content that breaks the field's [preset](#field-presets), with automatic fixes.
|
|
470
542
|
- **Check links** (`POST /magic-editor-x/quality/links`): internal links and mentions (entries you cannot read answer "Not checked", so nothing is revealed; "Not published" for drafts of Draft & Publish types), Media Library files of image, gallery, video and audio blocks (needs Media Library read) and, only when `qualityChecks.externalLinks.enabled` is true, external links through the SSRF-protected fetcher (public addresses only, pinned DNS, redirects re-checked, HEAD then a capped GET, rate limited per admin across processes, cached for 10 minutes). URLs are never logged.
|
|
471
|
-
- **Scheduled link check** (opt-in): with `qualityChecks.externalLinks.enabled` and `qualityChecks.externalLinks.schedule.enabled`, a cron job (`schedule.rule`, server time, default 03:00 every day) scans every editor field of every `api::` type (top level, components, dynamic zones; drafts and published versions; all locales) and checks up to `maxUrlsPerRun` external URLs, least recently checked first, at `perMinute` requests per minute and `perHostConcurrency` per host. In a cluster one process runs each check. The quality panel shows the last result for the field ("Scheduled check": broken links with their status for the draft and the published version; Enter on a link moves to its block), and Settings > Configuration shows the rule and the last run. 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.
|
|
543
|
+
- **Scheduled link check** (opt-in): with `qualityChecks.externalLinks.enabled` and `qualityChecks.externalLinks.schedule.enabled`, a cron job (`schedule.rule`, server time, default 03:00 every day) scans every editor field of every `api::` type (top level, components, dynamic zones; drafts and published versions; all locales) and checks up to `maxUrlsPerRun` external URLs, least recently checked first, at `perMinute` requests per minute and `perHostConcurrency` per host. In a cluster one process runs each check. The quality panel shows the last result for the field ("Scheduled check": broken links with their status for the draft and the published version; Enter on a link moves to its block), and Settings > Configuration shows the rule, the time zone, the next run and the last run, with **Run now** for admins with `settings.update` (`POST /magic-editor-x/quality/link-schedule/run`; it shows when a run is still going). Set `schedule.tz` (an IANA name such as `'Europe/Berlin'`) to run the rule in that zone instead of server time. URLs not checked within the budget keep their earlier result. Strapi's docs ask hosts to set `cron: { enabled: true }` in `config/server`; set it when you turn the schedule on. The plugin refuses to start when the schedule is on and `externalLinks.enabled` is off.
|
|
472
544
|
- **Private hosts:** `qualityChecks.externalLinks.allowPrivateOrigins` lists exact origins (for example `https://intranet.example.test`) that both link checks may reach although they resolve to a private address. Redirects from them are not followed.
|
|
473
|
-
- **Publishing guard:** with the field option `publishGuard`, publishing a document whose field has errors answers 400 `details.code: 'QUALITY_GATE'` with `details.issues: [{ field, rule, blockId, locale? }]` and `details.errors` for the form. Warnings never block.
|
|
545
|
+
- **Publishing guard:** with the field option `publishGuard`, publishing a document whose field has errors answers 400 `details.code: 'QUALITY_GATE'` with `details.issues: [{ field, rule, blockId, locale? }]` and `details.errors` for the form. Warnings never block. Since 2.4 the guard also runs when a document is created or updated directly as published (Content API `?status=published`, `strapi.documents().create/update({ status: 'published' })`); such writes skipped it before. Releases show entries the guard refuses as not ready (see [Strapi AI translations and Releases](#strapi-ai-translations-and-releases)).
|
|
546
|
+
|
|
547
|
+
## Audit trail
|
|
548
|
+
|
|
549
|
+
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.
|
|
550
|
+
|
|
551
|
+
- **No content:** an event holds its type, the target (content type, document, locale, field), counts, up to 20 block ids and identifiers, the person and the time. Never text, e-mail addresses, IP addresses or tokens.
|
|
552
|
+
- **Who can read it:** `audit.read`. The Settings page and listings across documents also need `settings.read`. The **Activity** tab in a field's version history shows that field's events and needs `audit.read` plus Content Manager read on the document (404 otherwise).
|
|
553
|
+
- **Retention:** `audit.retentionDays` (180 by default; 0 keeps everything). One process prunes once an hour. Deleting an admin keeps their events and shows them as "Deleted user". `audit.enabled: false` stops recording.
|
|
554
|
+
- **Coverage:** field changes are recorded from the Document Service, so the Content Manager, the Content API, imports and code are all covered; writes around it (`db.query`, raw SQL) are not. Content API writes are recorded without a person. With Strapi's Enterprise audit logs available, the events are also sent there.
|
|
555
|
+
- The events are stored in the table `magic_editor_x_audit`, not in a content type.
|
|
474
556
|
|
|
475
557
|
## Data format
|
|
476
558
|
|
|
@@ -492,6 +574,8 @@ The field stores an Editor.js document as JSON:
|
|
|
492
574
|
}
|
|
493
575
|
```
|
|
494
576
|
|
|
577
|
+
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.
|
|
578
|
+
|
|
495
579
|
Data of each block type as stored after sanitising (`shared/sanitize-policy.mjs`):
|
|
496
580
|
|
|
497
581
|
| Block | `data` |
|
|
@@ -505,9 +589,10 @@ Data of each block type as stored after sanitising (`shared/sanitize-policy.mjs`
|
|
|
505
589
|
| `alert` | `{ type: 'primary' \| 'secondary' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'light' \| 'dark', align: 'left' \| 'center' \| 'right', message }` |
|
|
506
590
|
| `toggle` | `{ text, status: 'open' \| 'closed', fk?, items }` (the next `items` blocks are its content) |
|
|
507
591
|
| `code` | `{ code }` (plain text) |
|
|
508
|
-
| `codeFlask` | `{ code, language, showlinenumbers? }`
|
|
592
|
+
| `codeFlask` | `{ code, language, showlinenumbers?, filename? }` (`filename` 2.4: plain text, max 200 characters, stored only when set) |
|
|
509
593
|
| `raw` | `{ html }` (see `rawHtml`) |
|
|
510
|
-
| `table` | `{ withHeadings, stretched, content: string[][] }`
|
|
594
|
+
| `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) |
|
|
595
|
+
| `math` (2.4) | `{ tex, display }` (`tex` plain-text TeX, max 10000; `display: false` = text style) |
|
|
511
596
|
| `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) |
|
|
512
597
|
| `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) |
|
|
513
598
|
| `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) |
|
|
@@ -526,9 +611,9 @@ Data of each block type as stored after sanitising (`shared/sanitize-policy.mjs`
|
|
|
526
611
|
| custom embedded-entry block | `{ entry: { id, documentId, title, <display fields> }, contentType, displayMode }` |
|
|
527
612
|
| block defined in code (SDK) | the keys of its `schema`, in declaration order (see [Custom blocks in code (SDK)](#custom-blocks-in-code-sdk)) |
|
|
528
613
|
|
|
529
|
-
Blocks `toc`, `gallery`, `video`, `audio` and `
|
|
614
|
+
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.
|
|
530
615
|
|
|
531
|
-
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`), `sub` and `sup
|
|
616
|
+
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.
|
|
532
617
|
|
|
533
618
|
### Internal links
|
|
534
619
|
|
|
@@ -589,6 +674,19 @@ All are off or neutral by default, so `renderHtml` output for existing content i
|
|
|
589
674
|
|
|
590
675
|
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.
|
|
591
676
|
|
|
677
|
+
### Options added in 2.4
|
|
678
|
+
|
|
679
|
+
Output for content without math, footnotes, code file names or 2.4 table keys is unchanged.
|
|
680
|
+
|
|
681
|
+
| Option | Values | Effect |
|
|
682
|
+
| ----------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
683
|
+
| `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. |
|
|
684
|
+
| `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">`. |
|
|
685
|
+
|
|
686
|
+
`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.
|
|
687
|
+
|
|
688
|
+
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.
|
|
689
|
+
|
|
592
690
|
`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.
|
|
593
691
|
|
|
594
692
|
```js
|
|
@@ -692,85 +790,116 @@ export const calloutCard = defineBlock({
|
|
|
692
790
|
|
|
693
791
|
The full guide with the admin tool, field types and security notes is [docs/guides/custom-blocks-sdk.md](docs/guides/custom-blocks-sdk.md).
|
|
694
792
|
|
|
793
|
+
## Strapi AI translations and Releases
|
|
794
|
+
|
|
795
|
+
Both run only when your Strapi plan includes the feature; on a Community Edition host the plugin's hooks stay inactive.
|
|
796
|
+
|
|
797
|
+
**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.
|
|
798
|
+
|
|
799
|
+
**Releases.** Strapi's Releases check entries with its own validator, which accepts any JSON. An entry the [publishing guard](#quality-checks) 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.
|
|
800
|
+
|
|
695
801
|
## Admin API and permissions
|
|
696
802
|
|
|
697
803
|
### Permissions
|
|
698
804
|
|
|
699
|
-
| Action | Label in Roles
|
|
700
|
-
| --------------------------------------------- |
|
|
701
|
-
| `plugin::magic-editor-x.access` | Use the editor (uploads, link previews, custom blocks, version history)
|
|
702
|
-
| `plugin::magic-editor-x.collaborate` | Edit together in real time
|
|
703
|
-
| `plugin::magic-editor-x.ai.use` | Use the AI assistant
|
|
704
|
-
| `plugin::magic-editor-x.custom-blocks.manage` | Manage custom blocks
|
|
705
|
-
| `plugin::magic-editor-x.settings.read` | Read settings
|
|
706
|
-
| `plugin::magic-editor-x.settings.update` | Update settings
|
|
707
|
-
| `plugin::magic-editor-x.comments.read` | Read block comments
|
|
708
|
-
| `plugin::magic-editor-x.comments.write` | Write block comments
|
|
709
|
-
| `plugin::magic-editor-x.comments.moderate` | Moderate block comments
|
|
710
|
-
| `plugin::magic-editor-x.grammar.use` | Use the grammar check (LanguageTool)
|
|
711
|
-
| `plugin::magic-editor-x.templates.manage` | Manage templates and block patterns
|
|
805
|
+
| Action | Label in Roles | Gates |
|
|
806
|
+
| --------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
807
|
+
| `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 |
|
|
808
|
+
| `plugin::magic-editor-x.collaborate` | Edit together in real time | Joining live rooms |
|
|
809
|
+
| `plugin::magic-editor-x.ai.use` | Use the AI assistant | AI requests |
|
|
810
|
+
| `plugin::magic-editor-x.custom-blocks.manage` | Manage custom blocks | Settings > Custom blocks and its routes |
|
|
811
|
+
| `plugin::magic-editor-x.settings.read` | Read settings | Settings > Configuration (read) |
|
|
812
|
+
| `plugin::magic-editor-x.settings.update` | Update settings | Saving settings, testing the AI connection |
|
|
813
|
+
| `plugin::magic-editor-x.comments.read` | Read block comments | Comment threads in the editor (with Content Manager read on the document) |
|
|
814
|
+
| `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) |
|
|
815
|
+
| `plugin::magic-editor-x.comments.moderate` | Moderate block comments | Deleting other people's comments |
|
|
816
|
+
| `plugin::magic-editor-x.grammar.use` | Use the grammar check (LanguageTool) | The "Check grammar" toolbar button and `POST /grammar/check` |
|
|
817
|
+
| `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 |
|
|
818
|
+
| `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`) |
|
|
819
|
+
| `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 |
|
|
820
|
+
| `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) |
|
|
712
821
|
|
|
713
822
|
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.
|
|
714
823
|
|
|
715
|
-
Super Admins have all actions. The `access` action keeps its 1.x id, so roles that had it keep using the editor.
|
|
824
|
+
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.
|
|
716
825
|
|
|
717
826
|
### Routes
|
|
718
827
|
|
|
719
828
|
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](#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.
|
|
720
829
|
|
|
721
|
-
| Method | Path
|
|
722
|
-
| ------ |
|
|
723
|
-
| GET | `/magic-editor-x/config`
|
|
724
|
-
| GET | `/magic-editor-x/link`
|
|
725
|
-
| POST | `/magic-editor-x/image/byFile`
|
|
726
|
-
| POST | `/magic-editor-x/image/byUrl`
|
|
727
|
-
| POST | `/magic-editor-x/
|
|
728
|
-
|
|
|
729
|
-
| GET | `/magic-editor-x/
|
|
730
|
-
| GET | `/magic-editor-x/links/
|
|
731
|
-
| GET | `/magic-editor-x/
|
|
732
|
-
| GET | `/magic-editor-x/custom-blocks
|
|
733
|
-
|
|
|
734
|
-
|
|
|
735
|
-
|
|
|
736
|
-
|
|
|
737
|
-
|
|
|
738
|
-
|
|
|
739
|
-
|
|
|
740
|
-
| GET | `/magic-editor-x/templates
|
|
741
|
-
|
|
|
742
|
-
|
|
|
743
|
-
| GET | `/magic-editor-x/templates/:id
|
|
744
|
-
|
|
|
745
|
-
|
|
|
746
|
-
|
|
|
747
|
-
|
|
|
748
|
-
| POST | `/magic-editor-x/
|
|
749
|
-
|
|
|
750
|
-
|
|
|
751
|
-
|
|
|
752
|
-
|
|
|
753
|
-
| POST | `/magic-editor-x/
|
|
754
|
-
| GET | `/magic-editor-x/
|
|
755
|
-
| GET | `/magic-editor-x/
|
|
756
|
-
| POST | `/magic-editor-x/
|
|
757
|
-
|
|
|
758
|
-
| POST | `/magic-editor-x/
|
|
759
|
-
|
|
|
760
|
-
|
|
|
761
|
-
| POST | `/magic-editor-x/
|
|
762
|
-
|
|
|
763
|
-
|
|
|
764
|
-
| POST | `/magic-editor-x/
|
|
765
|
-
|
|
|
766
|
-
| POST | `/magic-editor-x/
|
|
767
|
-
| POST | `/magic-editor-x/
|
|
768
|
-
|
|
|
769
|
-
|
|
|
770
|
-
|
|
|
771
|
-
| POST | `/magic-editor-x/
|
|
772
|
-
|
|
773
|
-
|
|
830
|
+
| Method | Path | Actions | Body / query | Response |
|
|
831
|
+
| ------ | ----------------------------------------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
832
|
+
| GET | `/magic-editor-x/config` | access | | `{ data: { collaboration, ai, grammar, uploads, linkPreview, quality, comments, rawHtml, codeBlocks, permissions } }` |
|
|
833
|
+
| GET | `/magic-editor-x/link` | access | `?url=` | `{ success: 1, link, meta }` |
|
|
834
|
+
| POST | `/magic-editor-x/image/byFile` | access, upload | multipart `image` | `{ success: 1, file: { url, ... } }` |
|
|
835
|
+
| POST | `/magic-editor-x/image/byUrl` | access, upload | `{ url }` | `{ success: 1, file }` |
|
|
836
|
+
| 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) |
|
|
837
|
+
| POST | `/magic-editor-x/file/upload` | access, upload | multipart `file` | `{ success: 1, file: { url, name, title, size, extension } }` |
|
|
838
|
+
| GET | `/magic-editor-x/content-types` | access | | `{ data: [{ uid, kind, displayName, attributes }] }` (types you can read) |
|
|
839
|
+
| GET | `/magic-editor-x/links/types` | access | | `{ data: [{ uid, kind, displayName, localized }] }` (API types you can read) |
|
|
840
|
+
| 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) |
|
|
841
|
+
| GET | `/magic-editor-x/custom-blocks` | access (`?all=true` also needs custom-blocks.manage) | `?all=true` | `{ data: [block] }` |
|
|
842
|
+
| GET | `/magic-editor-x/custom-blocks/export` | custom-blocks.manage | | `{ data: { format: 'magic-editor-x/custom-blocks', version: 2, exportedAt, blocks } }` |
|
|
843
|
+
| POST | `/magic-editor-x/custom-blocks/import` | custom-blocks.manage | export document | `{ data: { created: [name], skipped: [{ name, reason }] } }` |
|
|
844
|
+
| PUT | `/magic-editor-x/custom-blocks/order` | custom-blocks.manage | `{ ids }` (every block once) | `{ data: [block] }` |
|
|
845
|
+
| POST | `/magic-editor-x/custom-blocks` | custom-blocks.manage | block definition | 201 `{ data: block }` |
|
|
846
|
+
| PUT | `/magic-editor-x/custom-blocks/:id` | custom-blocks.manage | full block definition | `{ data: block }` |
|
|
847
|
+
| DELETE | `/magic-editor-x/custom-blocks/:id` | custom-blocks.manage | | `{ data: { id } }` |
|
|
848
|
+
| POST | `/magic-editor-x/custom-blocks/:id/duplicate` | custom-blocks.manage | | 201 `{ data: block }` |
|
|
849
|
+
| 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) |
|
|
850
|
+
| GET | `/magic-editor-x/templates/targets` | access, templates.manage | | `{ data: [{ uid, displayName, field, preset }] }` |
|
|
851
|
+
| PUT | `/magic-editor-x/templates/order` | access, templates.manage | `{ ids }` | `{ data: [template] }` |
|
|
852
|
+
| GET | `/magic-editor-x/templates/:id` | access | | `{ data: template }` (disabled ones only for managers; synced sources always) |
|
|
853
|
+
| GET | `/magic-editor-x/templates/:id/usage` | access, templates.manage | | `{ data: { entries, fields, templates, complete } }` (synced sources: how often they are referenced, counts only) |
|
|
854
|
+
| 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) |
|
|
855
|
+
| GET | `/magic-editor-x/templates/:id/versions/:versionId` | access, templates.manage | | `{ data: { ...version, content } }` |
|
|
856
|
+
| PUT | `/magic-editor-x/templates/:id/versions/:versionId` | access, templates.manage | `{ label }` (up to 120 characters, `''` or `null` clears) | `{ data: version }` |
|
|
857
|
+
| 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) |
|
|
858
|
+
| POST | `/magic-editor-x/templates` | access, templates.manage | `{ name, description?, kind, blocks, scope, enabled? }` | 201 `{ data: template }` |
|
|
859
|
+
| PUT | `/magic-editor-x/templates/:id` | access, templates.manage | full definition | `{ data: template }` |
|
|
860
|
+
| DELETE | `/magic-editor-x/templates/:id` | access, templates.manage | | `{ data: { id } }` |
|
|
861
|
+
| POST | `/magic-editor-x/templates/:id/duplicate` | access, templates.manage | | 201 `{ data: template }` (disabled copy) |
|
|
862
|
+
| POST | `/magic-editor-x/collaboration/session` | access, collaborate | `{ uid, documentId, locale?, field, initialValue? }` | `{ data: { token, path, canEdit, expiresAt } }` |
|
|
863
|
+
| GET | `/magic-editor-x/history` | access | `?uid&documentId&locale&field` | `{ data: [version], meta: { canRestore, canCreate } }` |
|
|
864
|
+
| GET | `/magic-editor-x/history/:id` | access | | `{ data: { ...version, content } }` |
|
|
865
|
+
| 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) |
|
|
866
|
+
| 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 |
|
|
867
|
+
| 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` |
|
|
868
|
+
| 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) |
|
|
869
|
+
| GET | `/magic-editor-x/quality/link-schedule` | settings.read | | `{ data: { enabled, scheduled, rule, tz, nextRunAt, maxUrlsPerRun, perMinute, perHostConcurrency, running, lastRun } }` (`tz`, `nextRunAt` 2.4) |
|
|
870
|
+
| POST | `/magic-editor-x/quality/link-schedule/run` | settings.read, settings.update | | 202 `{ data: { started: true } }`; 409 `RUNNING`; 400 `DISABLED` |
|
|
871
|
+
| GET | `/magic-editor-x/comments` | access, comments.read (+ Content Manager read) | `?uid&documentId&locale&field` | `{ data: [thread], meta: { counts, canWrite, canModerate } }` |
|
|
872
|
+
| 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` |
|
|
873
|
+
| POST | `/magic-editor-x/comments/:id/replies` | access, comments.read, comments.write (+ Content Manager read) | `{ body }` | 201 `{ data: comment }` (reopens a resolved thread) |
|
|
874
|
+
| PUT | `/magic-editor-x/comments/:id` | access, comments.read, comments.write (+ Content Manager read) | `{ body }` | `{ data: comment }`; author only (403) |
|
|
875
|
+
| POST | `/magic-editor-x/comments/:id/resolve` | access, comments.read, comments.write (+ Content Manager read) | | `{ data: { id, status, resolvedAt, resolvedBy } }` |
|
|
876
|
+
| POST | `/magic-editor-x/comments/:id/reopen` | access, comments.read, comments.write (+ Content Manager read) | | `{ data: { id, status, resolvedAt, resolvedBy } }` |
|
|
877
|
+
| DELETE | `/magic-editor-x/comments/:id` | access, comments.read (+ Content Manager read) | | `{ data: { id, removed } }`; others' comments need comments.moderate (403) |
|
|
878
|
+
| 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` |
|
|
879
|
+
| 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) |
|
|
880
|
+
| POST | `/magic-editor-x/notifications/read-all` | access, comments.read | `{ threadIds? }` (up to 100; without: all) | `{ data: { updated } }` |
|
|
881
|
+
| POST | `/magic-editor-x/notifications/:id/read` | access, comments.read | | `{ data: { id, read: true } }`; 404 for someone else's |
|
|
882
|
+
| POST | `/magic-editor-x/notifications/:id/unread` | access, comments.read | | `{ data: { id, read: false } }`; 404 for someone else's |
|
|
883
|
+
| 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 } }` |
|
|
884
|
+
| 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` |
|
|
885
|
+
| POST | `/magic-editor-x/suggestions/:id/accept` | access, suggestions.review (+ Content Manager update) | `{ outdated? }` | `{ data: suggestion }` with the cleaned `proposed` block; 409 `ALREADY_DECIDED` |
|
|
886
|
+
| POST | `/magic-editor-x/suggestions/:id/reject` | access, suggestions.review (+ Content Manager update) | `{}` | `{ data: suggestion }`; 409 `ALREADY_DECIDED` |
|
|
887
|
+
| DELETE | `/magic-editor-x/suggestions/:id` | access, suggestions.create | | `{ data: { id } }` (your own open suggestion; 403 otherwise) |
|
|
888
|
+
| POST | `/magic-editor-x/ai/:action` | access, ai.use | `{ text, language?, tone?, target: { uid, field } }` | `{ data: { text } }`; 403 when the field turns AI off |
|
|
889
|
+
| 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 |
|
|
890
|
+
| POST | `/magic-editor-x/ai/field/:action` | access, ai.use | `{ target, segments: [{ blockId, path, html }], language? }` | `{ data: { segments } }` or `{ data: { text } }` |
|
|
891
|
+
| 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) |
|
|
892
|
+
| POST | `/magic-editor-x/grammar/check` | access, grammar.use | `{ target, segments, locale? }` | `{ data: { language, matches, truncated } }` |
|
|
893
|
+
| GET | `/magic-editor-x/settings` | settings.read | | `{ data: { ai, languageTool, environment } }` (no secrets) |
|
|
894
|
+
| 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 } }` |
|
|
895
|
+
| POST | `/magic-editor-x/settings/ai/test` | settings.read, settings.update | `{ ai: {...} }` | `{ data: { ok: true } }` |
|
|
896
|
+
| POST | `/magic-editor-x/settings/language-tool/test` | settings.read, settings.update | `{ languageTool: {...} }` | `{ data: { ok: true } }` |
|
|
897
|
+
| 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) |
|
|
898
|
+
| GET | `/magic-editor-x/audit/actors` | audit.read, settings.read | | `{ data: [{ id, name }] }` (people in the trail, up to 200) |
|
|
899
|
+
|
|
900
|
+
`upload` means `plugin::upload.assets.create`.
|
|
901
|
+
|
|
902
|
+
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.
|
|
774
903
|
|
|
775
904
|
Example: save a version.
|
|
776
905
|
|
|
@@ -806,14 +935,17 @@ Content-Type: application/json
|
|
|
806
935
|
| Request | When | What is sent |
|
|
807
936
|
| ---------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
|
808
937
|
| 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 |
|
|
938
|
+
| 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 |
|
|
809
939
|
| 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 |
|
|
810
940
|
| 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 |
|
|
811
941
|
| AI assistant | An editor runs an action on selected text, after the owner configured a provider | The selected text and a fixed instruction |
|
|
812
942
|
| 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 |
|
|
813
943
|
| 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) |
|
|
944
|
+
| 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 |
|
|
945
|
+
| 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 |
|
|
814
946
|
| 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 |
|
|
815
947
|
|
|
816
|
-
Link previews, images 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;
|
|
948
|
+
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.
|
|
817
949
|
|
|
818
950
|
- **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.
|
|
819
951
|
- **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](./docs/security-audit-2.1.md).
|
|
@@ -822,10 +954,11 @@ Content-Type: application/json
|
|
|
822
954
|
- **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.
|
|
823
955
|
- **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.
|
|
824
956
|
- **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.
|
|
957
|
+
- **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](./docs/security-audit-2.4.md).
|
|
825
958
|
- **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.
|
|
826
959
|
- **Logs** contain operation names and error codes only, never content, URLs with queries, tokens, user ids or email addresses.
|
|
827
|
-
- **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, with the scheduled link check, the external URLs of editor fields with their last status.
|
|
828
|
-
- **Reviews:** [docs/security-audit-2.
|
|
960
|
+
- **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.
|
|
961
|
+
- **Reviews:** [docs/security-audit-2.4.md](./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](./docs/security-audit-2.3.md) every 2.3 surface (MEX-23-01 to MEX-23-15), each with controls, tests and residual risks.
|
|
829
962
|
- **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](#content-security-policy) below.
|
|
830
963
|
|
|
831
964
|
Report vulnerabilities privately through GitHub security advisories on the repository.
|
|
@@ -901,6 +1034,30 @@ Add only the services you use. Instead of `https:` in `img-src` you can list you
|
|
|
901
1034
|
| "The grammar check is not configured yet." | LanguageTool is on but has no base URL | Enter the base URL and use Test LanguageTool. |
|
|
902
1035
|
| Startup error `invalid configuration for: qualityChecks.externalLinks.schedule.enabled` | The schedule is on but `qualityChecks.externalLinks.enabled` is off | Turn on both, or neither. |
|
|
903
1036
|
| 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. |
|
|
1037
|
+
| "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. |
|
|
1038
|
+
| "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`). |
|
|
1039
|
+
| 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. |
|
|
1040
|
+
| 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. |
|
|
1041
|
+
| 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. |
|
|
1042
|
+
| 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). |
|
|
1043
|
+
| 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. |
|
|
1044
|
+
|
|
1045
|
+
## Upgrading from 2.3
|
|
1046
|
+
|
|
1047
|
+
2.4 is a minor release. Stored content, routes and configuration keep working; there are no breaking changes.
|
|
1048
|
+
|
|
1049
|
+
1. Update and rebuild the admin: `npm install magic-editor-x@latest && npm run build`.
|
|
1050
|
+
2. Grant the new actions to roles that need them: `suggestions.create`, `suggestions.review`, `audit.read`. No role gets them automatically.
|
|
1051
|
+
3. Optional: `comments.notifications.email: true` (needs a working Strapi email provider), `qualityChecks.externalLinks.schedule.tz`, `uploads.allowPrivateOrigins`, `ai.altText.allowPrivateOrigins`. The audit trail is on by default (`audit.enabled`, 180 days); set `audit.enabled: false` if you do not want it.
|
|
1052
|
+
|
|
1053
|
+
What changes for existing data and clients:
|
|
1054
|
+
|
|
1055
|
+
- Values inside repeatable components and dynamic zones get a `fieldKey` the next time they are saved. API clients that write such values should send the key back (or send the component `id`); otherwise each write gives them a new key and their history, comments and live room start fresh.
|
|
1056
|
+
- Versions and comments that 2.3 stored for such fields by position are mapped to their entry when their block ids prove it, the first time someone opens that field's history or comments. The rest stay readable but read-only. Nothing is deleted.
|
|
1057
|
+
- Tables use the plugin's own table tool instead of `@editorjs/table`. Stored tables are unchanged, and tables without the new keys render exactly as before.
|
|
1058
|
+
- Content API writes with `?status=published` now run the publishing guard (400 `QUALITY_GATE` for fields with `publishGuard` and errors).
|
|
1059
|
+
- A block registered in code with the name `math` keeps working; Settings custom blocks named `math` from before 2.4 keep their data, and new ones cannot take the name.
|
|
1060
|
+
- Editor.js stays at 2.31.7.
|
|
904
1061
|
|
|
905
1062
|
## Upgrading from 2.2
|
|
906
1063
|
|
|
@@ -938,7 +1095,7 @@ npm run verify
|
|
|
938
1095
|
MEX_HOST_URL=http://127.0.0.1:1421 MEX_CREDS=/path/to/creds.json npm run test:integration
|
|
939
1096
|
```
|
|
940
1097
|
|
|
941
|
-
[CONTRIBUTING.md](./CONTRIBUTING.md) explains the isolated acceptance host, the integration suite on SQLite and PostgreSQL and the multi-process acceptance run. [AGENTS.md](./AGENTS.md) is the contract for coding agents.
|
|
1098
|
+
[docs/engine-decision.md](./docs/engine-decision.md) records why the plugin stays on Editor.js for 2.x. [CONTRIBUTING.md](./CONTRIBUTING.md) explains the isolated acceptance host, the integration suite on SQLite and PostgreSQL and the multi-process acceptance run. [AGENTS.md](./AGENTS.md) is the contract for coding agents.
|
|
942
1099
|
|
|
943
1100
|
## Maintenance status
|
|
944
1101
|
|