
# Pages for search engines

The `spring_flutter_seo` builder gives a Flutter web app real HTML pages. For every route and every Markdown file it writes a copy of `web/index.html` with the page's own `<head>` and its text, plus `sitemap.xml`, `robots.txt`, `llms.txt`, `llms-full.txt` and a `.md` copy of each Markdown page. It reads the `spring.flutter.web.seo.*` properties. This site is built this way.

## Why

A Flutter web app draws on a canvas. Its HTML holds no text, and every address serves the same `index.html`. A search engine, a link preview in a chat, or a language model that reads the page sees an empty page with one title.

The builder fixes this at build time, from the sources the app already shows: the screens of the navigation, and the Markdown files the app renders. There is no second version of the site to keep in step. Each address gets:

- its own `<head>`: `<title>`, description, `canonical`, the `og:*` and `twitter:*` tags of link previews, `robots` where a page must not be indexed, and the language alternates;
- its text, as plain HTML in `<main id="spring-content">`, under the [page loader](page-loader.md) and then under Flutter's view. A visitor never sees it, and it is never removed, so a crawler that runs the page's scripts still reads it.

## Example

This site's configuration:

```yaml
# neon_farum_azula: lib/resources/application-web.yml
spring:
  flutter:
    web:
      seo:
        enabled: true
        page-files: html
        site-url: https://farum-azula.org
        from-routes: true
        title: '{title} · Spring for Dart'
        description: Spring's programming model for Dart and Flutter.
        site-name: Spring Dart
        image: resources:images/preview.png
        pages:
          - path: /
            title: Spring for Dart
```

and one of its screens, which shows a folder of Markdown files:

```dart
@ScreenRoute(
  '/components/{*path}',
  title: '#{docs.title}',
  content: 'resources:content/components/',
)
class DocsPage extends StatelessWidget { ... }
```

The file `lib/resources/content/components/spring-boot-starter-web/cors.md` becomes the page `/components/spring-boot-starter-web/cors`. The build writes `web/components/spring-boot-starter-web/cors.html`, a copy of `web/index.html` whose head gets:

```html
<title>CORS · Spring for Dart</title>
...
<!-- spring:seo:head:start -->
<meta name="description" content="Let pages of other origins call the API: @CrossOrigin, ...">
<link rel="canonical" href="https://farum-azula.org/components/spring-boot-starter-web/cors">
<meta property="og:title" content="CORS">
<meta property="og:description" content="Let pages of other origins call the API: @CrossOrigin, ...">
<meta property="og:url" content="https://farum-azula.org/components/spring-boot-starter-web/cors">
<meta property="og:type" content="website">
<meta property="og:site_name" content="Spring Dart">
<meta property="og:image" content="https://farum-azula.org/assets/lib/resources/images/preview.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="CORS">
<meta name="twitter:description" content="Let pages of other origins call the API: @CrossOrigin, ...">
<meta name="twitter:image" content="https://farum-azula.org/assets/lib/resources/images/preview.png">
<link rel="alternate" type="text/markdown" href="https://farum-azula.org/components/spring-boot-starter-web/cors.md">
<!-- spring:seo:head:end -->
```

and whose body gets the page's text, right before Flutter's bootstrap script:

```html
<!-- spring:seo:content:start -->
<main id="spring-content" style="position:absolute; top:0; left:0; width:100%; z-index:-1; overflow:hidden">
<h1 id="cors">CORS</h1>
<p>A browser keeps a page of <code>https://shop.example</code> from reading ...</p>
...
</main>
<!-- spring:seo:content:end -->
  <script src="flutter_bootstrap.js" async></script>
```

Next to it, `web/components/spring-boot-starter-web/cors.md` holds the Markdown as written, without its front matter.

Where each value came from:

| Value | Source |
|---|---|
| `CORS` | The `title:` of the file's front matter |
| `<title>` | The `title` pattern, `{title}` replaced by the page's title |
| The description | The `description:` of the front matter |
| The image | `spring.flutter.web.seo.image`, since the page has none of its own |
| The addresses | `site-url` and the page's path, without a `/` at the end because of `page-files: html` |

## When it runs

The builder runs for every package that depends on the generator, after `spring_metadata` (which lists the routes) and `spring_flutter_page_loader` (which writes the template). It reads the properties only when a file of `lib/resources/` contains the text `seo`, and writes pages only when `spring.flutter.web.seo.enabled` is `true` and `web/index.html` exists. With `enabled` but no `web/index.html`, it warns.

