pluginpal · boazpoolman · Dec 20, 2025 · Dec 20, 2025
diff --git a/.changeset/loose-toes-tap.md b/.changeset/loose-toes-tap.md
@@ -0,0 +1,5 @@
+---
+"docs": minor
+---
+
+docs: improve documentation for existing and new addons
diff --git a/packages/docs/docs/addons/breadcrumbs/api/rest.md b/packages/docs/docs/addons/breadcrumbs/api/rest.md
@@ -0,0 +1,70 @@
+---
+sidebar_label: 'Rest API'
+displayed_sidebar: webtoolsBreadcrumbsSidebar
+slug: /addons/breadcrumbs/api/rest
+---
+
+import ThemedImage from '@theme/ThemedImage';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+# REST API
+
+The Breadcrumbs addon for Webtools allows you to get a computed breadcrumb trail in the Strapi API response. You can populate the breadcrumbs like you would with any regular relation.
+
+<ApiCall>
+
+<Request>
+
+`GET http://localhost:1337/api/home-page?populate=breadcrumbs`
+
+</Request>
+
+<Response>
+
+```json
+{
+  "data": {
+    "id": 2,
+    "documentId": "ke1s1aroaexv8jt03iuxn81g",
+    "title": "Robust Strapi plugins for your project",
+    "createdAt": "2025-03-09T16:45:24.886Z",
+    "updatedAt": "2025-03-13T20:38:43.112Z",
+    "publishedAt": "2025-03-13T17:06:57.578Z",
+    "locale": "en",
+    "breadcrumbs": {
+      "items": [
+        {
+          "label": "Home",
+          "url": "/"
+        },
+        {
+          "label": "Plugins overview",
+          "url": "/plugins"
+        },
+        {
+          "label": "Strapi Webtools",
+          "url": "/plugins/webtools"
+        }
+      ]
+    }
+  },
+  "meta": {}
+}
+
+```
+
+</Response>
+
+</ApiCall>
+
+## Permissions
+
+To fetch the breadcrumbs from the API you need to enable the 'find' permissions of the Breadcrumbs content type.
+
+<ThemedImage
+  alt="Breadcrumbs permissions"
+  sources={{
+    light: useBaseUrl('/webtools/img/assets/addons/breadcrumbs/breadcrumbs-permissions-light.png'),
+    dark: useBaseUrl('/webtools/img/assets/addons/breadcrumbs/breadcrumbs-permissions-light.png'),
+  }}
+/>
diff --git a/packages/docs/docs/addons/breadcrumbs/getting-started/installation.md b/packages/docs/docs/addons/breadcrumbs/getting-started/installation.md
@@ -0,0 +1,62 @@
+---
+sidebar_label: 'Installation'
+displayed_sidebar: webtoolsBreadcrumbsSidebar
+slug: /addons/breadcrumbs/installation
+---
+
+# ⏳ Installation
+
+:::prerequisites
+Complete installation requirements are the exact same as for Strapi itself and can be found in the Strapi documentation.
+
+**Additional Requirements:**
+- **Node.js**: Version 18.18.2 or higher
+- **Strapi**: Version 5.x
+- **Webtools**: Version 1.x
+:::
+
+:::caution
+This addon is part of the premium package of Webtools. You'll have to purchase a license key to download and use this package. Once you have your license key you can run the following command to setup your license in your project:
+
+```
+npx webtools-cli setup-license
+```
+
+To purchase a license, please visit the [PluginPal website](https://www.pluginpal.io/plugin/webtools).
+:::
+
+### Installation
+
+After you've setup your license you can install the addon like so:
+
+<Tabs groupId="yarn-npm">
+  <TabItem value="yarn" label="Yarn">
+    ```
+    yarn add strapi-plugin-webtools @pluginpal/webtools-addon-breadcrumbs
+    ```
+  </TabItem>
+  <TabItem value="npm" label="NPM">
+    ```
+    npm install strapi-plugin-webtools @pluginpal/webtools-addon-breadcrumbs --save
+    ```
+  </TabItem>
+</Tabs>
+
+After successful installation you have to rebuild the admin UI so it'll include this plugin. To rebuild and restart Strapi run:
+
+<Tabs groupId="yarn-npm">
+  <TabItem value="yarn" label="Yarn">
+    ```
+    yarn build
+    yarn develop
+    ```
+  </TabItem>
+  <TabItem value="npm" label="NPM">
+    ```
+    npm run build
+    npm run develop
+    ```
+  </TabItem>
+</Tabs>
+
+Enjoy 🎉
diff --git a/packages/docs/docs/addons/breadcrumbs/getting-started/introduction.md b/packages/docs/docs/addons/breadcrumbs/getting-started/introduction.md
@@ -0,0 +1,20 @@
+---
+sidebar_label: 'Introduction'
+displayed_sidebar: webtoolsBreadcrumbsSidebar
+slug: /addons/breadcrumbs
+---
+
+# Webtools Breadcrumbs Add-on
+
+The **Breadcrumbs add-on** for Webtools provides a computed breadcrumbs trail in your API response based on the URL alias of your page. The breadcrumbs trail get's added as a relation and can be populated in the API response.
+
+:::note
+This plugin acts as an extension of the core `strapi-plugin-webtools`. Please install and configure that before proceeding.
+:::
+
+## Key Features
+
+- **⚡ Computed breadcrumbs trail** - Automatically generated based on the URL alias
+- **⚡ Loaded as relation** - The breadcrumbs can be populated like a relation
+- **⚙️ Overwrite the page title** - Allows configuration to select the title field of the page
+
diff --git a/packages/docs/docs/addons/breadcrumbs/settings/introduction.md b/packages/docs/docs/addons/breadcrumbs/settings/introduction.md
@@ -0,0 +1,20 @@
+---
+sidebar_label: 'Breadcrumbs settings'
+displayed_sidebar: webtoolsBreadcrumbsSidebar
+slug: /addons/breadcrumbs/settings
+---
+
+import ThemedImage from '@theme/ThemedImage';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+# Breadcrumbs settings
+
+The Breadcrumbs addon offers a settings page where you can configure the behavior of the computed breadcrumbs trail. Select if you want to include the homepage in the trail or configure the breadcrumb labels of the different content types.
+
+<ThemedImage
+  alt="Breadcrumbs settings"
+  sources={{
+    light: useBaseUrl('/webtools/img/assets/addons/breadcrumbs/breadcrumbs-settings-light.png'),
+    dark: useBaseUrl('/webtools/img/assets/addons/breadcrumbs/breadcrumbs-settings-light.png'),
+  }}
+/>
diff --git a/packages/docs/docs/addons/introduction.md b/packages/docs/docs/addons/introduction.md
@@ -14,4 +14,5 @@ To enhance Webtools in a modular way, the core plugin allows addons to be regist
 <CustomDocCard emoji="🔌" title="Sitemap" description="The Sitemap addon can be used to generate a customizable sitemap using all your Webtools URL aliases" link="/webtools/addons/sitemap" />
 <CustomDocCard emoji="🔀" title="Redirects" description="The Redirects addon can be used to manage your redirects in Strapi CMS." link="/webtools/addons/redirects" />
 <CustomDocCard emoji="🔗" title="Links" description="The Links addon can be used create dynamic links from 1 page to another." link="/webtools/addons/links" />
+<CustomDocCard emoji="🍞" title="Breadcrumbs" description="The Breadcrumbs addon can be used to included a computed breadcrumbs path " link="/webtools/addons/breadcrumbs" />
 </CustomDocCardsWrapper>
diff --git a/packages/docs/docs/addons/links/api/links-format.md b/packages/docs/docs/addons/links/api/links-format.md
@@ -4,15 +4,15 @@ displayed_sidebar: webtoolsLinksSidebar
 slug: /addons/links/api/links-format
 ---
 
-# Rewrite middleware
+# Links format
 
 This plugin stores the internal links in a specific format. That format looks something like this:
 
 ```
-wt-link://api::page.page/sp8bzbkn21pjy3m9wsf97dio
+wt-link://api::page.page/sp8bzbkn21pjy3m9wsf97dio?locale=en
 ```
 
 This makes it possible to fetch the page, and ultimately the URL alias of the document that you have linked to.
 
-The plugin also provides a middleware which will rewrite these link formats to the actual link when you're using the Strapi API.
+The plugin provides a [rewrite middleware](/addons/links/api/rewrite-middleware) so that this link format will be rewritten to the actual URL at request time.
 
diff --git a/packages/docs/docs/addons/links/api/rewrite-middleware.md b/packages/docs/docs/addons/links/api/rewrite-middleware.md
@@ -0,0 +1,52 @@
+---
+sidebar_label: 'Rewrite middleware'
+displayed_sidebar: webtoolsLinksSidebar
+slug: /addons/links/api/rewrite-middleware
+---
+
+# Rewrite middleware
+
+The plugin provides a rewrite middleware so that the [raw link format](/addons/links/api/links-format) will be rewritten to the actual URL at request time.
+
+## Opt out
+
+You might want to opt-out of the rewrite functionality to get the raw Webtools link value. You can do that by providing a URL param to your request.
+
+<ApiCall>
+
+<Request>
+
+`GET http://localhost:1337/api/home-page?skipLinkRewrite=true`
+
+</Request>
+
+<Response>
+```
+{
+  "data": {
+    "id": 1,
+    "documentId": "yk4tcq7bd51cdqt7qk9gu5v6",
+    "link": "wt-link://api::page.page/sp8bzbkn21pjy3m9wsf97dio?locale=en",
+    "createdAt": "2025-09-07T13:03:00.877Z",
+    "updatedAt": "2025-09-07T13:03:00.877Z",
+    "publishedAt": "2025-09-07T13:03:00.873Z"
+  },
+  "meta": {}
+}
+```
+</Response>
+
+</ApiCall>
+
+## GraphQL
+
+GraphQL requests are not rewritten automatically because it doesn't use the Document Service of Strapi. To rewrite the links in your GraphQL requests you can manually add a middleware provided by the plugin.
+
+```md title="config/middlewares.ts"
+export default [
+  // ...
+  'plugin::webtools-addon-links.graphql',
+  // ...
+]
+```
+
diff --git a/packages/docs/docs/addons/links/configuration/custom-links.md b/packages/docs/docs/addons/links/configuration/custom-links.md
@@ -0,0 +1,27 @@
+---
+sidebar_label: 'Custom links'
+displayed_sidebar: webtoolsLinksSidebar
+slug: /addons/links/configuration/custom-links
+---
+
+# Custom links
+
+By default the links addon only allows to create links to pages that have Webtools enabled. If you want to allow a content type to be selected by the links addon that does not have Webtools enabled you can use this configuration array. This might be useful if you want to define a content type that stores all the external links that can be linked to.
+
+```md title="config/plugins.ts"
+export default () => {
+  'webtools-addon-links': {
+    enabled: true,
+    config: {
+      custom_links: [{
+        content_type: 'api::external-link.external-link',
+        resolver: (externalLink) => externalLink.external_link,
+      }],
+    }
+  }
+}
+```
+
+###### Key: `custom_links`
+
+> `required:` NO | `type:` array | `default:` []
diff --git a/packages/docs/docs/addons/links/configuration/introduction.md b/packages/docs/docs/addons/links/configuration/introduction.md
@@ -0,0 +1,20 @@
+---
+sidebar_label: 'Introduction'
+displayed_sidebar: webtoolsLinksSidebar
+slug: /addons/links/configuration
+---
+
+# 🔧 Configuration
+The configuration of the plugin can be overridden in the `config/plugins.js` file. 
+In the example below you can see how, and also what the default settings are.
+
+```md title="config/plugins.js"
+module.exports = ({ env }) => ({
+  'webtools-addon-links': {
+    enabled: true,
+    config: {
+      custom_links: [],
+    },
+  },
+});
+```
diff --git a/packages/docs/docs/addons/links/getting-started/installation.md b/packages/docs/docs/addons/links/getting-started/installation.md
@@ -32,12 +32,12 @@ After you've setup your license you can install the addon like so:
 <Tabs groupId="yarn-npm">
   <TabItem value="yarn" label="Yarn">
     ```
-    yarn add @pluginpal/webtools-addon-links
+    yarn add strapi-plugin-webtools @pluginpal/webtools-addon-links
     ```
   </TabItem>
   <TabItem value="npm" label="NPM">
     ```
-    npm install @pluginpal/webtools-addon-links --save
+    npm install strapi-plugin-webtools @pluginpal/webtools-addon-links --save
     ```
   </TabItem>
 </Tabs>

diff --git a/.../addons/links/getting-started/ckeditor.md → ...ocs/addons/links/integrations/ckeditor.md b/.../addons/links/getting-started/ckeditor.md → ...ocs/addons/links/integrations/ckeditor.md
diff --git a/packages/docs/docs/addons/links/integrations/custom-text-editor.md b/packages/docs/docs/addons/links/integrations/custom-text-editor.md
@@ -0,0 +1,36 @@
+---
+sidebar_label: 'Custom text editor'
+displayed_sidebar: webtoolsLinksSidebar
+slug: /addons/links/api/open-link-picker
+---
+
+import ThemedImage from '@theme/ThemedImage';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+# Custom text editor
+
+When you want to use dynamics links in your rich text editor you can use our default [Ckeditor integration](/addons/links/ckeditor). However the plugin also provides an API to implement the link picker model in your own editor.
+
+```md title="Example implementation"
+import { useStrapiApp } from '@strapi/strapi/admin';
+// ...
+const getPlugin = useStrapiApp('WebtoolsLinks', (state) => state.getPlugin);
+const linksPlugin = getPlugin('webtools-addon-links');
+const { openLinkPicker } = linksPlugin?.apis;
+// ...
+const pick = await openLinkPicker({
+  linkType: 'both',
+  initialHref: 'if the link exists, put the existing link here',
+  initialText: 'put in the selected text here'
+});
+```
+
+This will open the modal where you can select the dynamic link.
+
+<ThemedImage
+  alt="Ckeditor link modal"
+  sources={{
+    light: useBaseUrl('/webtools/img/assets/addons/links/ckeditor-link-modal-light.png'),
+    dark: useBaseUrl('/webtools/img/assets/addons/links/ckeditor-link-modal-light.png'),
+  }}
+/>
diff --git a/packages/docs/docs/addons/links/integrations/magic-editor.md b/packages/docs/docs/addons/links/integrations/magic-editor.md
@@ -0,0 +1,29 @@
+---
+sidebar_label: 'Magic Editor'
+displayed_sidebar: webtoolsLinksSidebar
+slug: /addons/links/magic-editor
+---
+
+import ThemedImage from '@theme/ThemedImage';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+# Magic Editor integration
+This addon has an integration with [the Magic Editor plugin](https://www.npmjs.com/package/magic-editor-x). If the Magic Editor plugin is installed it will include a button to select a dynamic Webtools links.
+
+<ThemedImage
+  alt="Magic Editor"
+  sources={{
+    light: useBaseUrl('/webtools/img/assets/addons/links/magic-editor-light.png'),
+    dark: useBaseUrl('/webtools/img/assets/addons/links/magic-editor-light.png'),
+  }}
+/>
+
+If you click the link button it will open a modal in which you can manage your links.
+
+<ThemedImage
+  alt="Magic Editor link modal"
+  sources={{
+    light: useBaseUrl('/webtools/img/assets/addons/links/magic-editor-link-modal-light.png'),
+    dark: useBaseUrl('/webtools/img/assets/addons/links/magic-editor-link-modal-light.png'),
+  }}
+/>