Skip to content

Commit 042c237

Browse files
pwizlapwizla
authored
Content Source Map plugin (#1850)
* Add Dev Docs * Update User Guide * Add to Dev Docs TOC * Add GIF * Move content source map plugin higher up in the TOC … to respect alphabetical order. * Add prerequisites * Mention plugin in List of Plugins in User Guide * Replace GIF by unique screenshot * Improve list of plugins part * Improve TOC and SEO
1 parent dee3345 commit 042c237

File tree

7 files changed

+148
-0
lines changed

7 files changed

+148
-0
lines changed

‎docusaurus/docs/dev-docs/plugins/content-source-map.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
---
2+
title: Content Source Map plugin
3+
description: Use the Content Source Map plugin with Vercel Visual Editing to enhance the content edition experience.
4+
sidebar_label: Content Source Map
5+
displayed_sidebar: devDocsSidebar
6+
---
7+
8+
import CSMPrereq from '/docs/snippets/content-source-map-requirements.md'
9+
10+
# Content Source Map plugin <EnterpriseBadge />
11+
12+
<CSMPrereq />
13+
14+
The Content Source Map plugin adds content source maps support to a Strapi project.
15+
16+
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.
17+
18+
## Installation
19+
20+
To add the Content Source Map plugin to your Strapi project, run the following command in the terminal:
21+
22+
<Tabs groupId="yarn-npm">
23+
24+
<TabItem value="yarn" label="yarn">
25+
26+
```bash
27+
yarn add @strapi/plugin-content-source-map
28+
```
29+
30+
</TabItem>
31+
32+
<TabItem value="npm" label="npm">
33+
34+
```bash
35+
npm install @strapi/plugin-content-source-map
36+
```
37+
38+
</TabItem>
39+
40+
</Tabs>
41+
42+
## Configuration
43+
44+
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):
45+
46+
| Name | Description | Default |
47+
|----------------|-----------------------------------------------------------------------|-------------|
48+
| `contentTypes` | Array of content type uids to enable content source map for. | `[]` |
49+
| `origin` | Origin defined in the source map and used to display the edit button. | `strapi.io` |
50+
| `baseHref` | Base URL of your Strapi admin panel. | Generated based on the [`server.url` configuration value](/dev-docs/configurations/server) |
51+
52+
<Tabs groupId="js-ts">
53+
54+
<TabItem value="js" label="JavaScript">
55+
56+
```jsx title="./config/plugins.js"
57+
58+
module.exports = () => ({
59+
'content-source-map': {
60+
enabled: true,
61+
config: {
62+
contentTypes: ['api::article.article', 'api::restaurant.restaurant'],
63+
origin: 'strapi.io',
64+
baseHref: 'https://my.strapi-admin.com',
65+
},
66+
},
67+
});
68+
```
69+
70+
</TabItem>
71+
72+
<TabItem value="ts" label="TypeScript">
73+
74+
```jsx title="./config/plugins.ts"
75+
76+
export default () => ({
77+
'content-source-map': {
78+
enabled: true,
79+
config: {
80+
contentTypes: ['api::article.article', 'api::restaurant.restaurant'],
81+
origin: 'strapi.io',
82+
baseHref: 'https://my.strapi-admin.com',
83+
},
84+
},
85+
});
86+
```
87+
88+
</TabItem>
89+
90+
</Tabs>
91+
92+
## Usage
93+
94+
The Content Source Map plugin adds content source map support to the following API endpoints:
95+
96+
- `GET /api/:contentType` to list a content type entries
97+
- `GET /api/:contentType/:id` to retrieve a content type entry by id
98+
99+
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.
100+
101+
:::caution
102+
This will have performance impacts so you should use this only in draft mode or when doing previews.
103+
:::
104+
105+
:::tip
106+
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-).
107+
:::

‎docusaurus/docs/dev-docs/plugins/using-plugins.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ This section is about using Strapi built-in plugins from a developer's perspecti
1616
Strapi comes with the following built-in plugins that are officially maintained and documented by the Strapi core team:
1717

1818
<CustomDocCardsWrapper>
19+
<CustomDocCard emoji="ℹ️" title="Content Source Map" description="The Content Source Map plugin, used with Vercel Visual Editing, enhances the content edition experience." link="/dev-docs/plugins/content-source-map" />
1920
<CustomDocCard emoji="ℹ️" title="Documentation" description="The Documentation plugin is useful to document the available endpoints once you created an API." link="/dev-docs/plugins/documentation" />
2021
<CustomDocCard emoji="✉️" title="Email" description="The Email plugin enables applications to send emails from a server or an external provider." link="/dev-docs/plugins/email"/>
2122
<CustomDocCard title="GraphQL" description="The GraphQL plugin adds a GraphQL endpoint to fetch and mutate your content." link="/dev-docs/plugins/graphql"/>

‎docusaurus/docs/snippets/content-source-map-requirements.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
:::prerequisites
2+
3+
The Content Source Map plugin requires:
4+
5+
- A Strapi <EnterpriseBadge /> licence
6+
- A website deployed on [Vercel](https://vercel.com/docs/workflow-collaboration/visual-editing) with a Vercel Pro or Enterprise plan
7+
8+
:::

‎docusaurus/docs/user-docs/content-manager/writing-content.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ displayed_sidebar: userDocsSidebar
66

77
---
88

9+
import CSMPrereq from '/docs/snippets/content-source-map-requirements.md'
10+
911
# Writing content
1012

1113
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
146148
:::note
147149
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.
148150
:::
151+
152+
## Editing fields from a front-end website <EnterpriseBadge />
153+
154+
<CSMPrereq />
155+
156+
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.
157+
158+
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:
159+
160+
1. Visit any preview deployment website hosted on Vercel.
161+
2. Login using the Vercel Toolbar.
162+
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.
163+
4. Hover any content highlighted in blue to display an **Open in strapi.io** button.
164+
5. Click on the **Open in strapi.io** button to jump directly to the corresponding field in the admin panel and edit its content.
165+
166+
![Vercel Visual Editing in Strapi](/img/assets/content-manager/content-source-map-visual-editing.png)

‎docusaurus/docs/user-docs/plugins/strapi-plugins.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,12 @@ The Email plugin allows users to send email from the server or from external pro
6868

6969
## Additional plugins
7070

71+
### ✍️ Content Source Map <EnterpriseBadge />
72+
73+
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.
74+
75+
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.
76+
7177
### <img width="28" src="/img/assets/plugins/Documentation-swagger.png" /> Documentation
7278

7379
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:

‎docusaurus/sidebars.js‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -422,6 +422,14 @@ const sidebars = {
422422
label: 'Introduction',
423423
id: 'dev-docs/plugins/using-plugins'
424424
},
425+
{
426+
type: 'doc',
427+
label: 'Content Source Map',
428+
id: 'dev-docs/plugins/content-source-map',
429+
customProps: {
430+
new: true,
431+
}
432+
},
425433
{
426434
type: 'doc',
427435
label: 'Documentation',

‎docusaurus/static/img/assets/content-manager/content-source-map-visual-editing.png‎

3 MB
Loading

0 commit comments

Comments
 (0)