The properties are read the way the app reads them in a browser: `application.*`, `application-web.*`, the files of the active profiles and the imports, with the `web` profile active, as for the [web dev server](web-dev-server.md). Environment variables and `--dart-define` values do not count. Put the keys in the web profile's file, as only the web build uses them.

When the pages are turned off, or `web/index.html` is gone, the builder deletes the files it wrote before and takes its blocks out of `web/index.html`.

## Where the pages come from

Three sources, which can be combined.

### 1. The routes: `from-routes: true`

With `spring_boot_starter_flutter_navigation`, the screens are listed in `lib/spring_gen/spring_metadata.json` (its `routes`, written from `@ScreenRoute` and `@RouteInfo`). With `from-routes: true`, the builder makes pages of them:

| Screen | Pages |
|---|---|
| A path without variables (`/about`) | One page at that path |
| A path without variables and a `content:` file | One page, with the file's Markdown |
| A path that ends with `{*name}`, its only variable, and a `content:` folder ending in `/` | A page per Markdown file of the folder: `content/components/core/beans.md` under `/components/{*path}` is `/components/core/beans` |
| A path with other variables (`/books/{isbn}`) | None, unless `@RouteInfo(paths: [...])` lists its addresses |
| The not-found screen | None |

A screen's `title:` is the page's title, and `@RouteInfo`'s `description` and `image` its description and image. `#{key}` in a title or a description is read from `messages.properties` (or the language's file, below); a key that is not found gives the key's name. A guarded screen (`@PreAuthorize`), or one with `@RouteInfo(index: false)`, gets `noindex` and stays out of the sitemap and `llms.txt`.

A `content:` file or folder may be `resources:` or `asset:`. An `asset:` folder is read from the Flutter assets of `pubspec.yaml` (a directory entry gives its own files), so `asset:docs/` makes the same pages as `resources:content/docs/` would. Files left out of the binary by `spring.resources.embed.exclude` make pages too; see [Embedded resources](../resources.md#pages-for-search-engines-from-assets).

```dart
@ScreenRoute('/', title: '#{home.title}')
@RouteInfo(description: '#{home.description}')
class HomePage extends StatelessWidget { ... }

@ScreenRoute('/catalog/books/{isbn}', title: 'Book')
@RouteInfo(paths: ['/catalog/books/978-0441013593'])
class BookPage extends StatelessWidget { ... }
```

### 2. Markdown folders: `content[n]`

For pages that are no screen of their own:

```yaml
spring:
  flutter:
    web:
      seo:
        content:
          - location: resources:content/blog/   # or asset:blog/
            path: /blog
            exclude: ['_*.md', 'drafts/**']
```

Every `.md` file below `lib/resources/content/blog/` is a page: `first.md` is `/blog/first`, `index.md` is `/blog` itself, `2026/news.md` is `/blog/2026/news`. In `exclude`, `*` matches inside one folder and `**` across folders, relative to the folder; `**/` also matches no folder, so `**/contents.md` covers the folder's own `contents.md` too.

To leave a kind of file out of every folder, the routes' Markdown folders included, use the top-level `exclude`. A site whose menus are read from a `contents.md` in each folder keeps them out of the pages and the sitemap:

```yaml
spring:
  flutter:
    web:
      seo:
        from-routes: true
        exclude: ['**/contents*.md']
```

### 3. Pages by hand: `pages[n]`

For any other page, or to change what a route says about itself. When a page of that path already exists, the values given replace its own; otherwise a new page without text is made. This site uses it for a longer title on `/`.

### A Markdown page

A Markdown file may start with a front matter. Without a `title`, the first `#` heading is the title:

```markdown
---
title: Beans
description: How the container creates, wires and scopes beans.
image: resources:images/beans.png
index: true
---

# Beans
...
```

| Front matter key | Meaning |
|---|---|
| `title` | The page's title |
| `description` | The page's description |
| `image` | The page's preview image |
| `index` | `false`: `noindex`, out of the sitemap and `llms.txt` |

The Markdown is rendered with GitHub's flavour. HTML written in the Markdown is kept as text, in the page as in the app: the page's text must be the app's.

### Links between pages

A relative link to a `.md` file becomes the site's address: in `content/docs/core/configuration.md`, `beans.md#scopes` becomes `/docs/core/beans#scopes` (with the path of `site-url` before it). Links with a scheme, links starting with `/` or `#`, and links to other files stay as they are.

A link to a Markdown file that is no page of the site fails the build:

```text
lib/resources/content/docs/core/configuration.md links to bean.md, which is no page of the site
(lib/resources/content/docs/core/bean.md).
```

This is how this site's build catches a broken link between its pages.

### Placeholders

With `spring.flutter.markdown.placeholders: true`, each `{{key}}` of a Markdown file is replaced by the configuration's value before the page is made, as [MarkdownView](../../spring-boot-starter-flutter/markdown.md#values-from-the-configuration) replaces it in the app. The HTML text, the `.md` copy, `llms.txt` and `llms-full.txt` all get the value. A key without a value stays as it is, and `${...}` is not touched. This site writes `^{{site.package-version}}` in its dependency examples, and its pages show the latest release.

## What each page gets

| Tag | Value |
|---|---|
| `<title>` | The `title` pattern with `{title}` replaced by the page's title, made unique with section titles when needed (below). A page without a title keeps the template's `<title>` |
| `<meta name="description">` | The page's description, else `description`. It replaces the template's description tag |
| `<link rel="canonical">` | The page's address (for a page of another language without a translation, the default language's address) |
| `<link rel="alternate" hreflang>` | One per language that has the page's text, and `x-default` for the default language; only with two or more |
| `<meta name="robots" content="noindex">` | A page that must not be indexed |
| `og:title`, `twitter:title` | The page's title, without the pattern |
| `og:description`, `twitter:description` | As the description |
| `og:url` | The page's address |
| `og:type` | `website` |
| `og:site_name` | `site-name`, when set |
| `og:image`, `twitter:image` | The page's image, else `image`. A `resources:` location becomes `<site-url>/assets/lib/resources/<path>`, the address `flutter build web` gives the asset (list the folder under `flutter: assets:` in `pubspec.yaml`); a URL stays as it is |
| `twitter:card` | `summary_large_image` with an image, `summary` without |
| `<link rel="alternate" type="text/markdown">` | The `.md` copy, for a Markdown page with `markdown: true` |
| `<html lang>` | The page's language, with `spring.flutter.navigation.languages` |
| `<script type="application/ld+json">` | A `BreadcrumbList` (below), for a page below another page that has a title |

