
# SEO

Flutter の Web アプリはキャンバスに描画するため、その HTML にはテキストがありません。`spring.flutter.web.seo.enabled` を使うと、ビルドはアプリのアドレスごとに本物の HTML ページを書き出します。そのページ自身のタイトル、説明、プレビューのタグ、テキストを持つページです。`sitemap.xml`、`robots.txt`、`llms.txt`、`llms-full.txt`、そして各ページの Markdown のコピーも書き出します。訪問者には、これまでどおり Flutter のアプリが表示されます。このページでは、その仕組みを順を追って説明し、サイトを公開した後にすることを示します。

## 使う理由

素の Flutter の Web アプリでは、すべてのアドレスが同じ `index.html` を返します。そこには一つの `<title>`、Flutter の説明、スクリプトだけの空の `<body>` があります。Web ページを読むプログラムには、それしか見えません。

- X、Telegram、Slack、WhatsApp、Discord の**リンクのプレビュー**は HTML を読み、スクリプトは決して実行しません。共有されたリンクは、どのページを指していても、アプリの名前だけを表示し、画像はありません。
- **検索エンジン**はインデックスするテキストを得られず、すべてのページが同じタイトルを持ちます。Google は後で、ときどきスクリプトを実行しますが、キャンバスにはやはり読むテキストがありません。
- **言語モデル**とそのツールはテキストを読み、キャンバスは読みません。

サイトの HTML 版を別に書くこともできますが、アプリとずれていきます。ここでは、ビルドがアプリがすでに表示しているもの、つまりナビゲーションの画面と、アプリが描画する Markdown のファイルからページを作ります。元は一つなので、ページは常にアプリと同じことを言います。

## 例

```yaml
# lib/resources/application-web.yml: Web のビルドだけが読む
spring:
  flutter:
    navigation:
      languages: [en, ja]             # 英語のページと /ja/ の下のページ
    markdown:
      placeholders: true              # ページの {{key}}。アプリでもビルドでも
    web:
      seo:
        enabled: true
        site-url: https://books.example.com
        page-files: html              # <path>.html: Cloudflare Pages、GitHub Pages、Netlify
        from-routes: true             # すべての画面がページになる
        exclude: ['**/contents*.md']  # メニューであり、ページではない
        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。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: プレビューの画像は Flutter のアセットとして配信される
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 { ... }
```

次に、こう実行します。

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

これで `build/web/` には、アプリとその隣に `docs/getting-started.html`、`blog/first.html`、`books/978-0441013593.html`、`ja/docs/getting-started.html`、`sitemap.xml`、`robots.txt`、`llms.txt` などが入ります。

## 仕組み

すべてはビルド時に起こります。サーバーでは何も動かず、アプリも変わりません。

1. **`dart run build_runner build`。** `spring_core_dart_generator` がそのビルダーを実行します。その一つが、アプリの画面を `lib/spring_gen/spring_metadata.json` に列挙します。もう一つの SEO のビルダー (`spring_flutter_seo`) が、その後に動きます。
2. **SEO のビルダーは設定を読みます。** アプリがブラウザーで読むのと同じように、`application.*`、次に `application-web.*`、アクティブなプロファイルのファイルとインポートを、`web` プロファイルをアクティブにして読みます。`lib/resources/` のファイルが `seo` という文字列を含むときだけ読みます。
3. **ページを集めます。** 画面から、Markdown のフォルダーから、そして `pages` のリストからです。
4. **ファイルをアプリ自身のフォルダーである `web/` に書き出します。** 各ページは `web/index.html` のコピーに、ページのヘッドとテキストを加えたものです。ルートページは `web/index.html` そのものに入ります。
5. **`flutter build web`** が `web/` のすべてを、アプリの隣の `build/web/` にコピーします。
6. **ホストがファイルを配信します。** `/docs/getting-started` へのリクエストは `docs/getting-started.html` を受け取ります。クローラーはそのヘッドとテキストを読みます。ブラウザーはそのスクリプトを実行し、Flutter のアプリがテキストの上で起動するため、訪問者にはいつもどおりアプリが見えます。

