検索エンジン向けのページ

spring_flutter_seo ビルダーは、Flutter Web アプリに本物の HTML ページを与えます。すべてのルートとすべての Markdown ファイルについて、ページ独自の <head> とテキストを持つ web/index.html のコピーを書き出し、さらに sitemap.xml、robots.txt、llms.txt、llms-full.txt、各 Markdown ページの .md のコピーも書き出します。spring.flutter.web.seo.* プロパティを読みます。このサイトはこの方法でビルドされています。

使う理由

Flutter Web アプリはキャンバスに描画します。その HTML にはテキストがなく、どのアドレスも同じ index.html を配信します。検索エンジン、チャットのリンクプレビュー、ページを読む言語モデルは、タイトルが一つだけの空のページを目にします。

ビルダーは、アプリがすでに表示しているソース (ナビゲーションの画面と、アプリが描画する Markdown ファイル) から、ビルド時にこれを解決します。同期を保つべきサイトの第二版はありません。各アドレスは次のものを受け取ります。

例

このサイトの設定:

# 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

そして、Markdown ファイルのフォルダーを表示する画面の一つ:

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

ファイル lib/resources/content/components/spring-boot-starter-web/cors.md はページ /components/spring-boot-starter-web/cors になります。ビルドは web/components/spring-boot-starter-web/cors.html を書き出します。これは web/index.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 -->

そしてその本体は、Flutter のブートストラップのスクリプトの直前に、ページのテキストを受け取ります。

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

その隣の web/components/spring-boot-starter-web/cors.md には、フロントマターを除いた、書かれたとおりの Markdown が入ります。

各値の出どころ:

値 出どころ
CORS ファイルのフロントマターの title:
<title> title のパターン。{title} がページのタイトルに置き換えられる
説明 フロントマターの description:
画像 ページ独自のものがないので spring.flutter.web.seo.image
アドレス site-url とページのパス。page-files: html なので末尾に / はない

動くとき

ビルダーは、ジェネレーターに依存するすべてのパッケージで、spring_metadata (ルートを列挙する) と spring_flutter_page_loader (テンプレートを書く) の後に動きます。lib/resources/ のファイルにテキスト seo が含まれる場合にだけプロパティを読み、spring.flutter.web.seo.enabled が true で web/index.html が存在する場合にだけページを書き出します。enabled でも web/index.html がなければ警告します。

プロパティは、アプリがブラウザーで読むのと同じように読まれます。application.*、application-web.*、アクティブなプロファイルのファイルとインポートで、Web 開発サーバー と同じく web プロファイルが有効です。環境変数と --dart-define の値は数えられません。キーは Web のビルドだけが使うので、Web プロファイルのファイルに置いてください。

ページが無効にされたり web/index.html がなくなったりすると、ビルダーは以前に書き出したファイルを削除し、web/index.html から自身のブロックを取り出します。

ページの出どころ

三つの出どころがあり、組み合わせることができます。

1. ルート: from-routes: true

spring_boot_starter_flutter_navigation では、画面は lib/spring_gen/spring_metadata.json (@ScreenRoute と @RouteInfo から書かれたその routes) に列挙されます。from-routes: true では、ビルダーはそれらからページを作ります。

画面 ページ
変数のないパス (/about) そのパスに一つのページ
変数のないパスと content: のファイル ファイルの Markdown を持つ一つのページ
唯一の変数である {*name} で終わるパスと、/ で終わる content: のフォルダー フォルダーの Markdown ファイルごとに一つのページ: /components/{*path} の下の content/components/core/beans.md は /components/core/beans
その他の変数を持つパス (/books/{isbn}) なし。ただし @RouteInfo(paths: [...]) がそのアドレスを列挙していれば別
見つからない場合の画面 なし

画面の title: がページのタイトルになり、@RouteInfo の description と image がその説明と画像になります。タイトルや説明の中の #{key} は messages.properties (または言語のファイル。下記) から読まれます。見つからないキーはキーの名前になります。ガードされた画面 (@PreAuthorize)、または @RouteInfo(index: false) を持つ画面は noindex を受け取り、サイトマップと llms.txt から外されます。

content: のファイルやフォルダーは resources: でも asset: でも構いません。asset: のフォルダーは pubspec.yaml の Flutter のアセットから読まれる (ディレクトリーの項目はそのディレクトリー自身のファイルを与える) ため、asset:docs/ は resources:content/docs/ と同じページを作ります。spring.resources.embed.exclude でバイナリーから外したファイルもページになります。埋め込みリソース を参照してください。

