Kirby SEO Audit can be added to Panel views via a view button (recommended) or a section. Both approaches share their configuration properties and can be used together.

View Button Configuration

Add the seo-audit view button to a site or page blueprint, alongside default buttons such as preview and settings. The analysis needs an HTML preview URL, so file views are out of scope.

Clicking the SEO Audit view button immediately runs an SEO and readability analysis for the current page and opens the results in a Panel dialog. The dot on the button is the page's rating.

Basic Setup

To add the seo-audit view button to a Panel view, set the buttons option in the corresponding blueprint. Listing buttons replaces Kirby's defaults, so name the ones you want to keep – the default set differs per model, and seo-audit goes wherever it suits the view:

buttons:
  - seo-audit
  - open
  - preview
  - languages

buttons:
  - seo-audit
  - open
  - preview
  - "-" # Kirby's default divider
  - settings
  - languages
  - status

Add the Button to Every View

To add the button to the site view and every page view without editing each blueprint, set Kirby's panel.viewButtons option. It replaces the defaults the same way a blueprint list does, and a blueprint that sets buttons wins over it:

return [
    'panel' => [
        'viewButtons' => [
            'site' => ['seo-audit', 'open', 'preview', 'languages'],
            'page' => ['seo-audit', 'open', 'preview', '-', 'settings', 'languages', 'status']
        ]
    ]
];

The option takes button names only, so props such as keyphraseField stay in the blueprint.

Advanced Configuration

To pass properties, write buttons as an object: seo-audit takes the properties, and every other button you keep is set to true:

buttons:
  seo-audit:
    keyphraseField: metaKeyphrase
    assessments:
      - metaDescriptionKeyword
      - metaDescriptionLength
      - titleWidth
      - images
      - textLength
    contentSelector: "#main"
  open: true
  preview: true
  settings: true
  languages: true
  status: true

Section Configuration

As an alternative to the view button, you can add an SEO Audit section to your blueprint. The section displays analysis results directly within the page content area instead of in a dialog.

Basic Setup

To add the SEO Audit section to a blueprint, include the following configuration:

sections:
  seoAudit:
    type: seo-audit

This is how the section will render in the Panel:

Click the Analyze button to run the analysis. The report appears below the button:

Shared Properties

label String

Custom label for the view button or the section headline. Both fall back to the plugin's own label in the current Panel language – "SEO Audit" in English.

label: SEO Report

keyphraseField String

If you want to include keyphrase assessments in your SEO analysis, you need to define a field in your blueprint that contains the keyphrase for the given page. Alternatively, use the keyphrase property (see below). Then, the editor can enter the keyphrase for which they want the page to rank in Google.

Set the keyphraseField property to select which field of the current page model contains the keyphrase.

buttons:
  seo-audit:
    # Reference the keyphrase field for the view button
    keyphraseField: metaKeyphrase

sections:
  content:
    type: fields
    fields:
      # Define the keyphrase field
      metaKeyphrase:
        label: SEO Keyphrase
        type: text
        help: The keyphrase you want this page to rank for
  seoAudit:
    type: seo-audit
    # Reference the keyphrase field for the section
    keyphraseField: metaKeyphrase

keyphrase String

Sets the keyphrase in the blueprint, so the editor does not enter one. Set alongside keyphraseField, it wins over the field's value.

keyphrase: editorial design

A Kirby query resolves against the current page, so the keyphrase can follow the content:

keyphrase: "{{ page.title.value }}"

synonymsField String

Add synonyms to your keyphrase to avoid repeating the same keyphrase over and over again.

Set the synonymsField property to indicate which field of the current page model contains the synonyms.

buttons:
  seo-audit:
    synonymsField: metaSynonyms

sections:
  content:
    type: fields
    fields:
      metaKeyphrase:
        label: SEO Keyphrase
        type: text
        help: The keyphrase you want this page to rank for
      metaSynonyms:
        label: Keyphrase Synonyms
        type: tags
        help: Synonyms and variations of the keyphrase
  seoAudit:
    type: seo-audit
    keyphraseField: metaKeyphrase
    synonymsField: metaSynonyms

synonyms Array

Sets the synonyms in the blueprint, so the editor does not fill in a field. Like keyphrase, it wins over its field.

keyphrase: editorial design
synonyms:
  - book design
  - typography
  - publication design

A Kirby query is only resolved in a string, and the result is split on commas. In list form every entry is used verbatim, so a {{ }} placeholder inside a list stays unresolved:

synonyms: "{{ page.metaSynonyms }}"

assessments Array

Limits the report to the listed assessments; without it, all of them are enabled. The keys are listed in Assessments for SEO and Readability.

assessments:
  # Select the assessments you want to include
  - metaDescriptionKeyword
  - metaDescriptionLength
  - titleWidth
  - images
  - textLength
  - imageKeyphrase

contentSelector String

The contentSelector property lets you define a CSS selector that specifies which part of the page should be analyzed. Use this to exclude navigation, footers, or sidebars from analysis – this prevents the plugin from flagging repetitive content that appears on every page.

By default, the plugin uses the body tag to select the content of the page. To analyze only the content of a specific element, set the contentSelector property:

contentSelector: "#main:not(.sidebar):not(.footer)"

To debug the content used for the SEO analysis, you can set the log level to info or higher. This will log the extracted HTML to the console:

contentSelector: ".seo-audit-allowed > *:not(.seo-audit-ignore)"
logLevel: info

links Boolean

The analysis results contain links to recommendation articles on Yoast.com that explain the individual assessments in more detail. While these links may be helpful, you may want to disable them for privacy reasons or to avoid distracting the editor.

To disable any links in the SEO report, set the links property to false:

links: false

analyzeOn String | Boolean

Turns the analysis after publishing on with publish or off with false for this view button or section. A blueprint value overrides the global option.

analyzeOn: publish

logLevel String

Controls how much the plugin logs to the browser console during analysis. Available levels are error, warn (default), info, and debug. It can also be set globally; a blueprint value overrides it.

logLevel: info

View Button-Only Properties

theme String

Controls the visual appearance and color theme of the button.

Default: positive-icon
Options: Any theme Kirby's button component accepts, including the filled variants without the -icon suffix – see Kirby's UI reference.

buttons:
  seo-audit:
    theme: positive

Section-Only Properties

persisted Boolean

By default, SEO reports are saved to the browser's local storage, one per section, page, and language. This allows editors to close the Panel and return later without rerunning the analysis. The rating the plugin keeps on the server is unaffected by this property.

To disable saving the report, set the persisted property to false:

type: seo-audit
persisted: false