### Titles made unique

Search engines show only one of two pages with the same `<title>`. A site often has them: an `All properties` page in each package. The builder looks at the indexed pages. Where a title is repeated, it adds the title of the nearest page above (the nearest ancestor path that is a page with a title) after the page's own. It adds one more level each round, up to eight, until every title is unique:

| Page | `{title}` in the pattern |
|---|---|
| `/components/spring-search-dart/properties` | `All properties · spring_search_dart` |
| `/components/spring-boot-starter-data/properties` | `All properties · spring_boot_starter_data` |

The root page is no section: its title is the site's. A page without an ancestor page left keeps its title. `og:title` and `twitter:title` keep the short title. Each language is made unique on its own, with its own titles.

### Breadcrumbs

Every page but the root gets a `BreadcrumbList` of schema.org as JSON-LD in its head block: each page above it that has a title, the root included, then the page itself, each with its address. Google shows this path above the page's title in its results. A page with no titled page above it gets none, and so does a page of another language without a translation.

```html
<script type="application/ld+json">{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Spring for Dart","item":"https://farum-azula.org/"},{"@type":"ListItem","position":2,"name":"spring_boot_starter_web","item":"https://farum-azula.org/components/spring-boot-starter-web"},{"@type":"ListItem","position":3,"name":"CORS","item":"https://farum-azula.org/components/spring-boot-starter-web/cors"}]}</script>
```

The names are the pages' own titles, without the pattern. In a language's pages, the names and addresses are that language's.

### Page files and addresses

`page-files` decides the name of each page's file, and so the address that the canonical link, `og:url`, the alternates and the sitemap use. They always match what a static host serves without a redirect, because a canonical address that redirects keeps a page out of search engines.

| `page-files` | File of `/docs/beans` | Its address |
|---|---|---|
| `directory` (default) | `web/docs/beans/index.html` | `https://example.com/docs/beans/`: a static host serves the file after a redirect from `/docs/beans` to `/docs/beans/` |
| `html` | `web/docs/beans.html` | `https://example.com/docs/beans`: Cloudflare Pages, GitHub Pages and Netlify serve it there with no redirect |

The root page's address is `<site-url>/` in both cases.

### The root page

