Building til's taxonomy — a directory → JSON pipeline

ダブルクリックで英日反転

Applied Sciences · Engineering

Building til's Taxonomy — a Directory → JSON Pipeline

The two-tier taxonomy of this TIL site is generated, not hand-maintained. A Node.js script walks five division directories, derives category and subcategory from the path, and emits two JSON data files consumed by Jekyll.

Pipeline at a glance

`build-articles-tree.mjs` walks `<division>/<subcategory>/<slug>.md` recursively
Outputs `_data/articles.json` (flat list + tree_by_subcat + orphans)
Outputs `_data/taxonomy.json` (fixed vocab + counts + tags)
Jekyll reads the JSON via Liquid to render the index

Key design decisions

Source of truth is code: `CATEGORIES_META` + `SUBCATEGORIES_META` are fixed in the script
category/subcategory derived from path segments; articles outside the vocab become orphans
Only two fixed tiers — deeper structure uses `parent` (threads) and tags (facets)
Empty categories kept as a permanent 'map of disciplines'

Hard-won gotchas

Unquoted YAML arrays (`[a, b]`) char-split into junk tags — always quote them
Restructuring directories changes URLs; update all in-site links and `parent` refs
Use `git mv` to move files and preserve blame history
On Windows, run the build via PowerShell — git-bash background forks are unstable

Adding a new note

Place file at `<division>/<subcategory>/<slug>.md`, fill front matter
Run `node seo/scripts/build-articles-tree.mjs`, confirm `orphans: 0`
Commit and push → GitHub Pages rebuilds automatically

→ Keep the fixed vocabulary in code, derive structure from the directory path, and make `orphans: 0` your green light before every commit.

Applied Sciences · Engineering

TILの分類体系（タクソノミー）をディレクトリ→JSONパイプラインで自動生成する

このTILサイトの二層分類体系は手作業で管理していない。Node.jsスクリプトが5つのディビジョン（分野区分）ディレクトリを再帰的に走査し、カテゴリ・サブカテゴリをパスから導出して、JekyllがLiquidで読み込む2つのJSONファイルを生成する。

パイプラインの全体像

`build-articles-tree.mjs`が`<division>/<subcategory>/<slug>.md`を再帰的に走査
`_data/articles.json`（フラットリスト＋ツリー＋orphans）を出力
`_data/taxonomy.json`（固定語彙＋カウント＋タグ）を出力
JekyllがLiquid経由でJSONを読み込みインデックスを描画

設計上の重要な決断

正典（ソース・オブ・トゥルース）はコード：スクリプト内の`CATEGORIES_META` / `SUBCATEGORIES_META`が固定値
カテゴリ・サブカテゴリはパスセグメントから自動導出。語彙外の記事はorphan（孤立記事）として検出
固定階層は2層まで。それ以下の構造は`parent`（記事スレッド）とタグ（ファセット）で表現
エントリが0件のカテゴリも残す——「学問分野の地図」として恒久的に保持

実際に嵌った落とし穴

YAMLの配列を引用符なしで書くと文字単位で分割されてゴミタグが大量生成される——必ず引用符で囲む
ディレクトリ構造を変えるとURLが変わる。サイト内リンクと`parent`参照をすべて追随させること
`git mv`でファイルを移動するとリネームとして追跡され、blameの履歴が失われない
Windowsではgit-bashのバックグラウンドフォークが不安定——ビルドはPowerShellから実行する

新しい記事を追加する手順

`<division>/<subcategory>/<slug>.md`に配置し、フロントマターを記入
`node seo/scripts/build-articles-tree.mjs`を実行し`orphans: 0`を確認
コミット＆プッシュ → GitHub Pagesが自動ビルド

→ 固定語彙はコードで管理し、構造はディレクトリパスから導出する。コミット前の合格基準は`orphans: 0`。

Applied Sciences · Engineering