ADR-0030: 種別を記事の 1 つにし、構成を記事の形式で、シリーズをディレクトリで表す¶
Status¶
承認
Context¶
サイトの目的は、訪問者がコードを書いて動かしながら、技術の仕組みを体系的に学べることである。
出典: PRD
コンテンツの違いは、2 つの軸に分かれる。
- 構成: 1 ページで上から下へ読むか、複数のセクションに分かれた手順を順に進めるか。
- 埋め込むコンテンツ: Mermaid の記法で書いた図、実行環境、キャンバスの図、スライド。
今の決定は、次のとおり。
- サイトを about、blog、playground の 3 つのセクションに分け、記事とハンズオンを別の種別として、別のディレクトリと URL に置く。
- playground を collection にし、ディレクトリで分類する。
- 手を動かす場所を、frontmatter の
interactive.levelで 4 つに分ける。 - DB を使うハンズオンの実行環境、ハンズオンのページの island のつなぎ方、手順をまとめる処理の配置先を決めている。どれも、引き継がないコードの決定である。
- 本文の検索を、一覧のページに置く。Pagefind の索引を最初から作る。
- about は、トップが兼ねる。
- ADR-0026: トップの最初の訪問で水墨の門を描き、門をくぐった立体の庭にプロフィールを置く
- 安定した識別子の
contentIdと、片方向の関連を持つ。 - Mermaid の記法で書いた図を、Pele で SVG にする。
- ADR-0016: mermaid の図を、ビルドでも島でも Pele で SVG にする
運営者がハンズオンを別の種別にしていた理由は、構成（複数のセクション）であり、埋め込むコンテンツではない。
1 つの主題のシリーズには、1 ページの記事と、手順の記事の両方が入る。
古いサイトの記事、ハンズオン、playground の原稿とコードは、引き継がない。
実行環境の方式は、実行環境の要求の prototype で決める。
Decision¶
1. 種別と形式¶
- コンテンツの種別は、記事の 1 つにする。
- 構成は、記事の frontmatter の形式（
format）で決める。形式は、1 ページ（page）と手順（steps）の 2 つである。書かなければ 1 ページになる。 - 形式が手順の記事は、1 つの URL の中で、本文の
h2を 1 つの手順にする。手順は、URL の#で指す。 - schema は、実装した形式の値だけを受け付ける。先に受け付けると、ビルドを通った記事が、表示のときに崩れるためである。最初は、1 ページだけを受け付ける。
- 埋め込むコンテンツは、種別にも形式にもしない。本文に置く機能として、形式と独立に追加する。
- 記事の schema は、実行環境の項目を持たない。手を動かす場所の 4 つの分類をやめる。
- 実行環境の選び方と埋め込み方は、この ADR では決めない。実行環境の方式を決める ADR が決める。
- 手順の形式は、外部の Codelab のツールを使わず、サイトのページとして描く。
h2を手順にまとめる処理の配置先は、手順の形式を作るときに決め直す。 contentId、公開の状態（status）、片方向の関連は引き継ぐ。
種別を 1 つにする理由は、1 つのシリーズに、1 ページの記事と手順の記事を並べられるためである。
2. URL¶
| URL | 中身 |
|---|---|
/ |
トップ。プロフィールを兼ねる |
/articles |
記事の一覧 |
/articles/<slug> |
シリーズに入れない記事 |
/articles/<series>/<slug> |
シリーズの中の記事 |
/series/<series> |
シリーズのページ。タイトル、説明、読む順の記事の一覧 |
/playground |
プレイグラウンドの一覧。ツールは、プレイグラウンドのサブドメインに置く |
/rss.xml |
RSS |
- 記事の URL は
/articles/の下にあるので、ほかの URL と重ならない。記事のパスに使えない語の予約は持たない。 - 一覧は 1 つにする。形式が手順の記事には、一覧で「ハンズオン」のラベルを付ける。
- 古いサイトの URL（
/blog、/labs/<path>など）は、転送しない。同じ中身のページが無いためである。404 のページから、記事の一覧へ案内する。
3. シリーズ¶
- 原稿は
apps/web/src/content/articles/に置く。 articles/<series>/のディレクトリが、1 つのシリーズになる。ディレクトリの入れ子は 1 階層までにする。- 読む順は、記事の frontmatter の
orderで決める。1 つのシリーズの中でorderが重なると、ビルドが失敗する。 - シリーズのタイトルと説明は、ディレクトリの
index.mdに書く。 - シリーズに入れない記事は、
articles/の直下に置く。
記事を追加するときに変えるファイルは、その Markdown の 1 枚である。
新しいシリーズを作るときだけ、index.md を追加する。
4. 図と検索¶
mermaidのフェンスは、ビルドのときに Pele で SVG にする。- フェンスの
runの有無で、ビルドのときの描画と、クライアントの island の描画に分ける規則は引き継ぐ。最初に作るのは、ビルドのときの描画だけである。 - 本文の検索と Pagefind の索引は、最初は作らない。記事が増えて、一覧とシリーズから辿れなくなったときに作る。
Considered Options¶
| 選択肢 | 強み | 弱み |
|---|---|---|
| 採用: 種別は記事の 1 つ。構成は形式で、シリーズはディレクトリで表す | 1 つのシリーズに、1 ページの記事と手順の記事を並べられる。一覧と URL が 1 つで済む。新しい表示の形式を、形式の値で追加できる | frontmatter に形式を書くルールが増える |
| 記事とハンズオンを、ディレクトリと URL で分ける 2 つの種別にする | 種別ごとに schema を分けられる。今の URL を変えない | シリーズが種別をまたぐので、ディレクトリでシリーズを表せない。新しいシリーズのたびに、別のファイルを追加する。一覧と URL が種別の数だけ増える |
| 種別は記事の 1 つで、構成は 1 ページだけにする。ハンズオンは、シリーズで表す | 手順ごとに URL がある。JavaScript なしで手順を進められる | 手順をまたぐとページを開き直すので、埋め込んだ実行環境の状態が次の手順に残らない。ハンズオンを、シリーズの中の 1 本にできない |
| シリーズごとのファイルに、記事を読む順に並べて書く | 順の入れ替えが 1 か所で済む | 記事を追加するたびに、2 つのファイルを変える |
Consequences¶
Positive¶
- 記事を追加する操作が、Markdown の 1 枚で済む。
- 一覧、URL、schema が、種別の数に応じて増えない。
- 埋め込むコンテンツを、種別と形式を変えずに追加できる。
Negative¶
- 古いサイトの URL は、開けなくなる。
- シリーズの途中に記事を挟むと、後ろの記事の
orderを直すことがある。 - 「種別は置いたディレクトリで決まる」というルールは、種別が 1 つになるので意味を持たなくなる。形式は frontmatter で決まる。
- 手順の形式を作るときに、
h2を手順にまとめる処理の配置先を決め直す。