diff --git a/.changeset/loose-toes-tap.md b/.changeset/loose-toes-tap.md new file mode 100644 index 00000000..bf26eda5 --- /dev/null +++ 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 new file mode 100644 index 00000000..7a2c6cd1 --- /dev/null +++ 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. + + + + + +`GET http://localhost:1337/api/home-page?populate=breadcrumbs` + + + + + +```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": {} +} + +``` + + + + + +## Permissions + +To fetch the breadcrumbs from the API you need to enable the 'find' permissions of the Breadcrumbs content type. + + diff --git a/packages/docs/docs/addons/breadcrumbs/getting-started/installation.md b/packages/docs/docs/addons/breadcrumbs/getting-started/installation.md new file mode 100644 index 00000000..00e1bc0e --- /dev/null +++ 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: + + + + ``` + yarn add strapi-plugin-webtools @pluginpal/webtools-addon-breadcrumbs + ``` + + + ``` + npm install strapi-plugin-webtools @pluginpal/webtools-addon-breadcrumbs --save + ``` + + + +After successful installation you have to rebuild the admin UI so it'll include this plugin. To rebuild and restart Strapi run: + + + + ``` + yarn build + yarn develop + ``` + + + ``` + npm run build + npm run develop + ``` + + + +Enjoy 🎉 diff --git a/packages/docs/docs/addons/breadcrumbs/getting-started/introduction.md b/packages/docs/docs/addons/breadcrumbs/getting-started/introduction.md new file mode 100644 index 00000000..929010ad --- /dev/null +++ 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 new file mode 100644 index 00000000..90e08bf1 --- /dev/null +++ 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. + + diff --git a/packages/docs/docs/addons/introduction.md b/packages/docs/docs/addons/introduction.md index 24ed00ba..aa7170a7 100644 --- 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 + diff --git a/packages/docs/docs/addons/links/api/links-format.md b/packages/docs/docs/addons/links/api/links-format.md index 9c5d64ce..1d41ae28 100644 --- 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 new file mode 100644 index 00000000..6896ec27 --- /dev/null +++ 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. + + + + + +`GET http://localhost:1337/api/home-page?skipLinkRewrite=true` + + + + +``` +{ + "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": {} +} +``` + + + + +## 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 new file mode 100644 index 00000000..041e984e --- /dev/null +++ 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 new file mode 100644 index 00000000..310ffaa5 --- /dev/null +++ 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 index 70b7f2aa..5a256bd4 100644 --- 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: ``` - yarn add @pluginpal/webtools-addon-links + yarn add strapi-plugin-webtools @pluginpal/webtools-addon-links ``` ``` - npm install @pluginpal/webtools-addon-links --save + npm install strapi-plugin-webtools @pluginpal/webtools-addon-links --save ``` diff --git a/packages/docs/docs/addons/links/getting-started/ckeditor.md b/packages/docs/docs/addons/links/integrations/ckeditor.md similarity index 100% rename from packages/docs/docs/addons/links/getting-started/ckeditor.md rename to packages/docs/docs/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 new file mode 100644 index 00000000..a05cf672 --- /dev/null +++ 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. + + diff --git a/packages/docs/docs/addons/links/integrations/magic-editor.md b/packages/docs/docs/addons/links/integrations/magic-editor.md new file mode 100644 index 00000000..0926c496 --- /dev/null +++ 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. + + + +If you click the link button it will open a modal in which you can manage your links. + + diff --git a/packages/docs/docs/addons/redirects/getting-started/installation.md b/packages/docs/docs/addons/redirects/getting-started/installation.md index 32e3b663..0f9639a7 100644 --- a/packages/docs/docs/addons/redirects/getting-started/installation.md +++ b/packages/docs/docs/addons/redirects/getting-started/installation.md @@ -32,12 +32,12 @@ After you've setup your license you can install the addon like so: ``` - yarn add @pluginpal/webtools-addon-redirects + yarn add strapi-plugin-webtools @pluginpal/webtools-addon-redirects ``` ``` - npm install @pluginpal/webtools-addon-redirects --save + npm install strapi-plugin-webtools @pluginpal/webtools-addon-redirects --save ``` diff --git a/packages/docs/docs/addons/sitemap/expansion/introduction.md b/packages/docs/docs/addons/sitemap/expansion/introduction.md index 3effdc9d..45bc73e0 100644 --- a/packages/docs/docs/addons/sitemap/expansion/introduction.md +++ b/packages/docs/docs/addons/sitemap/expansion/introduction.md @@ -25,12 +25,12 @@ Note that this package can only be installed after you've [setup your license](/ ``` - yarn add @pluginpal/webtools-addon-sitemap-expansion + yarn add strapi-plugin-webtools @pluginpal/webtools-addon-sitemap-expansion ``` ``` - npm install @pluginpal/webtools-addon-sitemap-expansion --save + npm install strapi-plugin-webtools @pluginpal/webtools-addon-sitemap-expansion --save ``` diff --git a/packages/docs/docs/getting-started/bulk-generate.md b/packages/docs/docs/getting-started/bulk-generate.md new file mode 100644 index 00000000..95f26bcb --- /dev/null +++ b/packages/docs/docs/getting-started/bulk-generate.md @@ -0,0 +1,24 @@ +--- +sidebar_label: 'Bulk generate' +displayed_sidebar: webtoolsSidebar +slug: /bulk-generate +--- + +import ThemedImage from '@theme/ThemedImage'; +import useBaseUrl from '@docusaurus/useBaseUrl'; + +# Bulk generate + +The Bulk Generate feature let's you re-generate the URLs of your website. + +This can be useful when you install website with **existing content** in your Strapi app. With the bulk generate feature you can then retroactively generate all the URLs for the pages. + +Another use-case is to run the Bulk Generator after **updating your URL patterns**. You can then run the Bulk Generator to update all the existing URLs to adhere to the new pattern. + + diff --git a/packages/docs/docs/migration/strapi-v4-to-v5.md b/packages/docs/docs/migration/strapi-v4-to-v5.md new file mode 100644 index 00000000..4d72e2c3 --- /dev/null +++ b/packages/docs/docs/migration/strapi-v4-to-v5.md @@ -0,0 +1,59 @@ +--- +sidebar_label: 'Strapi v4 to v5' +displayed_sidebar: webtoolsSidebar +slug: /migration/strapi-v4-to-v5.md +--- + +# Strapi v4 to v5 + +When you use Webtools in Strapi v4 and you want to migrate to Strapi v5 you can follow this guide. + +## New package names + +For starters the package name has changed. + +### Old package names + +```md title="package.json" +{ + "dependencies": { + "@pluginpal/webtools-core": "*", + "@pluginpal/webtools-addon-sitemap": "*" + } +} +``` + +### New package names + +```md title="package.json" +{ + "dependencies": { + "strapi-plugin-webtools": "*", + "webtools-addon-sitemap": "*" + } +} +``` + +## Schema change + +The new Strapi v5 plugin for Webtools changes the URL alias relations from a `oneToOne` to a `oneToMany`. To run the native Strapi v5 migration scripts together with the Webtools update you have to add a manual migration script that handles the schema change. + +```md title="database/migrations/add-url-alias-order-column.js" +module.exports = { + async up(knex) { + const tables = await knex('information_schema.tables') + .select('table_name') + .where('table_name', 'like', '%url_alias_links'); + + for (const table of tables) { + await knex.schema.hasColumn(table.table_name, 'url_alias_ord').then(async function(exists) { + if (!exists) { + await knex.schema.alterTable(table.table_name, (t) => { + t.integer('url_alias_ord'); + }); + } + }); + } + }, +}; +``` diff --git a/packages/docs/sidebars.ts b/packages/docs/sidebars.ts index 23814748..8d8f5f8f 100644 --- a/packages/docs/sidebars.ts +++ b/packages/docs/sidebars.ts @@ -26,6 +26,7 @@ const sidebars = { "getting-started/usage", "getting-started/url-pattern", "getting-started/url-alias", + "getting-started/bulk-generate", "getting-started/api-permissions", "getting-started/admin-permissions", "getting-started/troubleshooting", @@ -33,7 +34,7 @@ const sidebars = { }, { type: "category", - collapsed: false, + collapsed: true, label: "📦 API", items: [ "api/rest", @@ -42,7 +43,7 @@ const sidebars = { }, { type: "category", - collapsed: false, + collapsed: true, label: "📟 CLI", items: [ "cli/install", @@ -52,7 +53,7 @@ const sidebars = { }, { type: "category", - collapsed: false, + collapsed: true, label: "🔌 Addons", items: [ "addons/introduction", @@ -71,11 +72,16 @@ const sidebars = { label: "Links addon", href: '/addons/links', }, + { + type: "link", + label: "Breadcrumbs addon", + href: '/addons/breadcrumbs', + }, ], }, { type: "category", - collapsed: false, + collapsed: true, label: "⚙️ Configuration", items: [ "configuration/introduction", @@ -86,14 +92,14 @@ const sidebars = { "configuration/unique-per-locale", ], }, - // { - // type: "category", - // collapsed: false, - // label: "♻️ Upgrading", - // items: [ - // "upgrading/generic-update", - // ], - // }, + { + type: "category", + collapsed: true, + label: "♻️ Upgrading", + items: [ + "migration/strapi-v4-to-v5", + ], + }, ], webtoolsSitemapSidebar: [ @@ -135,7 +141,7 @@ const sidebars = { }, { type: "category", - collapsed: false, + collapsed: true, label: "⚙️ Settings", items: [ "addons/sitemap/settings/introduction", @@ -149,7 +155,7 @@ const sidebars = { }, { type: "category", - collapsed: false, + collapsed: true, label: "🔧 Configuration", items: [ "addons/sitemap/configuration/introduction", @@ -227,7 +233,16 @@ const sidebars = { "addons/links/getting-started/introduction", "addons/links/getting-started/installation", "addons/links/getting-started/custom-field", - "addons/links/getting-started/ckeditor", + ], + }, + { + type: "category", + collapsed: false, + label: "✨ Integrations", + items: [ + "addons/links/integrations/ckeditor", + "addons/links/integrations/magic-editor", + "addons/links/integrations/custom-text-editor", ], }, { @@ -236,6 +251,56 @@ const sidebars = { label: "📦 API", items: [ "addons/links/api/links-format", + "addons/links/api/rewrite-middleware", + ], + }, + { + type: "category", + collapsed: false, + label: "🔧 Configuration", + items: [ + "addons/links/configuration/introduction", + "addons/links/configuration/custom-links", + ], + }, + ], + }, + ], + + webtoolsBreadcrumbsSidebar: [ + { + type: "link", + label: "⬅️ Back to Webtools Core docs", + href: "/addons", + }, + { + type: "category", + collapsed: false, + label: "🔗 Breadcrumbs addon", + items: [ + { + type: "category", + collapsed: false, + label: "🚀 Getting Started", + items: [ + "addons/breadcrumbs/getting-started/introduction", + "addons/breadcrumbs/getting-started/installation", + ], + }, + { + type: "category", + collapsed: false, + label: "📦 API", + items: [ + "addons/breadcrumbs/api/rest", + ], + }, + { + type: "category", + collapsed: false, + label: "🔧 Settings", + items: [ + "addons/breadcrumbs/settings/introduction", ], }, ], diff --git a/packages/docs/static/img/assets/addons/breadcrumbs/breadcrumbs-permissions-light.png b/packages/docs/static/img/assets/addons/breadcrumbs/breadcrumbs-permissions-light.png new file mode 100644 index 00000000..469b8329 Binary files /dev/null and b/packages/docs/static/img/assets/addons/breadcrumbs/breadcrumbs-permissions-light.png differ diff --git a/packages/docs/static/img/assets/addons/breadcrumbs/breadcrumbs-settings-light.png b/packages/docs/static/img/assets/addons/breadcrumbs/breadcrumbs-settings-light.png new file mode 100644 index 00000000..63fadce4 Binary files /dev/null and b/packages/docs/static/img/assets/addons/breadcrumbs/breadcrumbs-settings-light.png differ diff --git a/packages/docs/static/img/assets/addons/links/magic-editor-light.png b/packages/docs/static/img/assets/addons/links/magic-editor-light.png new file mode 100644 index 00000000..1e556b26 Binary files /dev/null and b/packages/docs/static/img/assets/addons/links/magic-editor-light.png differ diff --git a/packages/docs/static/img/assets/addons/links/magic-editor-link-modal-light.png b/packages/docs/static/img/assets/addons/links/magic-editor-link-modal-light.png new file mode 100644 index 00000000..d07265a8 Binary files /dev/null and b/packages/docs/static/img/assets/addons/links/magic-editor-link-modal-light.png differ diff --git a/packages/docs/static/img/assets/bulk-generate-light.png b/packages/docs/static/img/assets/bulk-generate-light.png new file mode 100644 index 00000000..967b374b Binary files /dev/null and b/packages/docs/static/img/assets/bulk-generate-light.png differ