
# SEO

A Flutter web app draws on a canvas, so its HTML has no text. With `spring.flutter.web.seo.enabled`, the build writes a real HTML page for every address of the app: its own title, description, preview tags and text. It also writes `sitemap.xml`, `robots.txt`, `llms.txt`, `llms-full.txt` and a Markdown copy of each page. Visitors still get the Flutter app. This page shows how it works, step by step, and what to do after the site is online.

## Why

Every address of a plain Flutter web app serves the same `index.html`. It has one `<title>`, Flutter's description and an empty `<body>` with a script. Programs that read web pages see only that:

- **Link previews** in X, Telegram, Slack, WhatsApp or Discord read the HTML and never run scripts. A shared link shows the app's name and no picture, whatever page it points to.
- **Search engines** get no text to index, and every page has the same title. Google runs scripts later, sometimes, but a canvas still has no text to read.
- **Language models** and their tools read text, not canvases.

You could write a second, HTML version of the site, but it would drift from the app. Here the build makes the pages from what the app already shows: the screens of the navigation and the Markdown files the app renders. One source, so the pages always say what the app says.

## Example

```yaml
# lib/resources/application-web.yml: only the web build reads it
spring:
  flutter:
    navigation:
      languages: [en, ja]             # pages in English and under /ja/
    markdown:
      placeholders: true              # {{key}} in pages, in the app and the build
    web:
      seo:
        enabled: true
        site-url: https://books.example.com
        page-files: html              # <path>.html: Cloudflare Pages, GitHub Pages, Netlify
        from-routes: true             # every screen is a page
        exclude: ['**/contents*.md']  # menus, not pages
        title: '{title} · Neon Books'
        description: A small bookshop with a catalog and a blog.
        site-name: Neon Books
        image: resources:images/preview.png   # 1200×630, listed in pubspec.yaml
        content:
          - location: resources:content/blog/
            path: /blog
            exclude: ['_*.md', 'drafts/**']
        pages:
          - path: /
            title: Neon Books, a small bookshop
          - path: /cart
            index: false
```

```yaml
# pubspec.yaml: the preview image is served as a Flutter asset
dependencies:
  spring_boot_starter_flutter: ^0.9.0
  spring_boot_starter_flutter_navigation: ^0.9.0

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0

flutter:
  assets:
    - lib/resources/images/
```

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

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

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

Then:

```text
dart run build_runner build
flutter build web --wasm
```

`build/web/` now holds the app and, next to it, `docs/getting-started.html`, `blog/first.html`, `books/978-0441013593.html`, `ja/docs/getting-started.html`, `sitemap.xml`, `robots.txt`, `llms.txt` and the rest.

## How it works

Everything happens at build time. Nothing runs on a server, and the app does not change.

1. **`dart run build_runner build`.** `spring_core_dart_generator` runs its builders. One of them lists the screens of the app in `lib/spring_gen/spring_metadata.json`. Another, the SEO builder (`spring_flutter_seo`), runs after it.
2. **The SEO builder reads the configuration** as the app reads it in a browser: `application.*`, then `application-web.*`, the files of the active profiles and the imports, with the `web` profile active. It reads it only when a file of `lib/resources/` contains the text `seo`.
3. **It collects the pages**: from the screens, from Markdown folders and from the `pages` list.
4. **It writes the files into `web/`**, the app's own folder. Each page is a copy of `web/index.html` with the page's head and text added. The root page goes into `web/index.html` itself.
5. **`flutter build web`** copies everything in `web/` into `build/web/`, next to the app.
6. **The host serves the files.** A request for `/docs/getting-started` gets `docs/getting-started.html`. A crawler reads its head and text. A browser runs its scripts, and the Flutter app starts over the text, so the visitor sees the app as always.

So run `build_runner` before `flutter build web`, every time the content changes.

## One page from start to end

