View Button & Section Configuration

Kirby SEO Audit can be added to Panel views via a view button (recommended) or a section, and both can be used together. The section adds the label and persisted properties.

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 a SEO and readability analysis for the current page and opens the results in a Panel dialog.

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

Advanced Configuration

When configuring the view button in blueprints, use the available properties as props for the seo-audit button. For example, to define a field for the keyphrase and limit the assessments to a few selected ones, you can use the following configuration:

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 a 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 a SEO and readability analysis on the current page. Results are grouped into Good, OK, Bad, and Feedback – empty groups are omitted:

Shared Properties

keyphraseField String

If you want to include keyword/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 keyword or 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 main keyword you want this page to rank for
  seoAudit:
    type: seo-audit
    # Reference the keyphrase field for the section
    keyphraseField: metaKeyphrase

keyphrase String

If you do not want the editor to enter a keyphrase manually, you can set a default keyphrase for SEO analysis. Alternatively, you can use a Kirby query to resolve the keyphrase dynamically.

When to use which:

• Use keyphraseField when editors should enter their own keyword per page.
• Use keyphrase for static keywords or when pulling from a parent page via query.

keyphrase: developers

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. Not only will readers like this, but it will also help Google to better understand what your content is about.

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 main keyword you want this page to rank for
      metaSynonyms:
        label: Keyphrase Synonyms
        type: tags
        help: Alternative keywords and variations
  seoAudit:
    type: seo-audit
    keyphraseField: metaKeyphrase
    synonymsField: metaSynonyms

synonyms Array

Similar to the keyphrase property, which is an alternative to the keyphraseField, you can set the synonyms property directly in the blueprint. This allows you to define synonyms inline, eliminating the need for a separate field that an editor would have to fill in.

keyphrase: SEO Audit
synonyms:
  - Kirby
  - SEO
  - Audit

A Kirby query resolves in the string form, and its result is split on commas – a list is taken as written, placeholders included:

synonyms: "{{ page.metaSynonyms }}"

assessments Array

Kirby SEO Audit comes with a set of assessments used to analyze page content. You can enable or disable individual assessments by setting the assessments property. All assessments are enabled by default.

Here is an example of a blueprint configuration that only includes a subset of assessments:

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

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

Section-Only Properties

label String

The plugin provides a section label based on the current Panel language. However, you can customize the label by setting the label property.

To change the label, set the label property to your desired text:

type: seo-audit
label: SEO Report

persisted Boolean

By default, SEO reports are saved to the browser's local storage. This allows editors to close the Panel and return later without rerunning the analysis. It is also useful for comparing "before" and "after" results when optimizing content.

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

type: seo-audit
persisted: false