studio-variable/world-game
3
1
Fork 0
Code Issues 10 Pull requests Projects Releases Packages Wiki Activity Actions

feat: intégration plugin Kirby SEO
All checks were successful
Deploy / Deploy to Production (push) Successful in 22s
Details

Browse source 
- Ajout de tobimori/kirby-seo via Composer
- snippet('seo/head') dans header.php (remplace les meta manuels)
- snippet('seo/schemas') dans footer.php pour JSON-LD
- Onglet SEO ajouté dans site.yml et tous les blueprints de pages
- Configuration SEO dans config.php (sitemap, robots, canonicalBase TODO)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
isUnknown 2026-03-25 12:59:18 +01:00
parent baab2fb3a1
commit 58c31ea391
133 changed files with 9201 additions and 253 deletions
Download patch file Download diff file Expand all files Collapse all files

141
site/plugins/kirby-seo/docs/0_getting-started/0_quickstart.md Normal file
View file

@ -0,0 +1,141 @@
---
title: Quickstart
intro: "All you need to get started with Kirby SEO: Installation & initial configuration"
---
## Requirements
Kirby SEO requires
- Kirby 5 or later
- PHP 8.3, 8.4 or 8.5
Composer is required for full feature support (e.g. schema.org support, background queuing). [Composer](https://getcomposer.org/) is a dependency manager for PHP. If you have never used Composer before, follow the instruction on the [Composer website](https://getcomposer.org/doc/00-intro.md).
## Installing Kirby SEO
In a terminal window, navigate to the folder of your Kirby installation. Then run the following command:
```bash
composer require tobimori/kirby-seo
```
Some features require additional packages. Install them when you need them:
- [Schema.org](2_customization/08_schema-org) requires `spatie/schema-org`
- Background Processing (coming soon)
<details>
<summary>Manual Installation</summary>
If you prefer not to use Composer, you can manually install Kirby SEO. Go to the [GitHub releases page](https://github.com/tobimori/kirby-seo/releases) and find the latest release. Click on "Assets" to expand it and select "Source code (zip)". Extract the contents of the zip file into the `site/plugins/kirby-seo` folder of your Kirby installation.
</details>
## Add meta tags to your site
Kirby SEO needs two snippets in your HTML: one in the `<head>` for meta tags, and one before `</body>` for structured data.
Find the place in your code where you output the `<head>` tag, this is usually a shared snippet like `header.php` or a layout file. Add the `seo/head` snippet to your `<head>` and the `seo/schemas` snippet before the `</body>` closing tag:
```php
<html lang="<?= $site->lang() ?>">
<head>
<?php snippet('seo/head'); ?>
</head>
<body>
[...]
<?php snippet('seo/schemas'); ?>
</body>
</html>
```
Make sure your `<html>` tag also includes the `lang` attribute as shown above. Browsers use it for automatic hyphenation, and Google uses it to determine the language of your page.
Now open your site in a browser and view the page source. You should already see `<title>`, `<meta>` and Open Graph tags in your `<head>`. The plugin fills them with sensible defaults out of the box.
## Editing meta tags in the panel
Next, you want to give your editors control over the SEO fields. Add the SEO tab to your site blueprint:
```yaml
# site/blueprints/site.yml
tabs:
content:
fields:
# move your existing fields here
seo: seo # <--- add this
```
This gives you global defaults for meta titles, descriptions and social images. Any page without its own SEO settings will use these.
Learn more about how defaults work in [Your first Meta Tags](0_getting-started/1_your-first-meta-tags).
And now add the SEO tab to any page blueprint where editors should be able to override the defaults:
```yaml
# site/blueprints/pages/default.yml
tabs:
content:
fields:
# move your existing fields here
seo: seo # <--- add this
```
Open the Panel and navigate to any page. You'll see a new SEO tab with fields for meta title, description, social images and more.
Try it: enter a custom meta title, save, and reload the page in your browser. View the source, your title is there.
Now delete the title you just entered and reload again. The plugin falls back to your page's regular title.
This is the **Meta Cascade**, the plugin always finds the best available value, so you only need to fill in fields when you want to override the default. [Learn more about the Meta Cascade](0_getting-started/1_your-first-meta-tags).
## Set your canonical URL
To prevent duplicate content issues (e.g. if your site is reachable with and without `www`), tell the plugin which URL is the canonical one:
```php
// site/config/config.php
return [
// [...]
'tobimori.seo' => [
'canonical' => [
'base' => 'https://www.example.com',
],
]
];
```
Reload your page and check the source. You'll see a `<link rel="canonical">` tag pointing to your configured domain.
## Single-language setup
If you're not using Kirby's [multi-language feature](https://getkirby.com/docs/guide/languages), set your language code so the plugin can generate the correct `og:locale` tag:
```php
// site/config/config.php
return [
// [...]
'tobimori.seo' => [
'canonical' => [
'base' => 'https://www.example.com',
],
'locale' => 'en_US',
],
];
```
If you already added the canonical config above, add `lang` to the same `tobimori.seo` block.
If you already have multi-language set up in Kirby the plugin will pick up the language automatically.
## Purchase license & activate your installation
Once you publish your website, you need to purchase a Kirby SEO license. We will send you a unique license code for your domain. You can activate your license with the following steps:
1. Open the Panel at `https://example.com/panel` and log in.
2. Click on the "Metadata & SEO" tab, and click on "Activate" in the top right.
3. Enter your license code and your email address and press "Activate".
It is not required to activate your license locally.
## Where to go from here

81
site/plugins/kirby-seo/docs/0_getting-started/1_your-first-meta-tags.md Normal file
View file

@ -0,0 +1,81 @@
---
title: Your First Meta Tags
intro: Learn how Kirby SEO decides which meta data to show and how to control it at every level
---
In the Quickstart, you installed Kirby SEO and saw meta tags appear in your source code. Now let's look at how to control what shows up, and where.
## Start with a site-wide default
Open the Panel, and click on "Metadata & SEO". You'll see something like this:
![Site SEO tab with meta description field](global-seo-settings.png)
Quite empty, but these are your global defaults. Every page that doesn't have its own meta data will use what you set here.
### Meta title templates
You probably don't want to write a custom meta title for every page. Kirby SEO lets you define a **title template** at the site level.
Go to the Site SEO tab and find the title template field. Click the buttons to insert placeholders like **Page Title** or **Site Title**, and type any separator you want between them.
A template like `Page Title | Site Title` turns a page called "About" on a site called "My Blog" into:
```
About | My Blog
```
Every page that doesn't have a custom meta title will use this pattern automatically.
### Set a default description
Below that, you'll find the Page Description field. Enter a default description like "A blog about good food." and save.
Open any page on your site and view the source. Every page shows this description, because no page has its own yet.
### Override on a single page
Navigate to a specific page in the Panel, and open its Metadata & SEO tab. You'll find a slightly different interface than the site tab:
![Page SEO tab with meta description field](page-seo-settings.png)
Enter a different description. Save and reload that page in the browser.
That page now shows its own description. Every other page still shows "A blog about good food."
### Remove the override
Delete the description you just entered on the page and save. Reload — the page falls back to the site-wide default again.
What you just experienced is the **Meta Cascade**. Kirby SEO looks for values in multiple places and uses the most specific one it finds:
1. **Page fields**: the Metadata & SEO tab on a specific page
2. **Programmatic content**: values set in a Page Model via `metaDefaults()`
3. **Parent page**: inherited from the parent page (if enabled)
4. **Fallback fields**: Open Graph tags fall back to their Meta counterparts
5. **Site globals**: the Metadata & SEO tab on the Site
6. **Plugin defaults**
The idea is simple: you set sensible defaults once at the site level, and only override where you need something different. Most pages will never need more than a description in their Metadata & SEO tab.
## Inheriting settings
So far you've seen two levels: site defaults and page overrides. But what if you have a section of your site — like a blog — where all pages should share specific settings that are different from the rest of your site?
Open a page's Metadata & SEO tab and use the Inherit settings field. Select which settings should be passed down to its child pages: title templates, descriptions, Open Graph, robots directives, or all at once. Child pages can still override anything individually.
![Inherit settings field](page-seo-inherit.png)
## Open Graph & Social
When someone shares a link to your site on Facebook, Mastodon, Slack or WhatsApp, these platforms look for Open Graph tags in your HTML to build a preview card. The [Open Graph Protocol](https://ogp.me/) is a standard originally created by Facebook that defines how a page's title, description and image appear when shared.
Kirby SEO generates these tags automatically. The SEO tab has separate fields for Open Graph titles, descriptions and images, but you usually don't need to fill them in. If you don't set an OG title, the plugin uses your meta title. If you don't set an OG image, it uses the default from your site settings.
Set a default OG image in the Site SEO tab so every shared link has a preview image, even if you don't set one per page.
## What's next
You now know how to control your meta tags, title templates and social previews. The rest of the docs cover individual features in detail:
// TODO: add links

BIN
site/plugins/kirby-seo/docs/0_getting-started/global-seo-settings.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 98 KiB

BIN
site/plugins/kirby-seo/docs/0_getting-started/page-seo-inherit.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 169 KiB

BIN
site/plugins/kirby-seo/docs/0_getting-started/page-seo-settings.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 118 KiB

127
site/plugins/kirby-seo/docs/1_features/00_robots-indexing.md Normal file
View file

@ -0,0 +1,127 @@
---
title: Robots & Indexing
intro: How your pages appear (or don't) in search results
---
Search engines and AI providers use programs called crawlers to discover and index pages on the web. You can tell these crawlers which pages they're allowed to index and which ones they should skip. These are not hard blocks: crawlers don't _have_ to follow them. But all major search engines do respect them.
Kirby SEO does this in two ways: a global `robots.txt` file and per-page `<meta name="robots">` tags. Both are generated automatically. Most of the indexing control happens through meta tags, while `robots.txt` acts as a global safety net.
## robots.txt
Kirby SEO generates a `robots.txt` automatically. You don't need to create or maintain it yourself. Visit `example.com/robots.txt` to see yours.
By default, the output looks like this:
```txt
User-agent: *
Allow: /
Disallow: /panel
Sitemap: https://example.com/sitemap.xml
```
- `User-agent: *` applies the rules to all crawlers.
- `Allow: /` permits crawling the entire site.
- `Disallow: /panel` blocks the Kirby Panel from being crawled.
- `Sitemap:` points crawlers to your sitemap (only shown when the [sitemap feature](1_features/01_sitemap) is active).
The `robots.txt` does **not** list individual pages. It only sets broad rules. To control indexing for a specific page, you need meta tags (see below).
### Debug mode
When Kirby's debug mode is on, the `robots.txt` blocks all crawlers:
```txt
User-agent: *
Disallow: /
```
This way your development or staging site doesn't end up in search results.
If you need to customize the `robots.txt`, see [Customizing robots.txt](2_customization/02_robots-txt).
## Robots meta tags
The `<meta name="robots">` tag tells search engines what to do with a specific page: whether to index it, follow its links, and more.
Kirby SEO adds this tag to every page automatically.
### Default behavior
The plugin follows page status in Kirby:
- **Listed** pages are visible to search engines
- **Unlisted** pages are hidden from search engines
- **Draft** pages are not publicly accessible
In debug mode, **all** pages are hidden from search engines regardless of their status.
### Overriding robots settings
Robots meta tags follow the same [Meta Cascade](0_getting-started/1_your-first-meta-tags) as all other fields. The defaults above kick in when nothing else is set, so you can override them:
- Set a page's robots fields in its **Metadata & SEO** tab to override just that page.
- Set the robots fields on the **Site** to override all pages at once.
One thing to watch out for: if you hard-set a value at the site level (e.g. setting "Index" to "No" instead of leaving it on "Default"), every page without its own override will follow that setting through the cascade. Leave fields on "Default" if you want the plugin to decide based on page status.
### Robots indicator in the Panel
Kirby SEO has a page view button that shows the current robots status at a glance. You need to add it to your page blueprints manually:
```yaml
# site/blueprints/pages/default.yml
buttons:
- open
- preview
- "-"
- settings
- languages
- status
- robots
```
The indicator has three states:
- **Green**: the page is visible to search engines
- **Yellow**: the page is indexed, but with some restrictions
- **Red**: the page is hidden from search engines
![Robots indicator showing "Indexing forbidden" in red](robots-indicator.png)
Clicking it takes you straight to the SEO tab, so you can quickly spot which pages are excluded from search engines.
### Disabling per-page robots fields
![Robots directives fields in the Panel](robots-section.png)
Our suggestion: hide the per-page robots fields unless you actually need them. The defaults are good enough for the vast majority of sites, and the individual settings tend to confuse editors more than they help. You can disable them entirely:
```php
// site/config/config.php
return [
'tobimori.seo' => [
'robots' => [
'pageSettings' => false,
],
],
];
```
This hides the robots fields on both page and site level. The defaults (based on page status and debug mode) still apply.
For more ways to customize robots behavior, see [Customizing robots.txt](2_customization/02_robots-txt).
<details>
<summary>Tags suppressed by noindex</summary>
When a page has `noindex`, Kirby SEO also removes some related tags that don't make sense on a page hidden from search engines:
- `<link rel="canonical">` is not rendered
- `<meta property="og:url">` is not rendered
- `<link rel="alternate" hreflang="...">` tags are not rendered
Other tags like `<title>`, `<meta name="description">` and Open Graph tags are still rendered.
</details>

35
site/plugins/kirby-seo/docs/1_features/01_sitemap.md Normal file
View file

@ -0,0 +1,35 @@
---
title: Sitemap
intro: A sitemap for search engines, generated from your pages
---
Kirby SEO generates an XML sitemap at `https://example.com/sitemap.xml`. Search engines like Google use it to discover all the pages on your site. You don't need to create or update it manually: it updates whenever your content changes.
What you see here are the defaults. The sitemap generator and all its options can be changed or replaced entirely. See [Customizing the sitemap](2_customization/05_sitemap) for details.
## What's in the sitemap
The sitemap only includes pages that are [visible to search engines](1_features/00_robots-indexing). Unlisted pages, drafts, and pages excluded by robots settings are left out. The `error` template is also excluded by default.
Each page in the sitemap includes:
- `loc`: the page URL
- `lastmod`: when the page was last modified
- `changefreq`: how often the page is likely to change (default: `weekly`)
- `priority`: how important the page is relative to other pages on your site
Priority is calculated from page depth: the homepage gets `1.0`, and each level deeper subtracts `0.2`, down to a minimum of `0.2`.
A `Sitemap:` line is also added to your [robots.txt](1_features/00_robots-indexing) automatically, so crawlers know where to find it.
## Multilingual sites
If your Kirby site has multiple languages, the sitemap automatically includes `hreflang` links for each page. These tell search engines which language versions of a page exist, so they can show the right one in search results.
Only languages where a translation actually exists are included. There is no separate sitemap per language: all translations are listed in a single sitemap using `<xhtml:link>` elements.
## Browser view
If you open `https://example.com/sitemap.xml` in a browser, you'll see a styled table instead of raw XML. This is powered by an XSL stylesheet that Kirby SEO serves at `/sitemap.xsl`. On multilingual sites, each URL shows language badges linking to its alternate translations.
To see the raw XML, use `view-source:https://example.com/sitemap.xml` in your browser's address bar.

56
site/plugins/kirby-seo/docs/1_features/02_indexnow.md Normal file
View file

@ -0,0 +1,56 @@
---
title: IndexNow
intro: Notify search engines when your content changes
---
Normally, search engines discover changes to your site on their own schedule, which can take days or weeks. [IndexNow](https://www.indexnow.org/) lets you skip the wait: whenever you save, publish, or move a page in Kirby, Kirby SEO notifies search engines so they can re-crawl right away.
IndexNow is supported by Bing, Yandex, Seznam, and others. Kirby SEO sends a single request to `api.indexnow.org`, which propagates to all participating search engines. Google does not support IndexNow but is not affected by it.
## How it works
IndexNow is triggered on three events:
- A page is saved
- A page changes status (e.g. draft to listed)
- A page's slug changes
Only pages that are listed and not marked as `noindex` are submitted. On local environments (localhost), no requests are sent.
## API key
IndexNow requires an API key to verify that you own the domain. Kirby SEO generates one automatically and caches it permanently. Search engines can verify it at `https://example.com/indexnow-{key}.txt`, which Kirby SEO serves as a route. You don't need to manage this yourself.
## Related URLs
By default, only the changed page itself is submitted. But when a page changes, other pages might be affected too: a blog post's parent archive shows a different excerpt, or sibling pages have updated navigation.
You can configure rules to submit related URLs along with the changed page:
```php
// site/config/config.php
return [
'tobimori.seo' => [
'indexnow' => [
'rules' => [
// when a blog post changes, also re-index its parent
'/blog/*' => ['parent' => true],
// when an article changes, re-index two levels of parents and specific URLs
'article' => ['parent' => 2, 'urls' => ['/blog', '/']],
// when a product changes, re-index siblings and all category pages
'product' => ['parent' => true, 'siblings' => true, 'templates' => ['category']],
],
],
],
];
```
Rules match either by URL pattern (`/blog/*`) or by template name (`article`). Each rule can use any combination of:
- `parent`: `true` for the direct parent, or a number for how many levels up
- `children`: `true` for all descendants, or a number to limit depth
- `siblings`: `true` to include all pages at the same level
- `urls`: an array of specific URLs to submit
- `templates`: an array of template names, all pages with those templates will be submitted

31
site/plugins/kirby-seo/docs/1_features/03_panel-previews.md Normal file
View file

@ -0,0 +1,31 @@
---
title: Panel Previews
intro: See how your pages look in search results and social shares
---
Meta titles and descriptions can look different in context than they do in a text field. The SEO tab in the Panel has a live preview sidebar that shows how the current page will appear when shared or found in search results. It updates as you type, so you can catch issues like truncated titles or missing images before you publish.
There are three preview types:
- **Google**: a search result card with your meta title, description, URL and favicon
- **Facebook**: a social sharing card with OG title, description and image
- **Slack**: a link preview card as Slack shows it when someone pastes a URL
The preview picks up all values through the [Meta Cascade](0_getting-started/1_your-first-meta-tags). If you haven't set an OG title, the preview shows the meta title instead, just like a real crawler would see it.
Keep in mind that Google sometimes decides to show a different title or description than what you set, if it thinks something else on the page is more relevant to the search query. The preview shows what you _tell_ Google to display, but the actual search result may look different. This is normal and not something we can control.
On the Site SEO tab, the preview shows data for the homepage since the site itself doesn't have a URL.
## Choosing which previews to show
By default, all three previews are available. If you only care about Google and Facebook, you can remove Slack from the list:
```php
// site/config/config.php
return [
'tobimori.seo' => [
'previews' => ['google', 'facebook'],
],
];
```

65
site/plugins/kirby-seo/docs/1_features/04_ai-assist.md Normal file
View file

@ -0,0 +1,65 @@
---
title: AI Assist
intro: Let AI draft your meta titles and descriptions
---
Writing meta titles and descriptions for every page gets tedious fast. AI Assist can generate them for you based on the actual content of each page. It reads the page, looks at your existing meta fields, and drafts a title or description that fits.
AI Assist works for these fields:
- Meta title
- Meta description
- Open Graph description
- Site-level meta description
- Site-level Open Graph description
The generated text matches the language of your page and respects your title template length, so titles don't get cut off in search results.
## Setting up a provider
AI Assist needs an API key from an AI provider. Sign up with one of the supported providers and create an API key in their dashboard. Kirby SEO supports [OpenAI](https://platform.openai.com/), [Anthropic](https://console.anthropic.com/), [Google Gemini](https://ai.google.dev/), and [OpenRouter](https://openrouter.ai/) out of the box. OpenRouter is a good starting point because it gives you access to many models through a single API, including models with free tiers.
AI providers charge based on usage. These costs are separate from your Kirby SEO license. For generating short texts like meta titles and descriptions, costs are typically very low.
Here's an example using OpenRouter:
```php
// site/config/config.php
return [
'tobimori.seo' => [
'ai' => [
'provider' => 'openrouter',
'providers' => [
'openrouter' => [
'config' => [
'apiKey' => 'sk-or-...',
'model' => 'google/gemini-3-flash-preview',
],
],
],
],
],
];
```
For generating meta titles and descriptions, you don't need the most powerful model. Small, fast models work well and keep costs low. Our recommendation is **Google Gemini 3 Flash** via the built-in Gemini provider: it's fast, capable, and has a generous free tier.
You can change the model for any provider via the `model` key in the config, as shown in the example above.
For config options for all providers, see [Customizing AI Assist](2_customization/06_ai-assist) for details.
## Using AI Assist in the Panel
The provider config is a one-time setup by the developer. Once it's in place, editors just use the buttons in the Panel.
You'll see new buttons next to the meta title and description fields in the SEO tab.
The **Generate** button drafts a new value from scratch based on the page content. If the field already has a value, it changes to **Regenerate**. If you want more control, click **Customize** to add your own instructions before generating, like "keep it under 50 characters" or "focus on the pricing".
Already have a value but want to tweak it? The **Edit** button lets you revise the current text with instructions like "make it shorter" or "add the brand name".
The result appears word by word. You can stop it early if you want.
## Custom providers and prompts
You can add your own providers or override the built-in prompts. See [Customizing AI Assist](2_customization/06_ai-assist) for details.

57
site/plugins/kirby-seo/docs/1_features/05_alt-texts.md Normal file
View file

@ -0,0 +1,57 @@
---
title: Alt Text Field
intro: Structured alt text for images, with AI generation and a decorative toggle
---
Every image on the web needs an `alt` attribute. Images that convey meaning need descriptive text. Decorative images need an empty `alt=""`, which tells screen readers to skip them entirely. Getting this wrong hurts accessibility.
Kirby SEO provides a dedicated `alt-text` field that handles both cases. It stores structured data instead of a plain string, so your templates always render the correct HTML attributes.
## Adding the field
Add a `alt-text` field to any file blueprint:
```yaml
# site/blueprints/files/image.yml
fields:
alt:
type: alt-text
label: Alt Text
```
Editors see a text input with a toggle. The toggle marks an image as decorative: when active, the text input disappears because decorative images don't need a description.
## AI generation
If [AI Assist](1_features/04_ai-assist) is configured, the field shows **Generate** and **Customize** buttons. The AI sees the actual image and writes alt text based on it, the filename, and the page context. Results stream in word by word and can be stopped early.
You can disable AI for a specific field by setting `ai: false` in the blueprint.
### Auto-generation on upload
Set `autogenerate: true` to generate alt text automatically when an image is uploaded:
```yaml
alt:
type: alt-text
autogenerate: true
```
By default, this runs synchronously during the upload. For better performance, you can offload it to a background queue. See [Background Processing](2_customization/10_background-processing) for setup. On multilingual sites, a single AI call generates alt text for all languages at once.
## Using alt text in templates
The plugin registers a `toAltText()` field method that returns an `AltText` object. Use its `toAttr()` method to get the correct HTML attributes, then spread them into your image helper:
```php
<?= Html::img($file->url(), [
'width' => $file->width(),
'height' => $file->height(),
...$file->alt()->toAltText()->toAttr(),
]) ?>
// <img alt="A dog playing fetch" src="..." width="..." height="...">
// decorative image:
// <img alt="" src="..." width="..." height="...">
The field also works with plain string values from existing `alt` fields. If you migrate from a regular text field, `toAltText()` treats the old value as manual alt text.

29
site/plugins/kirby-seo/docs/1_features/06_google-search-console.md Normal file
View file

@ -0,0 +1,29 @@
---
title: Google Search Console
intro: See what people search for when they find your pages
---
Kirby SEO can pull data from [Google Search Console](https://search.google.com/search-console) directly into the Panel. Editors can see search performance right next to their content, without needing their own Google account or leaving the Panel. You see which search queries lead people to each page, how many clicks and impressions you get, your click-through rate, and your average position in search results.
![Google Search Console section in the Panel](gsc-section.png)
The data shows up in a section on both the Site and individual page views. On a page, the queries are filtered to that specific page. On the Site view, you see all queries across your entire site. The section shows the top 10 search queries, sorted by clicks. You can switch the sorting to impressions, CTR, or position.
Click **Show all** to open a full table with all queries and all four metrics at once. There's also a direct link to open the page in Google Search Console if you want to dig deeper.
Data is cached for 24 hours, so it won't hit Google's API on every page load.
## Connecting your Google account
**IMPORTANT:** The following section describes a feature that is not implemented yet. For now, the Search Console integration requires your own GSC credentials.
The Google Search Console section needs access to your Google account. To keep setup simple, API requests to Google are proxied through a server operated by Love & Kindness GmbH (the company behind Kirby SEO). This proxy mode requires an active Kirby SEO license, which is used only for rate limiting. We do not log the content of any requests or responses, so we cannot see the actual search data for your site. The source code for the proxy is [open source on GitHub](https://github.com/tobimori/kirby-seo-gsc-proxy).
1. Open the Panel and navigate to any page with the SEO tab.
2. In the Google Search Console section, click **Connect**.
3. Google asks you to sign in and grant read-only access to your Search Console data.
4. Back in the Panel, select which Search Console property to use. If your domain is already registered in Google Search Console, it will be pre-selected.
The section starts showing data once the property is selected.
If you'd rather not use the proxy, you can connect with your own Google OAuth credentials instead. See [Setting up your own GSC credentials](2_customization/07_gsc-setup) for details.

6
site/plugins/kirby-seo/docs/1_features/07_seo-audit.md Normal file
View file

@ -0,0 +1,6 @@
---
title: SEO Audit
intro:
---
Coming soon

6
site/plugins/kirby-seo/docs/1_features/08_seo-overview.md Normal file
View file

@ -0,0 +1,6 @@
---
title: SEO Overview
intro:
---
Coming soon

42
site/plugins/kirby-seo/docs/1_features/09_utm-share.md Normal file
View file

@ -0,0 +1,42 @@
---
title: UTM Share
intro: Share links with tracking parameters for your marketing campaigns
---
When you share a link to your site in a newsletter, a social media post, or an ad, you want to know which links actually bring in traffic. UTM parameters are tags you add to a URL so analytics tools like Google Analytics can tell you exactly where a visitor came from.
A URL with UTM parameters looks like this:
```
https://example.com/blog/my-post?utm_source=newsletter&utm_medium=email&utm_campaign=spring-sale
```
Kirby SEO adds a **UTM Share** button to your page views. Click it to open a dialog where you can fill in the parameters and copy the resulting URL.
![UTM Share dialog in the Panel](utm-share.png)
The dialog has five standard UTM parameters:
- `utm_source`: where the traffic comes from (e.g. `google`, `newsletter`)
- `utm_medium`: the type of channel (e.g. `cpc`, `email`, `social`)
- `utm_campaign`: the name of the campaign (e.g. `spring_sale`)
- `utm_content`: to tell apart different links in the same campaign (e.g. `logo_link`)
- `utm_term`: the keyword, for paid search ads (e.g. `running shoes`)
You don't need all five. Most of the time, `utm_source`, `utm_medium`, and `utm_campaign` are enough.
There's also a `ref` field. This is not part of the UTM standard, but many analytics tools (like Plausible and Pirsch) use it as a lightweight way to track the referring site.
To add the button to your page blueprints:
```yaml
# site/blueprints/pages/default.yml
buttons:
- open
- preview
- "-"
- settings
- languages
- status
- utm-share
```

31
site/plugins/kirby-seo/docs/1_features/10_heading-structure.md Normal file
View file

@ -0,0 +1,31 @@
---
title: Heading Structure
intro: Check your heading hierarchy while editing
---
Search engines and screen readers rely on headings (H1, H2, H3, ...) to understand the structure of a page. A well-structured page starts with a single H1 and uses the other levels in order, without skipping any.
When headings skip levels (e.g. H2 followed by H4) or when there are multiple H1s, search engines have a harder time figuring out what the page is about. Screen readers use the heading tree to let users jump between sections, so broken hierarchy also affects accessibility.
Most Kirby sites tie heading levels to visual styles: H1 is the largest text, H2 is smaller, and so on. Editors often pick a heading level based on how big they want the text to look, not based on what it means semantically. An H3 after an H1 might look fine on the page, but it tells search engines and screen readers that something is missing.
Kirby SEO has a Panel section that extracts all headings from the current page and displays them as a nested tree. You see the full hierarchy at a glance, and headings that break the structure are highlighted. The section updates as the page content changes, so editors can fix issues while they write.
## Adding the section to your blueprint
Place the section next to your content editor, for example in a sidebar column beside your blocks or layout field:
```yaml
# site/blueprints/pages/default.yml
tabs:
content:
columns:
- width: 2/3
fields:
blocks:
type: blocks
- width: 1/3
sections:
headingStructure:
type: heading-structure
```

BIN
site/plugins/kirby-seo/docs/1_features/gsc-section.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 109 KiB

BIN
site/plugins/kirby-seo/docs/1_features/robots-indicator.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 32 KiB

BIN
site/plugins/kirby-seo/docs/1_features/robots-section.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 113 KiB

BIN
site/plugins/kirby-seo/docs/1_features/utm-share.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 74 KiB

84
site/plugins/kirby-seo/docs/2_customization/00_programmatic-content.md Normal file
View file

@ -0,0 +1,84 @@
---
title: Programmatic Content
intro: Set default SEO values from page models
---
Sometimes you want SEO fields to default to values from other fields, or generate them from code. A common example is using a plugin like [kirby-paparazzi](https://github.com/tobimori/kirby-paparazzi) to generate OG images for every page.
Add a `metaDefaults` method to a [page model](https://getkirby.com/docs/guide/templates/page-models). It returns an array of meta tag names mapped to their values. These defaults apply through the [Meta Cascade](0_getting-started/1_your-first-meta-tags) when no editor override exists.
```php
<?php
// site/models/article.php
use Kirby\Cms\Page;
class ArticlePage extends Page
{
public function metaDefaults(string $lang = null): array
{
return [
'og:image' => "{$this->url()}.png",
'og:image:width' => 1230,
'og:image:height' => 600,
'description' => $this->content($lang)->summary()->value(),
];
}
}
```
Kirby SEO picks the correct tag syntax from the name. Open Graph keys (starting with `og:`) get `property` and `content` attributes, link keys like `canonical` get `rel` and `href`, and everything else gets `name` and `content`.
## Custom tag attributes
If you need full control over a tag's output, pass an array with `tag` and `attributes`:
```php
return [
// shorthand
'description' => 'A page about something',
// tag with inner content
[
'tag' => 'title',
'content' => 'My Page Title',
],
// tag with attributes
[
'tag' => 'meta',
'attributes' => [
'property' => 'og:image:alt',
'content' => "An image of {$this->title()}",
],
],
// link tag
[
'tag' => 'link',
'attributes' => [
'rel' => 'preconnect',
'href' => 'https://fonts.googleapis.com',
],
],
];
```
## Global defaults via a plugin
Page models only apply to pages with a specific template. If you want to add meta tags to all pages, you can register a `metaDefaults` [page method](https://getkirby.com/docs/reference/plugins/extensions/page-methods) in a plugin:
```php
<?php
// site/plugins/my-meta/index.php
Kirby::plugin('my/meta', [
'pageMethods' => [
'metaDefaults' => function (string $lang = null): array {
return [
'og:image' => "{$this->url()}.png",
];
},
],
]);
```

95
site/plugins/kirby-seo/docs/2_customization/01_meta-cascade.md Normal file
View file

@ -0,0 +1,95 @@
---
title: Meta Cascade
intro: Understand how meta values are resolved across multiple levels
---
Kirby SEO is built with a cascading approach. Meta tags can be defined on multiple levels, and they are merged based on priority. If a value is empty on one level, it falls through to the next. This is how the plugin forms the final metadata for every page.
The default cascade, in order of priority:
1. **Page fields** (`fields`) -- Values the editor enters in the page's SEO blueprint fields. This is the highest priority: if an editor sets a meta description, it always wins.
2. **Programmatic** (`programmatic`) -- Values returned by `metaDefaults()` in [page models](2_customization/00_programmatic-content). Use this for computed defaults like generated OG images or descriptions derived from other fields.
3. **Parent** (`parent`) -- Inherited values from the parent page. If a parent page has "inherit settings" enabled for a field, its children pick up those values. Useful for giving all blog posts the same title template, for example.
4. **Fallback fields** (`fallbackFields`) -- Falls back to meta field values for Open Graph tags. If no `ogDescription` is set, the page's `metaDescription` is used instead.
5. **Site** (`site`) -- Global values from the site's SEO blueprint fields. These apply to all pages that don't have their own value set at a higher level.
6. **Options** (`options`) -- The final fallback, defined in the plugin's config defaults. These are the built-in defaults like the title template `{{ title }} - {{ site.title }}`.
## Configuring the cascade
The cascade order is configurable in your `config.php`. You can remove levels, reorder them, or add optional ones:
```php
<?php
// site/config/config.php
return [
'tobimori.seo' => [
'cascade' => [
'fields',
'programmatic',
'parent',
'fallbackFields',
'site',
'options',
],
],
];
```
Remove an entry to skip that level entirely. For example, to disable parent inheritance:
```php
'cascade' => [
'fields',
'programmatic',
'fallbackFields',
'site',
'options',
],
```
## Restore the 1.x behavior
In 1.x, if you set an `ogDescription` at the site level, it applied to every page, even pages that had their own `metaDescription`. The page-specific description never made it into the Open Graph tags.
In 2.x, the `fallbackFields` level sits between `parent` and `site`, so a page's `metaDescription` is used as `ogDescription` before site-wide Open Graph values are reached.
To restore the 1.x behavior, remove `fallbackFields` from the cascade:
```php
'cascade' => [
'fields',
'programmatic',
'parent',
'site',
'options',
],
```
<details>
<summary>If you used <code>fallbackFields</code> with additional mappings in 1.x</summary>
In 1.x, `fallbackFields` also mapped `ogTemplate` to `metaTemplate`. If you relied on this, you can restore it by extending the `Meta` class and overriding the `FALLBACK_MAP` constant:
```php
<?php
use tobimori\Seo\Meta;
class MyMeta extends Meta
{
public const FALLBACK_MAP = [
'ogDescription' => 'metaDescription',
'ogTemplate' => 'metaTemplate',
];
}
```
Then register your class in the config. See [Extending the Plugin](2_customization/11_plugin-extensions) for details.
</details>

66
site/plugins/kirby-seo/docs/2_customization/02_robots-txt.md Normal file
View file

@ -0,0 +1,66 @@
---
title: Customizing robots.txt
intro: Add custom rules to your robots.txt
---
By default, Kirby SEO generates a simple `robots.txt` that allows all crawlers and blocks the Panel. If you need to add your own rules, use the `robots.content` option.
## Blocking specific bots
Some AI providers crawl websites to use the content as training data. You can block their crawlers:
```php
<?php
// site/config/config.php
return [
'tobimori.seo' => [
'robots' => [
'content' => [
'GPTBot' => [
'Disallow' => ['/'],
],
'Google-Extended' => [
'Disallow' => ['/'],
],
'CCBot' => [
'Disallow' => ['/'],
],
],
],
],
];
```
This adds rules for each bot while keeping the default rules for all other crawlers intact.
## Custom rules for all crawlers
If you set rules for `*`, they replace the default rules entirely:
```php
'content' => [
'*' => [
'Allow' => ['/'],
'Disallow' => ['/panel', '/content', '/private'],
],
],
```
## Mixing rules
You can combine rules for all crawlers with rules for specific bots:
```php
'content' => [
'*' => [
'Allow' => ['/'],
'Disallow' => ['/panel', '/content'],
],
'GPTBot' => [
'Disallow' => ['/'],
],
],
```
The `Sitemap:` line is added automatically if the [sitemap module](1_features/01_sitemap) is active. You can override it with the `robots.sitemap` option.

27
site/plugins/kirby-seo/docs/2_customization/03_robots-noai.md Normal file
View file

@ -0,0 +1,27 @@
---
title: Opting Out of AI Training
intro: Signal to AI crawlers that your content should not be used for training
---
The `noai` and `noimageai` robot directives tell AI crawlers not to use your content or images for training. These are not an official standard, but were introduced by [DeviantArt and Spawning](https://www.deviantart.com/team/journal/UPDATE-All-Deviations-Are-Opted-Out-of-AI-Datasets-934500371) and are respected by some AI providers. Like all robot directives, they are signals, not hard blocks.
Kirby SEO has a `types` option that controls which robot directives are available. Add `ai` and `imageai` to the list:
```php
<?php
// site/config/config.php
return [
'tobimori.seo' => [
'robots' => [
'types' => ['index', 'follow', 'archive', 'imageindex', 'snippet', 'ai', 'imageai'],
],
],
];
```
The new fields show up in the robots section of the SEO tab. If you previously disabled `robots.pageSettings`, you need to re-enable it for the fields to appear.
By default, all directives are set to "Yes" (allowed). To opt out of AI training, an editor needs to set the AI Training and AI Image Training fields to "No". The plugin then outputs `noai` and `noimageai` in the robots meta tag.
If you want to opt out for all pages at once, set it on the Site level instead of per page. Translations for the field labels are included in the plugin.

77
site/plugins/kirby-seo/docs/2_customization/05_sitemap.md Normal file
View file

@ -0,0 +1,77 @@
---
title: Customizing the Sitemap
intro: Fine-tune the built-in sitemap or replace it entirely
---
The built-in sitemap generator has a few options to adjust its behavior. For most sites, these are enough. If you need full control, you can replace the generator with your own.
## Excluding templates
By default, only the `error` template is excluded. To exclude more templates:
```php
<?php
// site/config/config.php
return [
'tobimori.seo' => [
'sitemap' => [
'excludeTemplates' => ['error', 'redirect', 'internal'],
],
],
];
```
## Grouping by template
By default, all pages end up in a single sitemap. If you have many pages, you can split them into separate sitemaps per template. This creates a sitemap index at `/sitemap.xml` with links to `/sitemap-blog.xml`, `/sitemap-product.xml`, etc.
```php
'sitemap' => [
'groupByTemplate' => true,
],
```
## Change frequency and priority
Both `changefreq` and `priority` accept a static value or a callable:
```php
'sitemap' => [
'changefreq' => 'daily',
'priority' => fn (Page $page) => $page->isHomePage() ? 1.0 : 0.5,
],
```
The default `changefreq` is `weekly`. The default `priority` is calculated from page depth: the homepage gets `1.0`, each level deeper subtracts `0.2`, down to `0.2`.
## Writing your own generator
If the options above aren't enough, you can replace the entire sitemap generator. The `generator` option takes a callable that receives a `SitemapIndex` instance. Here's a minimal example:
```php
<?php
use tobimori\Seo\Sitemap\SitemapIndex;
return [
'tobimori.seo' => [
'sitemap' => [
'generator' => function (SitemapIndex $sitemap) {
$index = $sitemap->create('pages');
foreach (site()->index()->listed() as $page) {
$index->createUrl($page->url())
->lastmod($page->modified())
->changefreq('weekly')
->priority(0.8);
}
},
],
],
];
```
`$sitemap->create('key')` creates a sitemap group. `$index->createUrl($url)` adds a URL entry, and you can chain `->lastmod()`, `->changefreq()`, `->priority()`, and `->alternates()` on it.
The built-in generator does more: it filters by robots settings, respects `excludeTemplates`, handles `groupByTemplate`, and adds hreflang links for multilingual sites. You can find its source in `config/options/sitemap.php` as a reference for your own.

134
site/plugins/kirby-seo/docs/2_customization/06_ai-assist.md Normal file
View file

@ -0,0 +1,134 @@
---
title: Customizing AI Assist
intro: Override prompts or add your own AI provider
---
## Overriding prompts
AI Assist uses Kirby snippets for its prompts. You can override any of them by creating a snippet with the same path in your project.
The built-in prompt snippets are:
- `seo/prompts/tasks/title` - Meta title generation
- `seo/prompts/tasks/description` - Meta description generation
- `seo/prompts/tasks/og-description` - Open Graph description generation
- `seo/prompts/tasks/site-description` - Site-level meta description
- `seo/prompts/tasks/og-site-description` - Site-level OG description
To override the meta title prompt, create `site/snippets/seo/prompts/tasks/title.php` in your project. Kirby's snippet loading will pick up your version instead of the built-in one.
Each prompt snippet receives these variables:
- `$page` - the current page
- `$site` - the site object
- `$instructions` - custom instructions from the editor (if any)
- `$edit` - the existing text when editing (if any)
There are also shared snippets that the task prompts include:
- `seo/prompts/introduction` - Defines the AI's role and rules
- `seo/prompts/content` - Extracts the page content
- `seo/prompts/meta` - Shows existing metadata for context
You can override these too. Look at the built-in prompts in `site/plugins/kirby-seo/snippets/prompts/` to understand their structure before writing your own.
## Adding a custom provider
If you need a provider that isn't built in, you can add your own. A provider has two parts: a driver class that handles the API communication, and a config entry that registers it.
Create a class that extends `tobimori\Seo\Ai\Driver`. The only method you need to implement is `stream`, which receives a prompt string and must yield `Chunk` objects as the response comes in.
```php
<?php
namespace App\Ai;
use Generator;
use tobimori\Seo\Ai\Chunk;
use tobimori\Seo\Ai\Driver;
use tobimori\Seo\Ai\SseStream;
class MyProvider extends Driver
{
public function stream(string $prompt, string|null $model = null): Generator
{
$apiKey = $this->config('apiKey', required: true);
$model = $model ?? $this->config('model', 'default-model');
$endpoint = $this->config('endpoint', required: true);
$stream = new SseStream($endpoint, [
'Content-Type: application/json',
'Accept: text/event-stream',
"Authorization: Bearer {$apiKey}",
], [
'model' => $model,
'input' => $prompt,
'stream' => true,
], (int)$this->config('timeout', 120));
yield from $stream->stream(function (array $event): Generator {
$type = $event['type'] ?? null;
if ($type === 'start') {
yield Chunk::streamStart($event);
}
if ($type === 'delta') {
yield Chunk::textDelta($event['text'] ?? '', $event);
}
if ($type === 'done') {
yield Chunk::streamEnd($event);
}
if ($type === 'error') {
yield Chunk::error($event['message'] ?? 'Unknown error', $event);
}
});
}
}
```
The driver uses `$this->config()` to read values from the provider's `config` array in `config.php`. Pass `required: true` to throw an error if a value is missing.
`SseStream` is a helper class included in Kirby SEO that handles the cURL request and SSE parsing. You pass it the endpoint, headers, payload, and a mapper function that converts raw SSE events into `Chunk` objects.
If your API doesn't use SSE, you can skip `SseStream` and yield chunks directly.
The chunks the Panel expects, in order:
1. `Chunk::streamStart()` - Signals the stream has started
2. `Chunk::textDelta($text)` - Each piece of generated text (repeated)
3. `Chunk::textComplete()` - The text is done
4. `Chunk::streamEnd()` - The stream is finished
If something goes wrong, yield `Chunk::error($message)` at any point.
## Registering the provider
Add your driver to the config and set it as the active provider:
```php
<?php
// site/config/config.php
return [
'tobimori.seo' => [
'ai' => [
'provider' => 'myprovider',
'providers' => [
'myprovider' => [
'driver' => \App\Ai\MyProvider::class,
'config' => [
'apiKey' => 'sk-...',
'model' => 'my-model',
'endpoint' => 'https://api.example.com/v1/chat',
],
],
],
],
],
];
```
See the built-in drivers in `site/plugins/kirby-seo/classes/Ai/Drivers/` for complete implementations.

45
site/plugins/kirby-seo/docs/2_customization/07_gsc-setup.md Normal file
View file

@ -0,0 +1,45 @@
---
title: Setting up Google Search Console
intro: Connect Search Console with your own Google OAuth credentials
---
By default, the Search Console integration uses a proxy to keep setup simple. If you'd rather connect directly, you can set up your own Google OAuth credentials instead. This requires a Google Cloud project with the Search Console API enabled. The API is free to use.
## Create OAuth credentials
Go to the [Google Cloud Console](https://console.cloud.google.com/) and create a new project, or use an existing one.
Navigate to **APIs & Services** → **Credentials** → **Create Credentials** → **OAuth client ID** and configure it:
- **Application type:** Web application
- **Name:** e.g. "Kirby SEO on example.com"
- **Authorized redirect URIs:** your site URL followed by `/__seo/gsc/callback`, e.g. `https://example.com/__seo/gsc/callback`
Download the JSON file when prompted. You'll need it in the next step.
Then go to **APIs & Services** → **Library**, search for "Google Search Console API" and enable it. Without this, the OAuth flow will succeed but the API requests will fail.
## Add credentials to your config
Place the downloaded JSON file in your `site/config` directory (e.g. `site/config/gsc-credentials.json`), then reference it in your config:
```php
<?php
// site/config/config.php
use Kirby\Data\Json;
return [
'tobimori.seo' => [
'searchConsole' => [
'credentials' => Json::read(__DIR__ . '/gsc-credentials.json'),
],
],
];
```
## Connect in the Panel
Open the Panel and navigate to any page with the SEO tab. The Google Search Console section now shows a **Connect** button. Click it and authorize with your Google account. Make sure the Google account you use has access to the Search Console property for your site.
After authorizing, select which Search Console property to use. The section starts showing data once the property is selected.

89
site/plugins/kirby-seo/docs/2_customization/08_schema-org.md Normal file
View file

@ -0,0 +1,89 @@
---
title: Schema.org (JSON-LD)
intro: Add structured data to your pages
---
Kirby SEO can output Schema.org structured data as JSON-LD. It uses the [spatie/schema-org](https://github.com/spatie/schema-org) package, which must be installed separately:
```bash
composer require spatie/schema-org
```
Once installed, a `WebSite` schema is generated automatically for every page with the page's title, description, and canonical URL. You can build on top of this or add your own schemas.
## Adding structured data
The plugin exposes a global store for Schema.org objects. You can access it from templates, snippets, or block snippets using `$page->schema()` and `$site->schema()`. Calling the same type twice returns the same instance, so you can build up a schema across different files.
```php
<?php
// site/templates/article.php
$page->schema('Article')
->headline($page->title()->value())
->datePublished($page->date()->toDate('c'))
->author(
schema('Person')
->name($page->author()->value())
);
```
`$page->schema($type)` returns the stored schema for that type, or creates a new one if it doesn't exist yet. Both also exist as `$site->schema()` and `$site->schemas()` for site-level schemas.
The global `schema($type)` function creates a new instance without storing it. Use it for nested objects like the `Person` above that don't need their own top-level entry.
## Building schemas across blocks
Because `$page->schema()` always returns the same instance, you can add to a schema from individual block snippets. This is useful for types like `FAQPage` where the content comes from multiple blocks:
```php
<?php
// site/snippets/blocks/faq.php
$page->schema('FAQPage')
->mainEntity([
...($page->schema('FAQPage')->getProperty('mainEntity') ?? []),
schema('Question')
->name($block->question())
->acceptedAnswer(
schema('Answer')->text($block->answer())
),
]);
```
Each block appends its question to the `mainEntity` array. The final output combines all of them:
```json
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "How does it work?",
"acceptedAnswer": {
"@type": "Answer",
"text": "It works like this."
}
},
{
"@type": "Question",
"name": "Can it handle multiple blocks?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Yes, it can."
}
}
]
}
```
## Disabling the default schema
If you don't want the automatic `WebSite` schema, disable it in your config:
```php
'tobimori.seo' => [
'generateSchema' => false,
],
```

21
site/plugins/kirby-seo/docs/2_customization/09_optimizing-head-order.md Normal file
View file

@ -0,0 +1,21 @@
---
title: Optimizing Head Order
intro: Place high-priority elements before stylesheets and scripts
---
The order of elements in the `<head>` can affect perceived page performance. Ideally, the `<title>` element should appear early, before stylesheets and scripts, while other meta tags like Open Graph and description can go last. See [capo.js](https://rviscomi.github.io/capo.js/) for background on why this matters.
By default, `seo/head` outputs all tags in one block. If you want to split priority tags from the rest, use Kirby's [snippet slots](https://getkirby.com/docs/guide/templates/snippets#passing-data-to-snippets__slots):
```php
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<?php snippet('seo/head', slots: true) ?>
<link rel="stylesheet" href="/assets/css/main.css">
<script src="/assets/js/app.js" defer></script>
<?php endsnippet() ?>
</head>
```
This outputs the `<title>` first, then your stylesheets and scripts from the slot, then the remaining meta tags (description, Open Graph, robots, etc.).

6
site/plugins/kirby-seo/docs/2_customization/10_background-processing.md Normal file
View file

@ -0,0 +1,6 @@
---
title: Setup Background Processing
intro:
---
Coming soon

47
site/plugins/kirby-seo/docs/2_customization/11_plugin-extensions.md Normal file
View file

@ -0,0 +1,47 @@
---
title: Extending the Plugin
intro: Replace built-in classes with your own
---
Kirby SEO uses a component system similar to [Kirby's own](https://getkirby.com/docs/reference/plugins/components). Every major class in the plugin can be swapped out for a custom one. This lets you change how the plugin works without forking it.
The built-in components are:
| Key | Default class | Handles |
| ---------- | ---------------------------------- | --------------------------------- |
| `meta` | `tobimori\Seo\Meta` | Meta tag generation and cascading |
| `ai` | `tobimori\Seo\Ai` | AI Assist provider management |
| `indexnow` | `tobimori\Seo\IndexNow` | IndexNow ping requests |
| `schema` | `tobimori\Seo\SchemaSingleton` | Schema.org structured data store |
| `gsc` | `tobimori\Seo\GoogleSearchConsole` | Google Search Console integration |
To replace a component, create a class that extends the original. For example, to customize meta tag output, extend the `Meta` class:
```php
<?php
// site/plugins/my-seo/index.php
use tobimori\Seo\Meta;
class MyMeta extends Meta
{
// override any method you need
}
```
Then register your class in the config:
```php
<?php
// site/config/config.php
return [
'tobimori.seo' => [
'components' => [
'meta' => MyMeta::class,
],
],
];
```
The rest of the plugin picks up your class automatically. Page methods, hooks, routes, and sections all resolve components through the config, so your class is used everywhere the original would have been. Look at the built-in classes in `site/plugins/kirby-seo/classes/` to see what methods are available to override.

157
site/plugins/kirby-seo/docs/3_reference/0_options.md Normal file
View file

@ -0,0 +1,157 @@
---
title: Options
intro: All configuration options
---
All options are set under `tobimori.seo` in your `config.php`. Dots in the option names represent nested arrays. For example, `robots.enabled` becomes:
```php
<?php
// site/config/config.php
return [
'tobimori.seo' => [
'robots' => [
'enabled' => true,
],
],
];
```
You can also use Kirby's flat dot syntax:
```php
return [
'tobimori.seo.robots.enabled' => true,
];
```
Both are equivalent, but you cannot use dot syntax inside a nested array. `'robots.enabled' => true` only works at the top level as `'tobimori.seo.robots.enabled'`. Inside the `'tobimori.seo'` array, you must use nested arrays.
## General
| Option | Default | Description |
| ------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `locale` | `'en_US'` | Default locale for single-language sites |
| `dateFormat` | `null` | Custom date format for dates in meta tags |
| `generateSchema` | `true` | Generate a default `WebSite` schema for every page. Requires [spatie/schema-org](2_customization/08_schema-org) |
| `previews` | `['google', 'facebook', 'slack']` | Which preview types to show in the Panel |
| `cascade` | `['fields', 'programmatic', 'parent', 'fallbackFields', 'site', 'options']` | The [meta cascade](2_customization/01_meta-cascade) order |
| `canonical.base` | `null` | Base URL for canonical links. Uses the site URL if not set |
| `canonical.trailingSlash` | `false` | Add trailing slashes to canonical URLs |
| `files.parent` | `null` | Default parent page for file uploads in SEO fields |
| `files.template` | `null` | Default file template for SEO file uploads |
| `socialMedia` | See below | Social media account fields shown in the site blueprint |
The `socialMedia` option defines which fields appear in the site blueprint. Default fields: `twitter`, `facebook`, `instagram`, `youtube`, `linkedin`, `bluesky`, `mastodon`. Each key maps to a placeholder URL. Override the array to add or remove fields.
## Meta defaults
These are the fallback values for the last level of the [meta cascade](2_customization/01_meta-cascade). They apply when no other level provides a value. Each option can be a static value or a callable that receives the `Page` object.
| Option | Default | Description |
| -------------------------- | ---------------------------------- | ---------------------------------------------------------- |
| `default.metaTitle` | Page title | Meta title |
| `default.metaTemplate` | `'{{ title }} - {{ site.title }}'` | Title template applied to all pages |
| `default.ogTemplate` | `'{{ title }}'` | Open Graph title template |
| `default.ogSiteName` | Site title | Open Graph site name |
| `default.ogType` | `'website'` | Open Graph type |
| `default.ogDescription` | Meta description | Open Graph description, falls back to the meta description |
| `default.cropOgImage` | `true` | Crop OG images to 1200x630 |
| `default.locale` | Language locale or `'en_US'` | Locale for meta tags |
| `default.robotsIndex` | `true` if listed and not debug | Whether pages are indexable |
| `default.robotsFollow` | Same as `robotsIndex` | Whether links are followed |
| `default.robotsArchive` | Same as `robotsIndex` | Whether archiving is allowed |
| `default.robotsImageindex` | Same as `robotsIndex` | Whether image indexing is allowed |
| `default.robotsSnippet` | Same as `robotsIndex` | Whether snippets are allowed |
## Robots
| Option | Default | Description |
| ------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `robots.enabled` | `true` | Whether the plugin handles robots meta tags and robots.txt |
| `robots.index` | `true` (unless debug mode) | Site-wide indexing default. Set to `false` to noindex the entire site |
| `robots.followPageStatus` | `true` | Unlisted pages are noindex by default |
| `robots.pageSettings` | `true` | Show robots settings on each page in the Panel |
| `robots.types` | `['index', 'follow', 'archive', 'imageindex', 'snippet']` | Available robot directive types. Add `'ai'` and `'imageai'` for [AI training controls](2_customization/03_robots-noai) |
| `robots.content` | `[]` | Custom [robots.txt rules](2_customization/02_robots-txt) per user agent |
| `robots.sitemap` | `null` | Custom sitemap URL for robots.txt. Auto-detected when the sitemap module is active |
## Sitemap
| Option | Default | Description |
| -------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------- |
| `sitemap.enabled` | `true` | Whether to generate a sitemap |
| `sitemap.redirect` | `true` | Redirect `/sitemap` to `/sitemap.xml` |
| `sitemap.locale` | `'en'` | Locale for the sitemap XSL stylesheet |
| `sitemap.generator` | Built-in generator | A callable that receives a `SitemapIndex` instance. See [customizing the sitemap](2_customization/05_sitemap) |
| `sitemap.changefreq` | `'weekly'` | Default change frequency. Static value or callable |
| `sitemap.priority` | Calculated from depth | Homepage gets `1.0`, each level deeper subtracts `0.2`, minimum `0.2` |
| `sitemap.groupByTemplate` | `false` | Split the sitemap into separate files per template |
| `sitemap.excludeTemplates` | `['error']` | Templates to exclude from the sitemap |
## AI Assist
| Option | Default | Description |
| -------------- | ---------- | --------------------------------- |
| `ai.enabled` | `true` | Whether AI features are available |
| `ai.provider` | `'openai'` | The active provider ID |
| `ai.providers` | See below | Provider configurations |
Each provider has a `driver` class and a `config` array. The config options depend on the driver. All built-in drivers share `apiKey` (required), `model`, `endpoint`, and `timeout`. The OpenAI driver also accepts `organization`.
| Provider | Driver | Default model | Default endpoint |
| ------------ | ----------- | -------------------------------- | --------------------------------------------------------- |
| `openai` | `OpenAi` | `gpt-5-mini-2025-08-07` | `https://api.openai.com/v1/responses` |
| `anthropic` | `Anthropic` | `claude-4-5-haiku` | `https://api.anthropic.com/v1/messages` |
| `gemini` | `Gemini` | `gemini-3.1-flash-lite-preview` | `https://generativelanguage.googleapis.com/v1beta` |
| `openrouter` | `OpenAi` | `openai/gpt-5-nano` | `https://openrouter.ai/api/v1/responses` |
The Gemini driver authenticates via API key as a query parameter (not a header). All providers default to a timeout of 120 seconds. See [customizing AI Assist](2_customization/06_ai-assist) for adding your own provider.
## IndexNow
| Option | Default | Description |
| ----------------------- | ---------------------------- | ---------------------------------------------------------- |
| `indexnow.enabled` | `true` | Whether to ping search engines on page changes |
| `indexnow.searchEngine` | `'https://api.indexnow.org'` | IndexNow API endpoint. One engine propagates to all others |
| `indexnow.rules` | `[]` | Invalidation rules for related pages |
Rules map a match pattern to invalidation targets. Match patterns can be a URL glob (`'/blog/*'`), a template name (`'article'`), or a wildcard (`'*'`).
| Target | Value | Description |
| ----------- | --------------- | ---------------------------------------------------------- |
| `parent` | `true` or `int` | Invalidate the direct parent (`true`) or N levels up |
| `children` | `true` or `int` | Invalidate all descendants (`true`) or up to N levels deep |
| `siblings` | `true` | Invalidate all siblings at the same level |
| `urls` | `string[]` | Specific URLs to invalidate |
| `templates` | `string[]` | Invalidate all pages with these templates |
```php
'indexnow' => [
'rules' => [
'article' => ['parent' => true, 'urls' => ['/blog', '/']],
'product' => ['parent' => true, 'siblings' => true, 'templates' => ['category']],
],
],
```
## Search Console
| Option | Default | Description |
| --------------------------- | ------------------------------ | ----------------------------------------------------------------------------- |
| `searchConsole.enabled` | `true` | Whether the Search Console integration is active |
| `searchConsole.credentials` | `null` | Google OAuth credentials array. See [GSC setup](2_customization/07_gsc-setup) |
| `searchConsole.tokenPath` | `site/config/.gsc-tokens.json` | Where OAuth tokens are stored |
## Components
| Option | Default | Description |
| --------------------- | ---------------------------------- | ------------------------- |
| `components.meta` | `tobimori\Seo\Meta` | Meta tag generation class |
| `components.ai` | `tobimori\Seo\Ai` | AI Assist class |
| `components.indexnow` | `tobimori\Seo\IndexNow` | IndexNow class |
| `components.schema` | `tobimori\Seo\SchemaSingleton` | Schema.org store class |
| `components.gsc` | `tobimori\Seo\GoogleSearchConsole` | Search Console class |
See [extending the plugin](2_customization/11_plugin-extensions) for details on replacing components.

37
site/plugins/kirby-seo/docs/3_reference/1_permissions.md Normal file
View file

@ -0,0 +1,37 @@
---
title: Permissions
intro: Control access to plugin features by user role
---
Kirby SEO registers permissions that you can restrict per [user role](https://getkirby.com/docs/guide/users/permissions). By default, all permissions are granted.
## Available permissions
| Permission | Controls |
| ----------------- | -------------------------------------------------------------------------------- |
| `tobimori.seo.ai` | Access to all AI Assist features: generating, editing, and customizing meta text |
More permissions will be added in future releases.
## Restricting access
Set a permission to `false` in a role's blueprint to deny it:
```yaml
# site/blueprints/users/editor.yml
title: Editor
permissions:
tobimori.seo:
ai: false
```
You can also deny all current and future permissions at once using a wildcard:
```yaml
permissions:
tobimori.seo:
*: false
```
Users without a permission will not see the corresponding UI elements in the Panel, and API requests will be rejected.