_debris

1. _debrisについて

名前について

• "_debris"と書いて"space debris(スペースデブリ)"と読む
• "space debris"はいわゆる宇宙ゴミだが、それだけを意味しない
  • "space"は"空間"を意味する
  • "debris"は地質学的な文脈における"堆積物"を意味する
• 精神/バーチャル 空間の堆積物

ロゴについて

• 宇宙ゴミっぽくもありつつ、堆積したものの地層断面が見えるように
• オレンジの部分は金ぽくもあり琥珀っぽくもある
  • 金は資産価値の高さを
  • 琥珀は自分史的価値の高さを
    • ジュラシックパークのアレ¹
• まだwipなのでじっくり見ないで🐻

制作動機

• Obsidianで執筆した文章（md）をローカルでプレビューしつつ、そのまま個人Webサイトにデプロイしたい
• Wordpressやーだ → SSR,SPAきもい → SSG良いね！ → Astro良さそう？ → けどこれも結局いずれは使えなくなりそう → じゃあもっとバニラな感じで作っちゃえば良い

基本思想

_debris is a static system for accumulating, arranging, and re-projecting textual deposits over time.

• コンテンツの唯一の正はローカルに存在する Markdown（プレーンテキスト）である
• ツールやフレームワークの寿命と、コンテンツの寿命を分離する
• Obsidianは執筆・思考のための補助ツールであり、依存対象ではない
• WebサイトはMarkdown資産の投影物であり、常に再生成可能であること
• CMS的な管理画面、データベース、常駐サーバーは持たない
• 実装は「長生き」「捨てやすさ」「可読性」を最優先する

---

2. 実行環境・実装方針

• 実装言語：JavaScript
• 実行環境：Node.js
• フレームワーク非依存
• 外部依存は原則使用しない（標準API中心）
• Node.js は実行環境としてのみ使用し、ロジックは生の JavaScript で記述する

---

3. コンテンツ仕様

• すべてのコンテンツは .md ファイルで管理する
• UTF-8 プレーンテキスト
• Obsidianでそのまま編集・閲覧可能であること

Frontmatter（YAML）

---
title: 異邦性について
slug: alterity
created: 2023-05-12
updated: 2024-11-03
tags: maniac
published: true
permalink: /maniac/alterity/
thumbnail: ./images/alterity.jpg
description: 記事の概要文（任意）
og_description: OGP用の説明文（任意）
toc: true
template: 404
---

フィールド一覧（必須 / 任意）

• title（必須）: 記事/固定ページのタイトル
• slug（必須・記事）: URL生成に使用するスラッグ（a-z0-9-）
• created（必須・記事）: 初稿日（YYYY-MM-DD）
• updated（任意）: 更新日（YYYY-MM-DD、人手で更新）
• tags（必須・記事）: タグ配列または1件指定。カテゴリ抽出に使用
• published（必須・記事）: true のみ公開対象
• permalink（任意）: 既存URL維持のための固定URL（最優先）
• thumbnail（任意）: 一覧用サムネイル。OG画像にも利用
• description（任意）: 記事概要。OG説明の自動補完に使用
• og_description（任意）: OGP用説明（最優先）
• toc（任意）: true の場合のみTOCを生成
• template（任意・固定ページ）: 404 を指定した場合は404ページとして生成

ルール

• slug はURL生成に使用する（記事）
• created は初稿日、updated は追記・修正があった場合のみ人間が更新する
• 自動更新は行わない
• tags からカテゴリを1つだけ抽出する（publish.categories に一致）
• permalink がある場合は最優先で使用する
• thumbnail が指定されている場合、OGの og:image にも利用する
• thumbnail が未指定の場合、本文の最初の画像を og:image に使用する
• frontmatter は意味の宣言のみを行い、ロジックは含めない

---

4. URL設計

基本構造

• URL構造：/{category}/{slug}/
• URLは人間が直接手打ちしない
• ジェネレータが動的に生成する
• 既存URL維持のため permalink がある場合は最優先で使用する

tags による category 指定

• tags から公開カテゴリを1つだけ抽出する
• 抽出対象は config.yaml の publish.categories のみ
• 一致が複数ある場合は publish.categories の先頭優先
• 一致が0の場合はビルドエラー