そのため、コンテンツを変えるたびに、`flutter build web` の前に `build_runner` を実行してください。

## 1 ページを最初から最後まで

ここでは `/docs/getting-started` という 1 ページを取り上げ、あなたが書くものから、ビルドがそのページから作るすべてのファイルまでを示します。ファイルは、リポジトリの `seo_site` の例の実際の出力です (`page-files: directory`、デフォルト)。

### あなたが書くもの

設定です。Web のビルドだけが読みます。

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

| 設定 | このページに対する働き | 理由 |
|---|---|---|
| `enabled: true` | ビルダーを有効にする | デフォルトはオフ: Web 向けでないビルドは何も書き出さない |
| `site-url` | すべての絶対アドレスの先頭部分: `canonical`、`og:url`、`hreflang`、サイトマップ | 検索エンジンとプレビューには絶対アドレスが必要で、ビルドはドメインを推測できない |
| `from-routes: true` | `content:` を持つルート `/docs/{*path}` が、そのフォルダーのファイルごとにページを作る。このページも含まれる | ページがアプリ自身の画面に従い、二重に列挙しなくて済む |
| `title` | `<title>Getting started · Lumen</title>`: `{title}` はページ自身のタイトル | 検索結果とタブのすべてにサイトの名前が付く。プレビューはサイト名を別に表示するので、`og:title` は短いタイトルのまま |
| `description` | 説明を持たないページの説明 | このページは front matter に自分の説明を持つため、デフォルトは使われない |
| `image` | 画像を持たないページのプレビューの画像 | サイト全体で 1 枚の画像。ページは自分の画像を指定できる (front matter の `image:`) |
| `pages[0]` | ホームページのタイトル `Lumen, a small library` | このページのパンくずリストの最初の段になる |
| `languages: [en, ja]` | `/ja/` の下の 2 つ目のページと、両者の間の `hreflang` のリンク | 検索エンジンにとって言語ごとが別のページ。言語が 2 つなければ `hreflang` は書かれない |

画面は Dart で書きます。

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

`content:` は、その画面が表示するフォルダーを指定します。そこにあるファイル `getting-started.md` がアドレス `/docs/getting-started` になり、その隣の `getting-started.ja.md` が `/ja/docs/getting-started` になります。

ページは 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).
```

front matter がページのタイトルと説明を与えます。アプリは本文を表示し、ビルドは同じ本文を HTML として書き出します。

### ビルドが書き出すもの

このページは 4 つのファイルに現れ、サイト全体の 2 つのファイルがこのページを列挙します。

| ファイル | 読むもの |
|---|---|
| `web/docs/getting-started/index.html` | 検索エンジン、リンクのプレビュー、HTML を読むあらゆるプログラム。そしてブラウザー (その後アプリを起動する) |
| `web/docs/getting-started.md` | HTML なしでテキストを求める言語モデルやツール |
| `web/ja/docs/getting-started/index.html`、`.md` | 日本語のページについても同じ |
| `web/sitemap.xml` | 検索エンジン: インデックスするすべてのページと、その言語 |
| `web/llms.txt`、`web/llms-full.txt` | 言語モデル: `.md` ページの一覧と、すべてを 1 つにまとめたファイル |

`flutter build web` はそれらを `build/web/` にコピーし、ホストは `docs/getting-started/index.html` から `https://lumen.example/docs/getting-started/` を配信します。

### HTML ページ: なぜあるのか

アプリ自身の `index.html` はどのアドレスでも同じです。タイトルは 1 つで、テキストはありません。このファイルは、それにページのヘッドとテキストを加えたコピーなので、スクリプトを決して実行しないプログラムでもページを得られます。訪問者のブラウザーはいつもと同じスクリプトを実行し、アプリを見ます。

ヘッドは `<!-- spring:seo:head:start -->` と `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>
```