The root page (`/`) is `web/index.html` itself. Its head block goes between `<!-- spring:seo:head:start -->` and `<!-- spring:seo:head:end -->`, and its text, when it has Markdown, between `<!-- spring:seo:content:start -->` and `<!-- spring:seo:content:end -->`. Each build takes the old blocks out first, then writes the new ones. The page loader builder leaves the title and description of a page with these markers alone.

The other pages are copies of `web/index.html` without the root's blocks. `flutter build web` fills `$FLUTTER_BASE_HREF` in `web/index.html` only, so in the copies the builder writes the path of `site-url` there itself (`<base href="/">`).

## Files for crawlers and models

| File | Written when | Content |
|---|---|---|
| `web/sitemap.xml` | `sitemap: true` | Every indexed page's address, sorted, with its `<lastmod>` (below) and `xhtml:link` alternates for translated pages |
| `web/robots.txt` | `sitemap: true` | `User-agent: *`, `Allow: /` and the sitemap's address |
| `web/llms.txt` | `llms: true` | The root page's title and description, then the indexed Markdown pages grouped by their first path segment (`## Components`), each as a link to its `.md` copy with its description |
| `web/llms-full.txt` | `llms: true` | The text of every indexed Markdown page, each after a `<!-- address -->` line |
| `web/<path>.md` | `markdown: true` | The Markdown of each Markdown page, as written, without the front matter; the root page's is `web/index.md`, which its `text/markdown` link and `llms.txt` name |

This site's `robots.txt` and the start of its `llms.txt`:

```text
User-agent: *
Allow: /

Sitemap: https://farum-azula.org/sitemap.xml
```

```markdown
# Spring for Dart

> Spring's programming model for Dart and Flutter: beans, configuration, events and more, wired at build time.

## Components

- [spring_boot_starter_web](https://farum-azula.org/components/spring-boot-starter-web.md): An HTTP server for Spring for Dart: ...
```

### lastmod in the sitemap

With `lastmod: true` (the default), each Markdown page's sitemap entry gets `<lastmod>`: the day of the last commit that changed its file, from `git log` (`2026-11-08`). A translated page gets its translation file's day. A search engine fetches the pages that changed first.

- A page without a Markdown file (a screen without `content:`, a page of `pages[n]` alone) gets none.
- Outside a Git checkout, no page gets one.
- In a shallow clone, no page gets one: its one commit would date every file. Most CI checkouts are shallow; fetch the whole history to keep the dates:

```yaml
# .github/workflows/deploy.yml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0
```