URL生成例

maniac + alterity
→ /maniac/alterity/

---

5. 内部データモデル

• Markdownからビルド時に内部JavaScriptオブジェクトを生成する
• この内部オブジェクトが唯一の判断材料となる

例：

{
  title: "異邦性について",
  slug: "alterity",
  url: "/maniac/alterity/",
  created: "2023-05-12",
  updated: "2024-11-03",
  category: "maniac",
  tags: "maniac"
}

• TSVやJSONは派生物であり、内部ロジックでは使用しない

---

6. トップページ / 一覧仕様

• 記事一覧はビルド時に静的HTMLとして生成する
• 一覧は「読む場所」ではなく「選ぶ場所」と位置づける
• トップはデータビューアとして再設計する
  • 表現はCUI/レシート的な一覧
  • カテゴリ/年/月フィルタ、検索、ソートを提供する
  • 状態はURLパラメータに反映する
    • ?q=...&cat=...&year=...&month=...&sort=...&dir=...
  • 画面内の表示は段階的に追加する（無限スクロール）
• /{category}/ は /?cat=... にリダイレクトする
• サイト全体のページングは行わない

---

7. next / prev ナビゲーション

• ビルド時に記事配列を1回ソートする
• 隣接関係のみを参照して next / prev を付与する
• 各記事は以下を持つことができる：

post.prev
post.next

• カテゴリを跨ぐかどうかは後から切り替え可能な設計とする

---

8. テンプレート仕様

基本方針

• テンプレートはHTMLベース
• コメントは人間のためのコメントとしてのみ使用する
• 命令やロジックをコメントに書かない

独自属性（ビルド時専用）

• d-for
• d-if

例：

<ul>
  <li d-for="post in posts">
    <a href="{{ post.url }}">{{ post.title }}</a>
    <time>{{ post.created }}</time>
  </li>
</ul>

テンプレート展開ルール

• d-for は配列に対する単純なループのみ許可
• d-if は真偽値チェックのみ許可
• 展開後、d-* 属性は出力HTMLから除去する

---

9. 変数展開（{{ }}）

• {{ variable }} は単純なパス参照のみ許可
• 許可例：

• {{ post.title }}
• {{ post.url }}
• {{ site.title }}

• 式評価・関数呼び出しは禁止する

---

10. 検索用インデックス（TSV）

• TSVはクライアントサイド検索用の派生データとして生成する
• ビルド内部ロジックでは使用しない
• 人間可読性を優先する
• 検索UIはトップページに統合する（/search/ は廃止）

---

11. 画像の扱い

• 画像は原本をMarkdown資産として保持する
• ビルド時に派生画像を生成できる余地を残す
• 初期段階では画像最適化は必須としない
• 原本を上書きしないことを絶対ルールとする
• 記事本文の画像には loading / decoding を付与する
  • 先頭画像: loading="eager"
  • 2枚目以降: loading="lazy"
  • 共通: decoding="async"

---

12. ビルド処理

基本フロー

1. Markdown読み込み
2. 内部オブジェクト生成
3. 並び替え・フィルタリング
4. next / prev 付与
5. テンプレート展開
6. HTML出力
7. 派生データ（TSV等）生成

• 全体計算量は O(N) を前提とする

---

13. 差分ビルド

• 差分ビルドは将来の最適化として想定する
• 初期実装では常にフルビルドを行う
• 正しさはフルビルドで担保する
• 差分ビルドは壊れても破棄できる設計とする

---

14. コマンド設計

• npm scripts は必須としない
• 独自コマンドを採用する

例：

./_debris build
./_debris serve

---

15. 非目標

• 管理画面の実装
• データベース利用
• フレームワーク依存
• 実行時JavaScriptによる動的生成
• 過剰な最適化

---

16. 本プロジェクトの位置づけ

• 本プロジェクトはCMSの代替実装ではない
• Markdownによる思考・執筆資産の主権を取り戻すための装置である
• 再構築可能性・可読性・長期運用を最優先する

1. 今の技術で本物の「ジュラシック・パーク」を作ることは可能…ただし大昔の恐竜の再生は不可能 \| ワーナーブラザース・ディスカバリー・ジャパン ↩