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:

Example

This site's configuration:

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

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

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

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

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

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:

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:

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

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:

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

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.

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

User-agent: *
Allow: /

Sitemap: https://farum-azula.org/sitemap.xml
# 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.

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

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