Skip to content

Commit 10380c3

Browse files
boazpoolmanboazpoolman
authored
Merge pull request #371 from pluginpal/feature/docs
docs: improve documentation for existing and new addons
2 parents 6ffd7f3 + 3a96e10 commit 10380c3

File tree

24 files changed

+514
-24
lines changed

24 files changed

+514
-24
lines changed

‎.changeset/loose-toes-tap.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"docs": minor
3+
---
4+
5+
docs: improve documentation for existing and new addons

‎packages/docs/docs/addons/breadcrumbs/api/rest.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
sidebar_label: 'Rest API'
3+
displayed_sidebar: webtoolsBreadcrumbsSidebar
4+
slug: /addons/breadcrumbs/api/rest
5+
---
6+
7+
import ThemedImage from '@theme/ThemedImage';
8+
import useBaseUrl from '@docusaurus/useBaseUrl';
9+
10+
# REST API
11+
12+
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.
13+
14+
<ApiCall>
15+
16+
<Request>
17+
18+
`GET http://localhost:1337/api/home-page?populate=breadcrumbs`
19+
20+
</Request>
21+
22+
<Response>
23+
24+
```json
25+
{
26+
"data": {
27+
"id": 2,
28+
"documentId": "ke1s1aroaexv8jt03iuxn81g",
29+
"title": "Robust Strapi plugins for your project",
30+
"createdAt": "2025-03-09T16:45:24.886Z",
31+
"updatedAt": "2025-03-13T20:38:43.112Z",
32+
"publishedAt": "2025-03-13T17:06:57.578Z",
33+
"locale": "en",
34+
"breadcrumbs": {
35+
"items": [
36+
{
37+
"label": "Home",
38+
"url": "/"
39+
},
40+
{
41+
"label": "Plugins overview",
42+
"url": "/plugins"
43+
},
44+
{
45+
"label": "Strapi Webtools",
46+
"url": "/plugins/webtools"
47+
}
48+
]
49+
}
50+
},
51+
"meta": {}
52+
}
53+
54+
```
55+
56+
</Response>
57+
58+
</ApiCall>
59+
60+
## Permissions
61+
62+
To fetch the breadcrumbs from the API you need to enable the 'find' permissions of the Breadcrumbs content type.
63+
64+
<ThemedImage
65+
alt="Breadcrumbs permissions"
66+
sources={{
67+
light: useBaseUrl('/webtools/img/assets/addons/breadcrumbs/breadcrumbs-permissions-light.png'),
68+
dark: useBaseUrl('/webtools/img/assets/addons/breadcrumbs/breadcrumbs-permissions-light.png'),
69+
}}
70+
/>