| 行 | 出どころ | 与えるもの |
|---|---|---|
| `<title>` | `title` のパターンと front matter の `title` | 検索結果のリンクのテキスト |
| `description` | front matter の `description` | リンクの下のテキスト |
| `canonical` | `site-url` とページのアドレス | リンクがどんなクエリ文字列を付けても、検索エンジンが数える唯一のアドレス |
| `hreflang` ×3 | `languages` と `.ja.md` ファイル | Google は日本語の読者に日本語のページを表示する。`x-default` はそれ以外のすべての人向けのページ |
| `og:*`、`twitter:*` | タイトル、説明、`image` | 共有されたリンクにメッセンジャーが表示するカード。`og:image` はアセットのアドレスなので、`lib/resources/images/` は `flutter: assets:` に入っている |
| `text/markdown` の alternate | `markdown: true` (デフォルト) | `.md` のコピーがどこにあるかをプログラムに伝える |
| `BreadcrumbList` | その上にあるページ: `/` (`pages[0]`)、`/docs` (`index.md`) | Google の結果のタイトルの上に `Lumen › Documentation › Getting started` と表示される |

テキストは、Flutter のスクリプトの前の body にあります。

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

これが検索エンジンがインデックスするものです。ページローダーとアプリの下にあるので、訪問者には決して見えません。`guides/routing.md` へのリンクはサイトのアドレス `/docs/guides/routing#paths` になったので、クローラーはそれをたどって次のページへ進めます。ページでないファイルへのリンクは、ビルドを失敗させます。

### Markdown のコピー: なぜあるのか

