diff --git a/docusaurus/docs/dev-docs/plugins/content-source-map.md b/docusaurus/docs/dev-docs/plugins/content-source-map.md new file mode 100644 index 0000000000..1c31189d88 --- /dev/null +++ b/docusaurus/docs/dev-docs/plugins/content-source-map.md @@ -0,0 +1,107 @@ +--- +title: Content Source Map plugin +description: Use the Content Source Map plugin with Vercel Visual Editing to enhance the content edition experience. +sidebar_label: Content Source Map +displayed_sidebar: devDocsSidebar +--- + +import CSMPrereq from '/docs/snippets/content-source-map-requirements.md' + +# Content Source Map plugin + + + +The Content Source Map plugin adds content source maps support to a Strapi project. + +Content source maps are invisible values that include a link back to the field that generated the content. When combined with [Vercel's Visual Editing](https://vercel.com/docs/workflow-collaboration/visual-editing) feature, content source maps allow navigating directly from the front-end website of a Strapi-based project to the source of a field in Strapi's admin panel, making editing content more intuitive. + +## Installation + +To add the Content Source Map plugin to your Strapi project, run the following command in the terminal: + + + + + +```bash +yarn add @strapi/plugin-content-source-map +``` + + + + + +```bash +npm install @strapi/plugin-content-source-map +``` + + + + + +## Configuration + +Once installed, the Content Source Map plugin should be enabled and configured in your project by adding relevant parameters to the [plugins configuration file](/dev-docs/configurations/plugins): + +| Name | Description | Default | +|----------------|-----------------------------------------------------------------------|-------------| +| `contentTypes` | Array of content type uids to enable content source map for. | `[]` | +| `origin` | Origin defined in the source map and used to display the edit button. | `strapi.io` | +| `baseHref` | Base URL of your Strapi admin panel. | Generated based on the [`server.url` configuration value](/dev-docs/configurations/server) | + + + + + +```jsx title="./config/plugins.js" + +module.exports = () => ({ + 'content-source-map': { + enabled: true, + config: { + contentTypes: ['api::article.article', 'api::restaurant.restaurant'], + origin: 'strapi.io', + baseHref: 'https://my.strapi-admin.com', + }, + }, +}); +``` + + + + + +```jsx title="./config/plugins.ts" + +export default () => ({ + 'content-source-map': { + enabled: true, + config: { + contentTypes: ['api::article.article', 'api::restaurant.restaurant'], + origin: 'strapi.io', + baseHref: 'https://my.strapi-admin.com', + }, + }, +}); +``` + + + + + +## Usage + +The Content Source Map plugin adds content source map support to the following API endpoints: + +- `GET /api/:contentType` to list a content type entries +- `GET /api/:contentType/:id` to retrieve a content type entry by id + +To include source map data in the response, you will have to add the `encodeSourceMaps=true` query parameter to your [REST API](/dev-docs/api/rest) calls. Vercel will automatically detect Content Source Maps on the deployed website. + +:::caution +This will have performance impacts so you should use this only in draft mode or when doing previews. +::: + +:::tip +To see the Content Source Map plugin and Vercel Live Editing in action, refer to the [User Guide](/user-docs/content-manager/writing-content#editing-fields-from-a-front-end-website-). +::: diff --git a/docusaurus/docs/dev-docs/plugins/using-plugins.md b/docusaurus/docs/dev-docs/plugins/using-plugins.md index 5cf32e99c4..df8efe36d6 100644 --- a/docusaurus/docs/dev-docs/plugins/using-plugins.md +++ b/docusaurus/docs/dev-docs/plugins/using-plugins.md @@ -16,6 +16,7 @@ This section is about using Strapi built-in plugins from a developer's perspecti Strapi comes with the following built-in plugins that are officially maintained and documented by the Strapi core team: + diff --git a/docusaurus/docs/snippets/content-source-map-requirements.md b/docusaurus/docs/snippets/content-source-map-requirements.md new file mode 100644 index 0000000000..a9ce67b9e5 --- /dev/null +++ b/docusaurus/docs/snippets/content-source-map-requirements.md @@ -0,0 +1,8 @@ +:::prerequisites + +The Content Source Map plugin requires: + +- A Strapi licence +- A website deployed on [Vercel](https://vercel.com/docs/workflow-collaboration/visual-editing) with a Vercel Pro or Enterprise plan + +::: diff --git a/docusaurus/docs/user-docs/content-manager/writing-content.md b/docusaurus/docs/user-docs/content-manager/writing-content.md index cc5c3627ba..6056c88164 100644 --- a/docusaurus/docs/user-docs/content-manager/writing-content.md +++ b/docusaurus/docs/user-docs/content-manager/writing-content.md @@ -6,6 +6,8 @@ displayed_sidebar: userDocsSidebar --- +import CSMPrereq from '/docs/snippets/content-source-map-requirements.md' + # Writing content In Strapi, writing content consists in filling up fields, which are meant to contain specific content (e.g. text, numbers, media, etc.). These fields were configured for the collection or single type beforehand, through the [Content-type Builder](/user-docs/content-type-builder). @@ -146,3 +148,19 @@ You can also use the keyboard to reorder components: focus the component using T :::note Unlike regular fields, the order of the fields and components inside a dynamic field is important. It should correspond exactly to how end users will read/see the content. ::: + +## Editing fields from a front-end website + + + +Strapi's [Content Source Map plugin](/dev-docs/plugins/content-source-map) combined with [Vercel's Visual Editing](https://vercel.com/docs/workflow-collaboration/visual-editing) can offer another intuitive editing experience, where you can click on any editable content on the front-end website of a Strapi-based project to directly jump to the corresponding field in Strapi's admin panel. + +Once the Content Source Map plugin is installed and configured (see [Developer Docs](/dev-docs/plugins/content-source-map)), you can experience Visual Editing as follows: + +1. Visit any preview deployment website hosted on Vercel. +2. Login using the Vercel Toolbar. +3. When Content Source Maps are detected on the page, a pencil icon will appear in the Vercel toolbar. Clicking this icon will enable Edit Mode, highlighting all editable fields on the page in blue. +4. Hover any content highlighted in blue to display an **Open in strapi.io** button. +5. Click on the **Open in strapi.io** button to jump directly to the corresponding field in the admin panel and edit its content. + +![Vercel Visual Editing in Strapi](/img/assets/content-manager/content-source-map-visual-editing.png) diff --git a/docusaurus/docs/user-docs/plugins/strapi-plugins.md b/docusaurus/docs/user-docs/plugins/strapi-plugins.md index a3ad992108..86ff72cc36 100644 --- a/docusaurus/docs/user-docs/plugins/strapi-plugins.md +++ b/docusaurus/docs/user-docs/plugins/strapi-plugins.md @@ -68,6 +68,12 @@ The Email plugin allows users to send email from the server or from external pro ## Additional plugins +### ✍️ Content Source Map + +The Content Source Map plugin combined with Vercel's Visual Editing can offer an intuitive [editing experience](/user-docs/content-manager/writing-content#editing-fields-from-a-front-end-website-), where you can click on any editable content on the front-end website of a Strapi-based project deployed on Vercel to directly jump to the corresponding field in Strapi's admin panel. + +There is no access to the Content Source Map plugin in the admin panel. More information on using the Content Source Map plugin is located in the [Content Manager](/user-docs/content-manager/writing-content#editing-fields-from-a-front-end-website-) documentation and in the dedicated [Developer Documentation](/dev-docs/plugins/content-source-map) for the plugin. + ### Documentation The Documentation plugin automates documentation for APIs in a Strapi application using the Open API specification version 3.0.1. When the Documentation plugin is installed it is available in the admin panel, under the heading "Plugins". The Documentation plugin is available in the in-app Marketplace and the [Strapi Market](https://market.strapi.io/plugins/@strapi-plugin-documentation). The Documentation plugin enables: diff --git a/docusaurus/sidebars.js b/docusaurus/sidebars.js index 5997672d1a..fc02516c4c 100644 --- a/docusaurus/sidebars.js +++ b/docusaurus/sidebars.js @@ -422,6 +422,14 @@ const sidebars = { label: 'Introduction', id: 'dev-docs/plugins/using-plugins' }, + { + type: 'doc', + label: 'Content Source Map', + id: 'dev-docs/plugins/content-source-map', + customProps: { + new: true, + } + }, { type: 'doc', label: 'Documentation', diff --git a/docusaurus/static/img/assets/content-manager/content-source-map-visual-editing.png b/docusaurus/static/img/assets/content-manager/content-source-map-visual-editing.png new file mode 100644 index 0000000000..717efbc654 Binary files /dev/null and b/docusaurus/static/img/assets/content-manager/content-source-map-visual-editing.png differ