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 のファイルからページを作ります。元は一つなので、ページは常にアプリと同じことを言います。
例
# 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
# 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/
@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 { ... }
次に、こう実行します。
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 などが入ります。
仕組み
すべてはビルド時に起こります。サーバーでは何も動かず、アプリも変わりません。
dart run build_runner build。spring_core_dart_generatorがそのビルダーを実行します。その一つが、アプリの画面をlib/spring_gen/spring_metadata.jsonに列挙します。もう一つの SEO のビルダー (spring_flutter_seo) が、その後に動きます。- SEO のビルダーは設定を読みます。 アプリがブラウザーで読むのと同じように、
application.*、次にapplication-web.*、アクティブなプロファイルのファイルとインポートを、webプロファイルをアクティブにして読みます。lib/resources/のファイルがseoという文字列を含むときだけ読みます。 - ページを集めます。 画面から、Markdown のフォルダーから、そして
pagesのリストからです。 - ファイルをアプリ自身のフォルダーである
web/に書き出します。 各ページはweb/index.htmlのコピーに、ページのヘッドとテキストを加えたものです。ルートページはweb/index.htmlそのものに入ります。 flutter build webがweb/のすべてを、アプリの隣のbuild/web/にコピーします。- ホストがファイルを配信します。
/docs/getting-startedへのリクエストはdocs/getting-started.htmlを受け取ります。クローラーはそのヘッドとテキストを読みます。ブラウザーはそのスクリプトを実行し、Flutter のアプリがテキストの上で起動するため、訪問者にはいつもどおりアプリが見えます。
そのため、コンテンツを変えるたびに、flutter build web の前に build_runner を実行してください。
1 ページを最初から最後まで
ここでは /docs/getting-started という 1 ページを取り上げ、あなたが書くものから、ビルドがそのページから作るすべてのファイルまでを示します。ファイルは、リポジトリの seo_site の例の実際の出力です (page-files: directory、デフォルト)。
あなたが書くもの
設定です。Web のビルドだけが読みます。
# 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 で書きます。
@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 で書きます。
---
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 の間にあります。
<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 にあります。
<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 のコピー: なぜあるのか
# Getting started
Add the package:
...
Then read the [routing guide](guides/routing.md#paths).
書いたままのテキストで、front matter はありません。HTML はブラウザー向けです。言語モデルやドキュメントを読むツールが求めるのは、タグ、スタイル、スクリプトのない、テキストとその構造です。.md のコピーは、そのテキストを決まったアドレス (<page>.md) に置いたもので、ヘッドから指され、llms.txt に列挙されます。markdown: false にすると書き出されません。
サイト全体のファイル
<!-- 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 (デフォルト。この例ではオフにしています) で追加されます。
<!-- 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 があれば、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 の画面 を参照してください。
Markdown のフォルダー: content[n]
ブログのように、どの画面も指定しない Markdown のためのものです。
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 がなければ、最初の # の見出しがタイトルになります。
---
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: ビルドを実行する
dart run build_runner build
ビルダーは web/ に書き出し、書き出したすべてのファイルを web/.spring-seo に列挙します。次のビルドで、そのリストのファイルがもう書き出されなければ削除されるため、削除したページが公開されたまま残ることはありません。ファイルはコミットするか、サイトを常に先に build_runner でビルドするなら .gitignore に加えてください。enabled: false にすると、ビルダーは書き出したものを削除し、そのブロックを web/index.html から取り除きます。
エラーはビルドを止め、ページを一つも書き出しません。よくあるものは、site-url がない、二つのファイルが一つのアドレスになる、ページではないファイルへのリンク、パスが {*name} で終わらないフォルダーの画面、です。すべてのメッセージ: エラー。
各ページが受け取るもの
そのファイル
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 --> の間に書かれます。
<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 のブートストラップのスクリプトの前に入ります。
<!-- 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 です。ページローダー の下、次に 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} はページ自身のタイトルです。次のうち、最初に値があるものが使われます。
pages[n].title。そのアドレスに手で設定したページ (#{key}も使えます)。- Markdown ファイルの front matter の
title:。 - front matter にタイトルがないときは、Markdown ファイルの最初の
#見出し。 - 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 で日付を得るには、履歴をすべて取得してください。
# .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) にあります。アプリ自身が開くアドレスです。言語 を参照してください。
- 翻訳は、
.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 でもです。値のないキーはそのまま残り、\{{ は {{ をテキストとして書きます。設定の値 を参照してください。
クローラーが見るもの、訪問者が見るもの
同じファイルを、二つの方法で読みます。クローラーやプレビューのボットは HTML を読みます。
$ 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:
directoryのファイルにはspring.web.resources.directory-index: trueを、アプリの他のアドレスにはspa-fallback: trueを使います。
canonical のアドレスは、常にホストがリダイレクトなしで配信するアドレスです。リダイレクトする canonical のアドレスは、ページを検索エンジンから外してしまいます。
spring.flutter.navigation.web.url-strategy はデフォルトの path のままにしてください。hash ではルートが # の後 (/#/docs/beans) になり、クローラーはそれをたどりません。
確かめる
検索エンジンに伝える前に:
- ソースを表示します。 ページを開いて ⌘⌥U (Ctrl+U) を押します。
<title>、og:のタグ、<main id="spring-content">を探してください。ブラウザーのインスペクターは動いているページを、ソースはクローラーが受け取るものを表示します。 - 上のように、ページを curl します。
https://<site>/sitemap.xmlとhttps://<site>/robots.txtも開いてください。 - 画像:
og:imageのアドレスをブラウザーで開きます。404なら、そのフォルダーがflutter: assets:にありません。 - Google のリッチリザルト テスト (
search.google.com/test/rich-results): ページのアドレスを入力します。パンくずリストが見つかるはずです。 - Google Search Console の URL 検査 (下記): 公開 URL をテスト、次にテスト済みのページを表示。その HTML は Google が読んだテキストを、スクリーンショットはアプリを表示します。
Google Search Console
Search Console は、Google にサイトを伝え、インデックスされたものを見る場所です。
search.google.com/search-consoleを開き、プロパティを追加します。- ドメインのプロパティ (
books.example.com) は、ドメインのすべてのアドレスを対象にします。DNS のプロバイダーでTXTレコードを使って確認します。 - URL プレフィックスのプロパティ (
https://books.example.com/) は、代わりに HTML ファイルで確認できます。そのファイルをweb/に置けば、flutter build webが公開します。
- ドメインのプロパティ (
- サイトマップを開き、
sitemap.xml(完全なアドレスはhttps://<site>/sitemap.xml) を入力して送信を押します。しばらくすると、そのステータスは見つかったページの数とともに成功しましたになります。 - URL 検査を開き、重要なページ (まずホームページ) のアドレスを貼り付けて、インデックス登録をリクエストを押します。プロパティごとに一日の上限は小さいため、いくつかのページだけにしてください。残りはサイトマップが扱います。
- 待ちます。 新しいサイトでは数日から数週間かかります。インデックス作成 › ページは、何がインデックスされたか、他のページがなぜされていないかを表示します。
そこで見かけるメッセージ:
| メッセージ | 意味 |
|---|---|
| 検出 - インデックス未登録 | 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 も読みます。ビルダーがそれらをどう読むか、そして報告するすべてのエラー: 検索エンジン向けのページ。