https://x.com/podhmo/status/1982963813692674208

target_reader: Future me
objective: Markdownを核とした、バージョン管理機能内蔵の再編集可能なドキュメント形式の仕様策定プロセスを記録する。

再編集可能なMarkdownバンドル形式の設計思想

🤔 問題定義 - docxの代替としてのMarkdown

手順書の作成ツールとして、Wordは高機能だが環境設定が煩雑で、Markdownは手軽だが画像の同梱や非技術者への配布に課題がある。特に、編集不可なPDFとして共有すると修正依頼のサイクルが非効率になる。

この問題の解決策として、Markdownの書きやすさとdocxの自己完結性を両立させる新しいファイル形式を構想する。

初期案として、画像をBase64エンコードしてMarkdownファイルに直接埋め込む方法を検討した。

![alt text](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...)

しかし、このアプローチはテキストエディタでの可読性と編集性を著しく損なうため、即座に棄却した。docxのように、ファイル全体を展開せずとも内部のアセット一覧などのメタデータに高速にアクセスできることが重要な要件となる。

💡 基本設計 - TextBundle v2の採用

ゼロから仕様を策定するのではなく、既存の仕様であるTextBundle v2^[1]を基盤とすることにした。これにより、基本的なファイル構造についての議論を省略できる。

TextBundleの基本構造は以下の通り。

MyDocument.textbundle/
├── info.json
├── text.md
└── assets/
    └── image.png

• info.json: バンドルのメタデータを記述する。
• text.md: 文書の本体。
• assets/: 画像などの添付ファイルを格納する。

このディレクトリ構造をZIPでアーカイブしたものが.textpackファイルとなる。

💡 機能拡張 - 内部バージョン管理

TextBundleの仕様にはバージョン管理の概念がない。そこで、バンドル自体に変更履歴を内包させる機能を考案する。具体的にはinfo.jsonを拡張し、historyオブジェクトを追加する。

{
  "version": 2,
  "type": "net.daringfireball.markdown",
  "history": {
    "log": "history/commits.jsonl",
    "diff": true,
    "hash": false
  }
}

変更履歴はhistory/commits.jsonlにJSON Lines^[2]形式で追記していく。diff: trueの場合、変更差分をgit apply可能なpatchファイルとしてhistory/patches/以下に保存する。

{"author": "userA", "timestamp": "...", "message": "Initial commit"}
{"author": "userB", "timestamp": "...", "message": "Add image", "patchFile": "history/patches/1.patch"}

❌ 課題 - バイナリアセットの差分管理

テキストファイルの差分はpatchファイルで表現できるが、画像のようなバイナリファイルの変更を同様に扱うことは困難である。この問題を解決する必要がある。

✅ 解決策 - エイリアスによる間接参照

バイナリファイルの差分管理問題を回避するため、アセットを直接ファイル名で参照するのではなく、エイリアス（ユニークID）を介して間接的に参照する方式を導入する。

Markdown内での記述:

![alt text](assets/id-001)

info.jsonに対応表を追加:

{
  "version": 2,
  "type": "net.daringfireball.markdown",
  "aliases": {
    "id-001": "image.png"
  },
  "history": { ... }
}

これにより、画像の差し替えはinfo.json内のエイリアス定義を変更するだけで済む。info.jsonはテキストファイルであるため、この変更はpatchファイルとして記録可能となる。アセットの変更履歴を、テキストの変更履歴として間接的に管理できるようになった。

🤔 パフォーマンス - メタデータへの高速アクセス

.textpackはZIPアーカイブであるため、内部のinfo.jsonを読むためにアーカイブ全体を展開する必要があり、パフォーマンス上の懸念がある。docxの内部構造を参考に、この問題を解決する。

docxは、パッケージ内の関係性を定義したXMLファイル（_rels/.relsなど）を読み込むことで、全体を展開せずとも構造を把握している。

✅ 解決策 - Index-first ZIP

docxのアプローチを参考に、.textpackを作成する際のルールを定める。

• info.jsonを、非圧縮（DEFLATE Level 0）で、ZIPアーカイブの先頭に配置する。

これにより、ZIPファイルをシーケンシャルに読み進め、info.jsonの部分だけを高速に取得し、パースすることが可能になる。ファイル全体をメモリに読み込んだり、ディスクに展開したりする必要がなくなる。

💡 機能拡張 - スタイリングとレンダリング

ドキュメントの見た目を制御するため、スタイリングの仕様を追加する。

info.jsonにstyleキーとrendererキーを追加する。

{
  ...
  "style": "styles/github-theme.css",
  "renderer": "gfm"
}

• style: スタイルシートのURIを指定する。相対パスの場合はバンドル内のassets/または専用のstyles/ディレクトリを参照する。http/httpsから始まるURLも許容する。
• renderer: HTMLを生成する際のルールを指定する。gfm（GitHub Flavored Markdown）のように、デファクトスタンダードとなっている仕様を参照することで、CSSが適用されるHTMLのクラス名や構造を安定させる。

🤔 概念整理 - Wikiとの比較と本質的価値

このファイル形式と、Markdownで記述するWikiとの本質的な違いを明確にする。

• Wiki: 中央集権的なWebサービス。オンライン環境が前提。データはサーバーに属する。
• 新形式: 分散的でポータブルなファイル。オフラインでの編集が可能。データはユーザーに属する。

この形式の核心的な価値は、「自己完結したスナップショットとして扱える、オフライン編集可能な生きたドキュメント」であること。これにより、クライアントサイドでの自由な書き換えが可能になる。

❌ 未解決課題 - 衝突の解決

オフラインでの並行編集を許容するアーキテクチャであるため、変更の衝突（コンフリクト）は避けられない。あるユーザーが作成したファイルを、別のユーザーがコピーして同時に編集した場合、それらの変更をどうマージするかが大きな課題となる。

この問題を解決するには、SVNやGitが持つような衝突検知と、ユーザーに変更の解決を促すためのマージツールのような機構が必要になるだろう。