```markdown
# Getting started

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

書いたままのテキストで、front matter はありません。HTML はブラウザー向けです。言語モデルやドキュメントを読むツールが求めるのは、タグ、スタイル、スクリプトのない、テキストとその構造です。`.md` のコピーは、そのテキストを決まったアドレス (`<page>.md`) に置いたもので、ヘッドから指され、`llms.txt` に列挙されます。`markdown: false` にすると書き出されません。

### サイト全体のファイル

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

サイトマップは、リンクを待たずに、ページがあることを検索エンジンに伝えます。`robots.txt` はサイトマップを指します。Git からの `<lastmod>` は `lastmod: true` (デフォルト。この例ではオフにしています) で追加されます。

```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` は、言語モデルが最初に読む一覧です。各ページの `.md` のアドレスと説明を、フォルダーごとにまとめています。`llms-full.txt` は、すべてのページの Markdown を 1 つのファイルに収めたもので、各ページの前に `<!-- address -->` の行があります。

## 手順 1: 有効にする

キーは `lib/resources/application-web.yml` に書きます。Web のビルドだけが読み、アプリは決して読みません。

| キー | 書くもの |
|---|---|
| `spring.flutter.web.seo.enabled` | `true` |
| `spring.flutter.web.seo.site-url` | サイトの公開のアドレス。アプリがルートにない場合はそのパスも (`https://example.com/shop/`)。必須: canonical のリンク、`og:url`、サイトマップは絶対アドレスである必要がある |
| `spring.flutter.web.seo.title` | `<title>` のパターン: `'{title} · Neon Books'`。`{title}` はページ自身のタイトル |
| `spring.flutter.web.seo.description` | 説明を持たないページの説明 |
| `spring.flutter.web.seo.image` | 画像を持たないページのプレビューの画像: `resources:images/preview.png`、または完全な URL |
| `spring.flutter.web.seo.site-name` | 一部のプレビューでタイトルの上に表示されるサイトの名前 (`og:site_name`) |
| `spring.flutter.web.seo.page-files` | `directory` (デフォルト) または `html`。[ページの配信](#ページの配信) を参照 |

アプリには `web/index.html` が必要です (`flutter create --platforms web .` が書き出します)。`enabled` で `web/index.html` がない場合、ビルドは警告するだけです。

`resources:` の画像は `<site-url>/assets/lib/resources/<path>` になります。`flutter build web` がそのアセットに与えるアドレスです。そのため、例のように、そのフォルダーを `pubspec.yaml` の `flutter: assets:` に列挙してください。

## 手順 2: ページの出どころを選ぶ

出どころは三つです。一つでも、すべてでも使えます。

### 画面: `from-routes: true`

[spring_boot_starter_flutter_navigation](../spring-boot-starter-flutter-navigation/index.md) があれば、`from-routes: true` はアプリの画面からページを作ります。

| 画面 | ページ |
|---|---|
| 変数のないパス (`/about`) | そのパスに一つのページ |
| 変数のないパスと `content:` のファイル | そのファイルのテキストを持つ一つのページ |
| 唯一の変数である `{*name}` で終わるパスと、`/` で終わる `content:` のフォルダー | フォルダーの Markdown ファイルごとに一つのページ: `/docs/{*path}` の下の `content/docs/core/beans.md` は `/docs/core/beans`、`index.md` はフォルダー自身のアドレス |
| 他の変数を持つパス (`/books/{isbn}`) | なし。`@RouteInfo(paths: [...])` がそのアドレスを列挙する場合を除く |
| 見つからない場合の画面 | なし |

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

`content:` のフォルダーは `resources:` でも `asset:` (`pubspec.yaml` の任意の Flutter のアセットのフォルダー) でも構いません。[Markdown の画面](../spring-boot-starter-flutter-navigation/markdown-screens.md) を参照してください。

### Markdown のフォルダー: `content[n]`

ブログのように、どの画面も指定しない Markdown のためのものです。

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

フォルダーの下のすべての `.md` ファイルがページになります。`first.md` は `/blog/first`、`index.md` は `/blog`、`2026/news.md` は `/blog/2026/news` です。glob では、`*` は一つのフォルダーの中で、`**` はフォルダーをまたいで一致し、`**/` はフォルダーがない場合にも一致します。

### ファイルを外す: `exclude`

トップレベルの `exclude` は、画面のものも `content` のものも、すべての Markdown のフォルダーに適用されます。各フォルダーの `contents.md` からメニューを読むサイトは、`exclude: ['**/contents*.md']` でそれらのファイルをページとサイトマップから外します。

### 手で指定するページ: `pages[n]`

各項目は `path` を指定します。そのパスのページがすでにあれば、与えた値がそのページ自身の値を置き換えます。ホームページのより長いタイトルや、別の画像です。なければ、テキストのない新しいページが作られます。`index: false` はページを検索結果から外します。ページは `<meta name="robots" content="noindex">` を受け取り、サイトマップと `llms.txt` から外されます。

### Markdown ファイル自身の値

Markdown ファイルはフロントマターで始められます。`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
```

すべてのページに具体的な `description` を書いてください。検索エンジンはそれをタイトルの下によく表示し、プレビューは画像の下に表示します。

別の `.md` ファイルへの相対リンクは、サイトのアドレスになります。`beans.md#scopes` は `/docs/core/beans#scopes` になります。サイトのページではない Markdown ファイルへのリンクはビルドを失敗させるため、壊れたリンクは公開の前に見つかります。

## 手順 3: ビルドを実行する

```text
dart run build_runner build
```

ビルダーは `web/` に書き出し、書き出したすべてのファイルを `web/.spring-seo` に列挙します。次のビルドで、そのリストのファイルがもう書き出されなければ削除されるため、削除したページが公開されたまま残ることはありません。ファイルはコミットするか、サイトを常に先に `build_runner` でビルドするなら `.gitignore` に加えてください。`enabled: false` にすると、ビルダーは書き出したものを削除し、そのブロックを `web/index.html` から取り除きます。

エラーはビルドを止め、ページを一つも書き出しません。よくあるものは、`site-url` がない、二つのファイルが一つのアドレスになる、ページではないファイルへのリンク、パスが `{*name}` で終わらないフォルダーの画面、です。すべてのメッセージ: [エラー](../spring-core-dart-generator/flutter/seo.md#エラー)。

## 各ページが受け取るもの

### そのファイル

| `page-files` | `/docs/beans` のファイル | そのアドレス |
|---|---|---|
| `directory` (デフォルト) | `web/docs/beans/index.html` | `https://example.com/docs/beans/` |
| `html` | `web/docs/beans.html` | `https://example.com/docs/beans` |

ルートページ `/` は `web/index.html` そのもので、`<!-- spring:seo:head:start -->` と `end` のマーカーの間に書かれます。他の言語のページは `/<language>/` の下にあります: `web/ja/docs/beans.html`。

### そのヘッド

`/docs/core/beans` のヘッドです。マーカー `<!-- spring:seo:head:start -->` と `<!-- 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>
```

| タグ | 何のためか |
|---|---|
| `<title>` | 検索結果の青いリンクと、ブラウザーのタブ |
| `description` | 検索結果のリンクの下のテキスト |
| `canonical` | このページの唯一のアドレス。検索エンジンがコピー (`?v=2`、他の言語の代わりのページ) を別のページとして数えないように |
| `hreflang` の代替 | 他の言語の同じページと、デフォルトのための `x-default`。言語が二つ以上の場合だけ書かれる |
| `og:*` | メッセンジャーやソーシャルアプリのリンクのプレビュー (Open Graph プロトコル) |
| `twitter:*` | X のプレビュー。画像があれば `summary_large_image`、なければ `summary` |
| `text/markdown` の代替 | プログラムがページのテキストを Markdown として見つける場所 |
| `BreadcrumbList` (JSON-LD) | Google の検索結果でタイトルの上に表示されるパス (`Neon Books › Docs › Beans`)。タイトルを持つ別のページの下にあるすべてのページ |
| `robots` の `noindex` | 一覧に載せてはいけないページだけ |
| `<html lang>` | ページの言語。`spring.flutter.navigation.languages` がある場合 |

`og:title` はページ自身のタイトルです。`<title>` はパターンを使い、セクションのタイトルも付くことがあります (次の節)。

### そのテキスト

ページのテキストは、本文の中の Flutter のブートストラップのスクリプトの前に入ります。

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

アプリが表示するのと同じ Markdown から GitHub の書式で描画した、プレーンな HTML です。[ページローダー](../spring-core-dart-generator/flutter/page-loader.md) の下、次に Flutter のビューの下にあります。訪問者には決して見えず、決して取り除かれないため、ページのスクリプトを実行するクローラーも読めます。Markdown のない画面はヘッドだけを受け取ります。

### その Markdown のコピー

`markdown: true` (デフォルト) では、ページの Markdown が、フロントマターを除いて書かれたままに `<path>.md` として書き出されます: `web/docs/core/beans.md`。ヘッドは `<link rel="alternate" type="text/markdown">` でそれを指します。プログラムは HTML を解析せずにページのテキストを読めます。

## タイトルの出どころ

`spring.flutter.web.seo.title` はパターン (`'{title} · Neon Books'`) で、`{title}` はページ自身のタイトルです。次のうち、最初に値があるものが使われます。

1. `pages[n].title`。そのアドレスに手で設定したページ (`#{key}` も使えます)。
2. Markdown ファイルの front matter の `title:`。
3. front matter にタイトルがないときは、Markdown ファイルの最初の `#` 見出し。
4. Markdown のない画面では、`@ScreenRoute(title: ...)`。

`#{key}` は `messages.properties` から読み、日本語のページは先に `messages_ja.properties` から読みます。翻訳 (`beans.ja.md`) は自分の front matter か見出しを使います。パターンから `<title>Beans · Neon Books</title>` ができます。`og:title` と `twitter:title` は短いタイトルのままです。プレビューはサイト名を別に表示するからです。2 つのページのタイトルが同じになったときは、次の節のとおり重複しないようにします。

説明も同じ順で決まります。`pages[n].description`、front matter の `description:`、`@RouteInfo(description: ...)`、最後に `spring.flutter.web.seo.description`。画像も同じです。`pages[n].image`、front matter の `image:`、`@RouteInfo(image: ...)`、最後に `spring.flutter.web.seo.image`。

## 重複しないタイトル

同じタイトルの二つのページは検索エンジンを迷わせます。そのうち一つしか表示されないことがよくあります。多くのサイトにはそれがあります。各セクションの `すべてのプロパティ` のページです。ビルドはそのようなページに、自身のタイトルの後にセクションのタイトルを一つずつ加え、インデックスされるすべてのページが自分の `<title>` を持つようにします。

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

セクションとして数えられるのは、タイトルを持つページだけです。ルートページはセクションではありません。プレビュー (`og:title`) は短いタイトルのままです。

## サイト全体のファイル

| ファイル | 書き出されるとき | 何のためか |
|---|---|---|
| `web/sitemap.xml` | `sitemap: true` (デフォルト) | インデックスされるすべてのページのアドレスを、並べ替えて、`<lastmod>` と言語の代替とともに。検索エンジンはここからページを見つける |
| `web/robots.txt` | `sitemap: true` | `User-agent: *`、`Allow: /`、そしてサイトマップのアドレス |
| `web/llms.txt` | `llms: true` (デフォルト) | 言語モデルのためのサイトの地図: ルートページのタイトルと説明、次にインデックスされる各 Markdown のページを、その `.md` のコピーへのリンクと説明として、パスの最初の部分ごとにまとめて (`## Docs`) |
| `web/llms-full.txt` | `llms: true` | インデックスされるすべての Markdown のページのテキストを一つのファイルに。それぞれ `<!-- address -->` の行の後に |

### サイトマップの lastmod

`<lastmod>` は、前回の訪問以降にどのページが変わったかを検索エンジンに伝え、それらが先に取得されるようにします。ビルドはそれを Git から取ります。ページの Markdown ファイルを変えた最後のコミットの日付です (`git log`)。

- Markdown ファイルのないページには付きません。Git のチェックアウトの外では、どのページにも付きません。
- **シャロークローン**では、どのページにも付きません。その一つのコミットが、すべてのファイルの日付になってしまうからです。CI のチェックアウトの多くはシャローです。CI で日付を得るには、履歴をすべて取得してください。

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

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

## 言語

`spring.flutter.navigation.languages: [en, ja]` を使うと、すべてのページが各言語で書き出されます。最初の言語には接頭辞がなく (`/docs/beans`)、他の言語はそのタグの下 (`/ja/docs/beans`) にあります。アプリ自身が開くアドレスです。[言語](../spring-boot-starter-flutter-navigation/languages.md) を参照してください。

- 翻訳は、`.md` の前に言語を入れて、その Markdown ファイルの隣に置きます: `beans.ja.md`。そのフロントマターが翻訳されたタイトルと説明を与えます。翻訳はそれ自体でページにはなりません。
- `#{key}` のタイトルと説明は、その言語のメッセージ (`messages_ja.properties`、次に `messages.properties`) から来ます。
- 翻訳された各ページは、すべての言語を `hreflang` の代替として列挙し、サイトマップも列挙します。Google は日本語の読者に日本語のページを表示します。
- 翻訳のないページも書き出されるため、そのアドレスは動きます。デフォルトの言語のテキストを持ち、canonical のアドレスはデフォルトのページのもので、`noindex` を受け取ります。サイトマップと代替からは外されます。
- `llms.txt` と `llms-full.txt` はデフォルトの言語のままです。

## プレースホルダー

`spring.flutter.markdown.placeholders: true` を使うと、ページの `{{key}}` は設定の値に置き換えられます。アプリでも、SEO のページでも、`.md` のコピーでも、`llms.txt` でもです。値のないキーはそのまま残り、`\{{` は `{{` をテキストとして書きます。[設定の値](markdown.md#設定の値) を参照してください。

## クローラーが見るもの、訪問者が見るもの

同じファイルを、二つの方法で読みます。クローラーやプレビューのボットは 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">
```

ブラウザーはページのローダーを表示し、次に同じアドレスで Flutter のアプリを表示します。テキストはアプリの下で、ページに残ります。どちらも同じ Markdown ファイルから、同じ言葉を読みます。

## ページの配信

ホストは `/docs/beans` にページのファイルで応え、アプリの他のアドレスにはルートの `index.html` で応える必要があります。

- **Cloudflare Pages、GitHub Pages、Netlify**: `page-files: html` を使います。これらは `docs/beans.html` をリダイレクトなしで `/docs/beans` で配信します。このサイトはこの方法で配信されています。
- **他の静的ホスト** (Firebase Hosting、S3、nginx): `directory` は `docs/beans/index.html` を書き出し、どのホストもそれを `/docs/beans/` で配信します。ページの中のアドレスは `/` で終わるため、配信されるものと一致します。
- **[spring_boot_starter_web](../spring-boot-starter-web/static-resources.md)**: `directory` のファイルには `spring.web.resources.directory-index: true` を、アプリの他のアドレスには `spa-fallback: true` を使います。

canonical のアドレスは、常にホストがリダイレクトなしで配信するアドレスです。リダイレクトする canonical のアドレスは、ページを検索エンジンから外してしまいます。

`spring.flutter.navigation.web.url-strategy` はデフォルトの `path` のままにしてください。`hash` ではルートが `#` の後 (`/#/docs/beans`) になり、クローラーはそれをたどりません。

## 確かめる

検索エンジンに伝える前に:

1. **ソースを表示します。** ページを開いて ⌘⌥U (Ctrl+U) を押します。`<title>`、`og:` のタグ、`<main id="spring-content">` を探してください。ブラウザーのインスペクターは動いているページを、ソースはクローラーが受け取るものを表示します。
2. 上のように、ページを **curl** します。`https://<site>/sitemap.xml` と `https://<site>/robots.txt` も開いてください。
3. **画像**: `og:image` のアドレスをブラウザーで開きます。`404` なら、そのフォルダーが `flutter: assets:` にありません。
4. **Google のリッチリザルト テスト** (`search.google.com/test/rich-results`): ページのアドレスを入力します。**パンくずリスト**が見つかるはずです。
5. **Google Search Console の URL 検査** (下記): **公開 URL をテスト**、次に**テスト済みのページを表示**。その HTML は Google が読んだテキストを、スクリーンショットはアプリを表示します。

## Google Search Console

Search Console は、Google にサイトを伝え、インデックスされたものを見る場所です。

1. `search.google.com/search-console` を開き、**プロパティを追加**します。
   - **ドメイン**のプロパティ (`books.example.com`) は、ドメインのすべてのアドレスを対象にします。DNS のプロバイダーで `TXT` レコードを使って確認します。
   - **URL プレフィックス**のプロパティ (`https://books.example.com/`) は、代わりに HTML ファイルで確認できます。そのファイルを `web/` に置けば、`flutter build web` が公開します。
2. **サイトマップ**を開き、`sitemap.xml` (完全なアドレスは `https://<site>/sitemap.xml`) を入力して**送信**を押します。しばらくすると、そのステータスは見つかったページの数とともに**成功しました**になります。
3. **URL 検査**を開き、重要なページ (まずホームページ) のアドレスを貼り付けて、**インデックス登録をリクエスト**を押します。プロパティごとに一日の上限は小さいため、いくつかのページだけにしてください。残りはサイトマップが扱います。
4. **待ちます。** 新しいサイトでは数日から数週間かかります。**インデックス作成 › ページ**は、何がインデックスされたか、他のページがなぜされていないかを表示します。

そこで見かけるメッセージ:

| メッセージ | 意味 |
|---|---|
| 検出 - インデックス未登録 | Google はページを知っているが、まだ取得していない。待つ |
| 「noindex」タグによって除外されました | `index: false` のページ、ガードされた画面、または翻訳のないページ。意図どおり |
| 適切な canonical タグあり代替ページ | canonical のアドレスが別のページ。`/ja/` の下の翻訳のないページなど。意図どおり |
| 重複しています。ユーザーにより、正規ページとして選択されていません | 二つのアドレスが一つのページを返している。`page-files` とホストのリダイレクトを確かめる |

大きな変更の後は、サイトマップをもう一度送信してください。`<lastmod>` が新しいページが先に取得されます。

## Bing Webmaster Tools

Bing のインデックスは、他の検索エンジンやアシスタントにも使われています。`bing.com/webmasters` を開いてサイトを追加します。Google Search Console から**インポート**でき、確認とサイトマップの追加が一度で済みます。そうでなければ、確認してから、**サイトマップ**で `https://<site>/sitemap.xml` を送信します。**URL 検査**は Google のものと同じように使えます。

## リンクのプレビュー

X、Telegram、Slack、WhatsApp、Discord、LinkedIn は、リンクが共有されると `og:` と `twitter:` のタグを読みます。

- サイトには `spring.flutter.web.seo.image` で画像を、ページにはフロントマターの `image:` か `@RouteInfo(image:)` で専用の画像を与えてください。1200×630 ピクセル (約 1.91:1)、PNG か JPEG、5 MB 未満にします。画像があると大きなカード (`summary_large_image`) になります。
- 画像のアドレスは絶対で、公開されている必要があります。ログインや Cookie なしで読み込めなければなりません。
- **プレビューはキャッシュされます。** ページにタグがなかったとき、またはサイトが落ちていたときにリンクを取得したアプリは、そのプレビューを数日間保持します。新しいものを見るには、クエリを付けてアドレスを共有します: `https://books.example.com/docs/core/beans?v=2`。ホストは同じファイルを配信し、canonical のアドレスは変わらないため、検索エンジンは迷いません。Telegram では、`@WebpageBot` にリンクを送ると更新されます。Facebook と LinkedIn には、もう一度取得する独自の検査ツールがあります。

## 制限

- **ページはビルド時に作られます。** ページは `build_runner` を実行したときのファイルの内容を表示します。ユーザーごとのページや、サーバーやデータベースから読むデータのページはありません。新しい本には新しいビルドが必要です。
- **変数を持つルート** (`/books/{isbn}`) は、`@RouteInfo(paths: [...])` がそのアドレスを列挙しない限り、ページを作りません。
- **ログインの後ろのページは検索エンジンのためのものではありません。** ガードされた画面は `noindex` を受け取り、サイトマップと `llms.txt` から外されます。そのファイルと Markdown のコピーは書き出されます。`lib/resources/` のすべてはアプリとともに配布され、いずれにせよダウンロードできるため、秘密のものは置かないでください。
- **Markdown のない画面**は、ヘッド (タイトル、説明、プレビュー) を受け取りますが、テキストはありません。
- **Markdown に書いた HTML** は、アプリと同じく、ページでもテキストのままです。
- **`hash` の URL 戦略**には対応していません。

## プロパティ

`spring.flutter.web.seo.` の下のキーです。

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `enabled` | bool | `false` | ビルドがページを書き出すかどうか。`false` は以前に書き出したものを削除する |
| `site-url` | 絶対 URL | なし。`enabled` のときは必須 | サイトのアドレス。そのパスがアプリの配信される場所 |
| `from-routes` | bool | `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` | glob のリスト | なし | 除外するフォルダーのファイル |
| `exclude` | glob のリスト | なし | すべての Markdown のフォルダーから除外するファイル |
| `pages[n].path` | パス | なし | 手で指定するページ、または変更する画面のページ |
| `pages[n].title` | テキスト | ページ自身のもの | そのタイトル (`#{key}` を使える) |
| `pages[n].description` | テキスト | ページ自身のもの | その説明 (`#{key}` を使える) |
| `pages[n].image` | `resources:` の場所または URL | ページ自身のもの | そのプレビューの画像 |
| `pages[n].index` | bool | ページ自身のもの | `false`: `noindex`、サイトマップと `llms.txt` に含めない |
| `sitemap` | bool | `true` | `sitemap.xml` と `robots.txt` を書き出すかどうか |
| `lastmod` | bool | `true` | サイトマップが各 Markdown のページに Git からの `<lastmod>` を付けるかどうか |
| `llms` | bool | `true` | `llms.txt` と `llms-full.txt` を書き出すかどうか |
| `markdown` | bool | `true` | `.md` のコピーとその代替のリンクを書き出すかどうか |
| `page-files` | `directory`、`html` | `directory` | ページのファイルの名前の付け方 |

ビルドは `spring.flutter.navigation.languages` と `spring.flutter.markdown.placeholders` も読みます。ビルダーがそれらをどう読むか、そして報告するすべてのエラー: [検索エンジン向けのページ](../spring-core-dart-generator/flutter/seo.md)。

## 関連項目

- [Web](web.md)
- [検索エンジン向けのページ](../spring-core-dart-generator/flutter/seo.md)。ビルダーの内部
- [Web とディープリンク](../spring-boot-starter-flutter-navigation/web-and-deep-links.md)
- [Markdown の画面](../spring-boot-starter-flutter-navigation/markdown-screens.md)
- [静的リソース](../spring-boot-starter-web/static-resources.md)
- [すべてのプロパティ](properties.md)
