Merge pull request #346 from pluginpal/chore/documentation-quality

Chore/documentation quality

Author: boazpoolman

.changeset/hot-grapes-allow.md

@@ -0,0 +1,5 @@
+---
+"docs": patch
+---
+
+Chore/documentation quality

packages/docs/docs/addons/links/getting-started/ckeditor.md

@@ -4,11 +4,26 @@ displayed_sidebar: webtoolsLinksSidebar
 slug: /addons/links/ckeditor
 ---
 
+import ThemedImage from '@theme/ThemedImage';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
 # 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. 
+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.
 
-<img src="/webtools/img/assets/addons/links/ckeditor.png" alt="Ckeditor" />
+<ThemedImage
+  alt="Ckeditor"
+  sources={{
+    light: useBaseUrl('/webtools/img/assets/addons/links/ckeditor-light.png'),
+    dark: useBaseUrl('/webtools/img/assets/addons/links/ckeditor-light.png'),
+  }}
+/>
 
 If you click the link button it will open a modal in which you can manage your links.
 
-<img src="/webtools/img/assets/addons/links/ckeditor-link-modal.png" alt="Ckeditor link modal" />
+<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'),
+  }}
+/>

packages/docs/docs/addons/links/getting-started/custom-field.md

@@ -4,14 +4,29 @@ displayed_sidebar: webtoolsLinksSidebar
 slug: /addons/links/custom-field
 ---
 
+import ThemedImage from '@theme/ThemedImage';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
 # 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.
 
-<img src="/webtools/img/assets/addons/links/link-custom-field.png" alt="Link custom field" />
+<ThemedImage
+  alt="Link custom field"
+  sources={{
+    light: useBaseUrl('/webtools/img/assets/addons/links/link-custom-field-light.png'),
+    dark: useBaseUrl('/webtools/img/assets/addons/links/link-custom-field-light.png'),
+  }}
+/>
 
 ### This custom field will provide you three options in the advanced settings:
 * Set the link to "internal" and now you can search on something like "My first blog post". The field stores a documentId reference, so the link keeps working even if the slug or URL changes.
 * Set the link to "external" so you can enter a full url, e.g. https://strapi.io/
 * Set the link to "Internal & external links" and have both link options as described above, this is the default value. 
 
-<img src="/webtools/img/assets/addons/links/webtools-pro-link-addon-options.png" alt="Link advanced settings" />
+<ThemedImage
+  alt="Link advanced settings"
+  sources={{
+    light: useBaseUrl('/webtools/img/assets/addons/links/webtools-pro-link-addon-options-light.png'),
+    dark: useBaseUrl('/webtools/img/assets/addons/links/webtools-pro-link-addon-options-light.png'),
+  }}
+/>

packages/docs/docs/addons/redirects/api/rest.md

@@ -14,6 +14,17 @@ The plugin exposes a REST API endpoint that you can use to implement the redirec
 
 Use Public role or API Tokens as per Strapi defaults.
 
+### Permissions
+
+:::danger Permissions Required
+Before you can use the redirects endpoint publicly, you need to configure the **find** permission. Without proper permissions, you'll get a **403 Forbidden** error.
+
+**Quick Setup in Settings > Users & Permissions > Roles > Public:**
+- `webtools-addon-redirects.redirect.find`
+
+For detailed permission configuration including API tokens and admin panel access, see the [API Permissions](/webtools/addons/redirects/api-permissions) and [Admin Permissions](/webtools/addons/redirects/admin-permissions) documentation.
+:::
+
 <ApiCall>
 
 <Request>
@@ -71,11 +82,3 @@ Use Public role or API Tokens as per Strapi defaults.
 
 </ApiCall>
 
-## 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`

packages/docs/docs/addons/redirects/configuration/auto-generate.md