Here is one page, `/docs/getting-started`, from what you write to every file the build makes of it. The files are the real output of the `seo_site` example of the repository (`page-files: directory`, the default).

### What you write

The configuration, read only by the web build:

```yaml
# lib/resources/application-web.yml
spring:
  flutter:
    navigation:
      languages: [en, ja]
    web:
      seo:
        enabled: true
        site-url: https://lumen.example
        from-routes: true
        title: '{title} · Lumen'
        description: Lumen, a small library documented with a Flutter web site.
        image: resources:images/preview.png
        pages:
          - path: /
            title: Lumen, a small library
```

| Setting | What it does for this page | Why |
|---|---|---|
| `enabled: true` | Turns the builder on | Off by default: a build that is not for the web writes nothing |
| `site-url` | The start of every absolute address: `canonical`, `og:url`, `hreflang`, the sitemap | Search engines and previews need absolute addresses; the build cannot guess the domain |
| `from-routes: true` | The route `/docs/{*path}` with `content:` gives a page per file of its folder, this one included | So the pages follow the app's own screens, with nothing listed twice |
| `title` | `<title>Getting started · Lumen</title>`: `{title}` is the page's own title | The site's name in every search result and tab; `og:title` keeps the short title, since a preview shows the site apart |
| `description` | The description of a page that has none | This page has its own, from its front matter, so the default is not used |
| `image` | The preview picture of a page without one | One picture for the whole site; a page can give its own (`image:` in its front matter) |
| `pages[0]` | The home page's title, `Lumen, a small library` | It is the first step of this page's breadcrumbs |
| `languages: [en, ja]` | A second page under `/ja/`, and the `hreflang` links between the two | Each language is a page of its own for search engines; without two languages no `hreflang` is written |

The screen, in Dart:

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

`content:` says which folder the screen shows. The file `getting-started.md` there is the address `/docs/getting-started`, and `getting-started.ja.md` next to it is `/ja/docs/getting-started`.

The page, in Markdown:

```markdown
---
title: Getting started
description: Install Lumen and show the first page in five minutes.
---

# Getting started

Add the package:

    dependencies:
      lumen: ^1.0.0

Then read the [routing guide](guides/routing.md#paths).
```

The front matter gives the page's title and description. The app shows the body; the build writes the same body as HTML.

### What the build writes

Four files carry this page, and two of the site-wide files list it:

| File | Who reads it |
|---|---|
| `web/docs/getting-started/index.html` | Search engines, link previews, any program that reads HTML; a browser, which then starts the app |
| `web/docs/getting-started.md` | Language models and tools that want the text without HTML |
| `web/ja/docs/getting-started/index.html`, `.md` | The same for the Japanese page |
| `web/sitemap.xml` | Search engines: every page to index, with its languages |
| `web/llms.txt`, `web/llms-full.txt` | Language models: a map of the `.md` pages, and all of them in one file |

`flutter build web` copies them into `build/web/`, and the host serves `https://lumen.example/docs/getting-started/` from `docs/getting-started/index.html`.

### The HTML page: why it exists

The app's own `index.html` is the same for every address: one title, no text. This file is a copy of it with the page's head and text added, so a program that never runs scripts still gets the page. The visitor's browser runs the same scripts as always and sees the app.

The head, between `<!-- spring:seo:head:start -->` and `end`:

