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, theog:*andtwitter:*tags of link previews,robotswhere a page must not be indexed, and the language alternates; - its text, as plain HTML in
<main id="spring-content">, under the page loader 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:
# 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.
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:
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.
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.
<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.
- A page without a Markdown file (a screen without
content:, a page ofpages[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:
# .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.mdnext tobeans.md. Its front matter gives the translated title and description. A link in it may namerouting.mdorrouting.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, thenmessages.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.txtandllms-full.txtstay in the default language. The.mdcopy 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.htmlwhen told to. Choosepage-filesfor your host (see above). spring_boot_starter_webdoes it withspring.web.resources.directory-index: truefordirectoryfiles; see Static resources.
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: step by step, with Search Console and link previews
- The page loader
- The web dev server
- Metadata for editors
- Properties the build reads
- Static resources