feat: add Astro reference site and organize book contents

README.md

@@ -0,0 +1,72 @@
+# WIP Reference
+
+Web Interface Protocolの仕様文書と、その文書を読むための静的サイトです。
+
+## 構成
+
+- [`contents/`](contents/) — 仕様の正本。番号付きMarkdownを章順に読みます。
+- [`contents/draft/`](contents/draft/) — API設計・投影方針などの草案。正本とは区別します。
+- [`site/`](site/) — AstroによるトップページとBook。文書のコピーは持たず、`contents/**/*.md`をビルド時に読み込みます。
+
+[第1章：コンセプト](contents/1-concept.md) / [Core Model](contents/2-core-model.md) / [Protocol](contents/3-protocol.md) / [Client](contents/4-client.md) / [WIP over HTTP](contents/5.1-wip-over-http.md)
+
+以前の直下Markdownと`draft/`は`contents/`へ移動しました。文書の内容・ファイル名・相互の相対リンクは維持しています。外部からraw Markdownを参照する場合はパスへ`contents/`を追加してください。
+
+## 開発・検証
+
+Node.js 22.12以上（CIは24）、npmを使用します。
+
+```sh
+cd site
+npm ci
+npm run dev
+```
+
+開発サーバーは通常 `http://localhost:4321/` です。
+
+```sh
+npm run verify  # unit tests → Astro/TypeScript check → production build → link checks
+npm run preview
+```
+
+`/`がトップページ、`/book/`が目次です。各章は`/book/3-protocol/`のように元のファイル名を保持します。草案は`/book/draft/rust-api-model/`などに分離し、草案である旨を表示します。サイドバー、章内目次、前後の章へのリンクはsourceから生成します。
+
+ブラウザーでデスクトップ／モバイルの表示とナビゲーションを検証する場合（事前にbuildが必要）：
+
+```sh
+npx playwright install chromium
+npm run test:browser
+# インストール済みChromeを使う場合：CHROME_PATH=/path/to/chrome npm run test:browser
+```
+
+テストはクライアントJavaScriptを無効にして実行し、スクリーンショットを`site/test-results/`へ保存します。サブパスbuildの検証時は同じ`SITE_BASE`を設定してください。
+
+## 文書の編集
+
+文書は`contents/`だけを編集します。各文書の先頭の`#`見出しをタイトルに使用するため、frontmatterは不要です。番号付き文書は番号順、草案は別グループで表示します。
+
+Markdown上の相対`.md`リンクはリポジトリ上でもそのまま読めます。サイト生成時にremark pluginがBookのURLへ変換し、queryとfragmentを維持します。コードブロックや外部URLは変換しません。`npm run check:links`は生成ページ、文書の欠落、重複ID、内部リンク・画像・CSS/JSと見出しanchorを検証します。
+
+## サイト公開
+
+静的出力の`site/dist/`を公開します。SSR、常駐Nodeサーバー、データベースは不要です。ホスティング先や公開ドメインはまだ固定していません。**このリポジトリへのpushだけでインターネット上へ自動デプロイされる設定ではありません。**
+
+```sh
+cd site
+npm ci
+SITE_URL=https://your-domain.example npm run verify
+```
+
+サブパスへ公開する場合：
+
+```sh
+SITE_URL=https://your-domain.example SITE_BASE=/wip-reference npm run verify
+```
+
+- `SITE_URL`：公開サイトのorigin（例：`https://your-domain.example`）。path prefixは`SITE_BASE`へ分離します。設定時にcanonical URLを生成し、未指定時に仮ドメインは埋め込みません。
+- `SITE_BASE`：公開path prefix。既定は`/`。サブパスの場合は、そのprefixへ`dist/`の内容を配置します。
+- 本番ビルドはリポジトリ全体をcheckoutし、作業directoryを`site/`、build commandを`npm ci && npm run verify`、output directoryを`site/dist/`（作業directory基準では`dist/`）にします。
+- Static hostではディレクトリの`index.html`を配信し、未知のURLへ`404.html`を返す設定を使用します。SPA fallbackは不要です。
+- 文書は静的HTML、コードの色付けはビルド時のShiki、モバイルの目次はHTMLの`details`です。閲覧にクライアント側JavaScriptを必要としません。
+
+Gitea Actionsの`.gitea/workflows/site.yml`で、通常ビルドとサブパスビルドを検証し、公開用の`wip-reference-site` artifactを作成します。GiteaのActionsと対応runnerが必要です。Repository variablesの`SITE_URL`／`SITE_BASE`を設定すると成果物へ反映します。ホスティングへのアップロードは、その公開先を決めてから別途接続してください。