```html
<title>Getting started · Lumen</title>
<meta name="description" content="Install Lumen and show the first page in five minutes.">
<link rel="canonical" href="https://lumen.example/docs/getting-started/">
<link rel="alternate" hreflang="en" href="https://lumen.example/docs/getting-started/">
<link rel="alternate" hreflang="ja" href="https://lumen.example/ja/docs/getting-started/">
<link rel="alternate" hreflang="x-default" href="https://lumen.example/docs/getting-started/">
<meta property="og:title" content="Getting started">
<meta property="og:description" content="Install Lumen and show the first page in five minutes.">
<meta property="og:url" content="https://lumen.example/docs/getting-started/">
<meta property="og:type" content="website">
<meta property="og:image" content="https://lumen.example/assets/lib/resources/images/preview.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Getting started">
<meta name="twitter:description" content="Install Lumen and show the first page in five minutes.">
<meta name="twitter:image" content="https://lumen.example/assets/lib/resources/images/preview.png">
<link rel="alternate" type="text/markdown" href="https://lumen.example/docs/getting-started.md">
<script type="application/ld+json">{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Lumen, a small library","item":"https://lumen.example/"},{"@type":"ListItem","position":2,"name":"Documentation","item":"https://lumen.example/docs/"},{"@type":"ListItem","position":3,"name":"Getting started","item":"https://lumen.example/docs/getting-started/"}]}</script>
```

| Line | Comes from | What it gives |
|---|---|---|
| `<title>` | `title` pattern and the front matter's `title` | The link text in search results |
| `description` | the front matter's `description` | The text under the link |
| `canonical` | `site-url` and the page's address | The one address search engines count, whatever query string a link adds |
| `hreflang` ×3 | `languages` and the `.ja.md` file | Google shows the Japanese page to Japanese readers; `x-default` is the page for everyone else |
| `og:*`, `twitter:*` | title, description, `image` | The card a messenger shows for a shared link; `og:image` is the asset's address, so `lib/resources/images/` is under `flutter: assets:` |
| `text/markdown` alternate | `markdown: true` (the default) | Tells a program where the `.md` copy is |
| `BreadcrumbList` | the pages above it: `/` (`pages[0]`), `/docs` (`index.md`) | `Lumen › Documentation › Getting started` above the title in Google's results |

The text, in the body before Flutter's script:

```html
<main id="spring-content" style="position:absolute; top:0; left:0; width:100%; z-index:-1; overflow:hidden">
<h1 id="getting-started">Getting started</h1>
<p>Add the package:</p>
<pre><code class="language-yaml">dependencies:
  lumen: ^1.0.0
</code></pre>
<p>Then read the <a href="/docs/guides/routing#paths">routing guide</a>.</p>
</main>
```

It is what a search engine indexes. It sits under the page loader and the app, so a visitor never sees it. The link to `guides/routing.md` became the site's address `/docs/guides/routing#paths`, so a crawler follows it to the next page; a link to a file that is no page fails the build.

### The Markdown copy: why it exists

```markdown
# Getting started

Add the package:
...
Then read the [routing guide](guides/routing.md#paths).
```

The same text as written, without the front matter. HTML is made for browsers; a language model or a tool that reads documentation wants the text and its structure without tags, styles and scripts. The `.md` copy is that text at a known address (`<page>.md`), pointed to from the head and listed in `llms.txt`. `markdown: false` writes none.

### The site-wide files

```xml
<!-- web/sitemap.xml -->
<url>
  <loc>https://lumen.example/docs/getting-started/</loc>
  <xhtml:link rel="alternate" hreflang="en" href="https://lumen.example/docs/getting-started/"/>
  <xhtml:link rel="alternate" hreflang="ja" href="https://lumen.example/ja/docs/getting-started/"/>
</url>
```

The sitemap tells search engines that the page exists without waiting for a link to it; `robots.txt` points to the sitemap. A `<lastmod>` from Git is added with `lastmod: true` (the default; this example turns it off).

```markdown
<!-- web/llms.txt -->
## Docs

- [Getting started](https://lumen.example/docs/getting-started.md): Install Lumen and show the first page in five minutes.
```

`llms.txt` is the map a language model reads first: each page's `.md` address and description, grouped by folder. `llms-full.txt` holds every page's Markdown in one file, each after a `<!-- address -->` line.

## Step 1: turn it on

Put the keys in `lib/resources/application-web.yml`. Only the web build reads them, and the app never does.

