# SEO Analysis

> Source: https://agilitycms.com/docs/apps/seo-analysis

The **SEO Analysis** app scores the pages in your Agility instance for SEO and readability, using the open-source YoastSEO.js analysis library. It runs in the sidebar of the content editor and the page editor, reads the real rendered page from your website, and tells editors what to fix before they publish.

## What is the SEO Analysis app?

Most SEO tools score content after it is live. This app scores it while it is being written. Open a page or a content item and the panel:

- Fetches the page as your website renders it, including unpublished changes through your site's preview URL
- Runs the Yoast SEO and readability assessments over the main content of that page
- Shows an SEO score, a readability score, and a list of findings with plain-language advice
- Lets the editor set a **focus keyphrase** and a **meta description** without leaving the sidebar

It works on two kinds of page:

- **Regular pages** from the page tree, in the **page sidebar**
- **Dynamic-page content items** such as blog posts, articles and products, in the **content item sidebar**

Folders, links and dynamic page templates have no rendered page of their own, so the panel explains that instead of showing a score.

## What gets scored

The panel works with no setup. Without a focus keyphrase it still reports the structural checks:

- Meta description length
- Text length
- Internal and outbound links
- Images, including alt text
- SEO title width, measured in pixels the way Google measures it
- A single H1
- Readability: sentence length, paragraph length, subheading distribution, passive voice, transition words, and consecutive sentence beginnings

Setting a focus keyphrase unlocks the keyphrase-relative checks, and with them an overall SEO score:

- Keyphrase in the SEO title, the introduction, the subheadings, the slug and the meta description
- Keyphrase density and length
- Keyphrase in image alt text
- Competing links that use the keyphrase as anchor text

The overall SEO score is only shown once a keyphrase is set. Scoring the structural checks alone would produce a number that is not comparable to the one you get with a keyphrase, so the panel shows no score rather than a misleading one.

## Before you start

- Administrator access to the instance, to install the app
- A website that renders your Agility content and honours Agility **preview URLs**. The app fetches the page the same way the CMS preview button opens it, so unpublished changes are scored too. If your preview route sets a cookie and redirects, that is handled.
- For content items, a container that is a **dynamic page list**. Content items that are building blocks rather than pages have no URL to score.

## Installing the SEO Analysis app

You can install the app from the Marketplace under **Settings > Apps**. You need to be an administrator on the instance to install an app.

1. Navigate to **Settings > Apps**
2. Click **Install**
3. Type **SEO Analysis** into the search box, then select the **SEO Analysis** app
4. Review the app details, then click **Continue**
5. Optionally fill in the two configuration values (see below), then click **Next**
6. Click **Finish setup**

The panel appears right away in the sidebar of every page in the page tree, and of every content item whose container is a dynamic page list. There is no field to add to any model.

### Configuration values

Both settings are optional.

| Setting | What it does |
|---|---|
| **Main content selector** | A CSS selector for the part of the rendered page to analyze. Defaults to `main`, then `[role=main]`, `article`, `#content` and `.content`. Set this if your templates use a different wrapper for the page body. Navigation, header, footer, scripts and styles are excluded automatically. |
| **Default analysis language** | A fallback locale, such as `en_US`, used when an Agility locale has no matching analysis language. |

The content selector matters more than it looks. Link counts, image counts, word count and the single-H1 check are all counts over the main content. Leaving the navigation and footer in would inflate every one of them, identically on every page, and make the scores meaningless.

## Using the SEO Analysis app

### On a page

Open any page in **Pages** and select **SEO Analysis** in the right-hand sidebar. The panel fetches the rendered page and scores it.

- **Focus keyphrase** is saved for this page when you leave the field. The analysis updates as you type.
- **Meta description** is saved to the page's SEO settings when you leave the field. This is the same field the page's own **SEO** tab edits, so nothing about your website needs to change to pick it up.
- The **SEO title** is read from the rendered page and shown with a pixel-width meter. It is read-only here: the site usually decorates the page title with a suffix or the site name, so the panel shows what Google will actually see rather than a raw field.
- The **refresh** icon re-fetches the rendered page. Use it after saving component changes.

### On a content item

Open any item in a container that is a dynamic page list and select **SEO Analysis** in the sidebar. The panel resolves the item's own URL from its slug, so each post or product is scored as itself rather than as the dynamic page's default item.

- **Focus keyphrase** works the same way as on a page, and is saved per item and per locale.
- **Meta description** is written to the item's `DynamicPageMetaDescription` system field as you type, and saved when you save the item. This is an Agility system field present on every dynamic-page item, so no model change is needed, and the CMS's own SEO tab reads and writes the same key.
- The **SEO title** comes from the page template's title formula and is shown read-only.

### Reading the results

The **SEO** and **Readability** tabs each list their findings with a colored dot: green is good, orange is acceptable, red needs attention. Findings that point at a single field, such as the meta description, have a **Fix** action that jumps to that field in the panel. The footer shows how many words were analyzed.

## Language support

Twenty-two languages have dedicated analysis: Arabic, Catalan, Czech, German, Greek, English, Spanish, Persian, French, Hebrew, Hungarian, Indonesian, Italian, Japanese, Norwegian, Dutch, Polish, Portuguese, Russian, Slovak, Swedish and Turkish. The analysis language follows the locale of the item or page being edited.

Other languages fall back to a language-agnostic analysis. Most assessments still run; the ones that depend on word forms, such as passive voice and transition words, are skipped, and the panel says so.

## Where your data goes

The analysis itself runs on the app's own server, not in your browser and not in Agility. Your browser sends the rendered page content and receives scores and feedback text back. Nothing about the analysis is stored.

| Data | Where it lives |
|---|---|
| Meta description, content item | `DynamicPageMetaDescription` on the item, in your Agility instance |
| Meta description, page | The page's SEO settings, in your Agility instance |
| Focus keyphrase | The app's own store, keyed by instance, locale and item or page. Agility has no field for a keyphrase, and adding one would mean a model change on every instance. |

All writes to your instance are made with the editor's own Management API token, so the app can only change what the editor could change themselves.

## Troubleshooting

**"This item isn't connected to a dynamic page"** – the item's container is not a dynamic page list, so there is no rendered URL to score. Enable a dynamic page on the container to turn the analysis on.

**"The rendered page could not be loaded"** – the app could not fetch your site's preview URL. Check that the site is running and that its preview URL is reachable from the public internet, not only from your network.

**Scores look inflated, or every page reports the same link and image counts** – the main content selector is probably matching too much of the page. Set **Main content selector** to the element that wraps only the page body.

**The panel scores the wrong post** – the item has no slug field the app can recognise. It looks for fields named `URL`, `Slug`, `PageSlug` or `FriendlyURL`; add or rename one and the panel resolves the item's real URL.

## Licensing

This app is open source under the GNU General Public License v3.0, and its source is on [GitHub](https://github.com/agility/agility-cms-app-seo-analysis). It is built on YoastSEO.js, which is also GPL-3.0. The library runs only on the app's server; your browser receives scores and feedback text. This app is not affiliated with or endorsed by Yoast BV.

## Related

- [App Types In Agility](https://agilitycms.com/docs/apps/apps-in-agility), on Marketplace versus Private Apps
- [Apps](https://agilitycms.com/docs/owners-admins/apps), on installing and managing apps in an instance
- [Google Analytics](https://agilitycms.com/docs/apps/google-analytics), another app that adds a page sidebar