magic-editor-x 2.2.0 → 2.3.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 +72 -0
- package/README.md +493 -168
- package/dist/admin/{ConfigurationPage-3Dir3dAf.mjs → ConfigurationPage-BxLHIQdo.mjs} +450 -21
- package/dist/admin/{ConfigurationPage-YvnPnna6.js → ConfigurationPage-C-UktL1x.js} +479 -50
- package/dist/admin/ConfirmAction-DuQwvRYi.mjs +125 -0
- package/dist/admin/ConfirmAction-zLuIFj8t.js +124 -0
- package/dist/admin/{CustomBlocksPage-BiiL2ORG.js → CustomBlocksPage-CxcTfdOT.js} +135 -84
- package/dist/admin/{CustomBlocksPage-CR2BaP9O.mjs → CustomBlocksPage-D8aMbVXc.mjs} +92 -41
- package/dist/admin/DraftSync-BIA8cZgA.js +11 -0
- package/dist/admin/DraftSync-CUxOMG-E.mjs +12 -0
- package/dist/admin/TemplatesPage-Hn6gyu2l.js +993 -0
- package/dist/admin/TemplatesPage-jhYi6Zdf.mjs +993 -0
- package/dist/admin/{de-BmmLBJli.mjs → de-1cFMs-4c.mjs} +2 -0
- package/dist/admin/{de-BteRx2iA.js → de-2Ie5jy7j.js} +79 -1
- package/dist/admin/{de-62Vxb2iw.js → de-B1X46JJZ.js} +205 -2
- package/dist/admin/{de-CFX5atOk.mjs → de-BMY2LBaa.mjs} +79 -1
- package/dist/admin/{de-Bt6pYIWi.mjs → de-BUS1hUw0.mjs} +145 -0
- package/dist/admin/{de-CVbi685U.js → de-C3AsGauQ.js} +145 -0
- package/dist/admin/{de-BVvwSYYO.mjs → de-DOiGaTNX.mjs} +205 -2
- package/dist/admin/{de-DaJwN6nk.js → de-Dn8athM8.js} +2 -0
- package/dist/admin/{en-CyjAcccB.js → en-Ah-Cw0Wd.js} +79 -1
- package/dist/admin/{en-BX362fTp.js → en-BkEjpC3i.js} +145 -0
- package/dist/admin/{en-VlkaIzrM.js → en-CDg_18Bt.js} +205 -2
- package/dist/admin/{en-Cn78RZs-.js → en-CIZ5Ggod.js} +2 -0
- package/dist/admin/{en-Cg2Ak5Cr.mjs → en-CU6UzV4g.mjs} +205 -2
- package/dist/admin/{en-ea0tfA5i.mjs → en-CvFiqti2.mjs} +79 -1
- package/dist/admin/{en-D7mZWLGp.mjs → en-Dc9y-6n9.mjs} +2 -0
- package/dist/admin/{en-B_HltUxZ.mjs → en-GCzgS9Aw.mjs} +145 -0
- package/dist/admin/{es-BT9oAcHf.js → es-BCpJmUEM.js} +205 -2
- package/dist/admin/{es-C9-cXdb6.mjs → es-BmfffNM2.mjs} +205 -2
- package/dist/admin/{es-BmGtLkJD.js → es-C4IRHV5d.js} +2 -0
- package/dist/admin/{es-CHHEZi44.js → es-C4pEnDRv.js} +145 -0
- package/dist/admin/{es-C8GZFGjv.js → es-Cr8JH85N.js} +79 -1
- package/dist/admin/{es-joykG5I9.mjs → es-D2Kw6E4N.mjs} +2 -0
- package/dist/admin/{es-CrhwOq-5.mjs → es-DHBBZKl2.mjs} +145 -0
- package/dist/admin/{es-CEi_ycX8.mjs → es-DbKHZz5l.mjs} +79 -1
- package/dist/admin/{fr-CrzxGe5e.mjs → fr-BOvvfEH7.mjs} +2 -0
- package/dist/admin/{fr-B3SL0TBV.js → fr-C2aLSwEu.js} +145 -0
- package/dist/admin/{fr-BAMSvQbR.mjs → fr-DQJ_7aq5.mjs} +79 -1
- package/dist/admin/{fr-DpU_qiXR.mjs → fr-DZd2XJP6.mjs} +205 -2
- package/dist/admin/{fr-5djKfQ3s.mjs → fr-Dvq4xk2e.mjs} +145 -0
- package/dist/admin/{fr-oRCJNdeJ.js → fr-OJ4VW1kh.js} +79 -1
- package/dist/admin/{fr-D6KJqPWi.js → fr-ZcN0yM_2.js} +205 -2
- package/dist/admin/{fr-Ct_uPqxV.js → fr-Zkb8vfjN.js} +2 -0
- package/dist/admin/index-BHBRr562.js +1940 -0
- package/dist/admin/index-CQk1XeNb.mjs +1939 -0
- package/dist/admin/{EditorField-Diq1j8kc.js → index-Cm-fFUhE.js} +13704 -6766
- package/dist/admin/{EditorField-B8pyAxPE.mjs → index-XgfwqLfV.mjs} +10203 -3265
- package/dist/admin/index.js +1 -1
- package/dist/admin/index.mjs +2 -2
- package/dist/admin/{pt-chN2jrXl.js → pt-1IUyx6ae.js} +2 -0
- package/dist/admin/{pt-CQrfqsCN.mjs → pt-BSLzA17U.mjs} +79 -1
- package/dist/admin/{pt-jUqOR7Xh.mjs → pt-C3UdeIpd.mjs} +205 -2
- package/dist/admin/{pt-BOrl6x-r.js → pt-CImqDnLB.js} +205 -2
- package/dist/admin/{pt-BdnY2Cth.mjs → pt-CilDggGF.mjs} +145 -0
- package/dist/admin/{pt-tUeJ2Ywd.js → pt-D0I0_JYs.js} +79 -1
- package/dist/admin/{pt-EVwCuBUK.js → pt-DX0OAIoL.js} +145 -0
- package/dist/admin/{pt-Ga-4Hsv0.mjs → pt-etwsg3G4.mjs} +2 -0
- package/dist/admin/useBreakpoint-D30eNTkF.js +37 -0
- package/dist/admin/useBreakpoint-DCfn6pDG.mjs +38 -0
- package/dist/admin/useT-CmaeZbCr.mjs +65 -0
- package/dist/admin/{useT-BWZ_-Hel.js → useT-D3sM9Zf7.js} +4 -70
- package/dist/blocks/index.d.mts +167 -0
- package/dist/blocks/index.d.ts +167 -0
- package/dist/blocks/index.js +631 -0
- package/dist/blocks/index.mjs +609 -0
- package/dist/react/index.d.mts +39 -0
- package/dist/react/index.d.ts +39 -0
- package/dist/react/index.js +2687 -0
- package/dist/react/index.mjs +2657 -0
- package/dist/render/index.d.mts +131 -5
- package/dist/render/index.d.ts +131 -5
- package/dist/render/index.js +1679 -181
- package/dist/render/index.mjs +1679 -181
- package/dist/server/index.js +10645 -3716
- package/dist/server/index.mjs +10645 -3716
- package/dist/vue/index.d.mts +41 -0
- package/dist/vue/index.d.ts +41 -0
- package/dist/vue/index.js +2630 -0
- package/dist/vue/index.mjs +2610 -0
- package/package.json +30 -6
- package/schema/magic-editor-x.schema.json +540 -1
- package/types/blocks.d.ts +167 -0
- package/types/index.d.ts +127 -0
- package/types/react.d.ts +39 -0
- package/types/render.d.ts +131 -5
- package/types/vue.d.ts +41 -0
- package/dist/admin/api-Dsq53giv.js +0 -37
- package/dist/admin/api-RZ0Fz0BD.mjs +0 -38
- package/dist/admin/index-C-lyON1B.mjs +0 -303
- package/dist/admin/index-iA0lued_.js +0 -302
- package/dist/admin/sanitize-Cb4jvBhj.js +0 -628
- package/dist/admin/sanitize-ClkX823p.mjs +0 -627
- package/dist/admin/useT-pvHmgBFj.mjs +0 -131
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, version history, live collaboration across several servers and
|
|
7
|
+
Block editor for Strapi 5: an [Editor.js](https://editorjs.io/) custom field with Media Library uploads, custom blocks, templates, block comments, version history, 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)
|
|
@@ -23,16 +23,22 @@ Live docs: <https://schero94.github.io/Magic-Editor-X/>
|
|
|
23
23
|
- [Live collaboration](#live-collaboration)
|
|
24
24
|
- [Running several instances](#running-several-instances)
|
|
25
25
|
- [AI assistant](#ai-assistant)
|
|
26
|
+
- [Grammar check (LanguageTool)](#grammar-check-languagetool)
|
|
26
27
|
- [Field presets](#field-presets)
|
|
27
28
|
- [Writing tools](#writing-tools)
|
|
29
|
+
- [Templates, patterns and synced blocks](#templates-patterns-and-synced-blocks)
|
|
30
|
+
- [Comments](#comments)
|
|
28
31
|
- [Paste, import and migration](#paste-import-and-migration)
|
|
29
32
|
- [Version history](#version-history)
|
|
30
33
|
- [Quality checks](#quality-checks)
|
|
31
34
|
- [Data format](#data-format)
|
|
32
35
|
- [Rendering content](#rendering-content)
|
|
36
|
+
- [Content API and GraphQL output](#content-api-and-graphql-output)
|
|
37
|
+
- [Custom blocks in code (SDK)](#custom-blocks-in-code-sdk)
|
|
33
38
|
- [Admin API and permissions](#admin-api-and-permissions)
|
|
34
39
|
- [Security and privacy](#security-and-privacy)
|
|
35
40
|
- [Troubleshooting](#troubleshooting)
|
|
41
|
+
- [Upgrading from 2.2](#upgrading-from-22)
|
|
36
42
|
- [Migrating from 1.x](#migrating-from-1x)
|
|
37
43
|
- [Development and tests](#development-and-tests)
|
|
38
44
|
- [Maintenance status](#maintenance-status)
|
|
@@ -41,26 +47,31 @@ Live docs: <https://schero94.github.io/Magic-Editor-X/>
|
|
|
41
47
|
|
|
42
48
|
## Features
|
|
43
49
|
|
|
44
|
-
Every feature is available in every installation. There is nothing to activate, no tiers and no usage limits
|
|
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)).
|
|
45
51
|
|
|
46
52
|
- **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.
|
|
47
53
|
- **Block tools** (block name in brackets, the same names 1.x used):
|
|
48
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`);
|
|
49
|
-
-
|
|
50
|
-
-
|
|
55
|
+
- 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);
|
|
57
|
+
- 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`);
|
|
51
58
|
- other: link preview card (`linkTool`), person card (`personality`), call-to-action button (`button`), raw HTML (`raw`).
|
|
52
|
-
- **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)), marker, underline, strikethrough, inline code, tooltip, and the AI assistant when it is enabled.
|
|
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.
|
|
53
60
|
- **Block tunes:** alignment (`alignmentTune`), text variant call-out / citation / details (`textVariant`), indent (`indentTune`).
|
|
54
61
|
- **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).
|
|
55
|
-
- **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, undo and redo, drag and drop, full screen. See [Writing tools](#writing-tools).
|
|
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).
|
|
63
|
+
- **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
|
+
- **Block comments:** threads on single blocks with replies, resolve and reopen, for editors and read-only reviewers, with their own permissions. See [Comments](#comments).
|
|
56
65
|
- **Paste and import:** Word, Google Docs, LibreOffice, web pages and Markdown become real blocks; a CLI migrates Strapi Blocks, Markdown and HTML fields. See [Paste, import and migration](#paste-import-and-migration).
|
|
57
|
-
- **Media:** alternative text and "decorative image" on image blocks; images keep their Media Library id and responsive formats.
|
|
58
|
-
- **Quality checks:** accessibility lint (alternative texts, heading order, link texts, table headers, contrast of custom colours)
|
|
59
|
-
- **Renderers, schema and types:** `magic-editor-x/render` (HTML, plain text, Markdown; framework-free and XSS-safe), `magic-editor-x/schema` (JSON Schema) and `magic-editor-x/types` (TypeScript). See [Rendering content](#rendering-content).
|
|
60
|
-
- **
|
|
61
|
-
- **
|
|
66
|
+
- **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
|
+
- **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
|
+
- **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
|
+
- **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
|
+
- **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.
|
|
62
72
|
- **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.
|
|
63
|
-
- **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.
|
|
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).
|
|
74
|
+
- **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).
|
|
64
75
|
- **Strapi-native admin:** built with the Strapi Design System, light and dark mode, keyboard accessible, admin in English, German, French, Spanish and Portuguese.
|
|
65
76
|
- **Safe content:** every value is normalised and sanitised on the server when it is saved, from the Content Manager, the Content API or code.
|
|
66
77
|
|
|
@@ -78,9 +89,24 @@ Every feature is available in every installation. There is nothing to activate,
|
|
|
78
89
|
|  |  |
|
|
79
90
|
|  |  |
|
|
80
91
|
|
|
81
|
-
|
|
92
|
+
New in 2.3:
|
|
82
93
|
|
|
83
|
-
|
|
94
|
+
| | |
|
|
95
|
+
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
96
|
+
|  |  |
|
|
97
|
+
|  |  |
|
|
98
|
+
|  |  |
|
|
99
|
+
|  |  |
|
|
100
|
+
|  |  |
|
|
101
|
+
|  |  |
|
|
102
|
+
|  |  |
|
|
103
|
+
|  |  |
|
|
104
|
+
|
|
105
|
+
| | | |
|
|
106
|
+
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------- |
|
|
107
|
+
|  |  |  |
|
|
108
|
+
|
|
109
|
+
All screenshots use synthetic data (acceptance host: Strapi 5.61.1).
|
|
84
110
|
|
|
85
111
|
## Core concepts
|
|
86
112
|
|
|
@@ -88,24 +114,34 @@ All screenshots use synthetic data.
|
|
|
88
114
|
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
89
115
|
| Field | One Magic Editor X attribute of a content type or component. Its value is an Editor.js document. |
|
|
90
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`. |
|
|
91
|
-
| Custom block | A block type defined in Settings > Magic Editor X > Custom blocks. Its name becomes the block `type`.
|
|
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. |
|
|
92
122
|
| Version | A stored copy (snapshot) of one field of one document in one locale, listed in the version history. |
|
|
93
123
|
| 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. |
|
|
94
124
|
| Viewer | Someone in a room who can read the document but not update it. Viewers see changes live but cannot type. |
|
|
95
125
|
|
|
96
126
|
## Screens
|
|
97
127
|
|
|
98
|
-
| Screen | Where
|
|
99
|
-
| ------------------------------ |
|
|
100
|
-
| Editor field | Content Manager, edit view
|
|
101
|
-
| Version history | Clock button in the editor toolbar of a saved document
|
|
102
|
-
| Find and replace | Magnifier button, or Ctrl/Cmd+Shift+F in the editor
|
|
103
|
-
| Quality checks | Seal button in the editor toolbar (the number counts problems)
|
|
104
|
-
| Keyboard shortcuts, focus mode | More (…) button, or Ctrl/Cmd+/
|
|
105
|
-
| Field options | Content-Type Builder, Magic Editor X field, Basic and Advanced settings
|
|
106
|
-
| AI assistant | Inline toolbar (select text)
|
|
107
|
-
|
|
|
108
|
-
|
|
|
128
|
+
| Screen | Where | Who can open it |
|
|
129
|
+
| ------------------------------ | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
130
|
+
| 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). |
|
|
131
|
+
| Version history | Clock button in the editor toolbar of a saved document | `access` and Content Manager read on the document; saving, naming and restoring need update. |
|
|
132
|
+
| Find and replace | Magnifier button, or Ctrl/Cmd+Shift+F in the editor | Everyone who can read the field; replacing needs update. |
|
|
133
|
+
| Quality checks | Seal button in the editor toolbar (the number counts problems) | Everyone who can read the field; the link check needs `access`. |
|
|
134
|
+
| Keyboard shortcuts, focus mode | More (…) button, or Ctrl/Cmd+/ | Everyone who can read the field. |
|
|
135
|
+
| Field options | Content-Type Builder, Magic Editor X field, Basic and Advanced settings | Content-Type Builder access (development mode). |
|
|
136
|
+
| AI assistant | Inline toolbar (select text) | `access` and `ai.use`, when an administrator turned the assistant on. |
|
|
137
|
+
| AI for the whole field | More (…) button > 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. |
|
|
138
|
+
| Comments panel | Comments button in the editor toolbar (shows the open-thread count), or a block's comment marker | `access`, `comments.read` and Content Manager read on the document; writing needs `comments.write`, deleting others' comments `comments.moderate`. |
|
|
139
|
+
| Insert template | Insert template button in the editor toolbar | `access` and Content Manager read on the type; "Save content as template" and "Save as pattern" need `templates.manage`. |
|
|
140
|
+
| Preview | Preview button in the editor toolbar, or Ctrl/Cmd+Alt+P | Everyone who can read the field, read-only users included. |
|
|
141
|
+
| Grammar check | Check grammar button in the editor toolbar | `access` and `grammar.use`, when the owner turned LanguageTool on. |
|
|
142
|
+
| Configuration | Settings > Magic Editor X > Configuration | `settings.read` (view), `settings.update` (edit). |
|
|
143
|
+
| Custom blocks | Settings > Magic Editor X > Custom blocks | `custom-blocks.manage`. |
|
|
144
|
+
| Templates | Settings > Magic Editor X > Templates (templates, patterns and synced blocks) | `templates.manage`. |
|
|
109
145
|
|
|
110
146
|
## Compatibility
|
|
111
147
|
|
|
@@ -114,7 +150,13 @@ All screenshots use synthetic data.
|
|
|
114
150
|
| 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. |
|
|
115
151
|
| 1.x | 5.x | 22 | No longer developed. |
|
|
116
152
|
|
|
117
|
-
|
|
153
|
+
- `engines.node` is `>=22.0.0 <=26.x.x`; the 2.3 acceptance ran on Node 22.23.1.
|
|
154
|
+
- 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.
|
|
156
|
+
- `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
|
+
- `magic-editor-x/vue` needs Vue 3.5 or later (optional peer `^3.5.0`; it is never installed by the plugin).
|
|
158
|
+
- `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.
|
|
159
|
+
- The GraphQL fields need `@strapi/plugin-graphql`; without it nothing is registered.
|
|
118
160
|
|
|
119
161
|
## Install
|
|
120
162
|
|
|
@@ -152,48 +194,60 @@ After the first start, Super Admins can use everything. Other roles need the plu
|
|
|
152
194
|
|
|
153
195
|
All keys are optional. Infrastructure options live in `config/plugins`; the AI provider is edited at runtime in Settings > Magic Editor X > Configuration.
|
|
154
196
|
|
|
155
|
-
| Key
|
|
156
|
-
|
|
|
157
|
-
| `debug`
|
|
158
|
-
| `rawHtml`
|
|
159
|
-
| `sanitizeOnSave`
|
|
160
|
-
| `encryptionKey`
|
|
161
|
-
| `uploads.maxImageBytes`
|
|
162
|
-
| `uploads.maxFileBytes`
|
|
163
|
-
| `linkPreview.enabled`
|
|
164
|
-
| `linkPreview.timeoutMs`
|
|
165
|
-
| `api.autoParseJSON`
|
|
166
|
-
| `ai.allowPrivateBaseUrl`
|
|
167
|
-
| `ai.apiKey`
|
|
168
|
-
| `ai.requestsPerMinute`
|
|
169
|
-
| `ai.timeoutMs`
|
|
170
|
-
| `
|
|
171
|
-
| `
|
|
172
|
-
| `
|
|
173
|
-
| `collaboration.
|
|
174
|
-
| `collaboration.
|
|
175
|
-
| `collaboration.
|
|
176
|
-
| `collaboration.
|
|
177
|
-
| `collaboration.
|
|
178
|
-
| `collaboration.
|
|
179
|
-
| `collaboration.
|
|
180
|
-
| `collaboration.
|
|
181
|
-
| `collaboration.
|
|
182
|
-
| `collaboration.
|
|
183
|
-
| `
|
|
184
|
-
| `
|
|
185
|
-
| `
|
|
186
|
-
| `
|
|
187
|
-
| `
|
|
188
|
-
| `
|
|
197
|
+
| Key | Type | Default | Effect |
|
|
198
|
+
| --------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
199
|
+
| `debug` | boolean | `false` | Writes debug log lines (never content or personal data). |
|
|
200
|
+
| `rawHtml` | `'sanitize'` \| `'allow'` \| `'disable'` | `'sanitize'` | Raw HTML block on save: `sanitize` removes scripts, event handlers, iframes and unsafe URLs; `allow` stores the HTML as typed; `disable` empties it. |
|
|
201
|
+
| `sanitizeOnSave` | boolean | `true` | Normalise and sanitise Magic Editor X values on every Document Service write. Turning this off is not recommended. |
|
|
202
|
+
| `encryptionKey` | string (32+ characters) | unset | Key for the stored AI provider key. Prefer the `MAGIC_EDITOR_X_ENCRYPTION_KEY` environment variable. |
|
|
203
|
+
| `uploads.maxImageBytes` | integer | `10485760` (10 MiB) | Largest image accepted by file or URL (hard cap 500 MiB). |
|
|
204
|
+
| `uploads.maxFileBytes` | integer | `20971520` (20 MiB) | Largest attachment. |
|
|
205
|
+
| `linkPreview.enabled` | boolean | `true` | Link preview cards. When `false`, `GET /magic-editor-x/link` answers 404. |
|
|
206
|
+
| `linkPreview.timeoutMs` | integer | `8000` | Time limit for fetching a page (1000 to 30000). |
|
|
207
|
+
| `api.autoParseJSON` | boolean | `true` | Turn 1.x JSON strings into objects in Content API GET responses. |
|
|
208
|
+
| `ai.allowPrivateBaseUrl` | boolean | `false` | Allow AI base URLs on loopback or private networks (for local models). Owner decision; not editable in the admin. |
|
|
209
|
+
| `ai.apiKey` | string | unset | Provider key from the environment. When set it wins over a key stored in the settings. |
|
|
210
|
+
| `ai.requestsPerMinute` | integer | `20` | AI requests per admin per minute, shared by all processes. |
|
|
211
|
+
| `ai.timeoutMs` | integer | `60000` | Time limit for one provider request. |
|
|
212
|
+
| `languageTool.allowPrivateBaseUrl` | boolean | `false` | Allow a LanguageTool base URL on loopback or private networks (self-hosted server in the LAN). Owner decision. |
|
|
213
|
+
| `languageTool.requestsPerMinute` | integer | `30` | Grammar checks per admin per minute, shared by all processes. |
|
|
214
|
+
| `languageTool.timeoutMs` | integer | `20000` | Time limit for one LanguageTool request. |
|
|
215
|
+
| `collaboration.enabled` | boolean | `true` | Live collaboration and its Socket.IO server. |
|
|
216
|
+
| `collaboration.path` | string | `'/magic-editor-x/realtime'` | Socket.IO path on the Strapi HTTP server. |
|
|
217
|
+
| `collaboration.allowedOrigins` | string[] | `[]` | Extra browser origins allowed to open the socket. The admin URL and the server URL are always allowed. |
|
|
218
|
+
| `collaboration.pollIntervalMs` | integer | `400` | How often each process reads updates written by other processes (50 to 10000). |
|
|
219
|
+
| `collaboration.roomTtlMinutes` | integer | `30` | Keep a room's live state this long after the last person left. |
|
|
220
|
+
| `collaboration.maxMessageBytes` | integer | `2097152` (2 MiB) | Largest accepted socket message. |
|
|
221
|
+
| `collaboration.snapshotIntervalMinutes` | integer | `10` | Automatic version while people edit live. `0` turns it off. |
|
|
222
|
+
| `collaboration.tokenTtlSeconds` | integer | `60` | Lifetime of the one-time token that opens the socket. |
|
|
223
|
+
| `collaboration.maxConnectionsPerAdmin` | integer | `20` | Open live sockets per admin across all processes. |
|
|
224
|
+
| `collaboration.maxRoomsPerAdmin` | integer | `20` | Different fields one admin may have open live at the same time, across all processes. |
|
|
225
|
+
| `collaboration.revalidateSeconds` | integer | `60` | Full permission re-check of open sockets. Role, permission and user changes are applied within about a second anyway. |
|
|
226
|
+
| `collaboration.rateLimit` | object | `{ sessionsPerMinute: 60, updatesPer10s: 300, bytesPer10s: 8388608 }` | Session tokens per admin and minute (shared by all processes), updates and update bytes per socket in 10 seconds. |
|
|
227
|
+
| `collaboration.compaction` | object | `{ enabled: true, idleSeconds: 60, minBytes: 262144, ratio: 4, checkIntervalSeconds: 30 }` | Rebuilds an idle room whose live state is `ratio` times larger than a fresh copy (and at least `minBytes`) as a new generation, once across all processes. Open editors switch without reconnecting; edits that had not reached the server yet are kept. Bounds: `idleSeconds` 15 to 86400, `minBytes` 1 KiB to 512 MiB, `ratio` 1.5 to 1000, `checkIntervalSeconds` 1 to 3600. |
|
|
228
|
+
| `history.maxSnapshotsPerField` | integer | `50` | Versions kept per field and locale; older ones are deleted. |
|
|
229
|
+
| `comments.enabled` | boolean | `true` | Block comments in the editor. `false` hides them and the comment routes answer 404. |
|
|
230
|
+
| `comments.perMinute` | integer | `30` | New comments and replies one admin may post per minute, shared by all processes (1 to 1000). |
|
|
231
|
+
| `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
|
+
| `qualityChecks.externalLinks` | object | `{ enabled: false, timeoutMs: 5000, perMinute: 30 }` | External link check of the quality panel; keys below. |
|
|
233
|
+
| `qualityChecks.externalLinks.enabled` | boolean | `false` | Lets the quality panel check external links (outgoing requests through the SSRF-protected fetcher; owner opt-in). |
|
|
234
|
+
| `qualityChecks.externalLinks.timeoutMs` | integer | `5000` | Time limit per request and per redirect hop (1000 to 15000). |
|
|
235
|
+
| `qualityChecks.externalLinks.perMinute` | integer | `30` | External URLs one admin may check per minute, shared by all processes. |
|
|
236
|
+
| `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
|
+
| `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
|
+
| `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). |
|
|
240
|
+
| `qualityChecks.externalLinks.schedule.maxUrlsPerRun` | integer | `500` | Distinct URLs checked per run (1 to 10000). |
|
|
241
|
+
| `qualityChecks.externalLinks.schedule.perMinute` | integer | `60` | Requests per minute for the whole run (1 to 600). |
|
|
242
|
+
| `qualityChecks.externalLinks.schedule.perHostConcurrency` | integer | `2` | Requests in flight per host (1 to 8). |
|
|
189
243
|
|
|
190
244
|
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).
|
|
191
245
|
|
|
192
246
|
### Environment variables
|
|
193
247
|
|
|
194
|
-
| Name | Required
|
|
195
|
-
| ------------------------------- |
|
|
196
|
-
| `MAGIC_EDITOR_X_ENCRYPTION_KEY` | Only to store an AI key in the settings | unset | 32 or more characters. Encrypts the AI provider key (AES-256-GCM). Without it the settings page cannot store a key; you can still pass one with `ai.apiKey`. Generate one with `node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"`. Keep it stable: a different key makes a stored provider key unreadable, and the settings page then asks you to enter it again. |
|
|
248
|
+
| Name | Required | Default | Effect |
|
|
249
|
+
| ------------------------------- | ------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
250
|
+
| `MAGIC_EDITOR_X_ENCRYPTION_KEY` | Only to store an AI or LanguageTool key in the settings | unset | 32 or more characters. Encrypts the AI provider key and the LanguageTool key (AES-256-GCM). Without it the settings page cannot store a key; you can still pass one with `ai.apiKey`. Generate one with `node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"`. Keep it stable: a different key makes a stored provider key unreadable, and the settings page then asks you to enter it again. |
|
|
197
251
|
|
|
198
252
|
The plugin also uses Strapi's own `admin.auth.secret` (`ADMIN_JWT_SECRET`) to sign collaboration tokens. Every process of a cluster must use the same value.
|
|
199
253
|
|
|
@@ -201,15 +255,19 @@ The plugin also uses Strapi's own `admin.auth.secret` (`ADMIN_JWT_SECRET`) to si
|
|
|
201
255
|
|
|
202
256
|
Settings > Magic Editor X > Configuration stores these values in the Strapi store:
|
|
203
257
|
|
|
204
|
-
| Setting
|
|
205
|
-
|
|
|
206
|
-
| Enabled
|
|
207
|
-
| Provider
|
|
208
|
-
| Base URL
|
|
209
|
-
| Model
|
|
210
|
-
| API key
|
|
211
|
-
| Max input characters
|
|
212
|
-
| Max output tokens
|
|
258
|
+
| Setting | Default | Range |
|
|
259
|
+
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
|
260
|
+
| Enabled | off | |
|
|
261
|
+
| Provider | `anthropic` | `anthropic`, `openai`, `openai-compatible` |
|
|
262
|
+
| Base URL | provider default (`https://api.anthropic.com`, `https://api.openai.com`); required for `openai-compatible` | https, or private hosts when `ai.allowPrivateBaseUrl` is on |
|
|
263
|
+
| Model | `claude-opus-5-5` (Anthropic), `gpt-6-luna` (OpenAI) | letters, digits and `._:/@-` |
|
|
264
|
+
| API key | none | never returned; changing the provider or base URL requires entering it again |
|
|
265
|
+
| Max input characters | 8000 | 200 to 50000 |
|
|
266
|
+
| Max output tokens | 4096 | 64 to 16000 |
|
|
267
|
+
| Send images to the AI provider (`ai.allowImages`) | off | Allows alternative text suggestions; see [AI assistant](#ai-assistant) |
|
|
268
|
+
| Allow whole-field AI actions (`ai.allowFieldActions`) | off | Allows translate and summarize of a whole field |
|
|
269
|
+
|
|
270
|
+
The same page has a **Grammar check (LanguageTool)** section; see [Grammar check (LanguageTool)](#grammar-check-languagetool). It also shows the scheduled link check read-only (rule, budget and the last run).
|
|
213
271
|
|
|
214
272
|
## Live collaboration
|
|
215
273
|
|
|
@@ -244,9 +302,11 @@ How it works:
|
|
|
244
302
|
- Presence is stored in `magic_editor_x_collab_presence` with heartbeats; leases and one-time keys in `magic_editor_x_locks`. Seeding a room, compaction, automatic versions and cleanup each run once across all processes.
|
|
245
303
|
- Every process keeps the active rooms in memory, checks every update before it is stored (only the structures the editor uses, every dependency present, every touched block valid within the content limits) and relays it.
|
|
246
304
|
- Clients resynchronise their state every 20 seconds and after each reconnect, so a process restart or deploy loses nothing that was acknowledged.
|
|
247
|
-
- Permission changes set a signal in `magic_editor_x_locks` that every process checks every second. Session and
|
|
305
|
+
- Permission changes set a signal in `magic_editor_x_locks` that every process checks every second. Session, AI, link check, comment and grammar check rate limits are counted in `magic_editor_x_counters`, so they apply to the whole cluster.
|
|
306
|
+
- Every process fires the scheduled link check; a one-time key and a lease in `magic_editor_x_locks` let exactly one process run it. Its results are stored in `magic_editor_x_link_fields` and `magic_editor_x_link_urls`.
|
|
307
|
+
- Comments are read from the database (polled every 15 seconds while the field is visible, 8 seconds with the panel open), so they appear on every process.
|
|
248
308
|
|
|
249
|
-
The plugin creates these
|
|
309
|
+
The plugin creates these tables on startup. They are not content types, so Strapi's schema sync leaves them alone. Comments, templates and versions are content types of the plugin, hidden from the Content Manager.
|
|
250
310
|
|
|
251
311
|
Behind a proxy, also set `server.proxy` in `config/server` (`koa: true` and the number of trusted hops in `maxIpsCount`) so Strapi sees the real client address.
|
|
252
312
|
|
|
@@ -268,6 +328,36 @@ The assistant is off until an administrator turns it on in Settings > Magic Edit
|
|
|
268
328
|
- 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.
|
|
269
329
|
- 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.
|
|
270
330
|
|
|
331
|
+
### Alternative text and whole-field actions
|
|
332
|
+
|
|
333
|
+
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.
|
|
334
|
+
|
|
335
|
+
| Feature | Owner switch | What is sent | Result |
|
|
336
|
+
| ---------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
337
|
+
| Alternative text | Send images to the AI provider (`ai.allowImages`) | One Media Library image (the largest stored size with a long edge up to 1568 px and at most 3.5 MB; JPEG, PNG, GIF or WebP) and the content language | "Suggest alternative text" on image blocks and on every gallery image; plain text up to 150 characters that the editor reviews and uses with "Use suggestion". Needs Media Library read on the file (404 otherwise). |
|
|
338
|
+
| 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
|
+
|
|
340
|
+
- 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.
|
|
341
|
+
- 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
|
+
- `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
|
+
|
|
344
|
+
## Grammar check (LanguageTool)
|
|
345
|
+
|
|
346
|
+
Editors with `grammar.use` can check the spelling and grammar of a whole field with "Check grammar" in the editor toolbar. Issues are highlighted in the text; a suggested replacement is applied only when the flagged text is still there and lies in one piece of text (not across formatting or a line break). The check is not AI: `disableAi` does not affect it. To keep a field's text away from LanguageTool, turn on `disableGrammar` in its field settings: the field shows no "Check grammar" button and `POST /magic-editor-x/grammar/check` answers 403 for it, so nothing from it is sent.
|
|
347
|
+
|
|
348
|
+
It is off until an owner configures it in Settings > Magic Editor X > Configuration > **Grammar check (LanguageTool)**:
|
|
349
|
+
|
|
350
|
+
| Setting | Default | Notes |
|
|
351
|
+
| ------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
352
|
+
| Turn on the grammar check | off | Nothing is sent while it is off or until an editor starts a check. |
|
|
353
|
+
| LanguageTool base URL | empty | Your own server or a hosted service, for example `https://languagetool.example.com`; requests go to `<base URL>/v2/check`. Public https only, unless `languageTool.allowPrivateBaseUrl` is on. |
|
|
354
|
+
| User name, API key | empty | Only for hosted accounts. The key is encrypted with `MAGIC_EDITOR_X_ENCRYPTION_KEY` (own key derivation), never returned, and must be entered again when the base URL or user name change. |
|
|
355
|
+
| Rules | Standard | Standard or Strict (`level=picky`, adds style rules). |
|
|
356
|
+
|
|
357
|
+
- **Test LanguageTool** checks a fixed sample sentence (`POST /magic-editor-x/settings/language-tool/test`); a test against another URL never receives the stored key.
|
|
358
|
+
- What is sent: the plain text of every block in the field and the language of the content locale (`en` becomes `en-US`, `de` `de-DE`, `pt` `pt-PT`; without a locale `auto`). Up to 60,000 characters per check in requests of at most 20,000; longer fields answer 413. At most 500 issues are shown.
|
|
359
|
+
- `languageTool.requestsPerMinute` limits checks per admin, shared by all processes; `languageTool.timeoutMs` limits one request.
|
|
360
|
+
|
|
271
361
|
## Field presets
|
|
272
362
|
|
|
273
363
|
Each Magic Editor X field can have its own rules, set in the Content-Type Builder (field settings). They are stored as custom field options in the schema and enforced in three places with the same code (`shared/presets.mjs`): the editor offers only what the field allows, the realtime server refuses new blocks a preset does not allow, and every write (Content Manager, Content API, imports, code) is checked by the Document Service middleware.
|
|
@@ -282,15 +372,16 @@ Each Magic Editor X field can have its own rules, set in the Content-Type Builde
|
|
|
282
372
|
| `maxBlocks` | Advanced | number, empty or 0 = no limit | Block limit, shown in the toolbar (`12 / 20 blocks`). |
|
|
283
373
|
| `maxCharacters` | Advanced | number, empty or 0 = no limit | Visible characters, counted like the toolbar (`380 / 400 characters`). |
|
|
284
374
|
| `disableAi` | Advanced | checkbox | No AI button in this field; the AI route answers 403 for requests from it. |
|
|
375
|
+
| `disableGrammar` | Advanced | checkbox | No "Check grammar" button in this field; the grammar route answers 403, so its text is never sent to LanguageTool. |
|
|
285
376
|
| `disableCollaboration` | Advanced | checkbox | No live editing in this field (the session route answers 403). |
|
|
286
377
|
| `publishGuard` | Advanced | checkbox | Publishing is refused while the [quality checks](#quality-checks) report errors in this field. |
|
|
287
378
|
|
|
288
|
-
| Preset | Blocks
|
|
289
|
-
| --------- |
|
|
290
|
-
| `full` | all, custom blocks included
|
|
291
|
-
| `article` | paragraph, header, list, checklist, quote, warning, alert, toggle, code, codeFlask, delimiter, table, embed, image (and the Media Library picker), linkTool, attaches, button | all | H2-H4 |
|
|
292
|
-
| `basic` | paragraph, header, list, quote, image, delimiter
|
|
293
|
-
| `minimal` | paragraph, list
|
|
379
|
+
| Preset | Blocks | Inline tools | Headings |
|
|
380
|
+
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | -------- |
|
|
381
|
+
| `full` | all, custom blocks included | all | H1-H6 |
|
|
382
|
+
| `article` | paragraph, header, list, checklist, quote, warning, alert, toggle, code, codeFlask, delimiter, toc, synced, table, embed, image (and the Media Library picker), gallery, video, audio, linkTool, attaches, button, and code-registered blocks that list `article` | all | H2-H4 |
|
|
383
|
+
| `basic` | paragraph, header, list, quote, image, delimiter | bold, italic, underline, strikethrough, link | H2-H3 |
|
|
384
|
+
| `minimal` | paragraph, list | bold, italic, link | none |
|
|
294
385
|
|
|
295
386
|
How the rules apply:
|
|
296
387
|
|
|
@@ -310,9 +401,49 @@ Changing a preset never changes stored content by itself. Turning `sanitizeOnSav
|
|
|
310
401
|
| Focus mode | More > Focus mode: full screen, narrower text column, other blocks dimmed. Escape leaves. |
|
|
311
402
|
| 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. |
|
|
312
403
|
| Counts | Blocks, words, characters and reading time (200 words per minute) in the toolbar, with the field's limits. |
|
|
313
|
-
| Alternative text | Image and image-by-URL blocks: "Alternative text" field (prefilled from the Media Library) and "Decorative image (no alternative text)". Required when the field has `requireAlt`.
|
|
404
|
+
| 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)). |
|
|
405
|
+
| 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. |
|
|
406
|
+
| Mentions | Select text and press the Mention button or Ctrl/Cmd+Shift+2: the internal-link picker opens with the selection as search text and 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`). |
|
|
407
|
+
| 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. |
|
|
408
|
+
| 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. |
|
|
409
|
+
| 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. |
|
|
314
410
|
| 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. |
|
|
315
411
|
|
|
412
|
+
## Templates, patterns and synced blocks
|
|
413
|
+
|
|
414
|
+
Settings > Magic Editor X > **Templates** (permission `templates.manage`) holds three kinds of reusable content, each with a name, an optional description, its blocks (edited in an embedded editor), a scope and an on/off switch:
|
|
415
|
+
|
|
416
|
+
| Kind | Stored as | In the editor |
|
|
417
|
+
| ------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
418
|
+
| Template | `kind: 'template'` | "Insert template" replaces the field content (with a confirmation when the field is not empty; Undo brings it back). |
|
|
419
|
+
| Pattern | `kind: 'pattern'` | Inserted after the block you worked on last (or into an empty field). |
|
|
420
|
+
| Synced block | `kind: 'synced'` | Inserted as a reference. The field stores `{ type: 'synced', data: { ref } }` and shows the current content of the source; a change to the source appears in every field that uses it. |
|
|
421
|
+
|
|
422
|
+
- **Scope:** every Magic Editor X field, or only fields with chosen presets and chosen fields. The "Insert template" dialog lists the enabled entries whose scope covers the field (searchable, with a preview).
|
|
423
|
+
- **Field rules apply:** blocks the field's preset does not allow are left out, heading levels and links are fixed like "Fix automatically", `maxBlocks` cuts the list, and every inserted block gets a new id. The dialog says how many blocks were left out or adjusted.
|
|
424
|
+
- **Saving from the editor:** managers can save the whole field ("Save content as template" in the dialog) or the selected blocks ("Save as pattern" in the block selection bar).
|
|
425
|
+
- **Limits:** 1 to 200 blocks and 256 KiB per entry, at most 500 entries. Blocks are cleaned with the same sanitiser as field values on every write; raw HTML is sanitised (or emptied when `rawHtml` is `disable`), never stored as typed.
|
|
426
|
+
|
|
427
|
+
Synced blocks in detail:
|
|
428
|
+
|
|
429
|
+
- In the editor a synced block shows "Synced block:" with the source name and the rendered source. **Edit source** (only with `templates.manage`) opens it in Settings; **Detach** replaces the reference with a copy of the blocks, which then become normal content of the field (one undo step). A deleted source shows "Synced block removed" and renders nothing.
|
|
430
|
+
- 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
|
+
- 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
|
+
- 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".
|
|
433
|
+
- 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
|
+
- 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
|
+
|
|
436
|
+
## Comments
|
|
437
|
+
|
|
438
|
+
Reviewers and editors can discuss single blocks without changing the content. The Comments button in the editor toolbar shows the number of open threads and opens the panel; each block with open threads gets a marker at its end.
|
|
439
|
+
|
|
440
|
+
- 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.
|
|
441
|
+
- 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.
|
|
443
|
+
- 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
|
+
- Deleting a document locale deletes its comments. Deleting an admin keeps their comments and shows them as "Deleted user". `comments.enabled: false` hides comments and the routes answer 404.
|
|
446
|
+
|
|
316
447
|
## Paste, import and migration
|
|
317
448
|
|
|
318
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.
|
|
@@ -328,15 +459,17 @@ Options: `--format auto|blocks|markdown|html` (auto: Blocks fields as Strapi Blo
|
|
|
328
459
|
|
|
329
460
|
## Version history
|
|
330
461
|
|
|
331
|
-
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)
|
|
462
|
+
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`).
|
|
332
463
|
|
|
333
464
|
## Quality checks
|
|
334
465
|
|
|
335
466
|
The seal button opens the quality panel; its number counts problems. It never blocks editing.
|
|
336
467
|
|
|
337
|
-
- **Accessibility lint** (`shared/quality.mjs`): 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,
|
|
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.
|
|
338
469
|
- **Field settings:** content that breaks the field's [preset](#field-presets), with automatic fixes.
|
|
339
|
-
- **Check links** (`POST /magic-editor-x/quality/links`): internal links (entries you cannot read answer "Not checked", so nothing is revealed; "Not published" for drafts of Draft & Publish types), Media Library files (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.
|
|
470
|
+
- **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.
|
|
472
|
+
- **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.
|
|
340
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.
|
|
341
474
|
|
|
342
475
|
## Data format
|
|
@@ -361,32 +494,41 @@ The field stores an Editor.js document as JSON:
|
|
|
361
494
|
|
|
362
495
|
Data of each block type as stored after sanitising (`shared/sanitize-policy.mjs`):
|
|
363
496
|
|
|
364
|
-
| Block | `data`
|
|
365
|
-
| --------------------------- |
|
|
366
|
-
| `paragraph` | `{ text }` (inline HTML)
|
|
367
|
-
| `header` | `{ text, level: 1-6 }`
|
|
368
|
-
| `list` | `{ style: 'ordered' \| 'unordered' \| 'checklist', meta?: { start?, counterType? }, items: [{ content, meta?, items: [...] }] }`
|
|
369
|
-
| `checklist` | `{ items: [{ text, checked }] }`
|
|
370
|
-
| `quote` | `{ text, caption, alignment: 'left' \| 'center' }`
|
|
371
|
-
| `warning` | `{ title, message }`
|
|
372
|
-
| `alert` | `{ type: 'primary' \| 'secondary' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'light' \| 'dark', align: 'left' \| 'center' \| 'right', message }`
|
|
373
|
-
| `toggle` | `{ text, status: 'open' \| 'closed', fk?, items }` (the next `items` blocks are its content)
|
|
374
|
-
| `code` | `{ code }` (plain text)
|
|
375
|
-
| `codeFlask` | `{ code, language, showlinenumbers? }`
|
|
376
|
-
| `raw` | `{ html }` (see `rawHtml`)
|
|
377
|
-
| `table` | `{ withHeadings, stretched, content: string[][] }`
|
|
378
|
-
| `image` | `{ file: { url, mime?, alt?, width?, height?, size?, formats?, id?, documentId? }, caption, withBorder, withBackground, stretched, decorative? }` (`id`/`documentId` reference the Media Library file, `formats` its responsive sizes; `decorative: true` = intentionally empty alternative text) |
|
|
379
|
-
| `
|
|
380
|
-
| `
|
|
381
|
-
| `
|
|
382
|
-
| `
|
|
383
|
-
| `
|
|
384
|
-
| `
|
|
385
|
-
| `
|
|
386
|
-
|
|
|
387
|
-
|
|
|
388
|
-
|
|
389
|
-
|
|
497
|
+
| Block | `data` |
|
|
498
|
+
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
499
|
+
| `paragraph` | `{ text }` (inline HTML) |
|
|
500
|
+
| `header` | `{ text, level: 1-6 }` |
|
|
501
|
+
| `list` | `{ style: 'ordered' \| 'unordered' \| 'checklist', meta?: { start?, counterType? }, items: [{ content, meta?, items: [...] }] }` |
|
|
502
|
+
| `checklist` | `{ items: [{ text, checked }] }` |
|
|
503
|
+
| `quote` | `{ text, caption, alignment: 'left' \| 'center' }` |
|
|
504
|
+
| `warning` | `{ title, message }` |
|
|
505
|
+
| `alert` | `{ type: 'primary' \| 'secondary' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'light' \| 'dark', align: 'left' \| 'center' \| 'right', message }` |
|
|
506
|
+
| `toggle` | `{ text, status: 'open' \| 'closed', fk?, items }` (the next `items` blocks are its content) |
|
|
507
|
+
| `code` | `{ code }` (plain text) |
|
|
508
|
+
| `codeFlask` | `{ code, language, showlinenumbers? }` |
|
|
509
|
+
| `raw` | `{ html }` (see `rawHtml`) |
|
|
510
|
+
| `table` | `{ withHeadings, stretched, content: string[][] }` |
|
|
511
|
+
| `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
|
+
| `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
|
+
| `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) |
|
|
514
|
+
| `audio` (2.3) | `{ file, title, caption, loop, tracks }` (`file` must be `audio/*`) |
|
|
515
|
+
| video/audio `tracks` | `[{ file, kind: 'captions' \| 'subtitles' \| 'descriptions' \| 'chapters', srclang, label, default? }]` (at most 8, WebVTT files only, at most one `default`) |
|
|
516
|
+
| `toc` (2.3) | `{ title, minLevel: 1-6 (default 2), maxLevel: 1-6 (default 4), style: 'ordered' \| 'unordered' }` (only the settings are stored; the entries are built from the headings when rendering) |
|
|
517
|
+
| `synced` (2.3) | `{ ref }` (the `documentId` of a synced source, or `''` when invalid; nothing else is stored) |
|
|
518
|
+
| `simpleImage` | `{ url, caption, withBorder, withBackground, stretched, alt?, decorative? }` |
|
|
519
|
+
| `linkTool` | `{ link, meta: { title, description, site_name?, image?: { url } } }` |
|
|
520
|
+
| `attaches` | `{ file: { url, name?, extension?, size?, title? }, title }` |
|
|
521
|
+
| `embed` | `{ service, source, embed, width?, height?, caption }` (`embed` is always https) |
|
|
522
|
+
| `personality` | `{ name, description, link, photo }` |
|
|
523
|
+
| `button` | `{ text, link, style, openInNewTab }` |
|
|
524
|
+
| `delimiter` | `{}` |
|
|
525
|
+
| custom simple block | `{ content, <field values>, blockType: 'simple', blockName }` |
|
|
526
|
+
| custom embedded-entry block | `{ entry: { id, documentId, title, <display fields> }, contentType, displayMode }` |
|
|
527
|
+
| 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
|
+
|
|
529
|
+
Blocks `toc`, `gallery`, `video`, `audio` and `synced` (2.3) 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`.
|
|
530
|
+
|
|
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`. Links allow `http`, `https`, `mailto`, `tel` and relative URLs. Escape plain-text fields (`code`, `personality`, `button.text`, link card text) when you render them.
|
|
390
532
|
|
|
391
533
|
### Internal links
|
|
392
534
|
|
|
@@ -404,6 +546,7 @@ The link tool (`CMD+K`) has a **Link to an entry** button: choose a content type
|
|
|
404
546
|
|
|
405
547
|
- `href` is always a normal URL, so every frontend can render the link as it is. It is built on the server from `links.urlPattern` when the link is inserted: `{documentId}`, `{locale}` (empty for types without i18n; empty path segments are removed), `{slug}` (the first `uid` attribute of the type, or the documentId when there is none), `{collection}` (plural API name) and `{singular}` (singular API name). Values are URL-encoded. The pattern must be a site-relative path or an `http(s)` URL with a fixed host. Without a pattern the link is `/{collection}/{documentId}`.
|
|
406
548
|
- `data-mex-uid`, `data-mex-document-id` and `data-mex-locale` identify the entry, so a frontend can resolve the current URL itself (for example when a slug changed after the link was inserted). They are kept only when they are valid and only on `<a>`; a link whose address you edit by hand becomes a normal link.
|
|
549
|
+
- **Mentions** are internal links with `data-mex-mention="true"`; their text is the entry title at the time of insertion. Everything above applies to them (presets, link check, `resolveHrefs`, API output); renderers add `class="mex-mention"`, and the `links` resolver receives `mention: true`.
|
|
407
550
|
- **Links follow slug changes** because the entry reference is stored, not only the URL: render with `renderHtml(value, { links: ({ uid, documentId, locale, href }) => urlFor(uid, documentId, locale) })` (see [Rendering content](#rendering-content)), or in server code `await strapi.plugin('magic-editor-x').service('links').resolveHrefs(value, { status: 'published' })`, which re-renders every internal `href` from `links.urlPattern` and the entry's current slug (one query per type and locale; links to deleted entries keep their stored `href`; it does not check admin permissions, so use it for content the caller may already see).
|
|
408
551
|
|
|
409
552
|
Tunes are stored per block in `tunes`: `alignmentTune: { alignment }`, `textVariant: '' | 'call-out' | 'citation' | 'details'`, `indentTune: { indentLevel }`.
|
|
@@ -431,20 +574,141 @@ const markdown = renderMarkdown(entry.body); // feeds, LLM context, export
|
|
|
431
574
|
- **Deterministic:** the same value always gives the same string.
|
|
432
575
|
- **Schema:** `magic-editor-x/schema` is a JSON Schema (draft 2020-12) of the stored value with one data schema per block type; validate content in CI. **Types:** `import type { MagicEditorXData, MagicEditorXBlock } from 'magic-editor-x/types'`.
|
|
433
576
|
|
|
434
|
-
|
|
577
|
+
### Options added in 2.3
|
|
578
|
+
|
|
579
|
+
All are off or neutral by default, so `renderHtml` output for existing content is the same as in 2.2 unless the value has a table of contents.
|
|
580
|
+
|
|
581
|
+
| Option | Values | Effect |
|
|
582
|
+
| ------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
583
|
+
| `code` | `{ lineNumbers?: boolean \| 'block', copyButton?: boolean \| { label, copiedLabel, failedLabel } }` | Line numbers (`<span class="mex-code-line">` per line, numbers from CSS counters; `'block'` follows the block's own setting) and a copy button with a polite status region. Call `enhanceCodeBlocks()` in the browser to wire the buttons of server-rendered HTML. |
|
|
584
|
+
| `focalPoint` | `'data'` (default) \| `'style'` | `data-mex-focal-x`/`data-mex-focal-y` on `<img>` (no inline style, works under a strict CSP), or also `style="object-position:X% Y%"`. |
|
|
585
|
+
| `headingIds` | `true` \| `false` | `id="mex-h-<blockId>"` on headings. Default: only when the value has a `toc` block. The anchor is the block id, so it survives text edits, reordering and translated locales. |
|
|
586
|
+
| `toc` | `{ label? }` | `aria-label` of a table of contents without a title (default "Table of contents"). |
|
|
587
|
+
| `blocks` | array of `defineBlock` definitions | Blocks defined in code (see [Custom blocks in code (SDK)](#custom-blocks-in-code-sdk)). |
|
|
588
|
+
| `synced` | `{ [ref]: document \| blocks }`, a `Map`, or `(ref) => document \| blocks \| null` | Sources of synced blocks. Without it, or for an unknown `ref`, a synced block renders nothing. The copies are cleaned and rendered like any block, and a table of contents lists their headings. |
|
|
589
|
+
|
|
590
|
+
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
|
+
|
|
592
|
+
`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
|
+
|
|
594
|
+
```js
|
|
595
|
+
import { renderHtml } from 'magic-editor-x/render';
|
|
596
|
+
|
|
597
|
+
const html = renderHtml(entry.body, {
|
|
598
|
+
synced: (ref) => sources.get(ref) ?? null, // sources you loaded, for example from ?mex=json
|
|
599
|
+
code: { lineNumbers: 'block', copyButton: true },
|
|
600
|
+
focalPoint: 'style',
|
|
601
|
+
});
|
|
602
|
+
```
|
|
603
|
+
|
|
604
|
+
### React and Vue components
|
|
605
|
+
|
|
606
|
+
`magic-editor-x/react` and `magic-editor-x/vue` export `MagicEditorXContent`, built on the same render tree as `renderHtml`: text stays text, URLs are validated, and `dangerouslySetInnerHTML`/`innerHTML` is used only for raw HTML blocks you opt in to with `rawHtml: 'allow'` and `sanitizeRaw`.
|
|
607
|
+
|
|
608
|
+
```jsx
|
|
609
|
+
import { MagicEditorXContent } from 'magic-editor-x/react';
|
|
610
|
+
|
|
611
|
+
<MagicEditorXContent
|
|
612
|
+
value={article.content}
|
|
613
|
+
options={{ code: { lineNumbers: 'block', copyButton: true } }}
|
|
614
|
+
components={{ paragraph: ({ children }) => <div className="lead">{children}</div> }}
|
|
615
|
+
/>;
|
|
616
|
+
```
|
|
617
|
+
|
|
618
|
+
- Props: `value`, `options` (every option above) and `components` (per block type, receives `{ block, helpers, children }`; `children` is the default output). Vue also takes scoped slots `block-<type>`, which win over `components`.
|
|
619
|
+
- React 18 and 19, server rendering and React Server Components (the copy button needs a client component or `enhanceCodeBlocks()`); Vue 3.5 or later, also with Nuxt server rendering.
|
|
620
|
+
- Guides: [React](docs/guides/react.md), [Vue and Nuxt](docs/guides/vue-nuxt.md), [Astro](docs/guides/astro.md) (`renderHtml` with `set:html`, or the components as server-rendered islands, plus the CSS for line numbers and copy buttons).
|
|
621
|
+
|
|
622
|
+
## Content API and GraphQL output
|
|
623
|
+
|
|
624
|
+
Without extra parameters the Content API returns the stored value, as in 2.2. Add `?mex=` to a GET request to get the field rendered or resolved instead:
|
|
625
|
+
|
|
626
|
+
| `mex` | Each Magic Editor X field becomes |
|
|
627
|
+
| ---------- | ----------------------------------------------------------------------------------- |
|
|
628
|
+
| `html` | The rendered HTML string (`''` when empty) |
|
|
629
|
+
| `text` | Plain text |
|
|
630
|
+
| `markdown` | Markdown |
|
|
631
|
+
| `json` | The stored document with resolved references (internal links, media, synced blocks) |
|
|
632
|
+
|
|
633
|
+
```http
|
|
634
|
+
GET /api/articles/k9d2w4xq8m1n0p3r5t7v9b1c?mex=text
|
|
635
|
+
Authorization: Bearer <API token>
|
|
636
|
+
```
|
|
637
|
+
|
|
638
|
+
```json
|
|
639
|
+
{
|
|
640
|
+
"data": {
|
|
641
|
+
"documentId": "k9d2w4xq8m1n0p3r5t7v9b1c",
|
|
642
|
+
"title": "Release notes",
|
|
643
|
+
"body": "Release notes\n\nRead our guide.\n\nShared footer"
|
|
644
|
+
},
|
|
645
|
+
"meta": {}
|
|
646
|
+
}
|
|
647
|
+
```
|
|
648
|
+
|
|
649
|
+
- Works on GET requests of Content API routes of `api::` content types (`find`, `findOne` and custom GET actions of the same controller), for fields at the top level, in components, in dynamic zones and in populated relations, in the flat and the `Strapi-Response-Format: v4` response. Admin and plugin routes and error responses are never changed. Any other value answers 400 (`details.param: 'mex'`). `mex` is registered with Strapi's `contentAPI.addQueryParams`, so it also passes with `api.rest.strictParams: true`.
|
|
650
|
+
- References are resolved with the caller's own permissions (API token or users-permissions role): a target entry is read only when the caller has `find` on its type, Media Library files only with the upload plugin's `find`, and every row goes through Strapi's output sanitising. Published versions are used unless the request asks for `status=draft`.
|
|
651
|
+
- Internal links and mentions get the `href` from `links.urlPattern` with the current slug; a resolved mention shows the entry's current title. A link the caller may not see, or that points to a missing or draft-only entry, is removed and only its text stays. Embedded entries (custom blocks) get the live display fields, or `entry: null`. Media Library files get their current URL and formats. Synced blocks are expanded with the containing field's sanitiser and preset; `json` output marks the copied blocks with `syncedFrom`.
|
|
652
|
+
- Raw HTML blocks are left out of `html`, `text` and `markdown`. Heading ids are written in `html` when the value has a table of contents.
|
|
653
|
+
- Bounds: 500 distinct references and 5 seconds per response; at most 100 distinct synced sources per response. References over the limit stay unresolved.
|
|
654
|
+
|
|
655
|
+
**GraphQL** (when `@strapi/plugin-graphql` is installed): for every Magic Editor X attribute `body` of an `api::` content type or component in the schema, the plugin adds `bodyRendered(format: MagicEditorXFormat = HTML): String` (`HTML`, `TEXT`, `MARKDOWN`) and `bodyResolved: JSON`, with the same resolution and permissions. Fields that are private, disabled through `shadowCRUD`, or that would clash with an existing attribute name are skipped.
|
|
656
|
+
|
|
657
|
+
```graphql
|
|
658
|
+
query {
|
|
659
|
+
articles {
|
|
660
|
+
title
|
|
661
|
+
bodyRendered(format: HTML)
|
|
662
|
+
}
|
|
663
|
+
}
|
|
664
|
+
```
|
|
665
|
+
|
|
666
|
+
In server code, `strapi.plugin('magic-editor-x').service('references').transform(items, { format, auth, status })` gives the same output.
|
|
667
|
+
|
|
668
|
+
## Custom blocks in code (SDK)
|
|
669
|
+
|
|
670
|
+
When a block needs real code (its own editor UI, strict data rules or frontend output you control), define it once with `defineBlock` from `magic-editor-x/blocks` and use the definition on the server, in the admin and in your frontend:
|
|
671
|
+
|
|
672
|
+
```js
|
|
673
|
+
import { defineBlock } from 'magic-editor-x/blocks';
|
|
674
|
+
|
|
675
|
+
export const calloutCard = defineBlock({
|
|
676
|
+
name: 'calloutCard',
|
|
677
|
+
title: 'Callout card',
|
|
678
|
+
schema: {
|
|
679
|
+
title: { type: 'text', max: 120 },
|
|
680
|
+
body: { type: 'inline', max: 2000 },
|
|
681
|
+
link: { type: 'url' },
|
|
682
|
+
tone: { type: 'enum', values: ['info', 'success', 'warning'] },
|
|
683
|
+
},
|
|
684
|
+
presets: ['article'],
|
|
685
|
+
});
|
|
686
|
+
```
|
|
687
|
+
|
|
688
|
+
- **Server:** call `strapi.plugin('magic-editor-x').service('blocks').register(calloutCard)` in your app's `register()`. Every save cleans the block with its schema (unknown keys dropped, values bounded, URLs and inline HTML through the same policies as built-in blocks); presets, live collaboration, `?mex=` and GraphQL use it without further wiring. A Settings custom block with the same name stops Strapi from starting (`NAME_TAKEN`).
|
|
689
|
+
- **Admin:** in `src/admin/app.js`, call `app.getPlugin('magic-editor-x').apis.registerBlock({ definition, tool, title?, icon?, i18n?, inlineToolbar?, shortcut? })`; `apis.createReactTool(Component)` turns a React component into an Editor.js tool. Settings > Custom blocks lists code blocks read-only under "Defined in code".
|
|
690
|
+
- **Frontend:** pass `blocks: [calloutCard]` to `renderHtml`, `renderText`, `renderMarkdown` or the React/Vue components; give the definition a `render`, `text` or `markdown` function for your own output, or get a neutral default.
|
|
691
|
+
- Field types: `text`, `inline`, `url`, `enum`, `number`, `boolean`, `array`, `object`. `blockJsonSchema(definition)` returns the JSON Schema of the stored shape.
|
|
692
|
+
|
|
693
|
+
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).
|
|
435
694
|
|
|
436
695
|
## Admin API and permissions
|
|
437
696
|
|
|
438
697
|
### Permissions
|
|
439
698
|
|
|
440
|
-
| Action | Label in Roles | Gates
|
|
441
|
-
| --------------------------------------------- | ----------------------------------------------------------------------- |
|
|
442
|
-
| `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, version history, collaboration and AI routes |
|
|
443
|
-
| `plugin::magic-editor-x.collaborate` | Edit together in real time | Joining live rooms
|
|
444
|
-
| `plugin::magic-editor-x.ai.use` | Use the AI assistant | AI requests
|
|
445
|
-
| `plugin::magic-editor-x.custom-blocks.manage` | Manage custom blocks | Settings > Custom blocks and its routes
|
|
446
|
-
| `plugin::magic-editor-x.settings.read` | Read settings | Settings > Configuration (read)
|
|
447
|
-
| `plugin::magic-editor-x.settings.update` | Update settings | Saving settings, testing the AI connection
|
|
699
|
+
| Action | Label in Roles | Gates |
|
|
700
|
+
| --------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
701
|
+
| `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 |
|
|
702
|
+
| `plugin::magic-editor-x.collaborate` | Edit together in real time | Joining live rooms |
|
|
703
|
+
| `plugin::magic-editor-x.ai.use` | Use the AI assistant | AI requests |
|
|
704
|
+
| `plugin::magic-editor-x.custom-blocks.manage` | Manage custom blocks | Settings > Custom blocks and its routes |
|
|
705
|
+
| `plugin::magic-editor-x.settings.read` | Read settings | Settings > Configuration (read) |
|
|
706
|
+
| `plugin::magic-editor-x.settings.update` | Update settings | Saving settings, testing the AI connection |
|
|
707
|
+
| `plugin::magic-editor-x.comments.read` | Read block comments | Comment threads in the editor (with Content Manager read on the document) |
|
|
708
|
+
| `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) |
|
|
709
|
+
| `plugin::magic-editor-x.comments.moderate` | Moderate block comments | Deleting other people's comments |
|
|
710
|
+
| `plugin::magic-editor-x.grammar.use` | Use the grammar check (LanguageTool) | The "Check grammar" toolbar button and `POST /grammar/check` |
|
|
711
|
+
| `plugin::magic-editor-x.templates.manage` | Manage templates and block patterns | Settings > Magic Editor X > Templates (templates, patterns and synced blocks, usage counts), "Save content as template" and "Save as pattern" in the editor, "Edit source" on synced blocks |
|
|
448
712
|
|
|
449
713
|
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.
|
|
450
714
|
|
|
@@ -452,36 +716,59 @@ Super Admins have all actions. The `access` action keeps its 1.x id, so roles th
|
|
|
452
716
|
|
|
453
717
|
### Routes
|
|
454
718
|
|
|
455
|
-
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. 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.
|
|
456
|
-
|
|
457
|
-
| Method | Path | Actions
|
|
458
|
-
| ------ | --------------------------------------------- |
|
|
459
|
-
| GET | `/magic-editor-x/config` | access
|
|
460
|
-
| GET | `/magic-editor-x/link` | access
|
|
461
|
-
| POST | `/magic-editor-x/image/byFile` | access, upload
|
|
462
|
-
| POST | `/magic-editor-x/image/byUrl` | access, upload
|
|
463
|
-
| POST | `/magic-editor-x/file/upload` | access, upload
|
|
464
|
-
| GET | `/magic-editor-x/content-types` | access
|
|
465
|
-
| GET | `/magic-editor-x/links/types` | access
|
|
466
|
-
| GET | `/magic-editor-x/links/search` | access (+ Content Manager read)
|
|
467
|
-
| GET | `/magic-editor-x/custom-blocks` | access (`?all=true` also needs custom-blocks.manage)
|
|
468
|
-
| GET | `/magic-editor-x/custom-blocks/export` | custom-blocks.manage
|
|
469
|
-
| POST | `/magic-editor-x/custom-blocks/import` | custom-blocks.manage
|
|
470
|
-
| PUT | `/magic-editor-x/custom-blocks/order` | custom-blocks.manage
|
|
471
|
-
| POST | `/magic-editor-x/custom-blocks` | custom-blocks.manage
|
|
472
|
-
| PUT | `/magic-editor-x/custom-blocks/:id` | custom-blocks.manage
|
|
473
|
-
| DELETE | `/magic-editor-x/custom-blocks/:id` | custom-blocks.manage
|
|
474
|
-
| POST | `/magic-editor-x/custom-blocks/:id/duplicate` | custom-blocks.manage
|
|
475
|
-
|
|
|
476
|
-
| GET | `/magic-editor-x/
|
|
477
|
-
|
|
|
478
|
-
|
|
|
479
|
-
|
|
|
480
|
-
| POST | `/magic-editor-x/
|
|
481
|
-
|
|
|
482
|
-
|
|
|
483
|
-
|
|
|
484
|
-
| POST | `/magic-editor-x/
|
|
719
|
+
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
|
+
|
|
721
|
+
| Method | Path | Actions | Body / query | Response |
|
|
722
|
+
| ------ | --------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
723
|
+
| GET | `/magic-editor-x/config` | access | | `{ data: { collaboration, ai, grammar, uploads, linkPreview, quality, comments, rawHtml, codeBlocks, permissions } }` |
|
|
724
|
+
| GET | `/magic-editor-x/link` | access | `?url=` | `{ success: 1, link, meta }` |
|
|
725
|
+
| POST | `/magic-editor-x/image/byFile` | access, upload | multipart `image` | `{ success: 1, file: { url, ... } }` |
|
|
726
|
+
| POST | `/magic-editor-x/image/byUrl` | access, upload | `{ url }` | `{ success: 1, file }` |
|
|
727
|
+
| POST | `/magic-editor-x/file/upload` | access, upload | multipart `file` | `{ success: 1, file: { url, name, title, size, extension } }` |
|
|
728
|
+
| GET | `/magic-editor-x/content-types` | access | | `{ data: [{ uid, kind, displayName, attributes }] }` (types you can read) |
|
|
729
|
+
| GET | `/magic-editor-x/links/types` | access | | `{ data: [{ uid, kind, displayName, localized }] }` (API types you can read) |
|
|
730
|
+
| 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) |
|
|
731
|
+
| GET | `/magic-editor-x/custom-blocks` | access (`?all=true` also needs custom-blocks.manage) | `?all=true` | `{ data: [block] }` |
|
|
732
|
+
| GET | `/magic-editor-x/custom-blocks/export` | custom-blocks.manage | | `{ data: { format: 'magic-editor-x/custom-blocks', version: 2, exportedAt, blocks } }` |
|
|
733
|
+
| POST | `/magic-editor-x/custom-blocks/import` | custom-blocks.manage | export document | `{ data: { created: [name], skipped: [{ name, reason }] } }` |
|
|
734
|
+
| PUT | `/magic-editor-x/custom-blocks/order` | custom-blocks.manage | `{ ids }` (every block once) | `{ data: [block] }` |
|
|
735
|
+
| POST | `/magic-editor-x/custom-blocks` | custom-blocks.manage | block definition | 201 `{ data: block }` |
|
|
736
|
+
| PUT | `/magic-editor-x/custom-blocks/:id` | custom-blocks.manage | full block definition | `{ data: block }` |
|
|
737
|
+
| DELETE | `/magic-editor-x/custom-blocks/:id` | custom-blocks.manage | | `{ data: { id } }` |
|
|
738
|
+
| POST | `/magic-editor-x/custom-blocks/:id/duplicate` | custom-blocks.manage | | 201 `{ data: block }` |
|
|
739
|
+
| 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) |
|
|
740
|
+
| GET | `/magic-editor-x/templates/targets` | access, templates.manage | | `{ data: [{ uid, displayName, field, preset }] }` |
|
|
741
|
+
| PUT | `/magic-editor-x/templates/order` | access, templates.manage | `{ ids }` | `{ data: [template] }` |
|
|
742
|
+
| GET | `/magic-editor-x/templates/:id` | access | | `{ data: template }` (disabled ones only for managers; synced sources always) |
|
|
743
|
+
| GET | `/magic-editor-x/templates/:id/usage` | access, templates.manage | | `{ data: { entries, fields, templates, complete } }` (synced sources: how often they are referenced, counts only) |
|
|
744
|
+
| POST | `/magic-editor-x/templates` | access, templates.manage | `{ name, description?, kind, blocks, scope, enabled? }` | 201 `{ data: template }` |
|
|
745
|
+
| PUT | `/magic-editor-x/templates/:id` | access, templates.manage | full definition | `{ data: template }` |
|
|
746
|
+
| DELETE | `/magic-editor-x/templates/:id` | access, templates.manage | | `{ data: { id } }` |
|
|
747
|
+
| POST | `/magic-editor-x/templates/:id/duplicate` | access, templates.manage | | 201 `{ data: template }` (disabled copy) |
|
|
748
|
+
| POST | `/magic-editor-x/collaboration/session` | access, collaborate | `{ uid, documentId, locale?, field, initialValue? }` | `{ data: { token, path, canEdit, expiresAt } }` |
|
|
749
|
+
| GET | `/magic-editor-x/history` | access | `?uid&documentId&locale&field` | `{ data: [version], meta: { canRestore, canCreate } }` |
|
|
750
|
+
| GET | `/magic-editor-x/history/:id` | access | | `{ data: { ...version, content } }` |
|
|
751
|
+
| 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) |
|
|
752
|
+
| 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 |
|
|
753
|
+
| 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` |
|
|
754
|
+
| 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) |
|
|
755
|
+
| GET | `/magic-editor-x/quality/link-schedule` | settings.read | | `{ data: { enabled, scheduled, rule, maxUrlsPerRun, perMinute, perHostConcurrency, running, lastRun } }` |
|
|
756
|
+
| POST | `/magic-editor-x/quality/link-schedule/run` | settings.read, settings.update | | 202 `{ data: { started: true } }`; 409 `RUNNING`; 400 `DISABLED` |
|
|
757
|
+
| GET | `/magic-editor-x/comments` | access, comments.read (+ Content Manager read) | `?uid&documentId&locale&field` | `{ data: [thread], meta: { counts, canWrite, canModerate } }` |
|
|
758
|
+
| POST | `/magic-editor-x/comments` | access, comments.read, comments.write (+ Content Manager read) | `{ uid, documentId, locale?, field, blockId, body (1-4000), excerpt? }` | 201 `{ data: thread }`; 429 above `comments.perMinute` |
|
|
759
|
+
| POST | `/magic-editor-x/comments/:id/replies` | access, comments.read, comments.write (+ Content Manager read) | `{ body }` | 201 `{ data: comment }` (reopens a resolved thread) |
|
|
760
|
+
| PUT | `/magic-editor-x/comments/:id` | access, comments.read, comments.write (+ Content Manager read) | `{ body }` | `{ data: comment }`; author only (403) |
|
|
761
|
+
| POST | `/magic-editor-x/comments/:id/resolve` | access, comments.read, comments.write (+ Content Manager read) | | `{ data: { id, status, resolvedAt, resolvedBy } }` |
|
|
762
|
+
| POST | `/magic-editor-x/comments/:id/reopen` | access, comments.read, comments.write (+ Content Manager read) | | `{ data: { id, status, resolvedAt, resolvedBy } }` |
|
|
763
|
+
| DELETE | `/magic-editor-x/comments/:id` | access, comments.read (+ Content Manager read) | | `{ data: { id, removed } }`; others' comments need comments.moderate (403) |
|
|
764
|
+
| POST | `/magic-editor-x/ai/:action` | access, ai.use | `{ text, language?, tone?, target: { uid, field } }` | `{ data: { text } }`; 403 when the field turns AI off |
|
|
765
|
+
| 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 |
|
|
766
|
+
| POST | `/magic-editor-x/ai/field/:action` | access, ai.use | `{ target, segments: [{ blockId, path, html }], language? }` | `{ data: { segments } }` or `{ data: { text } }` |
|
|
767
|
+
| POST | `/magic-editor-x/grammar/check` | access, grammar.use | `{ target, segments, locale? }` | `{ data: { language, matches, truncated } }` |
|
|
768
|
+
| GET | `/magic-editor-x/settings` | settings.read | | `{ data: { ai, languageTool, environment } }` (no secrets) |
|
|
769
|
+
| 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 } }` |
|
|
770
|
+
| POST | `/magic-editor-x/settings/ai/test` | settings.read, settings.update | `{ ai: {...} }` | `{ data: { ok: true } }` |
|
|
771
|
+
| POST | `/magic-editor-x/settings/language-tool/test` | settings.read, settings.update | `{ languageTool: {...} }` | `{ data: { ok: true } }` |
|
|
485
772
|
|
|
486
773
|
`upload` means `plugin::upload.assets.create`. 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.
|
|
487
774
|
|
|
@@ -514,14 +801,31 @@ Content-Type: application/json
|
|
|
514
801
|
## Security and privacy
|
|
515
802
|
|
|
516
803
|
- **Stored content:** every Magic Editor X value is normalised and sanitised on save by a Document Service middleware (Content Manager, Content API, imports and code). Unknown keys of known block types are dropped, URLs are checked, inline HTML is limited to the tags above and the raw HTML block follows `rawHtml`. Values over 5 MiB, with more than 5000 blocks or nested deeper than 24 levels are rejected with 400, never truncated. The admin sanitises again before rendering (DOMPurify with the same rules).
|
|
517
|
-
- **Outgoing requests:**
|
|
804
|
+
- **Outgoing requests:** the plugin sends nothing on its own; there is no telemetry. What leaves the server, and when:
|
|
805
|
+
|
|
806
|
+
| Request | When | What is sent |
|
|
807
|
+
| ---------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
|
808
|
+
| 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 |
|
|
809
|
+
| 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
|
+
| 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
|
+
| AI assistant | An editor runs an action on selected text, after the owner configured a provider | The selected text and a fixed instruction |
|
|
812
|
+
| 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
|
+
| 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) |
|
|
814
|
+
| 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
|
+
|
|
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; link-check origins on private networks need `qualityChecks.externalLinks.allowPrivateOrigins`.
|
|
817
|
+
|
|
518
818
|
- **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.
|
|
519
819
|
- **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).
|
|
520
820
|
- **Field presets** are enforced on the server (save middleware and realtime guard), not only in the editor; see [Field presets](#field-presets).
|
|
521
821
|
- **Paste, import and rendering:** pasted and imported HTML/Markdown is parsed into an inert document and rebuilt from the editor's own tags only, then sanitised again on save; `magic-editor-x/render` re-parses stored inline HTML and never trusts it. The link check fetches external URLs only when the owner turns it on, through the SSRF-protected fetcher, rate limited, without logging URLs. See [docs/security-audit-2.2.md](./docs/security-audit-2.2.md).
|
|
522
|
-
- **
|
|
822
|
+
- **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
|
+
- **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
|
+
- **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.
|
|
825
|
+
- **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.
|
|
523
826
|
- **Logs** contain operation names and error codes only, never content, URLs with queries, tokens, user ids or email addresses.
|
|
524
|
-
- **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)
|
|
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.3.md](./docs/security-audit-2.3.md) covers every 2.3 surface (findings MEX-23-01 to MEX-23-14 with their controls and tests, and the residual risks).
|
|
525
829
|
- **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.
|
|
526
830
|
|
|
527
831
|
Report vulnerabilities privately through GitHub security advisories on the repository.
|
|
@@ -573,21 +877,41 @@ Add only the services you use. Instead of `https:` in `img-src` you can list you
|
|
|
573
877
|
|
|
574
878
|
## Troubleshooting
|
|
575
879
|
|
|
576
|
-
| Symptom
|
|
577
|
-
|
|
|
578
|
-
| The field shows "The editor could not be loaded."
|
|
579
|
-
| No upload or "You do not have permission to upload files"
|
|
580
|
-
| No version history (clock) button
|
|
581
|
-
| Badge shows "Live editing unavailable"
|
|
582
|
-
| Badge stays at "Connecting" or "Reconnecting"
|
|
583
|
-
| "Reload the page to keep editing live"
|
|
584
|
-
| Settings say the API key cannot be stored
|
|
585
|
-
| Settings say the stored key is unreadable
|
|
586
|
-
| AI error "The AI provider rejected the key."
|
|
587
|
-
| Startup error `[magic-editor-x] invalid configuration for: <key>`
|
|
588
|
-
| 400 "A Magic Editor X field contains invalid content"
|
|
589
|
-
| 400 "A Magic Editor X field does not match its field settings"
|
|
590
|
-
| 400 "Quality checks failed for a Magic Editor X field" on publish
|
|
880
|
+
| Symptom | Cause | Fix |
|
|
881
|
+
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
882
|
+
| The field shows "The editor could not be loaded." | The role lacks `plugin::magic-editor-x.access`, or the server is unreachable | Grant the action; check the server log. |
|
|
883
|
+
| No upload or "You do not have permission to upload files" | The role lacks `plugin::upload.assets.create` | Grant Media Library create to the role. |
|
|
884
|
+
| No version history (clock) button | The entry was never saved | Save the entry once. |
|
|
885
|
+
| Badge shows "Live editing unavailable" | No `collaborate` action, no read access to the document, or `collaboration.enabled: false` | Grant the action or check the Content Manager permissions. |
|
|
886
|
+
| Badge stays at "Connecting" or "Reconnecting" | The proxy does not forward WebSocket upgrades on `collaboration.path`, or the origin is not allowed | Allow upgrades on the path; add the admin origin to `collaboration.allowedOrigins` when the admin runs on another host. |
|
|
887
|
+
| "Reload the page to keep editing live" | The browser still runs the admin of an older version after an update | Reload the page. |
|
|
888
|
+
| Settings say the API key cannot be stored | `MAGIC_EDITOR_X_ENCRYPTION_KEY` is missing or shorter than 32 characters | Set the variable and restart, or use `ai.apiKey`. |
|
|
889
|
+
| Settings say the stored key is unreadable | The encryption key changed | Enter the provider key again. |
|
|
890
|
+
| AI error "The AI provider rejected the key." | Wrong key for this provider | Enter the key again and use Test connection. |
|
|
891
|
+
| Startup error `[magic-editor-x] invalid configuration for: <key>` | Wrong type or range in `config/plugins` | Fix the named key (see the reference table). |
|
|
892
|
+
| 400 "A Magic Editor X field contains invalid content" | The value is not editor JSON, too large or too deep | Send an Editor.js object within the limits. |
|
|
893
|
+
| 400 "A Magic Editor X field does not match its field settings" | The content breaks the field's preset (`details.violations` lists rule codes and block ids) | Open the quality panel of the field and use Fix automatically, or change the content or the field options. |
|
|
894
|
+
| 400 "Quality checks failed for a Magic Editor X field" on publish | The field has `publishGuard` and the quality checks report errors | Fix the errors listed in the quality panel (missing alternative texts, empty links). |
|
|
895
|
+
| 400 with `details.param: 'mex'` from the Content API | `mex` has another value than `html`, `text`, `markdown` or `json`, or is repeated | Send one of the four values once. |
|
|
896
|
+
| `?mex=html` shows link text without the link | The caller may not read the linked entry, it is missing, or it has no published version | Grant `find` on the target type to the token or role, publish the entry, or request `status=draft` where appropriate. |
|
|
897
|
+
| A synced block renders nothing in my frontend | Without `?mex` the API returns only `{ ref }`; the renderers need the sources | Use `?mex=` or the GraphQL fields, or pass the sources with the `synced` render option. |
|
|
898
|
+
| "Synced block removed" in the editor | Its source was deleted in Settings > Templates | Delete the block, or insert another synced block. |
|
|
899
|
+
| No Comments or Check grammar button | Comments: the role lacks `comments.read`, `comments.enabled` is false, or the entry was never saved. Grammar: the role lacks `grammar.use`, or LanguageTool is off or has no base URL | Grant the action, save the entry once, or turn the feature on. |
|
|
900
|
+
| "Alternative text suggestions are turned off." | "Send images to the AI provider" is off (503 `IMAGES_DISABLED`) | Turn it on in Settings > Magic Editor X > Configuration, if you accept that images are sent. |
|
|
901
|
+
| "The grammar check is not configured yet." | LanguageTool is on but has no base URL | Enter the base URL and use Test LanguageTool. |
|
|
902
|
+
| 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
|
+
| 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. |
|
|
904
|
+
|
|
905
|
+
## Upgrading from 2.2
|
|
906
|
+
|
|
907
|
+
2.3 is a minor release. Stored content, routes and configuration keep working.
|
|
908
|
+
|
|
909
|
+
1. Update and rebuild the admin: `npm install magic-editor-x@latest && npm run build`.
|
|
910
|
+
2. Grant the new actions to roles that need them: `comments.read`, `comments.write`, `comments.moderate`, `templates.manage`, `grammar.use`.
|
|
911
|
+
3. Optional: turn on the AI image and whole-field switches and LanguageTool in Settings, and the scheduled link check (`qualityChecks.externalLinks.enabled` and `qualityChecks.externalLinks.schedule.enabled`, plus `cron: { enabled: true }` in `config/server`).
|
|
912
|
+
4. Optional: use `?mex=` or the GraphQL fields, or the React and Vue components, in your frontend.
|
|
913
|
+
|
|
914
|
+
A custom block named `toc`, `gallery`, `video`, `audio`, `synced` or `mention` that you created before 2.3 keeps working as a custom block, with its stored data unchanged; new custom blocks cannot use these names.
|
|
591
915
|
|
|
592
916
|
## Migrating from 1.x
|
|
593
917
|
|
|
@@ -608,6 +932,7 @@ npm ci
|
|
|
608
932
|
npm run lint
|
|
609
933
|
npm run format:check
|
|
610
934
|
npm test # unit tests, no Strapi host needed
|
|
935
|
+
npm run bench # performance benchmark (500 to 5000 blocks) against fixed budgets
|
|
611
936
|
npm run build # admin and server bundles, then a runtime check
|
|
612
937
|
npm run verify
|
|
613
938
|
MEX_HOST_URL=http://127.0.0.1:1421 MEX_CREDS=/path/to/creds.json npm run test:integration
|