@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 のフォルダー: content[n]

独自の画面を持たないページのためのものです。

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

lib/resources/content/blog/ の下のすべての .md ファイルがページになります。first.md は /blog/first、index.md は /blog そのもの、2026/news.md は /blog/2026/news です。exclude では、フォルダーからの相対で、* は一つのフォルダーの中に、** はフォルダーをまたいで一致します。**/ はフォルダーなしにも一致するので、**/contents.md はそのフォルダー自身の contents.md も対象にします。

ルートの Markdown フォルダーを含むすべてのフォルダーから、ある種類のファイルを外すには、トップレベルの exclude を使います。各フォルダーの contents.md からメニューを読むサイトは、それらをページとサイトマップから外します。

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

3. 手で指定するページ: pages[n]

その他のページのため、またはルートが自身について示す内容を変えるためのものです。そのパスのページがすでに存在する場合は、与えられた値がそのページ自身の値を置き換えます。そうでなければ、テキストのない新しいページが作られます。このサイトは、/ のより長いタイトルのためにこれを使っています。

Markdown のページ

Markdown ファイルはフロントマターで始めることができます。title がなければ、最初の # の見出しがタイトルになります。

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

# Beans
...
フロントマターのキー 意味
title ページのタイトル
description ページの説明
image ページのプレビュー画像
index false: noindex、サイトマップと llms.txt から外す

Markdown は GitHub の方言で描画されます。Markdown の中に書かれた HTML は、アプリと同じくページでもテキストとして保たれます。ページのテキストはアプリのテキストと同じでなければならないからです。

ページ間のリンク

.md ファイルへの相対リンクはサイトのアドレスになります。content/docs/core/configuration.md の中の beans.md#scopes は /docs/core/beans#scopes になります (前に site-url のパスが付きます)。スキームを持つリンク、/ や # で始まるリンク、その他のファイルへのリンクはそのままです。

サイトのページでない Markdown ファイルへのリンクはビルドを失敗させます。

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

このサイトのビルドは、こうしてページ間の壊れたリンクを見つけています。

プレースホルダー

spring.flutter.markdown.placeholders: true を使うと、Markdown ファイルの各 {{key}} は、ページが作られる前に設定の値に置き換えられます。アプリで MarkdownView が置き換えるのと同じです。HTML のテキスト、.md のコピー、llms.txt、llms-full.txt のすべてが値を受け取ります。値のないキーはそのまま残り、${...} には触れません。このサイトは依存関係の例に ^{{site.package-version}} と書き、そのページは最新のリリースを表示します。

各ページが受け取るもの

タグ 値
<title> {title} をページのタイトルに置き換えた title のパターン。必要なら、セクションのタイトルで重複しないようにする (下記)。タイトルのないページはテンプレートの <title> を保つ
<meta name="description"> ページの説明、なければ description。テンプレートの description のタグを置き換える
<link rel="canonical"> ページのアドレス (翻訳のない別の言語のページでは、デフォルトの言語のアドレス)
<link rel="alternate" hreflang> ページのテキストを持つ言語ごとに一つと、デフォルトの言語のための x-default。二つ以上ある場合のみ
<meta name="robots" content="noindex"> インデックスされてはならないページ
og:title、twitter:title パターンなしのページのタイトル
og:description、twitter:description 説明と同じ
og:url ページのアドレス
og:type website
og:site_name 設定されていれば site-name
og:image、twitter:image ページの画像、なければ image。resources: の場所は、flutter build web がアセットに与えるアドレス <site-url>/assets/lib/resources/<path> になる (pubspec.yaml の flutter: assets: の下にフォルダーを列挙すること)。URL はそのまま
twitter:card 画像があれば summary_large_image、なければ summary
<link rel="alternate" type="text/markdown"> markdown: true の Markdown のページでは .md のコピー
<html lang> spring.flutter.navigation.languages があればページの言語
<script type="application/ld+json"> BreadcrumbList (下記)。タイトルを持つ別のページの下にあるページ

重複しないタイトル

検索エンジンは、同じ <title> を持つ二つのページのうち一つしか表示しません。サイトにはよくあります。パッケージごとの すべてのプロパティ のページです。ビルダーはインデックスされるページを調べます。タイトルが重複していれば、ページ自身のタイトルの後に、すぐ上のページ (タイトルを持つページである、最も近い祖先のパス) のタイトルを加えます。すべてのタイトルが重複しなくなるまで、一回ごとに一段ずつ、最大八段まで加えます。

