製品概要とコアバリュー
EpoCanvas Docs は、EpoCanvas オープンソースエコシステムのために作られた公式技術ドキュメントサイトシステムです。モダンな静的サイトフレームワーク Astro 5 と Starlight をベースに構築されており、体裁が整っていて、表示が速く、検索がしやすく、保守しやすいドキュメントプラットフォームを開発者に提供することを目指しています。
製品のユーザーマニュアルや API 仕様の作成から、システムアーキテクチャ設計の記録まで、EpoCanvas Docs なら執筆者は Markdown コンテンツを書くことに集中でき、読者には快適で自然な閲覧体験を届けられます。
解決する実際の課題
日常の開発や技術文書の執筆では、多くのチームがドキュメントの保守で次のような悩みを抱えています:
- ページの表示が遅く、メモリ消費が多い: 多くのドキュメントツールが生成するページには大量の JavaScript ランタイムが含まれており、スマートフォンや低速回線では表示が遅く、長文をスクロールすると動作が重くなりがちです。
- 長文のナビゲーションがつらい: 一般的なドキュメントサイトには左側メニューしかなく、数千字に及ぶ技術解説を読むとき、記事内の小見出しの階層をすぐに把握するのが難しいものです。
- 検索が外部サービス頼み: Algolia などのクラウド検索サービスは、アカウントの申し込みやクローラーキーの設定が別途必要で、外部サービスに接続できないイントラネット環境ではまったく機能しません。
- 多言語対応が半端: 多言語対応をうたうドキュメントサイトの多くは、実際にはナビゲーションボタンだけが翻訳されていて、記事本文は原文のままだったり、翻訳が欠けているとそのまま 404 になったりします。読者は URL を書き換えてコンテンツを探すしかありません。
EpoCanvas Docs は、まさにこうした実際の課題を解決するために設計されました。
コア機能一覧
図：製品概要ページの実際のレンダリング結果。左側がドキュメントのカテゴリ一覧、中央が本文、右側が自動生成された「目次」のアウトラインで、スクロールに合わせて現在のセクションがハイライトされます。
1. 見やすい 3 カラムのリーディング画面
- 左側ナビゲーションバー: モジュールごとにすべてのドキュメントカテゴリを整理し、階層の折りたたみに対応。ページを切り替えても表示位置が飛びません。
- 中央本文エリア: 本文の最大幅は 60rem、行間は 1.68、コードブロックは幅を自動調整。長時間読んでも疲れにくい作りです。
- 右側アウトラインバー: 記事内の
h2とh3の見出しを自動取得して「目次」を生成し、スクロールに合わせて現在の読書位置をハイライト。小見出しをクリックするとスムーズにジャンプします。
2. 2 モードの検索：ページ内検索 + サイト全体検索
- 現在のページ内検索: 上部の検索ボックスにキーワードを入力すると、ページ内の一致する文字がすべて即座にハイライトされ、
3/9のような進捗カウントも表示されます。Enter キーで順番にジャンプできます。 - サイト全体検索のポップアップ:
Ctrl + K（Mac はCmd + K）を押すと全体検索のポップアップが開き、Pagefind の静的インデックスに基づいて、ヒットしたドキュメントと段落のプレビューが一覧表示されます。 - 検索機能はすべてブラウザ内でローカルに完結し、バックエンドサービスに一切依存しないため、イントラネットにホストしても使えます。
3. 10 言語の完全翻訳
- 簡体字中国語、繁体字中国語、英語、日本語、韓国語、スペイン語、フランス語、ドイツ語、ロシア語、ポルトガル語の 10 言語に対応し、各言語のナビゲーション、サイドバー、全ドキュメントの本文が完全翻訳されています。
- 右上の言語ボタンをクリックするだけで、同じ記事の目的言語版に移動できます。URL には言語プレフィックスが付く（例:
/en/canvas/）ので、そのままブックマークでき、他の言語を使う同僚にもそのまま共有できます。 - ページによっては各言語の翻訳がまだ用意されていない場合でも、そのページはデフォルトの中国語コンテンツに自動フォールバック表示され、404 エラーにはなりません。
4. プロフェッショナルな Markdown とコードの整形
- Expressive Code によるコードハイライト。コードブロックにファイル名のタイトルを付けたり、指定行をハイライトしたり、diff 差分を表示したりできます。
- 4 種類のカラー吹き出し（Note、Tip、Caution、Danger）を標準でサポートし、タイトルのカスタマイズにも対応しています。
- GFM テーブル、タスクリスト、打ち消し線など、よく使う Markdown 拡張構文に対応しています。完全なルールはレンダリングルールの詳細を参照してください。
5. ビルドが速く、ホスティングは無料
- Astro 5 の静的コンパイルにより、ビルド成果物は純粋な HTML、CSS、必要時に読み込まれる少量の JS のみ。10 言語・約 180 ページのサイト全体の完全ビルドは約 25 秒です。
- Cloudflare Pages のデプロイコマンドを同梱しており、コマンド 1 行でドキュメントを公開でき、HTTPS 証明書も自動で取得できます。
プロジェクト全体のアーキテクチャ
ドキュメントを軽量で保守しやすく保つため、システムは役割ごとに 4 つの部分に分かれています:
図：システムアーキテクチャ。執筆者が保守するのは Markdown コンテンツソースだけで、それ以外の工程はすべて自動で行われます。
- 土台とスタイル: Astro 5 の静的コアをベースに、
src/styles/custom.cssでデザイン変数を定義します。ライトモードとダークモードは同じ変数名を共用します。 - コンテンツソース管理: すべてのドキュメントは
src/content/docs/ディレクトリに保存し、プレーンな Markdown（.md）か、コンポーネントを埋め込める MDX（.mdx）で記述します。 - UI コンポーネント: Starlight のネイティブコンポーネントをオーバーライドし、トップバー、サイドバー、目次、検索ポップアップをカスタマイズしています。
- 配信とアクセス: コンパイル成果物は
dist/ディレクトリに保存され、Cloudflare Pages でホストされます。世界中の CDN ノードが近隣から応答します。
どんな場面に向いているか
EpoCanvas Docs が向いているのは、次のような場面です:
- オープンソースプロジェクトの公式ドキュメントサイト: 製品マニュアル、API リファレンス、アーキテクチャ解説を 1 つのリポジトリでまかなえます。
- チーム内部のナレッジベース: 完全な静的サイトで外部サービスに依存しないため、イントラネットに置いても検索をフルに使えます。
- 個人技術ブログ風のドキュメント: Markdown を書くだけでフロントエンドの工程は不要で、コマンド 1 本で公開できます。
一方で、ログイン認証、コメントでのやり取り、リアルタイムのデータ表示が必要な場面には向いていません。純粋な静的サイトにはバックエンドがないため、こうした要件は別途サービスを組み合わせる必要があります。
代表的なドキュメントツールとの比較
| 機能 | EpoCanvas Docs | Docusaurus | VitePress | GitBook 商用版 |
|---|---|---|---|---|
| 基盤技術 | Astro 5 + Starlight | React 18 | Vue 3 + Vite | クローズドソースの SaaS |
| 検索方式 | Pagefind のローカル静的インデックス | Algolia クラウドサービスに依存 | Minisearch のメモリ内検索 | 独自バックエンドの検索 |
| レイアウト | 3 カラム（左メニュー + 中央本文 + 右目次） | プラグイン設定での改造が必要 | デフォルトで 2 カラム/3 カラム | 固定 2 カラム |
| デプロイ方式 | Cloudflare Pages へ直接アップロード | S3 / Vercel / GitHub | GitHub Pages | プラットフォーム独自のホスティング |
| 自主管理性 | 100% オープンソース、ソースコードを完全に保有 | 100% オープンソース | 100% オープンソース | クローズドソース、有料機能が多い |
技術スタックとバージョン
現在のバージョンで実際に使われている技術スタック（ビルド成果物が基準）:
| コンポーネント | バージョン | 役割 |
|---|---|---|
| Astro | v5.18.2 | 静的サイトのコア。ビルドとルーティングを担当 |
| Starlight | v0.32.6 | ドキュメントサイトフレームワーク。レイアウトの骨格とコンテンツ処理を提供 |
| Expressive Code | Starlight に同梱 | コードブロックのハイライト、タイトルバー、行ハイライト |
| Pagefind | @pagefind/default-ui 1.5.2 で統合 | ビルド時に静的検索インデックスを生成 |
| Wrangler | v4.131.0 | Cloudflare 公式 CLI。デプロイを実行 |
| 実行環境 | Node.js 18.20.8 / 20.3+ / 22+、pnpm 10 | ローカル開発とビルド。pnpm run deploy は wrangler の関係で Node.js 22 以上が必要 |
依存関係をアップグレードするときは、UI コンポーネントとカスタム開発 の回帰テストに関する注意事項も併せて確認してください。
プロジェクトのディレクトリ構成
本プロジェクトのコードは次のように整理されており、各ディレクトリの役割が明確です:
epocanvas-docs/├── public/ # 静的アセットディレクトリ（画像やベクターアイコンはここに置く）│ └── images/canvas/ # UI スクリーンショットとシステムアーキテクチャのベクター図├── src/│ ├── components/starlight/ # カスタムページコンポーネント（トップバー、サイドバー、ページ目次、検索ポップアップなど）│ ├── config/navigation.ts # トップナビゲーションバーの設定（メニュー項目の追加・削除はここ）│ ├── content/docs/ # ドキュメント本文の Markdown ファイルの置き場所│ │ ├── index.mdx # ドキュメントサイトのトップランディングページ│ │ ├── canvas/ # 各章のドキュメント（簡体字中国語、デフォルト言語）│ │ └── en/ ja/ ... # 他の 9 言語の完全翻訳ディレクトリ│ ├── styles/custom.css # グローバルスタイルとテーマカラー変数│ ├── utils/i18n.ts # UI 用語辞書と言語リスト│ └── pages/404.astro # カスタム 404 ページ（ブラウザ言語で案内文を出力）├── scripts/ # ビルド前キャッシュ無効化、i18n・画像・見出しリンクの点検、スクリーンショット生成├── astro.config.mjs # サイトのメイン設定ファイル（タイトル、言語リスト、サイドバーをここで設定）└── package.json # プロジェクトの依存関係と実行コマンドの設定次のステップ
- プロジェクトをローカルで動かしたい方は クイックスタート (3分で起動) をご覧ください。
- 画面の具体的なレイアウトと使い方を知りたい方は ページレイアウトと閲覧体験 をご覧ください。
- 新しいドキュメントを書き始めたい方は Markdown 執筆と整形ガイド と レンダリングルールの詳細 をご覧ください。