@@ -6,7 +6,97 @@ 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!
+## Overview
+
+The auto-generate feature automatically creates redirects whenever you change the URL alias of a content entry in your Strapi application. This ensures visitors following old links will be seamlessly redirected to the new URL without encountering broken links or 404 errors.
+
+## How it works
+
+When enabled (which it is by default), the addon monitors URL alias changes and creates redirect entries automatically:
+
+1. You change a page's URL from `/old-blog-post` to `/new-blog-post`
+2. The addon detects this change
+3. A redirect is automatically created: `/old-blog-post` → `/new-blog-post`
+4. Visitors using the old URL are redirected to the new location
+
+## Why use this?
+
+**Preserves SEO rankings**: Search engines have indexed your old URLs. Redirects ensure you don't lose search engine rankings when changing URLs.
+
+**Prevents broken links**: External sites, bookmarks, and shared links pointing to your old URLs continue to work.
+
+**Improves user experience**: Visitors are automatically sent to the correct page instead of seeing a 404 error.
+
+**Saves time**: No need to manually track and create redirects for every URL change.
+
+## Example scenario
+
+Imagine you have a blog post at `/blog/how-to-use-strapi` that's been shared widely and indexed by Google. Later, you decide to rename it to `/blog/complete-strapi-guide`.
+
+**With auto-generate enabled:**
+- You update the URL alias in Strapi
+- A redirect is automatically created
+- Old links continue to work
+- Your SEO rankings are preserved
+
+**With auto-generate disabled:**
+- You update the URL alias in Strapi
+- Old links lead to 404 errors
+- You lose traffic from external links
+- You have to manually create redirects
+
+## When to disable
+
+You might want to disable auto-generate if:
+- You want full manual control over all redirects
+- You're doing bulk URL changes and want to review redirects afterwards
+- You're migrating content and have a custom redirect strategy
+
+:::tip
+Keep this enabled for production sites. It's a safety net that prevents broken links automatically.
+:::
+
+## Multiple URL Changes
+
+When you change the same URL multiple times, the addon intelligently manages redirects to prevent chains:
+
+**Scenario 1: First URL change**
+```
+Original URL:  /my-article
+New URL:       /my-article-updated
+
+Result: Creates redirect /my-article → /my-article-updated ✓
+```
+
+**Scenario 2: Second URL change (updates existing redirect)**
+```
+Current URL:   /my-article-updated
+New URL:       /my-article-final
+
+Result:
+- Updates existing redirect to: /my-article → /my-article-final ✓
+- Creates new redirect: /my-article-updated → /my-article-final ✓
+```
+
+This strategy prevents redirect chains and ensures all old URLs point directly to the current URL. Both `/my-article` and `/my-article-updated` will redirect straight to `/my-article-final` without intermediate hops.
+
+:::tip Smart Redirect Management
+The addon automatically updates existing redirects that point to the old URL, ensuring no chains are created. This means you can freely change URLs multiple times without worrying about redirect performance.
+:::
+
+## Chain Prevention
+
+Auto-generate includes built-in protection against [redirect chains and loops](/addons/redirects/usage#redirect-chains-and-loops). If a URL change would create a chain or loop, the system will:
+
+1. **Log an error** in your server console
+2. **Skip creating the redirect** automatically
+3. **Allow you to manually resolve** the conflict
+
+Check your server logs if you suspect redirects aren't being created as expected.
+
+## Difference from sitemap cron
+
+Unlike the sitemap addon which uses a cron job to periodically regenerate files, redirects are created **instantly** when you change a URL. There's no delay and no need for scheduled tasks - redirects are event-driven and created the moment you save your changes.
 
 ###### Key: `auto_generate `
 

packages/docs/docs/addons/redirects/configuration/default-status-code.md

@@ -1,5 +1,5 @@
 ---
-sidebar_label: 'Cron'
+sidebar_label: 'Default status code'
 displayed_sidebar: webtoolsRedirectsSidebar
 slug: /addons/redirects/configuration/default-status-code
 ---

packages/docs/docs/addons/redirects/getting-started/admin-permissions.md

@@ -0,0 +1,98 @@
+---
+sidebar_label: 'Admin Permissions'
+displayed_sidebar: webtoolsRedirectsSidebar
+slug: /addons/redirects/admin-permissions
+---
+
+# 🔐 Admin Panel Permissions
+
+Configure granular permissions to control what administrators can do with redirects in the Strapi admin panel.
+
+---
+
+## Configuration
+
+To configure permissions for a role:
+
+1. Go to **Strapi Admin → Settings → Administration Panel → Roles**.
+2. Choose the role (e.g., **Editor**, **Author**).
+3. Scroll to **Webtools-addon-redirects** plugin section.
+4. Enable the permissions needed for this role.
+5. Click **Save**.
+
+---
+
+## Available Permissions
+
+The following table lists all available permissions for the Redirects addon in the admin panel:
+
+| Permission | Description |
+|------------|-------------|
+| **Access the redirects plugin** | Gives access to the redirects overview page at `/plugins/webtools/redirects` |
+| **Create** | Allows to create new redirect rules |
+| **Read** | Allows to view existing redirect configurations |
+| **Update** | Allows to edit existing redirect rules |
+| **Delete** | Allows to remove redirect rules from the system |
+
+---
+
+## Permission Combinations
+
+Common permission setups for different roles:
+
+| Role | Access | Create | Read | Update | Delete |
+|------|--------|--------|------|--------|--------|
+| **Content Editor** | ✅ | ✅ | ✅ | ✅ | ❌ |
+| **Senior Editor** | ✅ | ✅ | ✅ | ✅ | ✅ |
+| **Viewer** | ✅ | ❌ | ✅ | ❌ | ❌ |
+
+**Content Editor** - Can manage redirects but cannot delete them to prevent accidental data loss.
+
+**Senior Editor** - Has full access to all redirect management features.
+
+**Viewer** - Can view redirects in read-only mode without making changes.
+
+---
+
+## Super Admin Role
+
+:::info Automatic Access
+The **Super Admin** role has all permissions enabled by default and cannot be modified. All configurations are in read-only mode.
+:::
+
+The **Settings** button visible in the permissions UI is for configuring RBAC conditions on other roles, but has no effect on Super Admin permissions.
+
+---
+
+## Testing Permissions
+
+To verify permissions are configured correctly:
+
+1. Create a test user with the configured role
+2. Log in as that user
+3. Navigate to **Webtools → Redirects**
+4. Verify the available actions match the configured permissions
+
+:::tip
+Restart Strapi and clear your browser cache after making permission changes.
+:::
+
+---
+
+## Troubleshooting
+
+**Webtools menu not visible:**
+- Verify the role has at least "Access the redirects plugin" permission enabled
+- Log out and log back in
+- Clear browser cache
+
+**Action buttons missing:**
+- Check that Create/Update/Delete permissions are enabled for the role
+- Refresh the page
+- Check browser console for errors
+
+**Permission changes not applying:**
+- Verify you clicked "Save" after modifying permissions
+- Restart Strapi server
+- Have the user log out and log back in
+- Clear browser cache and cookies