ページ パターンの中の {title}
/components/spring-search-dart/properties All properties · spring_search_dart
/components/spring-boot-starter-data/properties All properties · spring_boot_starter_data

ルートページはセクションではありません。そのタイトルはサイトのものです。上に祖先のページが残っていないページは、そのタイトルのままです。og:title と twitter:title は短いタイトルのままです。各言語は、その言語のタイトルで、それぞれ別に重複しないようにされます。

パンくずリスト

ルート以外のすべてのページは、ヘッドのブロックに schema.org の BreadcrumbList を JSON-LD として受け取ります。その上にあるタイトルを持つ各ページ (ルートを含む)、次にページ自身で、それぞれアドレスを持ちます。Google は検索結果で、このパスをページのタイトルの上に表示します。上にタイトルを持つページがないページは受け取らず、翻訳のない別の言語のページも受け取りません。

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

名前はパターンを除いたページ自身のタイトルです。言語のページでは、名前とアドレスはその言語のものです。

ページのファイルとアドレス

page-files は各ページのファイル名を決め、それによって canonical のリンク、og:url、代替、サイトマップが使うアドレスも決めます。それらは常に、静的ホストがリダイレクトなしに配信するものと一致します。リダイレクトする canonical のアドレスは、ページを検索エンジンから外してしまうからです。

page-files /docs/beans のファイル そのアドレス
directory (デフォルト) web/docs/beans/index.html https://example.com/docs/beans/: 静的ホストは /docs/beans から /docs/beans/ へのリダイレクトの後にファイルを配信する
html web/docs/beans.html https://example.com/docs/beans: Cloudflare Pages、GitHub Pages、Netlify はそこでリダイレクトなしに配信する

ルートページのアドレスはどちらの場合も <site-url>/ です。

ルートページ

ルートページ (/) は web/index.html そのものです。そのヘッドのブロックは <!-- spring:seo:head:start --> と <!-- spring:seo:head:end --> の間に入り、Markdown がある場合、そのテキストは <!-- spring:seo:content:start --> と <!-- spring:seo:content:end --> の間に入ります。各ビルドは、まず古いブロックを取り出し、それから新しいものを書きます。ページローダーのビルダーは、これらのマーカーを持つページのタイトルと説明に触れません。

その他のページは、ルートのブロックを除いた web/index.html のコピーです。flutter build web は web/index.html の中の $FLUTTER_BASE_HREF だけを埋めるので、コピーではビルダーが自分でそこに site-url のパスを書きます (<base href="/">)。

クローラーとモデルのためのファイル

