Kirby Tools
v3.0.1Hub

View Button & Section

Configure the SEO Audit Panel view button and section in your blueprints with various options.

You can configure the SEO Audit view button and section when adding them to your blueprints. This gives you fine-grained control over which blueprints have SEO analysis capabilities and how the analysis is performed.

Most of the available options can be set for both the view button and section:

  • keyphraseField – Field name containing the target keyphrase
  • keyphrase – Static keyphrase or Kirby query
  • synonymsField – Field name containing keyphrase synonyms
  • synonyms – Static synonyms array
  • assessments – Which assessments to include
  • contentSelector – CSS selector for content analysis
  • links – Enable or disable recommendation links
  • logLevel – Set the logging level

The following options are only available for the SEO Audit section:

  • label – Custom label for the section
  • persisted – Save results to local storage

View Button 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.

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 don't 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.

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.

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 that should be analyzed. This is useful if you want to exclude certain parts of the page, such as the header, footer, or sidebar, from the SEO analysis.

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 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

Decide whether or not to save the audit to local storage. By default, the generated SEO report is saved to (and read from) the browser's local storage. This allows the editor to close the panel and return to the SEO audit later without having to rerun the analysis.

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.