Kirby Tools
v3.1.0Hub

View Button & Section

Configure the SEO Audit view button and section in your blueprints.

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

View Button Configuration

The SEO Audit view button can be added to any Panel view (site, page, file) alongside the default buttons like the preview and settings buttons. It provides instant access to SEO and readability analysis.

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:

pages/default.yml
buttons:
  - seo-audit
  - preview
  - settings
  - 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:

pages/default.yml
buttons:
  seo-audit:
    keyphraseField: metakeyphrase
    assessments:
      - metaDescriptionKeyword
      - metaDescriptionLength
      - titleWidth
      - images
      - textLength
    contentSelector: "#main"
  preview: true
  settings: true
  status: true

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.

Field references in Kirby are case-insensitive and normalized to lowercase. If your field is named metaKeyphrase, reference it as metakeyphrase (all lowercase) in the configuration.
pages/default.yml
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
Unless you explicitly include them in the assessments property, all keyphrase assessments will be skipped if no keyphraseField is defined.

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.
Kirby queries are only supported when using the SEO Audit section, not the view button.

For example, it is useful to automatically use the page title as the keyphrase:

buttons:
  seo-audit:
    keyphrase: developers

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.

Field references in Kirby are case-insensitive and normalized to lowercase. Use lowercase for field names in the configuration (e.g., metasynonyms instead of metaSynonyms).
pages/default.yml
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 as an alternative to the keyphraseField, you can set the synonyms property directly in the blueprint. This allows you to define synonyms itself, eliminating the need for a separate field that an editor would have to fill in.

buttons:
  seo-audit:
    keyphrase: SEO Audit
    synonyms:
      - Kirby
      - SEO
      - Audit
Kirby queries are only supported when using the SEO Audit section, not the view button.

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.

For a list of available SEO checks, see the Assessments Guide page.

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

buttons:
  seo-audit:
    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:

buttons:
  seo-audit:
    contentSelector: "#main:not(.sidebar):not(.footer)"
The contentSelector also supports querying for multiple elements. For instance, to select all elements with the class .seo-audit-allowed while excluding elements certain elements with the class .seo-audit-ignore, you can use the following selector: .seo-audit-allowed > *:not(.seo-audit-ignore).

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:

buttons:
  seo-audit:
    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:

buttons:
  seo-audit:
    links: false

logLevel String

Set the log level for debugging purposes. This property controls how much information is logged to the browser console during the analysis process.

The available log levels are: error, warn, info, debug

buttons:
  seo-audit:
    logLevel: info

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:

pages/default.yml
sections:
  seoAudit:
    type: seo-audit

This is how the section will render in the Panel:

SEO audit section in Kirby Panel

Click the Analyze button to perform a SEO and readability analysis on the current page. The analysis results are organized into three categories: Good, OK, and Bad, making it easy to prioritize optimization efforts:

SEO audit section showing categorized results

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:

sections/seo-audit.yml
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:

sections/seo-audit.yml
type: seo-audit
persisted: false

Global Configuration

Configure global defaults for the SEO Audit Panel view buttons and sections.

Assessments for SEO and Readability

Pick from 28 different SEO and readability assessments powered by Yoast SEO v3 with improved performance and accuracy.