ファイル 書き出される条件 内容
web/sitemap.xml sitemap: true インデックスされるすべてのページのアドレスをソートしたもの。その <lastmod> (下記) と、翻訳されたページには xhtml:link の代替
web/robots.txt sitemap: true User-agent: *、Allow: /、サイトマップのアドレス
web/llms.txt llms: true ルートページのタイトルと説明、続いてインデックスされる Markdown のページを最初のパスのセグメントでグループ化したもの (## Components)。それぞれ .md のコピーへのリンクとその説明
web/llms-full.txt llms: true インデックスされるすべての Markdown のページのテキスト。それぞれ <!-- address --> の行の後
web/<path>.md markdown: true 各 Markdown のページの、フロントマターを除いた書かれたとおりの Markdown。ルートページのものは web/index.md で、その text/markdown のリンクと llms.txt がそれを指す

このサイトの robots.txt と 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

lastmod: true (デフォルト) では、各 Markdown のページのサイトマップの項目が <lastmod> を受け取ります。そのファイルを変えた最後のコミットの日付で、git log から取ります (2026-11-08)。翻訳されたページは、翻訳ファイルの日付を受け取ります。検索エンジンは変わったページを先に取得します。

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

lastmod: false で無効になります。ページをコミットし、CI が別のチェックアウトからもう一度ビルドする場合に使ってください。その日付は、ページをビルドしたときのものではないからです (リポジトリーの seo_site の例がそうしています)。

言語

spring.flutter.navigation.languages ([en, ja]) があると、すべてのページが各言語で書き出されます。最初の言語はページのアドレスに、その他は /<language> の下 (/ja/components) に置かれます。これはアプリ自身が開くアドレスです。

言語は言語タグ (en、ja、pt-BR) でなければならず、それ以外はビルドを失敗させます。

書き出されるものと、コミットするもの

ビルダーはアプリ自身のフォルダーである web/ に書き込むので、ファイルは宣言されたビルドの出力ではありません。書き出したすべてのファイルを web/.spring-seo に列挙します (ルートの web/index.html は除く)。次のビルドで、そのリストにあってもう書き出されないファイルは削除されるので、なくなったページが残ることはありません。テキストが変わっていないファイルは再び書き出されません。

build_runner なしで別の場所でサイトをビルドする場合はファイルをコミットし、そうでなければ .gitignore に追加します。ページのフォルダーや .html ファイル、.txt、.xml、.md ファイル、そして web/.spring-seo です。flutter build web はそれらを build/web/ にコピーします。

ページの配信

サーバーは /docs/beans に対してページのファイルで応答しなければなりません。

spring.flutter.navigation.web.url-strategy はデフォルトの path のままにしてください。hash 戦略はルートを # の後に置き (/#/docs/beans)、クローラーはそれをたどらず、これらのページとも一致しません。

プロパティ

表は spring.flutter.web.seo. の下のキーを示します。

キー 型 デフォルト 意味
enabled true / false false ページを書き出すかどうか
site-url 絶対 URL なし。enabled の場合は必須 canonical、og:url、サイトマップ、画像のアドレスのためのサイトのアドレス。そのパスはアプリが配信される場所 (/docs/ の下のアプリなら https://example.com/docs/)
from-routes true / false false ナビゲーションの画面がページを作るかどうか
title {title} を含むテキスト {title} <title> のパターン
description テキスト なし 説明を持たないページの説明
image resources: の場所または URL なし 画像を持たないページのプレビュー画像。約 1200×630
site-name テキスト なし og:site_name
content[n].location resources: または asset: のフォルダー なし Markdown ファイルのフォルダー。ファイルごとに一つのページ
content[n].path パス / フォルダーのアドレス
content[n].exclude グロブのリスト なし 外されるフォルダーのファイル
exclude グロブのリスト なし すべての Markdown フォルダー (ルートのものと content[n] のもの) から外されるファイル
pages[n].path パス なし 手で指定するページ、または変更するルートのページ
pages[n].title テキスト ルートまたはファイルのもの ページのタイトル (#{key} を使える)
pages[n].description テキスト ルートまたはファイルのもの ページの説明 (#{key} を使える)
pages[n].image resources: の場所または URL ルートまたはファイルのもの ページのプレビュー画像
pages[n].index true / false ルートまたはファイルのもの false: noindex、サイトマップと llms.txt から外す
sitemap true / false true sitemap.xml と robots.txt を書き出すかどうか
lastmod true / false true サイトマップが各 Markdown のページに Git からの <lastmod> を付けるかどうか。シャロークローンでは付かない
llms true / false true llms.txt と llms-full.txt を書き出すかどうか
markdown true / false true .md のコピーとその代替のリンクを書き出すかどうか
page-files directory / html directory ページのファイルの名前の付け方

ビルダーは spring.flutter.navigation.languages と spring.flutter.markdown.placeholders も読みます。true / false のキーにそれ以外の値を指定すると、デフォルトとみなされます。

エラー

どのエラーもビルドを止め、ページを書き出しません。

問題 メッセージ (短縮)
有効な site-url なしの enabled: true 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 が directory でも html でもない spring.flutter.web.seo.page-files: "..." is directory (<path>/index.html) or html (<path>.html).
言語タグでない言語 spring.flutter.navigation.languages: "..." is no language tag (en, ja, pt-BR).
一つのアドレスに二つのファイル Two files make the page /docs/beans: ... and ....
一つのファイルが二つのアドレスに (ルートのフォルダーと content[n] のフォルダー) The file ... makes two pages: ... and ....
パスが唯一の変数である {*name} で終わらないフォルダーのルート The route ... shows the folder ...: its path must end with {*name}, its only variable.
.md ファイルのない Markdown のフォルダー The Markdown folder ... has no .md file.
ルートの content: のファイルが存在しない lib/resources/... is missing.
有効な YAML でないフロントマター The front matter of lib/resources/...: ...
ページでない Markdown ファイルへのリンク lib/resources/... links to ..., which is no page of the site (...).
設定ファイルを読めない 読み込みのエラーに続けて The pages of spring.flutter.web.seo are not written.

Spring (Java) との対応

Spring には対応するものがありません。Spring MVC のアプリケーションは、リクエストのたびにサーバーで HTML を描画します。このビルダーが存在するのは、Flutter Web アプリがブラウザーの中で、キャンバスに描画するからです。

関連項目