til の分類をビルドする — directory → JSON パイプライン

> TL;DR (EN): This til's two-tier taxonomy is generated, not hand-maintained. seo/scripts/build-articles-tree.mjs walks the five division directories recursively, derives category from the top path segment and subcategory from the second, reads front matter, and writes _data/articles.json (flat list + tree_by_subcat + orphans) and _data/taxonomy.json (fixed categories/subcategories with counts + tags). The fixed vocabulary lives in code (CATEGORIES_META / SUBCATEGORIES_META); anything outside it is flagged as an orphan. Depth below subcategory is not a fixed tier — it's expressed by tags (facets) and parent (article threads). Hard-won gotchas: unquoted YAML arrays char-split into junk tags; restructuring directories changes URLs; git mv preserves history.

分類の再設計をしたとき、「カテゴリは3箇所で同期が要る」ことに気づいた：①ディレクトリ名、②ビルドスクリプトの定義、③README の表。これを正しく回す設計をメモしておく。

パイプラインの全体像

<division>/<subcategory>/<slug>.md   (front matter: category / subcategory / tags / parent)
        │
        ▼  node seo/scripts/build-articles-tree.mjs
        │
   _data/articles.json   … flat list + tree_by_category + tree_by_subcat + orphans
   _data/taxonomy.json   … categories(固定) × subcategories(固定) + counts + tags
        │
        ▼  Jekyll (GitHub Pages)
   README.md の Liquid が JSON を読んで一覧を描画

設計の要点

  • 正本はコード。CATEGORIES_META（5大分類）と SUBCATEGORIES_META（標準サブ領域）をスクリプトに固定で持つ。ディレクトリはそれに従う器。
  • category/subcategory はパスから導出。トップ＝第1セグメント、サブ＝第2セグメント。再帰的に .md を収集する。
  • 固定語彙の強制。規定外のサブカテゴリを使った記事は orphan として検出される（category 不正・parent 不在も同様）。orphans: 0 を緑信号にする。
  • 2階層まで固定、それ以下は作らない。連続する深掘りは parent（記事スレッド、tree_by_subcat に親子で反映）、横断は タグ（facet）。folksonomy-vs-hierarchy の結論通り、小規模で3階層目を固定するのは過剰設計。
  • 空の箱は残す。natural-sciences や mathematics が0件でも「学問の地図」として常設。

ハマったところ（再発防止）

  • 未クオートの YAML 配列：tags: [ai, mcp, claude-code] は素朴な YAML パーサで JSON.parse に失敗 → 文字列にフォールバック → for (tag of tags) が1文字ずつ回り、a i , といったゴミタグが量産された。配列はクオートする：tags: ["AI", "MCP", "Claude Code"]。
  • ディレクトリ再編は URL を変える：/til/people/x/ → /til/humanities/history/x/。サイト内リンクと parent のフルパス参照を全て追従させる必要がある。外部からの旧 URL は 404 になる（必要なら jekyll-redirect-from）。
  • git mv で履歴保持：31本を移動しても rename として追跡され、blame が切れない。
  • CRLF/LF：Windows で生成 JSON に改行警告が出る。.gitattributes で正規化しておくと静かになる。
  • git-bash のバックグラウンド fork が Windows で不安定（cygwin の CreateFileMapping エラー）。ビルド検証は PowerShell から node を叩くのが確実だった。

運用

新規ノートは <division>/<subcategory>/<slug>.md に置き、front matter に category/subcategory/tags/parent を埋め、node seo/scripts/build-articles-tree.mjs を回して orphans: 0 を確認 → commit → push で GitHub Pages が自動再ビルド。

参考・引用元

関連ノート