| Key | What to write |
|---|---|
| `spring.flutter.web.seo.enabled` | `true` |
| `spring.flutter.web.seo.site-url` | The site's public address, with its path if the app is not at the root (`https://example.com/shop/`). Required: canonical links, `og:url` and the sitemap must be absolute |
| `spring.flutter.web.seo.title` | The `<title>` pattern: `'{title} · Neon Books'`. `{title}` is the page's own title |
| `spring.flutter.web.seo.description` | The description of a page that has none |
| `spring.flutter.web.seo.image` | The preview picture of a page that has none: `resources:images/preview.png`, or a full URL |
| `spring.flutter.web.seo.site-name` | The site's name, shown above the title in some previews (`og:site_name`) |
| `spring.flutter.web.seo.page-files` | `directory` (the default) or `html`; see [Serving the pages](#serving-the-pages) |

The app needs a `web/index.html` (`flutter create --platforms web .` writes one). With `enabled` and no `web/index.html`, the build only warns.

A `resources:` image becomes `<site-url>/assets/lib/resources/<path>`, the address `flutter build web` gives the asset. So list its folder under `flutter: assets:` in `pubspec.yaml`, as in the example.

## Step 2: choose where the pages come from

Three sources. Use one or all of them.

### The screens: `from-routes: true`

With [spring_boot_starter_flutter_navigation](../spring-boot-starter-flutter-navigation/index.md), `from-routes: true` makes pages of the app's screens:

| 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 text |
| A path ending with `{*name}`, its only variable, and a `content:` folder ending in `/` | A page per Markdown file of the folder: `content/docs/core/beans.md` under `/docs/{*path}` is `/docs/core/beans`, and `index.md` is the folder's own address |
| 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. `@RouteInfo`'s `description` and `image` are its description and picture. `#{key}` is read from `messages.properties`, or from the language's own file. A guarded screen (`@PreAuthorize`) or one with `@RouteInfo(index: false)` gets `noindex` and stays out of the sitemap and `llms.txt`.

A `content:` folder may be `resources:` or `asset:` (any Flutter asset folder of `pubspec.yaml`). See [Markdown screens](../spring-boot-starter-flutter-navigation/markdown-screens.md).

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

For Markdown that no screen names, such as a blog:

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

Every `.md` file below the folder is a page: `first.md` is `/blog/first`, `index.md` is `/blog`, `2026/news.md` is `/blog/2026/news`. In the globs, `*` matches inside one folder, `**` across folders, and `**/` also matches no folder at all.

### Leaving files out: `exclude`

The top-level `exclude` applies to every Markdown folder, the screens' and the `content` ones. A site that reads its menu from a `contents.md` in each folder keeps those files out of the pages and the sitemap with `exclude: ['**/contents*.md']`.

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

Each entry names a `path`. If a page of that path exists already, the values given replace its own: a longer title for the home page, another picture. If not, a new page without text is made. `index: false` keeps a page out of search results: it gets `<meta name="robots" content="noindex">` and is left out of the sitemap and `llms.txt`.

### The Markdown file's own values

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

```markdown
---
title: Getting started
description: Install the app, sign in and find your first book in two minutes.
image: resources:images/getting-started.png
index: true
---

# Getting started
```

Write a specific `description` for every page. Search engines often show it under the title, and previews show it under the picture.

A relative link to another `.md` file becomes the site's address: `beans.md#scopes` becomes `/docs/core/beans#scopes`. A link to a Markdown file that is no page of the site fails the build, so broken links are caught before they are published.

## Step 3: run the build

```text
dart run build_runner build
```

The builder writes into `web/` and lists every file it wrote in `web/.spring-seo`. At the next build, a file of that list that is no longer written is deleted, so a removed page does not stay online. Commit the files, or add them to `.gitignore` if the site is always built with `build_runner` first. With `enabled: false`, the builder deletes what it wrote and takes its blocks out of `web/index.html`.

An error stops the build and writes no page. The common ones: no `site-url`, two files on one address, a link to a file that is no page, a folder screen whose path does not end with `{*name}`. Every message: [Errors](../spring-core-dart-generator/flutter/seo.md#errors).

## What each page gets

### Its file

| `page-files` | File of `/docs/beans` | Its address |
|---|---|---|
| `directory` (default) | `web/docs/beans/index.html` | `https://example.com/docs/beans/` |
| `html` | `web/docs/beans.html` | `https://example.com/docs/beans` |

The root page `/` is `web/index.html` itself, between `<!-- spring:seo:head:start -->` and `end` markers. A page of another language is under `/<language>/`: `web/ja/docs/beans.html`.

### Its head

Here is the head of `/docs/core/beans`, written between the markers `<!-- spring:seo:head:start -->` and `<!-- spring:seo:head:end -->`:

```html
<title>Beans · Neon Books</title>
<meta name="description" content="How the app keeps the cart, the user and the catalog.">
<link rel="canonical" href="https://books.example.com/docs/core/beans">
<link rel="alternate" hreflang="en" href="https://books.example.com/docs/core/beans">
<link rel="alternate" hreflang="ja" href="https://books.example.com/ja/docs/core/beans">
<link rel="alternate" hreflang="x-default" href="https://books.example.com/docs/core/beans">
<meta property="og:title" content="Beans">
<meta property="og:description" content="How the app keeps the cart, the user and the catalog.">
<meta property="og:url" content="https://books.example.com/docs/core/beans">
<meta property="og:type" content="website">
<meta property="og:site_name" content="Neon Books">
<meta property="og:image" content="https://books.example.com/assets/lib/resources/images/preview.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Beans">
<meta name="twitter:description" content="How the app keeps the cart, the user and the catalog.">
<meta name="twitter:image" content="https://books.example.com/assets/lib/resources/images/preview.png">
<link rel="alternate" type="text/markdown" href="https://books.example.com/docs/core/beans.md">
<script type="application/ld+json">{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Neon Books, a small bookshop","item":"https://books.example.com/"},{"@type":"ListItem","position":2,"name":"Docs","item":"https://books.example.com/docs"},{"@type":"ListItem","position":3,"name":"Beans","item":"https://books.example.com/docs/core/beans"}]}</script>
```

| Tag | What it is for |
|---|---|
| `<title>` | The blue link in search results, and the browser tab |
| `description` | The text under the link in search results |
| `canonical` | The one address of this page, so search engines do not count copies (`?v=2`, another language's fallback) as other pages |
| `hreflang` alternates | The same page in the other languages, and `x-default` for the default; written only with two or more languages |
| `og:*` | Link previews in messengers and social apps (the Open Graph protocol) |
| `twitter:*` | X's previews; `summary_large_image` with a picture, `summary` without |
| `text/markdown` alternate | Where a program finds the page's text as Markdown |
| `BreadcrumbList` (JSON-LD) | The path shown above the title in Google's results (`Neon Books › Docs › Beans`); every page below another page that has a title |
| `robots` `noindex` | Only on a page that must not be listed |
| `<html lang>` | The page's language, with `spring.flutter.navigation.languages` |

`og:title` is the page's own title. `<title>` uses the pattern and may get section titles too (next section).

### Its text

The page's text goes into the body, 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="beans">Beans</h1>
<p>The app keeps three beans for the whole session ...</p>
</main>
<!-- spring:seo:content:end -->
<script src="flutter_bootstrap.js" async></script>
```

It is plain HTML rendered from the same Markdown the app shows, with GitHub's flavour. It sits under the [page loader](../spring-core-dart-generator/flutter/page-loader.md), 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. A screen without Markdown gets the head only.

### Its Markdown copy

With `markdown: true` (the default), the Markdown of the page is written as `<path>.md`, as written, without its front matter: `web/docs/core/beans.md`. The head points to it with `<link rel="alternate" type="text/markdown">`. A program can read the page's text without parsing HTML.

## Where the title comes from

`spring.flutter.web.seo.title` is a pattern (`'{title} · Neon Books'`); `{title}` is the page's own title, the first of these that has one:

1. `pages[n].title`, the page set by hand for its address (`#{key}` allowed).
2. The Markdown file's front matter: `title:`.
3. The Markdown file's first `#` heading, when the front matter has no title.
4. The screen's `@ScreenRoute(title: ...)`, for a screen without Markdown.

`#{key}` is read from `messages.properties`, and a Japanese page's from `messages_ja.properties` first. A translation (`beans.ja.md`) gives its own front matter or heading. The pattern then makes `<title>Beans · Neon Books</title>`; `og:title` and `twitter:title` keep the short title, as a preview shows the site apart. When two pages end with one title, the next section makes them unique.

The description comes the same way: `pages[n].description`, the front matter's `description:`, `@RouteInfo(description: ...)`, then `spring.flutter.web.seo.description`. So does the picture: `pages[n].image`, the front matter's `image:`, `@RouteInfo(image: ...)`, then `spring.flutter.web.seo.image`.

## Titles made unique

Two pages with one title confuse search engines: they often show only one of them. Many sites have that: an `All properties` page in each section. The build gives such pages the titles of their sections after their own, one more each time, until every indexed page has its own `<title>`:

| Page | `<title>` |
|---|---|
| `/docs/search/properties` | `All properties · Search · Neon Books` |
| `/docs/data/properties` | `All properties · Data · Neon Books` |

A section counts only when it is a page with a title. The root page is not a section. Previews (`og:title`) keep the short title.

## Files for the whole site

| File | Written when | What it is for |
|---|---|---|
| `web/sitemap.xml` | `sitemap: true` (default) | Every indexed page's address, sorted, with `<lastmod>` and the language alternates. Search engines find pages from it |
| `web/robots.txt` | `sitemap: true` | `User-agent: *`, `Allow: /` and the sitemap's address |
| `web/llms.txt` | `llms: true` (default) | A map of the site for language models: the root page's title and description, then each indexed Markdown page as a link to its `.md` copy with its description, grouped by first path segment (`## Docs`) |
| `web/llms-full.txt` | `llms: true` | The text of every indexed Markdown page in one file, each after an `<!-- address -->` line |

### The sitemap's lastmod

`<lastmod>` tells a search engine which pages changed since its last visit, so it fetches those first. The build takes it from Git: the day of the last commit that changed the page's Markdown file (`git log`).

- A page without a Markdown file 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. To get the dates in CI, fetch the whole history:

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

- `spring.flutter.web.seo.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.

## Languages

With `spring.flutter.navigation.languages: [en, ja]`, every page is written in each language. The first language has no prefix (`/docs/beans`); the others are under their tag (`/ja/docs/beans`), the addresses the app itself opens. See [Languages](../spring-boot-starter-flutter-navigation/languages.md).

- A translation sits next to its Markdown file, with the language before `.md`: `beans.ja.md`. Its front matter gives the translated title and description. It is never a page of its own.
- `#{key}` titles and descriptions come from that language's messages (`messages_ja.properties`, then `messages.properties`).
- Each translated page lists every language as an `hreflang` alternate, and the sitemap lists them too. Google then shows Japanese readers the Japanese page.
- A page without a translation is still written, so its address works. It has the default language's text, its canonical address is the default page's, and it gets `noindex`. It is left out of the sitemap and the alternates.
- `llms.txt` and `llms-full.txt` stay in the default language.

## Placeholders

With `spring.flutter.markdown.placeholders: true`, a `{{key}}` in a page is replaced by the configuration's value: in the app, in the SEO pages, in the `.md` copies and in `llms.txt`. A key without a value stays as it is, and `\{{` writes `{{` as text. See [Values from the configuration](markdown.md#values-from-the-configuration).

## What a crawler sees, and what a visitor sees

The same file, read two ways. A crawler or a preview bot reads the HTML:

```text
$ curl -s https://books.example.com/docs/core/beans | grep -A2 'spring-content'
<main id="spring-content" style="position:absolute; top:0; left:0; width:100%; z-index:-1; overflow:hidden">
<h1 id="beans">Beans</h1>
<p>The app keeps three beans for the whole session ...</p>

$ curl -s https://books.example.com/docs/core/beans | grep -E '<title>|og:image'
<title>Beans · Neon Books</title>
<meta property="og:image" content="https://books.example.com/assets/lib/resources/images/preview.png">
```

A browser shows the page loader, then the Flutter app on the same address. The text stays in the page, under the app. Both read the same words, from the same Markdown file.

## Serving the pages

The host must answer `/docs/beans` with the page's file, and any other address of the app with the root `index.html`.

- **Cloudflare Pages, GitHub Pages, Netlify**: use `page-files: html`. They serve `docs/beans.html` at `/docs/beans` with no redirect. This site is served this way.
- **Other static hosts** (Firebase Hosting, S3, nginx): `directory` writes `docs/beans/index.html`, which any host serves at `/docs/beans/`. The addresses in the pages end with `/`, so they match what is served.
- **[spring_boot_starter_web](../spring-boot-starter-web/static-resources.md)**: `spring.web.resources.directory-index: true` for `directory` files, and `spa-fallback: true` for the other addresses of the app.

The canonical address is always the one the host serves without a redirect: a canonical address that redirects keeps a page out of search engines.

Keep `spring.flutter.navigation.web.url-strategy` at `path`, its default. With `hash` the route is after a `#` (`/#/docs/beans`), which crawlers do not follow.

## Checking it

Before you tell any search engine:

1. **View the source.** Open a page and press ⌘⌥U (Ctrl+U). Look for your `<title>`, the `og:` tags and `<main id="spring-content">`. The browser's inspector shows the live page; the source shows what a crawler gets.
2. **curl** the page, as above. Also open `https://<site>/sitemap.xml` and `https://<site>/robots.txt`.
3. **The picture**: open the `og:image` address in a browser. A `404` there means its folder is not under `flutter: assets:`.
4. **Google's Rich Results Test** (`search.google.com/test/rich-results`): enter a page's address. It should find **Breadcrumbs**.
5. **Google Search Console's URL inspection** (below): **Test live URL**, then **View tested page**. Its HTML shows the text Google read, and its screenshot shows the app.

## Google Search Console

Search Console is how you tell Google about the site and see what it indexed.

1. Go to `search.google.com/search-console` and **add a property**.
   - A **Domain** property (`books.example.com`) covers every address of the domain. Verify it with a DNS `TXT` record at your DNS provider.
   - A **URL prefix** property (`https://books.example.com/`) can be verified with an HTML file instead. Put the file in `web/`, and `flutter build web` publishes it.
2. Open **Sitemaps**, enter `sitemap.xml` (the full address is `https://<site>/sitemap.xml`) and press **Submit**. After a while its status is **Success**, with the number of pages found.
3. Open **URL inspection**, paste the address of an important page (the home page first) and press **Request indexing**. Each property has a small daily quota, so do it for a few pages; the sitemap covers the rest.
4. **Wait.** A new site takes days to a few weeks. **Indexing › Pages** shows what is indexed and why other pages are not.

Messages you may see there:

| Message | Meaning |
|---|---|
| Discovered – currently not indexed | Google knows the page and has not fetched it yet; wait |
| Excluded by 'noindex' tag | A page with `index: false`, a guarded screen, or a page without a translation; as intended |
| Alternate page with proper canonical tag | A page whose canonical address is another one, such as an untranslated page under `/ja/`; as intended |
| Duplicate without user-selected canonical | Two addresses serve one page; check `page-files` and your host's redirects |

After a big change, submit the sitemap again. Pages with a newer `<lastmod>` are fetched first.

## Bing Webmaster Tools

Bing's index also serves other search engines and assistants. Go to `bing.com/webmasters` and add the site. You can **import** it from Google Search Console, which verifies it and adds the sitemap in one step. Otherwise verify it, and submit `https://<site>/sitemap.xml` under **Sitemaps**. **URL Inspection** works as Google's does.

## Link previews

X, Telegram, Slack, WhatsApp, Discord and LinkedIn read the `og:` and `twitter:` tags when a link is shared.

- Give the site a picture with `spring.flutter.web.seo.image`, and pages their own with `image:` in the front matter or `@RouteInfo(image:)`. Use 1200×630 pixels (about 1.91:1), PNG or JPEG, under 5 MB. A picture makes the large card (`summary_large_image`).
- The picture's address is absolute and public. It must load without a login or a cookie.
- **Previews are cached.** An app that fetched a link while the page had no tags, or while the site was down, keeps that preview for days. To see the new one, share the address with a query: `https://books.example.com/docs/core/beans?v=2`. The host serves the same file, and the canonical address stays the same, so search engines are not confused. Telegram also refreshes a link you send to its `@WebpageBot`; Facebook and LinkedIn have their own inspectors that fetch again.

## Limits

- **Pages are made at build time.** A page shows what the files said when you ran `build_runner`. There is no page per user, and no page for data read from a server or a database. A new book needs a new build.
- **Routes with variables** (`/books/{isbn}`) make no page unless `@RouteInfo(paths: [...])` lists their addresses.
- **Pages behind a login are not for search engines.** A guarded screen gets `noindex` and is left out of the sitemap and `llms.txt`. Its file and its Markdown copy are still written. Everything in `lib/resources/` ships with the app and can be downloaded anyway, so keep nothing secret there.
- **A screen without Markdown** gets a head (title, description, previews) but no text.
- **HTML written in the Markdown** is kept as text, in the page as in the app.
- **The `hash` URL strategy** is not supported.

## Properties

The keys below `spring.flutter.web.seo.`:

| Key | Type | Default | Meaning |
|---|---|---|---|
| `enabled` | bool | `false` | Whether the build writes the pages; `false` deletes those written before |
| `site-url` | absolute URL | none; required when `enabled` | The site's address; its path is where the app is served |
| `from-routes` | bool | `false` | Whether the navigation's screens 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 picture 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 |
| `pages[n].path` | path | none | A page by hand, or the page of a screen to change |
| `pages[n].title` | text | the page's own | Its title (`#{key}` allowed) |
| `pages[n].description` | text | the page's own | Its description (`#{key}` allowed) |
| `pages[n].image` | `resources:` location or URL | the page's own | Its preview picture |
| `pages[n].index` | bool | the page's own | `false`: `noindex`, out of the sitemap and `llms.txt` |
| `sitemap` | bool | `true` | Whether `sitemap.xml` and `robots.txt` are written |
| `lastmod` | bool | `true` | Whether the sitemap gives each Markdown page its `<lastmod>` from Git |
| `llms` | bool | `true` | Whether `llms.txt` and `llms-full.txt` are written |
| `markdown` | bool | `true` | Whether the `.md` copies and their alternate links are written |
| `page-files` | `directory`, `html` | `directory` | How a page's file is named |

The build also reads `spring.flutter.navigation.languages` and `spring.flutter.markdown.placeholders`. How the builder reads all of them, and every error it reports: [Pages for search engines](../spring-core-dart-generator/flutter/seo.md).

## See also

- [The web](web.md)
- [Pages for search engines](../spring-core-dart-generator/flutter/seo.md), the builder's internals
- [The web and deep links](../spring-boot-starter-flutter-navigation/web-and-deep-links.md)
- [Markdown screens](../spring-boot-starter-flutter-navigation/markdown-screens.md)
- [Static resources](../spring-boot-starter-web/static-resources.md)
- [All properties](properties.md)