`lastmod: false` turns it off. Use it when the pages are committed and CI builds them again from another checkout, whose dates are not the ones the pages were built from (the repository's `seo_site` example does this).

## Languages

With `spring.flutter.navigation.languages` (`[en, ja]`), every page is written in each language: the first language at the page's address, the others under `/<language>` (`/ja/components`), the addresses the app itself opens.

- A Markdown page's translation sits next to it, the language before `.md`: `beans.ja.md` next to `beans.md`. Its front matter gives the translated title and description. A link in it may name `routing.md` or `routing.ja.md`; both lead to `/ja/...`. A translation file is never a page of its own.
- `#{key}` titles and descriptions come from that language's messages (`messages_ja.properties`, then `messages.properties`).
- A page without a translation is still written, so the address works: with the default language's text, its canonical address the default page's, `noindex`, and out of the sitemap and the alternates.
- `llms.txt` and `llms-full.txt` stay in the default language. The `.md` copy of a translation is at `/ja/<path>.md`.

A language must be a language tag (`en`, `ja`, `pt-BR`); anything else fails the build.

## What is written, and what to commit

The builder writes into `web/`, which is the app's own folder, so the files are no declared build outputs. It lists every file it wrote in `web/.spring-seo` (the root `web/index.html` aside). At the next build, a file in that list that is no longer written is deleted, so a page that is gone does not stay behind. A file whose text has not changed is not written again.

Commit the files if the site is built elsewhere without `build_runner`, or add them to `.gitignore`: the folders or `.html` files of the pages, the `.txt`, `.xml` and `.md` files, and `web/.spring-seo`. `flutter build web` copies them into `build/web/`.

## Serving the pages

The server must answer `/docs/beans` with the page's file.

- **Static hosts** (Cloudflare Pages, GitHub Pages, Netlify, Firebase Hosting) do that, and answer other addresses of the app with the root `index.html` when told to. Choose `page-files` for your host (see above).
- **`spring_boot_starter_web`** does it with `spring.web.resources.directory-index: true` for `directory` files; see [Static resources](../../spring-boot-starter-web/static-resources.md).

Keep `spring.flutter.navigation.web.url-strategy` at `path`, its default. The `hash` strategy puts the route after a `#` (`/#/docs/beans`), which a crawler does not follow and these pages do not match.

## Properties

The table gives the key below `spring.flutter.web.seo.`.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `enabled` | `true` / `false` | `false` | Whether the pages are written |
| `site-url` | absolute URL | none; required when `enabled` | The site's address, for `canonical`, `og:url`, the sitemap and the image addresses. Its path is where the app is served (`https://example.com/docs/` for an app under `/docs/`) |
| `from-routes` | `true` / `false` | `false` | Whether the screens of the navigation make pages |
| `title` | text with `{title}` | `{title}` | The `<title>` pattern |
| `description` | text | none | The description of a page that has none |
| `image` | `resources:` location or URL | none | The preview image of a page that has none. About 1200×630 |
| `site-name` | text | none | `og:site_name` |
| `content[n].location` | `resources:` or `asset:` folder | none | A folder of Markdown files, a page per file |
| `content[n].path` | path | `/` | The folder's address |
| `content[n].exclude` | list of globs | none | Files of the folder left out |
| `exclude` | list of globs | none | Files left out of every Markdown folder, the routes' and `content[n]`'s |
| `pages[n].path` | path | none | A page by hand, or the page of a route to change |
| `pages[n].title` | text | the route's or file's | The page's title (`#{key}` allowed) |
| `pages[n].description` | text | the route's or file's | The page's description (`#{key}` allowed) |
| `pages[n].image` | `resources:` location or URL | the route's or file's | The page's preview image |
| `pages[n].index` | `true` / `false` | the route's or file's | `false`: `noindex`, out of the sitemap and `llms.txt` |
| `sitemap` | `true` / `false` | `true` | Whether `sitemap.xml` and `robots.txt` are written |
| `lastmod` | `true` / `false` | `true` | Whether the sitemap gives each Markdown page its `<lastmod>` from Git; none in a shallow clone |
| `llms` | `true` / `false` | `true` | Whether `llms.txt` and `llms-full.txt` are written |
| `markdown` | `true` / `false` | `true` | Whether the `.md` copies and their alternate links are written |
| `page-files` | `directory` / `html` | `directory` | How a page's file is named |

The builder also reads `spring.flutter.navigation.languages` and `spring.flutter.markdown.placeholders`. A `true` / `false` key with another value counts as its default.

## Errors

Every error stops the build and writes no page.

| Problem | Message (shortened) |
|---|---|
| `enabled: true` without a valid `site-url` | `spring.flutter.web.seo.site-url must be the site's address (https://spring-dart.dev) when spring.flutter.web.seo.enabled is true.` |
| `page-files` neither `directory` nor `html` | `spring.flutter.web.seo.page-files: "..." is directory (<path>/index.html) or html (<path>.html).` |
| A language that is no language tag | `spring.flutter.navigation.languages: "..." is no language tag (en, ja, pt-BR).` |
| Two files on one address | `Two files make the page /docs/beans: ... and ....` |
| One file on two addresses (a route's folder and a `content[n]` folder) | `The file ... makes two pages: ... and ....` |
| A folder route whose path does not end with `{*name}` as its only variable | `The route ... shows the folder ...: its path must end with {*name}, its only variable.` |
| A Markdown folder with no `.md` file | `The Markdown folder ... has no .md file.` |
| A route's `content:` file that does not exist | `lib/resources/... is missing.` |
| A front matter that is no valid YAML | `The front matter of lib/resources/...: ...` |
| A link to a Markdown file that is no page | `lib/resources/... links to ..., which is no page of the site (...).` |
| The config files cannot be read | The reading's error, then `The pages of spring.flutter.web.seo are not written.` |

## In Spring (Java)

Spring has no counterpart: a Spring MVC application renders its HTML on the server for every request. The builder exists because a Flutter web app renders in the browser, on a canvas.

## See also

- [SEO](../../spring-boot-starter-flutter/seo.md): step by step, with Search Console and link previews
- [The page loader](page-loader.md)
- [The web dev server](web-dev-server.md)
- [Metadata for editors](../metadata.md)
- [Properties the build reads](../build-properties.md)
- [Static resources](../../spring-boot-starter-web/static-resources.md)
