検索エンジン向けのページ
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 ファイル) から、ビルド時にこれを解決します。同期を保つべきサイトの第二版はありません。各アドレスは次のものを受け取ります。
- 独自の
<head>:<title>、説明、canonical、リンクプレビューのog:*とtwitter:*のタグ、インデックスされてはならないページのrobots、言語の代替。 - そのテキスト。ページローダー の下、さらに Flutter のビューの下にある
<main id="spring-content">の中の素の HTML です。訪問者がそれを目にすることはなく、取り除かれることもないので、ページのスクリプトを実行するクローラーも引き続きそれを読めます。
例
このサイトの設定:
# 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)。翻訳されたページは、翻訳ファイルの日付を受け取ります。検索エンジンは変わったページを先に取得します。
- Markdown ファイルのないページ (
content:のない画面、pages[n]だけのページ) には付きません。 - Git のチェックアウトの外では、どのページにも付きません。
- シャロークローンでは、どのページにも付きません。その一つのコミットが、すべてのファイルの日付になってしまうからです。CI のチェックアウトの多くはシャローです。日付を保つには履歴をすべて取得してください。
# .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) に置かれます。これはアプリ自身が開くアドレスです。
- Markdown のページの翻訳はその隣にあり、
.mdの前に言語が付きます:beans.mdの隣のbeans.ja.md。そのフロントマターが翻訳されたタイトルと説明を与えます。その中のリンクはrouting.mdとrouting.ja.mdのどちらを指してもよく、どちらも/ja/...に導きます。翻訳ファイルがそれ自体でページになることはありません。 #{key}のタイトルと説明は、その言語のメッセージ (messages_ja.properties、次にmessages.properties) から来ます。- 翻訳のないページも、アドレスが機能するように書き出されます。デフォルトの言語のテキストで、canonical のアドレスはデフォルトのページのもの、
noindexで、サイトマップと代替から外されます。 llms.txtとllms-full.txtはデフォルトの言語のままです。翻訳の.mdのコピーは/ja/<path>.mdにあります。
言語は言語タグ (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 に対してページのファイルで応答しなければなりません。
- 静的ホスト (Cloudflare Pages、GitHub Pages、Netlify、Firebase Hosting) はそうし、指示すればアプリの他のアドレスにはルートの
index.htmlで応答します。ホストに合わせてpage-filesを選んでください (上記を参照)。 spring_boot_starter_webは、directoryのファイルにはspring.web.resources.directory-index: trueでそうします。静的リソース を参照してください。
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 アプリがブラウザーの中で、キャンバスに描画するからです。
関連項目
- SEO: 手順、Search Console、リンクのプレビュー
- ページローダー
- Web 開発サーバー
- エディター向けのメタデータ
- ビルドが読むプロパティ
- 静的リソース