‎packages/docs/docs/addons/breadcrumbs/getting-started/installation.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
sidebar_label: 'Installation'
3+
displayed_sidebar: webtoolsBreadcrumbsSidebar
4+
slug: /addons/breadcrumbs/installation
5+
---
6+
7+
# ⏳ Installation
8+
9+
:::prerequisites
10+
Complete installation requirements are the exact same as for Strapi itself and can be found in the Strapi documentation.
11+
12+
**Additional Requirements:**
13+
- **Node.js**: Version 18.18.2 or higher
14+
- **Strapi**: Version 5.x
15+
- **Webtools**: Version 1.x
16+
:::
17+
18+
:::caution
19+
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:
20+
21+
```
22+
npx webtools-cli setup-license
23+
```
24+
25+
To purchase a license, please visit the [PluginPal website](https://www.pluginpal.io/plugin/webtools).
26+
:::
27+
28+
### Installation
29+
30+
After you've setup your license you can install the addon like so:
31+
32+
<Tabs groupId="yarn-npm">
33+
<TabItem value="yarn" label="Yarn">
34+
```
35+
yarn add strapi-plugin-webtools @pluginpal/webtools-addon-breadcrumbs
36+
```
37+
</TabItem>
38+
<TabItem value="npm" label="NPM">
39+
```
40+
npm install strapi-plugin-webtools @pluginpal/webtools-addon-breadcrumbs --save
41+
```
42+
</TabItem>
43+
</Tabs>
44+
45+
After successful installation you have to rebuild the admin UI so it'll include this plugin. To rebuild and restart Strapi run:
46+
47+
<Tabs groupId="yarn-npm">
48+
<TabItem value="yarn" label="Yarn">
49+
```
50+
yarn build
51+
yarn develop
52+
```
53+
</TabItem>
54+
<TabItem value="npm" label="NPM">
55+
```
56+
npm run build
57+
npm run develop
58+
```
59+
</TabItem>
60+
</Tabs>
61+
62+
Enjoy 🎉

‎packages/docs/docs/addons/breadcrumbs/getting-started/introduction.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
sidebar_label: 'Introduction'
3+
displayed_sidebar: webtoolsBreadcrumbsSidebar
4+
slug: /addons/breadcrumbs
5+
---
6+
7+
# Webtools Breadcrumbs Add-on
8+
9+
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.
10+
11+
:::note
12+
This plugin acts as an extension of the core `strapi-plugin-webtools`. Please install and configure that before proceeding.
13+
:::
14+
15+
## Key Features
16+
17+
- **⚡ Computed breadcrumbs trail** - Automatically generated based on the URL alias
18+
- **⚡ Loaded as relation** - The breadcrumbs can be populated like a relation
19+
- **⚙️ Overwrite the page title** - Allows configuration to select the title field of the page
20+

‎packages/docs/docs/addons/breadcrumbs/settings/introduction.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
sidebar_label: 'Breadcrumbs settings'
3+
displayed_sidebar: webtoolsBreadcrumbsSidebar
4+
slug: /addons/breadcrumbs/settings
5+
---
6+
7+
import ThemedImage from '@theme/ThemedImage';
8+
import useBaseUrl from '@docusaurus/useBaseUrl';
9+
10+
# Breadcrumbs settings
11+
12+
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.
13+
14+
<ThemedImage
15+
alt="Breadcrumbs settings"
16+
sources={{
17+
light: useBaseUrl('/webtools/img/assets/addons/breadcrumbs/breadcrumbs-settings-light.png'),
18+
dark: useBaseUrl('/webtools/img/assets/addons/breadcrumbs/breadcrumbs-settings-light.png'),
19+
}}
20+
/>

‎packages/docs/docs/addons/introduction.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,4 +14,5 @@ To enhance Webtools in a modular way, the core plugin allows addons to be regist
1414
<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" />
1515
<CustomDocCard emoji="🔀" title="Redirects" description="The Redirects addon can be used to manage your redirects in Strapi CMS." link="/webtools/addons/redirects" />
1616
<CustomDocCard emoji="🔗" title="Links" description="The Links addon can be used create dynamic links from 1 page to another." link="/webtools/addons/links" />
17+
<CustomDocCard emoji="🍞" title="Breadcrumbs" description="The Breadcrumbs addon can be used to included a computed breadcrumbs path " link="/webtools/addons/breadcrumbs" />
1718
</CustomDocCardsWrapper>

‎packages/docs/docs/addons/links/api/links-format.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,15 @@ displayed_sidebar: webtoolsLinksSidebar
44
slug: /addons/links/api/links-format
55
---
66

7-
# Rewrite middleware
7+
# Links format
88

99
This plugin stores the internal links in a specific format. That format looks something like this:
1010

1111
```
12-
wt-link://api::page.page/sp8bzbkn21pjy3m9wsf97dio
12+
wt-link://api::page.page/sp8bzbkn21pjy3m9wsf97dio?locale=en
1313
```
1414

1515
This makes it possible to fetch the page, and ultimately the URL alias of the document that you have linked to.
1616

17-
The plugin also provides a middleware which will rewrite these link formats to the actual link when you're using the Strapi API.
17+
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.
1818

‎packages/docs/docs/addons/links/api/rewrite-middleware.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
sidebar_label: 'Rewrite middleware'
3+
displayed_sidebar: webtoolsLinksSidebar
4+
slug: /addons/links/api/rewrite-middleware
5+
---
6+
7+
# Rewrite middleware
8+
9+
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.
10+
11+
## Opt out
12+
13+
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.
14+
15+
<ApiCall>
16+
17+
<Request>
18+
19+
`GET http://localhost:1337/api/home-page?skipLinkRewrite=true`
20+
21+
</Request>
22+
23+
<Response>
24+
```
25+
{
26+
"data": {
27+
"id": 1,
28+
"documentId": "yk4tcq7bd51cdqt7qk9gu5v6",
29+
"link": "wt-link://api::page.page/sp8bzbkn21pjy3m9wsf97dio?locale=en",
30+
"createdAt": "2025-09-07T13:03:00.877Z",
31+
"updatedAt": "2025-09-07T13:03:00.877Z",
32+
"publishedAt": "2025-09-07T13:03:00.873Z"
33+
},
34+
"meta": {}
35+
}
36+
```
37+
</Response>
38+
39+
</ApiCall>
40+
41+
## GraphQL
42+
43+
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.
44+
45+
```md title="config/middlewares.ts"
46+
export default [
47+
// ...
48+
'plugin::webtools-addon-links.graphql',
49+
// ...
50+
]
51+
```
52+

‎packages/docs/docs/addons/links/configuration/custom-links.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
sidebar_label: 'Custom links'
3+
displayed_sidebar: webtoolsLinksSidebar
4+
slug: /addons/links/configuration/custom-links
5+
---
6+
7+
# Custom links
8+
9+
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.
10+
11+
```md title="config/plugins.ts"
12+
export default () => {
13+
'webtools-addon-links': {
14+
enabled: true,
15+
config: {
16+
custom_links: [{
17+
content_type: 'api::external-link.external-link',
18+
resolver: (externalLink) => externalLink.external_link,
19+
}],
20+
}
21+
}
22+
}
23+
```
24+
25+
###### Key: `custom_links`
26+
27+
> `required:` NO | `type:` array | `default:` []

‎packages/docs/docs/addons/links/configuration/introduction.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
sidebar_label: 'Introduction'
3+
displayed_sidebar: webtoolsLinksSidebar
4+
slug: /addons/links/configuration
5+
---
6+
7+
# 🔧 Configuration
8+
The configuration of the plugin can be overridden in the `config/plugins.js` file.
9+
In the example below you can see how, and also what the default settings are.
10+
11+
```md title="config/plugins.js"
12+
module.exports = ({ env }) => ({
13+
'webtools-addon-links': {
14+
enabled: true,
15+
config: {
16+
custom_links: [],
17+
},
18+
},
19+
});
20+
```

0 commit comments

Comments
 (0)