diff --git a/.changeset/green-wasps-follow.md b/.changeset/green-wasps-follow.md new file mode 100644 index 00000000..467c314e --- /dev/null +++ b/.changeset/green-wasps-follow.md @@ -0,0 +1,5 @@ +--- +"docs": minor +--- + +docs: add docs for the cli specifically diff --git a/.changeset/wide-lies-enter.md b/.changeset/wide-lies-enter.md new file mode 100644 index 00000000..1fc73cc6 --- /dev/null +++ b/.changeset/wide-lies-enter.md @@ -0,0 +1,5 @@ +--- +"docs": minor +--- + +docs: add docs for the Links addon, Redirects addon and enhance the docs in general diff --git a/README.md b/README.md index ec47716c..76cf75c2 100644 --- a/README.md +++ b/README.md @@ -1,54 +1,59 @@
-

Strapi Webtools

- -

Everything you need to build a website with Strapi CMS

- -Read the documentation - -

- - NPM Version - - - Monthly download on NPM - - - CI build status - - - codecov.io - -

- +

Strapi Webtools

+

Everything you need to build a website with Strapi CMS

+ +

+ Read the documentation → +

+ +

+ + NPM Version + + + Monthly download on NPM + + + CI build status + + + codecov.io + +

+--- + ## ✨ Features -- **Unique URLs** Every page will get their own unique path -- **Auto generated** Automatically generated based on a pattern -- **Flexible** Overwrite single URLs -- **Frontend router** Get any page by it's unique path from the public API -- **Auto slugify** The URLs will automatically be slugified to ensure valid paths +- Unique URLs – Every page gets its own unique path +- Auto-generated – Based on a configurable URL pattern +- Flexible – Override individual URLs when needed +- Frontend router – Fetch any page by its unique path via the public API +- Auto-slugify – Ensures valid, clean URL paths -## ⏳ Installation +## ✅ Requirements -[Read the Getting Started tutorial](https://docs.pluginpal.io/webtools) or follow the steps below: +- Node.js: >= 18.17 +- Strapi: v5.x -### Installer wizard +## ⏳ Installation -To provide easy installation, this plugin comes with it's own installer wizard. It let's you interactively select which content types you want to enable and which addons you want to install. Making it easy to get started with Webtools! +Read the full Getting Started guide in the docs, or run the installer. The command below executes the Webtools installer (webtools-cli) in your current project directory: ```bash npx webtools-cli install ``` -### Enabling +The installer lets you: +- Enable Webtools for selected content types +- Optionally install addons (e.g. Sitemap) -Using the installer wizard you can easily enable Webtools for your content types. If there are still more content-types you want to enable, you can do that manually through the admin panel. Read more about how to do that in the [usage documentation](https://docs.pluginpal.io/webtools/usage). +> Keyboard shortcuts: Space (toggle), a (all), i (invert), Enter (confirm) -### Building +### Build the admin -After successful installation you have to rebuild the admin UI so it'll include this plugin. To rebuild and restart Strapi run: +After installation, rebuild the Strapi admin so it includes the plugin: ```bash # using yarn @@ -60,32 +65,36 @@ npm run build npm run develop ``` -Enjoy 🎉 +## 🚀 Quick start -## 📓 Documentation +1) Enable Webtools for your content types (via the installer or Admin → Content-Type Builder) +2) Create URL patterns (Webtools → Patterns) +3) Bulk generate aliases (Webtools → All URLs) +4) Optionally set up the Sitemap addon (see docs) -The full documentation of this plugin can be found on it's dedicated documentation website. +Enjoy 🎉 -- [Webtools core plugin](https://docs.pluginpal.io/webtools) -- [Webtools sitemap addon](https://docs.pluginpal.io/webtools/addons/sitemap) +## 📓 Documentation +- Core plugin: https://docs.pluginpal.io/webtools +- Sitemap addon: https://docs.pluginpal.io/webtools/addons/sitemap ## 🔌 Addons -Webtools can be extended by installing addons that hook into the core Webtools functionality. Read more about how addons work and how to install them in the [addons documentation](https://docs.pluginpal.io/webtools/addons). +Webtools can be extended with addons that hook into the core. Learn more: https://docs.pluginpal.io/webtools/addons ## 🔗 Links -- [PluginPal marketplace](https://www.pluginpal.io/plugin/webtools) -- [NPM package](https://www.npmjs.com/package/strapi-plugin-webtools) -- [GitHub repository](https://github.com/pluginpal/strapi-webtools) -- [Strapi marketplace](https://market.strapi.io/plugins/@pluginpal-webtools-core) +- PluginPal marketplace: https://www.pluginpal.io/plugin/webtools +- NPM package: https://www.npmjs.com/package/strapi-plugin-webtools +- GitHub repository: https://github.com/pluginpal/strapi-webtools +- Strapi marketplace: https://market.strapi.io/plugins/@pluginpal-webtools-core ## 🌎 Community support -- For general help using Strapi, please refer to [the official Strapi documentation](https://strapi.io/documentation/). -- You can contact me on the Strapi Discord [channel](https://discord.strapi.io/). +- For Strapi usage questions, see the official docs: https://strapi.io/documentation/ +- Chat on Strapi Discord: https://discord.strapi.io/ -## 📝 Resources +## 📝 License -- [MIT License](https://github.com/pluginpal/strapi-webtools/blob/master/LICENSE.md) +MIT — https://github.com/pluginpal/strapi-webtools/blob/master/LICENSE.md diff --git a/packages/docs/docs/addons/introduction.md b/packages/docs/docs/addons/introduction.md index eac07f68..24ed00ba 100644 --- a/packages/docs/docs/addons/introduction.md +++ b/packages/docs/docs/addons/introduction.md @@ -11,5 +11,7 @@ Webtools is all about tools to enhance your website management workflow in Strap To enhance Webtools in a modular way, the core plugin allows addons to be registered to build upon it's functionalities. Addons are in Strapi terms just standalone plugins, but have `strapi-plugin-webtools` as a peer dependency. You will have to install each addon as you would normally install a plugin in to Strapi. - + + + diff --git a/packages/docs/docs/addons/links/api/links-format.md b/packages/docs/docs/addons/links/api/links-format.md new file mode 100644 index 00000000..9c5d64ce --- /dev/null +++ b/packages/docs/docs/addons/links/api/links-format.md @@ -0,0 +1,18 @@ +--- +sidebar_label: 'Links format' +displayed_sidebar: webtoolsLinksSidebar +slug: /addons/links/api/links-format +--- + +# Rewrite middleware + +This plugin stores the internal links in a specific format. That format looks something like this: + +``` +wt-link://api::page.page/sp8bzbkn21pjy3m9wsf97dio +``` + +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. + diff --git a/packages/docs/docs/addons/links/getting-started/ckeditor.md b/packages/docs/docs/addons/links/getting-started/ckeditor.md new file mode 100644 index 00000000..f59a8b04 --- /dev/null +++ b/packages/docs/docs/addons/links/getting-started/ckeditor.md @@ -0,0 +1,14 @@ +--- +sidebar_label: 'Ckeditor' +displayed_sidebar: webtoolsLinksSidebar +slug: /addons/links/ckeditor +--- + +# Ckeditor integration +This addon has an integration with [the Ckeditor plugin](https://github.com/nshenderov/strapi-plugin-ckeditor). If the Ckeditor plugin is installed this addon will replace the link button in the editor. With this new button you can create internal links in the ckeditor. + +Ckeditor + +If you click the link button it will open a modal in which you can manage your links. + +Ckeditor link modal diff --git a/packages/docs/docs/addons/links/getting-started/custom-field.md b/packages/docs/docs/addons/links/getting-started/custom-field.md new file mode 100644 index 00000000..8dc583ff --- /dev/null +++ b/packages/docs/docs/addons/links/getting-started/custom-field.md @@ -0,0 +1,10 @@ +--- +sidebar_label: 'Custom field' +displayed_sidebar: webtoolsLinksSidebar +slug: /addons/links/custom-field +--- + +# Custom field +This addon introduces a new custom field which you can add to your content types. This field can be used in your content types to accommodate internal linking from one page to another. + +Link custom field diff --git a/packages/docs/docs/addons/links/getting-started/installation.md b/packages/docs/docs/addons/links/getting-started/installation.md new file mode 100644 index 00000000..ac8c9051 --- /dev/null +++ b/packages/docs/docs/addons/links/getting-started/installation.md @@ -0,0 +1,62 @@ +--- +sidebar_label: 'Installation' +displayed_sidebar: webtoolsLinksSidebar +slug: /addons/links/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 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 @pluginpal/webtools-addon-links + ``` + + + ``` + npm install @pluginpal/webtools-addon-links --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/links/getting-started/introduction.md b/packages/docs/docs/addons/links/getting-started/introduction.md new file mode 100644 index 00000000..e308050b --- /dev/null +++ b/packages/docs/docs/addons/links/getting-started/introduction.md @@ -0,0 +1,23 @@ +--- +sidebar_label: 'Introduction' +displayed_sidebar: webtoolsLinksSidebar +slug: /addons/links +--- + +# Webtools Links Add-on + +The **Links add-on** for Webtools Pro provides a powerful custom field type that allows content creators to easily create internal links within their Strapi CMS content. This field type streamlines the process of linking to other content entries, pages, or sections within your application. + +:::note +This plugin acts as an extension of the core `strapi-plugin-webtools`. Please install and configure that before proceeding. +::: + +## Key Features + +- **🔗 Internal Link Management** - Easy selection of internal content for linking +- **⚡ Custom field** - Add the link field to any content type +- **⚡ Ckeditor integration** - Integrate the dynamic links in to your ckeditor +- **🔍 Smart Search** - Find content quickly with built-in search functionality +- **📝 Content Type Support** - Works with all your custom content types +- **🎨 Intuitive UI** - Clean, user-friendly interface integrated with Strapi's design system + diff --git a/packages/docs/docs/addons/links/getting-started/link-component.md b/packages/docs/docs/addons/links/getting-started/link-component.md new file mode 100644 index 00000000..34757d81 --- /dev/null +++ b/packages/docs/docs/addons/links/getting-started/link-component.md @@ -0,0 +1,35 @@ +--- +sidebar_label: 'Link component' +displayed_sidebar: webtoolsLinksSidebar +slug: /addons/links/link-component +--- + +# Link component +This addon provides a custom field for you to create internal linking. It's good to note that the custom field only provides you a way to set the URL value of a link. We recommend you to create a Component in your Strapi application which combines all the attributes needed to create a link. This can also include the link text and other possible attributes like target. + +This component can then be used to as a reference field anywhere you need it. + +Link component + +The schema of this link component can look something like this: + +``` +{ + "collectionName": "components_core_links", + "info": { + "displayName": "Link" + }, + "options": {}, + "attributes": { + "Text": { + "type": "string" + "required": true, + }, + "Link": { + "type": "customField", + "required": true, + "customField": "plugin::webtools-addon-links.link" + } + } +} +``` diff --git a/packages/docs/docs/addons/redirects/api/rest.md b/packages/docs/docs/addons/redirects/api/rest.md new file mode 100644 index 00000000..6ef5dfec --- /dev/null +++ b/packages/docs/docs/addons/redirects/api/rest.md @@ -0,0 +1,81 @@ +--- +sidebar_label: 'Rest API' +displayed_sidebar: webtoolsRedirectsSidebar +slug: /addons/redirects/api/rest +--- + +# REST API + +## Overview + +The plugin exposes a REST API endpoint that you can use to implement the redirects in your front-end of choice. + +### Authentication + +Use Public role or API Tokens as per Strapi defaults. + + + + + +`GET http://localhost:1337/api/webtools/redirects` + + + + +``` +{ + "data": [ + { + "id": 1, + "documentId": "yk4tcq7bd51cdqt7qk9gu5v6", + "from": "/old-url", + "to": "/new-url", + "status_code": 307, + "createdAt": "2025-09-07T13:03:00.877Z", + "updatedAt": "2025-09-07T13:03:00.877Z", + "publishedAt": "2025-09-07T13:03:00.873Z" + }, + { + "id": 2, + "documentId": "zl1ec15d8uuph7250epetorg", + "from": "/campaign", + "to": "/my-blog-post", + "status_code": 302, + "createdAt": "2025-09-07T13:03:22.444Z", + "updatedAt": "2025-09-07T13:03:22.444Z", + "publishedAt": "2025-09-07T13:03:22.442Z" + }, + { + "id": 3, + "documentId": "ps5hqbk3idsanua30w8udvxe", + "from": "/blogs", + "to": "/articles", + "status_code": 307, + "createdAt": "2025-09-07T13:03:41.516Z", + "updatedAt": "2025-09-07T13:03:41.516Z", + "publishedAt": "2025-09-07T13:03:41.515Z" + } + ], + "meta": { + "pagination": { + "page": 1, + "pageSize": 25, + "pageCount": 1, + "total": 3 + } + } +} +``` + + + + +## Permissions + +Before you can use the redirects endpoint publicly, you need to configure the *find* permission. + +### Quick Setup + +Enable in **Settings > Users & Permissions > Roles > Public**: +- `webtools-addon-redirects.redirect.find` diff --git a/packages/docs/docs/addons/redirects/configuration/auto-generate.md b/packages/docs/docs/addons/redirects/configuration/auto-generate.md new file mode 100644 index 00000000..229c20ca --- /dev/null +++ b/packages/docs/docs/addons/redirects/configuration/auto-generate.md @@ -0,0 +1,13 @@ +--- +sidebar_label: 'Auto generate' +displayed_sidebar: webtoolsRedirectsSidebar +slug: /addons/redirects/configuration/auto-generate +--- + +# Auto generate + +When this option is set to true (which it is by default) the addon will automatically generate a redirect whenever you change the URL alias of a page. This way you will never have dead links in your website! + +###### Key: `auto_generate ` + +> `required:` NO | `type:` bool | `default:` true diff --git a/packages/docs/docs/addons/redirects/configuration/default-status-code.md b/packages/docs/docs/addons/redirects/configuration/default-status-code.md new file mode 100644 index 00000000..2327426b --- /dev/null +++ b/packages/docs/docs/addons/redirects/configuration/default-status-code.md @@ -0,0 +1,13 @@ +--- +sidebar_label: 'Cron' +displayed_sidebar: webtoolsRedirectsSidebar +slug: /addons/redirects/configuration/default-status-code +--- + +# Default status code + +This is the default status code that is used when new redirects are created. It does not matter if they are created through the admin interface, the document service or automatically generated, it will always use this default status code except when you overwrite it. + +###### Key: `default_status_code` + +> `required:` NO | `type:` bool | `default:` 307 diff --git a/packages/docs/docs/addons/redirects/configuration/introduction.md b/packages/docs/docs/addons/redirects/configuration/introduction.md new file mode 100644 index 00000000..b2425928 --- /dev/null +++ b/packages/docs/docs/addons/redirects/configuration/introduction.md @@ -0,0 +1,21 @@ +--- +sidebar_label: 'Introduction' +displayed_sidebar: webtoolsRedirectsSidebar +slug: /addons/redirects/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-redirects': { + enabled: true, + config: { + default_status_code: 307, + auto_generate: true, + }, + }, +}); +``` diff --git a/packages/docs/docs/addons/redirects/getting-started/installation.md b/packages/docs/docs/addons/redirects/getting-started/installation.md new file mode 100644 index 00000000..32e3b663 --- /dev/null +++ b/packages/docs/docs/addons/redirects/getting-started/installation.md @@ -0,0 +1,62 @@ +--- +sidebar_label: 'Installation' +displayed_sidebar: webtoolsRedirectsSidebar +slug: /addons/redirects/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 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 @pluginpal/webtools-addon-redirects + ``` + + + ``` + npm install @pluginpal/webtools-addon-redirects --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/redirects/getting-started/introduction.md b/packages/docs/docs/addons/redirects/getting-started/introduction.md new file mode 100644 index 00000000..501bd6f9 --- /dev/null +++ b/packages/docs/docs/addons/redirects/getting-started/introduction.md @@ -0,0 +1,22 @@ +--- +sidebar_label: 'Introduction' +displayed_sidebar: webtoolsRedirectsSidebar +slug: /addons/redirects +--- + +# Webtools Redirects addon + +This plugin offers the ability to configure **server-side redirects**. It integrates with Strapi Webtools to automatically generate redirects whenever the URL alias of a page changes. + +:::note +This plugin acts as an extension of the core `strapi-plugin-webtools`. Please install and configure that before proceeding. +::: + +## ✨ Features + +- **Automatic creation** (Automatic redirect creation when your URL changes) +- **Chain detection** (Prevents you from creating redirects that create chains) +- **Loop detection** (Prevents you from creating redirects that create loops) +- **Custom redirects** (Create custom redirects, separate from Webtools pages) +- **API endpoint** (Fetch and use the redirects in your front-end) + diff --git a/packages/docs/docs/addons/redirects/getting-started/usage.md b/packages/docs/docs/addons/redirects/getting-started/usage.md new file mode 100644 index 00000000..378ac723 --- /dev/null +++ b/packages/docs/docs/addons/redirects/getting-started/usage.md @@ -0,0 +1,29 @@ +--- +sidebar_label: 'Usage' +displayed_sidebar: webtoolsRedirectsSidebar +slug: /addons/redirects/usage +--- + +# 💡 Usage +With this plugin you have full control over which redirects should be active for your front-end. You can create, update and delete redirects right from the Strapi admin panel. + +## Overview + +On the redirects overview you can see all the redirects on your site. + +Redirects overview + +## Create redirects + +With the button in the top right you can create new redirects. + +Create redirects + +## Access +After you've followed the steps above you can now access your sitemap through the REST api of strapi. It will be available at: + +http://localhost:1337/api/webtools/redirects. + +:::caution +You might have to setup permissions for this endpoint to be accessible. +::: diff --git a/packages/docs/docs/addons/sitemap/getting-started/cli.md b/packages/docs/docs/addons/sitemap/getting-started/cli.md index 52bb4258..f666eecc 100644 --- a/packages/docs/docs/addons/sitemap/getting-started/cli.md +++ b/packages/docs/docs/addons/sitemap/getting-started/cli.md @@ -6,7 +6,8 @@ slug: /addons/sitemap/cli # 📺 CLI -This plugin comes with it's own `strapi-sitemap` CLI. +This addon includes its own `strapi-sitemap` CLI. This is separate from the core Webtools CLI used during installation/enabling. For core Webtools installation and enabling content types, see the [Installation guide](/webtools/). + You can add it to your project like so: ``` diff --git a/packages/docs/docs/addons/sitemap/settings/hostname.md b/packages/docs/docs/addons/sitemap/settings/hostname.md index c3de53a3..05442756 100644 --- a/packages/docs/docs/addons/sitemap/settings/hostname.md +++ b/packages/docs/docs/addons/sitemap/settings/hostname.md @@ -8,6 +8,10 @@ slug: /addons/sitemap/settings/hostname The hostname is the URL of your website. It will be used as the base URL of all URLs added to the sitemap XML. It is required to generate the XML file. +:::note +This setting belongs to the Sitemap addon and is not the same as the core Webtools "Website URL" configuration used for permalinks. For the core setting, see [Website URL](/webtools/configuration/website-url). +::: + ###### Key: `hostname` > `required:` YES | `type:` string | `default:` '' diff --git a/packages/docs/docs/api/graphql.md b/packages/docs/docs/api/graphql.md index 5e60a0ad..d40804e7 100644 --- a/packages/docs/docs/api/graphql.md +++ b/packages/docs/docs/api/graphql.md @@ -6,6 +6,7 @@ slug: /api/graphql # GraphQL API -As of writing this page there is no GraphQL API exposed by the Webtools core plugin. You might be able to still get most of it's functionality by querying the native Strapi GraphQL API, but this is not officially supported at this time. +## Overview + +As of writing this page there is no GraphQL API exposed by the Webtools core plugin. You might be able to still get most of its functionality by querying the native Strapi GraphQL API, but this is not officially supported at this time. -If you want this feature to happen, go get involved on Github! Webtools is a rapidly growing plugin suitte for Strapi and community feedback is always appreciated. diff --git a/packages/docs/docs/api/rest.md b/packages/docs/docs/api/rest.md index c4810ef9..99848ef6 100644 --- a/packages/docs/docs/api/rest.md +++ b/packages/docs/docs/api/rest.md @@ -6,8 +6,14 @@ slug: /api/rest # REST API +## Overview + The plugin exposes a couple of REST API endpoints that you can use to implement Webtools in your front-end of choice. +### Authentication + +Use Public role or API Tokens as per Strapi defaults. + ## Router Probably the most important endpoint of the plugin is it's router endpoint. @@ -58,6 +64,18 @@ This endpoint is just a native findMany endpoint exposed to query multiple URL a As it's a native findMany endpoint you can use all the parameters you're used to like `populate`, `filters` and `fields`. +### Lookup Single URL + +To find a specific URL alias, use Strapi's filter syntax: + +```bash +GET http://localhost:1337/api/webtools/url-alias?filters[url_path][$eq]=/your-path +``` + +:::warning Filter Syntax +The query parameter `?url_path=` does not work correctly. Always use the full filter syntax: `?filters[url_path][$eq]=` to lookup specific URLs. +::: + @@ -137,3 +155,18 @@ As it's a native findMany endpoint you can use all the parameters you're used to + +## Permissions + +Before you can use the router and url-alias endpoints publicly, you need to configure the *find* permissions. + +### Quick Setup + +Enable in **Settings > Users & Permissions > Roles > Public**: +- `webtools.url-alias.find` +- `webtools.router.find` + +For each enabled content type, also enable: +- `[content-type].find` + +See [Permissions](/permissions) for a complete explanation of all three permission levels that need to be configured. diff --git a/packages/docs/docs/cli/enable.md b/packages/docs/docs/cli/enable.md new file mode 100644 index 00000000..dbaafb66 --- /dev/null +++ b/packages/docs/docs/cli/enable.md @@ -0,0 +1,17 @@ +--- +sidebar_label: 'Enable' +displayed_sidebar: webtoolsSidebar +slug: /cli/enable +--- + +# Enable + +## Overview + +This command let's you interactively enable Webtools for your content types. It's essentially a programmatic interface for the docs as written on [the Usage docs](/usage). + +## Usage + +``` +npx webtools-cli enable +``` diff --git a/packages/docs/docs/cli/install.md b/packages/docs/docs/cli/install.md new file mode 100644 index 00000000..2f32141f --- /dev/null +++ b/packages/docs/docs/cli/install.md @@ -0,0 +1,22 @@ +--- +sidebar_label: 'Install' +displayed_sidebar: webtoolsSidebar +slug: /cli/install +--- + +# Install + +## Overview + +The install command is used when you're first installing Webtools in your Strapi project. It helps you to setup your license, enable Webtools for your content types, and select the addons you want to install. + +## Usage + +``` +npx webtools-cli install +``` + +Apart from installing the packages, the functions of this command can also be ran separately. + +1. [The `enable` command](/cli/enable) +2. [The `setup-license` command](/cli/setup-license) diff --git a/packages/docs/docs/cli/setup-license.md b/packages/docs/docs/cli/setup-license.md new file mode 100644 index 00000000..4f1df7d7 --- /dev/null +++ b/packages/docs/docs/cli/setup-license.md @@ -0,0 +1,17 @@ +--- +sidebar_label: 'Setup License' +displayed_sidebar: webtoolsSidebar +slug: /cli/setup-license +--- + +# Setup license + +## Overview + +If you've purchased a license for the premium features of Webtools you can use this CLI to setup the configuration for proper installation and license validation. The CLI will ask you to input your license key which will be added to the `.npmrc` and `.env` files. + +## Usage + +``` +npx webtools-cli setup-license +``` diff --git a/packages/docs/docs/configuration/default-pattern.md b/packages/docs/docs/configuration/default-pattern.md index dba919b4..a53522ed 100644 --- a/packages/docs/docs/configuration/default-pattern.md +++ b/packages/docs/docs/configuration/default-pattern.md @@ -8,6 +8,8 @@ slug: /configuration/default-pattern Webtools allows you to create custom URL patterns, specifically tweaked to your requirements. The default pattern acts as a fallback, for when you have not set an URL pattern for a specific content type. This fallback will then be used to generate the URLs for this content type. +For a quick conceptual overview, see [URL pattern](/webtools/url-pattern). For path formatting rules, see [Slugify](/webtools/configuration/slugify). + | Name | Details | | ---- | ------- | | Key | `default_pattern` | diff --git a/packages/docs/docs/configuration/introduction.md b/packages/docs/docs/configuration/introduction.md index 42b94bff..2ae9d43e 100644 --- a/packages/docs/docs/configuration/introduction.md +++ b/packages/docs/docs/configuration/introduction.md @@ -5,8 +5,9 @@ slug: /configuration --- # 🔧 Configuration -The settings 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. +The plugin works with default settings out of the box. You can optionally override settings in your `config/plugins.js` (or `config/plugins.ts`) file. + +The example below shows all available configuration options with their default values: ```md title="config/plugins.js" import deburr from 'lodash/deburr'; @@ -19,8 +20,32 @@ export default ({ env }) => ({ config: { default_pattern: "/[pluralName]/[documentId]", website_url: null, + unique_per_locale: false, slugify: (fieldValue) => kebabCase(deburr(toLower(fieldValue))), }, }, }); ``` + +## Configuration options overview + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `default_pattern` | string | `/[pluralName]/[documentId]` | Fallback pattern when no specific pattern is set for a content type | +| `website_url` | string | `null` | Base URL for permalink generation in admin UI | +| `slugify` | function | `kebabCase(deburr(toLower()))` | Transform field values into URL-safe slugs (converts "My Title" to "my-title") | +| `unique_per_locale` | boolean | `false` | Allow same URL alias across different locales | + +## URL bundle settings (sitemap) + +When configuring sitemap URL bundles, each bundle supports: + +| Setting | Options | Description | +|---------|---------|-------------| +| **Change frequency** | `hourly`, `daily`, `weekly`, `monthly`, `yearly` | How often search engines should crawl these URLs | +| **Priority** | `0.1` - `1.0` | Relative importance of URLs in this bundle | +| **Default language URL type** | `Disabled`, `Default language URL of bundles`, `Other` | How default locale appears in URLs | + +:::tip Pattern tokens +Available tokens for URL patterns: `[documentId]`, `[locale]`, `[pluralName]`, and any field from your content type. Type `[` in the pattern field to see all available options. +::: diff --git a/packages/docs/docs/configuration/slugify.md b/packages/docs/docs/configuration/slugify.md index ca2f7023..ece1c9f7 100644 --- a/packages/docs/docs/configuration/slugify.md +++ b/packages/docs/docs/configuration/slugify.md @@ -8,6 +8,8 @@ slug: /configuration/slugify This config can be used to overwrite the function that is used to slugify your URLs. The function takes a single parameter which is the path before being slugified. It expects the return value to be the slugified URL. +For an introduction to patterns and how slugs are derived, see [URL pattern](/webtools/url-pattern). For the fallback behavior, see [Default pattern](/webtools/configuration/default-pattern). + ### Example: ```md title="config/plugins.js" diff --git a/packages/docs/docs/configuration/website-url.md b/packages/docs/docs/configuration/website-url.md index da7b00b7..e86307e2 100644 --- a/packages/docs/docs/configuration/website-url.md +++ b/packages/docs/docs/configuration/website-url.md @@ -8,6 +8,10 @@ slug: /configuration/website-url The website URL config is a handy tool that can be used to add a `copy permalink` button to the sidebar of the edit view. When Webtools knows what the absolute URL of your website is, we can combine that with the URL alias to get you your permalinks. +:::note +This setting is part of the core Webtools configuration and is not the same as the Sitemap addon "Hostname" setting. For Sitemap hostname, see [Hostname](/webtools/addons/sitemap/settings/hostname). +::: + | Name | Details | | ---- | ------- | | Key | `website_url` | diff --git a/packages/docs/docs/getting-started/installation.md b/packages/docs/docs/getting-started/installation.md index 8aa16c1c..8b1c4aca 100644 --- a/packages/docs/docs/getting-started/installation.md +++ b/packages/docs/docs/getting-started/installation.md @@ -8,23 +8,43 @@ slug: / :::prerequisites Complete installation requirements are the exact same as for Strapi itself and can be found in the Strapi documentation. -::: -### Supported versions +**Additional Requirements:** +- **Node.js**: Version 18 or higher +- **Strapi**: Version 5.x -- Strapi v5 +::: ### Installation -To install the plugin run the following command. +To install the plugin run the following command in your Strapi project directory. This invokes the core Webtools CLI (webtools-cli). -``` +```bash npx webtools-cli install ``` +### Command Line Interface (installer) + +During installation the Webtools CLI guides you through a short wizard: +- Select content types to enable Webtools for +- Optionally select addons to install (e.g. Sitemap) + +CLI: select content types + +CLI: select addons to install + +:::tip Keyboard shortcuts +In the selector you can use: + +- Space — toggle selection +- a — toggle all +- i — invert selection +- Enter — proceed +::: + ### Enabling -The installer wizard will ask you which content-types you want to enable. Select the content types that you consider to be web-pages in your website front-end. Each content-type you select will get it's own unique URL which can be used on the front-end. Read more about enabling content-types in the [usage documentation](/webtools/usage). +The installer wizard will ask you which content types you want to enable. Select the content types that you consider to be web pages in your website front-end. Each content type you select will get its own unique URL which can be used on the front-end. Read more about enabling content types in the [usage documentation](/webtools/usage). ### Building @@ -45,3 +65,7 @@ After successful installation you have to rebuild the admin UI so it'll include +### Post-install checklist + +- Enable Webtools per content type → see [Usage](/webtools/usage) +- Review Roles & Permissions → see [Permissions](/webtools/permissions) diff --git a/packages/docs/docs/getting-started/permissions.md b/packages/docs/docs/getting-started/permissions.md new file mode 100644 index 00000000..15e3d3b9 --- /dev/null +++ b/packages/docs/docs/getting-started/permissions.md @@ -0,0 +1,75 @@ +--- +sidebar_label: 'Permissions' +displayed_sidebar: webtoolsSidebar +slug: /permissions +--- + +# 🔐 Role-Based Access Control (RBAC) + +After installation, review Webtools permissions per role in Settings so your front-end can access the required endpoints. + +Without the proper permissions, you'll get a **403 Forbidden** error when calling: +- `GET /api/webtools/router?path=…` +- `GET /api/webtools/url-alias` + +Below are the three permission categories you need to configure. + +--- + +## 1. Content-Type "find" permissions + +For each content-type where you've enabled Webtools, you need to open up the standard **find** permission. + +1. Go to **Strapi Admin → Settings → Users & Permissions plugin → Roles**. +2. Select the role (e.g., **Public**). +3. Under **Application** you'll find your enabled content-types (e.g., `page`, `article`). +4. Check **Find** (and **Find One** if desired). +5. Click **Save**. + +Content Type Find permissions + +--- + +## 2. Webtools plugin permissions + +Enable the Webtools endpoints for your front-end: + +1. In the same role (e.g., **Public**) scroll to the **Webtools** section. +2. Check: + - **Router: find** + - **URL Alias: find** +3. Click **Save**. + +Webtools Router & URL Alias find permissions + +--- + +## 3. Admin Panel roles + +Want your editors/admins to manage Webtools settings? Configure: + +1. Go to **Strapi Admin → Settings → Administration Panel → Roles**. +2. Choose the role (e.g., **Author**). +3. Under **Plugins** → **Webtools** enable the permissions you need: + - **Access the URL alias list** + - **Access the URL alias patterns** + - **Access the URL alias sidebar** +4. Click **Save**. + +Admin Panel Webtools access rights + +--- + +## Test your permissions + +After saving: + +```bash +curl "http://localhost:1337/api/webtools/router?path=/about-page" +``` + +You should now receive data instead of a 403 error. + +:::tip +Restart Strapi after making changes and clear the cache if necessary. +::: diff --git a/packages/docs/docs/getting-started/troubleshooting.md b/packages/docs/docs/getting-started/troubleshooting.md new file mode 100644 index 00000000..2e1017ab --- /dev/null +++ b/packages/docs/docs/getting-started/troubleshooting.md @@ -0,0 +1,143 @@ +--- +sidebar_label: 'Troubleshooting' +displayed_sidebar: webtoolsSidebar +slug: /troubleshooting +--- + +# 🔧 Troubleshooting + +Common issues and solutions when working with Strapi Webtools. + +## Installation Issues + +### Node.js version error +``` +The engine "node" is incompatible with this module. Expected version ">=18" +``` + +**Solution:** Update Node.js to version 18 or higher: +```bash +nvm install 18 +nvm use 18 +``` + +### Peer dependency warnings +Multiple warnings about unmet peer dependencies during installation. + +**Solution:** These warnings are normal and won't affect functionality. The plugin will work correctly despite these warnings. + +## Pattern & URL Issues + +### URL is incorrect +The Webtools plugin applies it's own slugify function to your URLs. That means that if you have already have a slugified field, which you then use in an URL pattern, it will be slugified again, potentially causing incorrect URLs. If you want you can disable the slugify function of Webtools by updating the slugify configuration. + +See [slugify configuration docs](/configuration/slugify) + +### Can't select field in pattern +When creating URL patterns, some content types don't show field options. + +**Possible causes:** +- Content type has internationalization enabled +- Content type has no suitable fields for URL generation +- Browser cache issue - try hard refresh (Ctrl+R) + +### Locale required +Some content types require locale selection when creating patterns. + +**Explanation:** Multi-language content types need locale-specific patterns. This is normal behavior for internationalized content. + +### Multiple content type bundles +Content types can be selected multiple times in sitemap bundles. + +**Use case:** Each bundle can have different settings (change frequency, priority, locale-specific configurations). + +## Sitemap Issues + +### Invalid URL error (500) +``` +TypeError [ERR_INVALID_URL]: Invalid URL +``` + +**Solution:** Ensure hostname includes protocol prefix: +- ✅ Correct: `http://localhost:1337` +- ❌ Wrong: `localhost:1337` + +### Generate sitemap button stuck +UI becomes unresponsive after sitemap generation error (usually caused by incorrect hostname format). + +**Solution:** Hard refresh browser (Ctrl+R) to reset the interface state. + +### Router permissions error +500 error when generating sitemap, even with correct URL format. + +**Solution:** Enable router permissions in **Settings > Users & Permissions > Public**: +- `webtools.router.find` + +## API Issues + +### Returns all URLs instead of one +```bash +curl "localhost:1337/api/webtools/url-alias?url_path=/my-path" +# Returns all URLs, not just the requested one +``` + +**Solution:** Use Strapi's filter syntax: +```bash +curl "localhost:1337/api/webtools/url-alias?filters[url_path][$eq]=/my-path" +``` + +### 403 forbidden error +```json +{"error": {"status": 403, "name": "ForbiddenError"}} +``` + +**Solution:** Enable webtools permissions in **Settings > Users & Permissions > Public**: +- `webtools.url-alias.find` +- `webtools.router.find` + +### CORS Errors in Development +``` +Origin null is not allowed by Access-Control-Allow-Origin +``` + +**Solution:** Add development origins to `config/middlewares.ts`: +```js +{ + name: 'strapi::cors', + config: { + origin: [ + 'http://localhost:3000', + 'file://', + 'null' + ] + } +} +``` + +## Configuration Issues + +### Default Language URL Type +Controls how the default locale appears in URLs: + +- **Disabled**: All URLs use same format `/path` +- **Default language URL of bundles**: Default locale gets `/en/path`, others `/nl/path` +- **Other**: Custom locale handling + +Choose based on your multilingual URL structure needs. + +### URL Bundle Configuration +Each content type can have multiple bundles with different: +- Change frequency (hourly, daily, monthly) +- Priority settings (0.1 - 1.0) +- Locale-specific configurations + +This allows fine-grained control over how different content appears in your sitemap. + +## Still Having Issues? + +1. **Check server logs** for detailed error messages +2. **Restart Strapi** after configuration changes +3. **Clear browser cache** if UI behaves unexpectedly +4. **Verify permissions** are correctly set for all required endpoints + +If problems persist, check the [GitHub issues](https://github.com/pluginpal/strapi-webtools/issues) or create a new issue with your configuration details. diff --git a/packages/docs/docs/getting-started/url-pattern.md b/packages/docs/docs/getting-started/url-pattern.md index 689c2f15..49eef7d7 100644 --- a/packages/docs/docs/getting-started/url-pattern.md +++ b/packages/docs/docs/getting-started/url-pattern.md @@ -7,7 +7,9 @@ slug: /url-pattern # 🔌 URL pattern To create dynamic URLs this plugin uses **URL patterns**. The URL pattern will be used to generate unique URLs based on the data available. -You can add URL patterns in the settings section of the plugin. +You can add URL patterns in the settings section of the plugin. For configuration details and fallbacks, see [Default pattern](/webtools/configuration/default-pattern) and [Slugify](/webtools/configuration/slugify). + +URL patterns overview ``` /pages/[my-title-field] @@ -15,6 +17,10 @@ You can add URL patterns in the settings section of the plugin. Fields can be injected in the pattern by escaping them with `[]`. +:::tip Pattern discovery +Type `[` in the pattern field to see all available fields from your content type. +::: + The following field types are allowed in a pattern: - `documentId` @@ -23,4 +29,4 @@ The following field types are allowed in a pattern: See below a screenshot of the URL pattern creation form in Strapi. -URL pattern +Add new pattern with field suggestions diff --git a/packages/docs/docs/getting-started/usage.md b/packages/docs/docs/getting-started/usage.md index 25747f25..28eec2f7 100644 --- a/packages/docs/docs/getting-started/usage.md +++ b/packages/docs/docs/getting-started/usage.md @@ -5,8 +5,13 @@ slug: /usage --- # 💡 Usage + This plugin is specifically designed for usage in Strapi managed websites. Hence the name **web**tools. The plugin offers a variety of functionalities which you'll have to manually enable. +:::note +Webtools needs to be enabled per content type. This is typically done during installation using the CLI selector, but can also be enabled later via the Admin interface or manually in the schema. +::: + ## Enabling Webtools Once you enable Webtools for a content-type each entry of that type will get it's own unique URL alias. That alias can be used as the slug of your page in the front-end. To enable Webtools, you have a few options. @@ -25,6 +30,12 @@ You can also use the Webtools CLI to enable Webtools for your content types. Thi npx webtools-cli enable ``` +The CLI presents a selector where you can: +- Choose content types to enable Webtools for +- Optionally select addons to install (e.g. Sitemap) + +Keyboard shortcuts: Space (toggle), a (all), i (invert), Enter (confirm). + ### Manually :::tip @@ -36,4 +47,18 @@ pluginOptions: { enabled: true, }, }, +``` ::: + +## Workflow + +After enabling Webtools for your content types: + +1. **Create URL patterns** - See [URL pattern](/url-pattern) documentation +2. **Bulk generate URLs** - Go to Webtools > All URLs to create aliases for existing content +3. **Generate sitemap** - Configure and generate XML sitemap with your URLs + +:::tip Pattern discovery +Type `[` in the pattern field to see available fields from your content type. +::: + diff --git a/packages/docs/sidebars.ts b/packages/docs/sidebars.ts index 6b34797b..fd65905e 100644 --- a/packages/docs/sidebars.ts +++ b/packages/docs/sidebars.ts @@ -24,8 +24,10 @@ const sidebars = { items: [ "getting-started/installation", "getting-started/usage", - "getting-started/url-alias", "getting-started/url-pattern", + "getting-started/url-alias", + "getting-started/permissions", + "getting-started/troubleshooting", ], }, { @@ -37,6 +39,16 @@ const sidebars = { "api/graphql", ], }, + { + type: "category", + collapsed: false, + label: "📟 CLI", + items: [ + "cli/install", + "cli/enable", + "cli/setup-license", + ], + }, { type: "category", collapsed: false, @@ -48,6 +60,16 @@ const sidebars = { label: "Sitemap addon", href: '/addons/sitemap', }, + { + type: "link", + label: "Redirects addon", + href: '/addons/redirects', + }, + { + type: "link", + label: "Links addon", + href: '/addons/links', + }, ], }, { @@ -125,6 +147,83 @@ const sidebars = { ], }, ], + + webtoolsRedirectsSidebar: [ + { + type: "link", + label: "⬅️ Back to Webtools Core docs", + href: "/addons", + }, + { + type: "category", + collapsed: false, + label: "🔀 Redirects addon", + items: [ + { + type: "category", + collapsed: false, + label: "🚀 Getting Started", + items: [ + "addons/redirects/getting-started/introduction", + "addons/redirects/getting-started/installation", + "addons/redirects/getting-started/usage", + ], + }, + { + type: "category", + collapsed: false, + label: "📦 API", + items: [ + "addons/redirects/api/rest", + ], + }, + { + type: "category", + collapsed: false, + label: "🔧 Configuration", + items: [ + "addons/redirects/configuration/introduction", + "addons/redirects/configuration/auto-generate", + "addons/redirects/configuration/default-status-code", + ], + }, + ], + }, + ], + + webtoolsLinksSidebar: [ + { + type: "link", + label: "⬅️ Back to Webtools Core docs", + href: "/addons", + }, + { + type: "category", + collapsed: false, + label: "🔗 Links addon", + items: [ + { + type: "category", + collapsed: false, + label: "🚀 Getting Started", + items: [ + "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: "📦 API", + items: [ + "addons/links/api/links-format", + ], + }, + ], + }, + ], }; module.exports = sidebars; diff --git a/packages/docs/static/img/assets/add_new_pattern.png b/packages/docs/static/img/assets/add_new_pattern.png new file mode 100644 index 00000000..45b5b16a Binary files /dev/null and b/packages/docs/static/img/assets/add_new_pattern.png differ diff --git a/packages/docs/static/img/assets/addons/links/ckeditor-link-modal.png b/packages/docs/static/img/assets/addons/links/ckeditor-link-modal.png new file mode 100644 index 00000000..53edb748 Binary files /dev/null and b/packages/docs/static/img/assets/addons/links/ckeditor-link-modal.png differ diff --git a/packages/docs/static/img/assets/addons/links/ckeditor.png b/packages/docs/static/img/assets/addons/links/ckeditor.png new file mode 100644 index 00000000..022c4b02 Binary files /dev/null and b/packages/docs/static/img/assets/addons/links/ckeditor.png differ diff --git a/packages/docs/static/img/assets/addons/links/link-component.png b/packages/docs/static/img/assets/addons/links/link-component.png new file mode 100644 index 00000000..e53c96f1 Binary files /dev/null and b/packages/docs/static/img/assets/addons/links/link-component.png differ diff --git a/packages/docs/static/img/assets/addons/links/link-custom-field.png b/packages/docs/static/img/assets/addons/links/link-custom-field.png new file mode 100644 index 00000000..81fa45af Binary files /dev/null and b/packages/docs/static/img/assets/addons/links/link-custom-field.png differ diff --git a/packages/docs/static/img/assets/addons/redirects/create-redirects.png b/packages/docs/static/img/assets/addons/redirects/create-redirects.png new file mode 100644 index 00000000..f8090947 Binary files /dev/null and b/packages/docs/static/img/assets/addons/redirects/create-redirects.png differ diff --git a/packages/docs/static/img/assets/addons/redirects/redirects-overview.png b/packages/docs/static/img/assets/addons/redirects/redirects-overview.png new file mode 100644 index 00000000..9d9c26dc Binary files /dev/null and b/packages/docs/static/img/assets/addons/redirects/redirects-overview.png differ diff --git a/packages/docs/static/img/assets/install/cli-select-addons.png b/packages/docs/static/img/assets/install/cli-select-addons.png new file mode 100644 index 00000000..dec338e3 Binary files /dev/null and b/packages/docs/static/img/assets/install/cli-select-addons.png differ diff --git a/packages/docs/static/img/assets/install/cli-select-content-types.png b/packages/docs/static/img/assets/install/cli-select-content-types.png new file mode 100644 index 00000000..333aafea Binary files /dev/null and b/packages/docs/static/img/assets/install/cli-select-content-types.png differ diff --git a/packages/docs/static/img/assets/permissions-admin-roles.png b/packages/docs/static/img/assets/permissions-admin-roles.png new file mode 100644 index 00000000..afd0bb36 Binary files /dev/null and b/packages/docs/static/img/assets/permissions-admin-roles.png differ diff --git a/packages/docs/static/img/assets/permissions-ct-find.png b/packages/docs/static/img/assets/permissions-ct-find.png new file mode 100644 index 00000000..bed4c8ab Binary files /dev/null and b/packages/docs/static/img/assets/permissions-ct-find.png differ diff --git a/packages/docs/static/img/assets/permissions-webtools-find.png b/packages/docs/static/img/assets/permissions-webtools-find.png new file mode 100644 index 00000000..eb51a951 Binary files /dev/null and b/packages/docs/static/img/assets/permissions-webtools-find.png differ diff --git a/packages/docs/static/img/assets/url-pattern.png b/packages/docs/static/img/assets/url-pattern.png deleted file mode 100644 index 1dc7a0f6..00000000 Binary files a/packages/docs/static/img/assets/url-pattern.png and /dev/null differ diff --git a/packages/docs/static/img/assets/url_patterns.png b/packages/docs/static/img/assets/url_patterns.png new file mode 100644 index 00000000..98eb1a3c Binary files /dev/null and b/packages/docs/static/img/assets/url_patterns.png differ