SEO とパフォーマンス最適化
ドキュメントは人に読んでもらうために書くものですが、その前提になるのは、検索で見つかることと、開くのが速いことです。EpoCanvas Docs はビルドのレイヤーに、初期設定なしですぐ使える SEO 機能とパフォーマンス機構を組み込んでいます。このページでは、それぞれが何なのか、どう検証するか、そして公開後にやっておくべきことを説明します。
組み込みの SEO 機能
以下の機能はすべてビルド時に自動で有効になり、追加設定は不要です:
| 機能 | 実装方法 | 検証方法 |
|---|---|---|
| ページタイトル | <title>記事タイトル | EpoCanvas Docs</title>。Frontmatter から取得 | ページのソースまたはブラウザのタブで確認 |
| ページの説明 | <meta name="description">。Frontmatter の description から取得 | ソースを確認 |
| Open Graph タグ | og:title、og:type、og:url、og:locale、og:description。SNS にシェアしたときにカードを表示 | リンクをチャットツールに貼り付けてプレビューを確認 |
| Canonical リンク | 各ページに <link rel="canonical"> を自動生成し、メインドメインを指す | ソースを確認 |
| Sitemap | ビルド時に sitemap-index.xml を自動生成 | /sitemap-index.xml にアクセス |
| robots.txt | プロジェクトに public/robots.txt を同梱。すべてのクローラーを許可し、sitemap の場所を宣言 | /robots.txt にアクセス |
Canonical とミラードメイン
サイトのメインドメインは docs.epocanvas.com で、<site> の設定もこれに一致させています。各ページの canonical と og:url はメインドメインを指します。内容が epocanvas-docs.pages.dev のミラーからも同時に閲覧できる場合でも、検索エンジンは評価をメインドメインに一本化し、重複コンテンツとは判定しません。
パフォーマンス機構
純粋な静的出力、フレームワークのランタイムなし
ビルド成果物は純粋な HTML + CSS です。ページのナビゲーション、閲読、目次のスクロールハイライトには、どのフロントエンドフレームワークもダウンロードする必要がなく（React/Vue などのランタイムのサイズはゼロ）、検索・テーマ切替・言語切替などのインタラクティブなコンポーネントだけが必要に応じて少量のスクリプトを読み込みます。初回レンダリングは JavaScript を待たないため、遅い回線や低スペックの端末でも同じようにスムーズです。
画像のサイズはソースの時点で制御
本サイトではビルド時の画像処理を有効にしていません。astro.config.mjs で image.service を passthroughImageService() に設定しているため、public/ 内の画像は圧縮もリサイズもされず dist/ にそのままコピーされます。sharp を採用していないのは、pnpm の分離ディレクトリ構造ではネイティブ依存を解決できず、キャッシュが空の状態（CI や初回ビルド）で MissingSharp によりビルドが中断されるからです。そのためサイズはコミット前に制御しており、画面スクリーンショットは幅 1440 ピクセルに統一して事前に圧縮し、構成図はすべて SVG のベクター画像としています。
検索 index の必要時ロード
Pagefind は pnpm run build のときに高圧縮の index シャードを生成します。読者がページを開くときに index は一切ダウンロードされず、実際にサイト全体検索を使ったときにのみ、ブラウザがキーワードに応じて該当するシャード（数 KB〜数十 KB）を取得します。初回表示の速度には影響しません。
パフォーマンスの検証方法
- ブラウザ開発者ツールの Network パネルを開き、ページをリロードして、初回表示の転送サイズを確認します。
- Chrome のシークレットウィンドウで Lighthouse 監査（Performance カテゴリ）を実行し、スコアを確認します。
curl -sI https://docs.epocanvas.comで、応答ヘッダーのCache-Controlなど CDN のキャッシュポリシーが有効になっているかを確認します。
公開後にやっておきたい 3 つのこと
デプロイが完了したら（Cloudflare Pages へのデプロイ を参照）、順番に以下を行うことをおすすめします:
1. Sitemap を Google Search Console に登録する
- Google Search Console を開き、リソース
docs.epocanvas.comを追加します。 - 画面の案内に従い、DNS TXT レコードでドメインの所有権を確認します（ドメインを Cloudflare で管理していれば、数分で反映されます）。
- 左側の「サイトマップ」で
https://docs.epocanvas.com/sitemap-index.xmlを送信します。
2. インデックス登録の効果を確認する
公開から 1 週間後、Google で site:docs.epocanvas.com を検索して、記事がインデックス登録されているかを確認します。Search Console の「ページ」レポートで、インデックス登録されたページ数がドキュメント数と一致しているかを確認します。
3. 定期的にリンク切れをチェックする
ドキュメントの改訂やパスの改名の後、外部から張られた古いリンクが無効になることがあります。Search Console の「ページ」レポートで「見つかりませんでした (404)」の項目を確認し、astro.config.mjs の redirects テーブルで、アクセスの多い無効なパスにリダイレクトを追加してください。