npx markshelf で、Gitリポジトリ内のMarkdownを独立ウィンドウで構造化ビューで読めるツールを作りました。
なぜ作ったのか
AI駆動開発が浸透して、仕様・要求・ドメイン知識・設計メモなど、あらゆる情報をMarkdownファイルで管理するようになりました。
Markdownは構造化されていてAIにも人間にも読みやすい優れた記法ですが、管理するファイル数が増えてくると、人間が"読む"目的で参照するときに不便を感じるようになってきました。
具体的には次の5つです。
1. プレビューを大きく見るのが面倒
大きい画面で読みたいので、VSCodeでプレビューウィンドウを独立させて全画面表示させる、という手順を毎回踏んでいた。
2. ドキュメント間の依存関係が見えない
フォルダ階層でしか関係を表現できず、親子関係は表現できても 依存関係 が見えない。要求・仕様の管理がしづらい。
3. ドキュメント内リンクが書きづらい / 読みづらい
他のドキュメントへリンクを張るには相対パスを書くしかなく、相対パスだらけになる。読む側もクリックするまでリンク先の内容が分からない。
4. ドメイン用語がオンボーディングの障害
各ドキュメントに書かれたドメイン用語がオンボーディングの壁になる。用語定義に辿り着くまでの導線が弱い。
5. 技術者以外に共有しずらい
Markdownファイルって技術者だと当たり前にプレビューを使ってみるのですが、非技術者が原文のまま読んでしまうと、テーブルやリンクのせいで反って読みづらい。
markshelfで何が変わるか
上の5つの不満にそれぞれ機能が対応しています。
独立した全画面ビューア
npx markshelf
対象リポジトリのルートで叩けば、ブラウザで独立した閲覧用ビューアが立ち上がります。VSCodeのプレビューを毎回独立化する手間から解放されます。
リンクグラフで依存関係を俯瞰
ドキュメント間のMarkdownリンクを グラフで可視化 します。参照元が上、参照先が下に並ぶので、「このドキュメントは何に依存していて、誰から参照されているか」が一目でわかります。
表示階層は1〜全階層まで切り替え可能で、選択状態はブラウザに保存されます。
リンクホバーでプレビュー
ドキュメント内のリンクをホバーすると、リンク先のMarkdownをポップアップでプレビュー します。クリックして移動するまでもなく、その場で内容を確認できます。相対パスの見づらさがかなり緩和されます。
オンボーディング導線
用語定義ドキュメントへリンクを張っておけば、プレビューポップアップでその場で意味を確認できます。リンクグラフで「この用語がどのドキュメント群で使われているか」も追えるので、新メンバーが全体像を掴む助けになります。
ちなみにプレビュー中のMarkdown内にMarkShelf内で管理しているファイル名と同一の単語に対しては自動でリンクを張る仕様になっています。
Gitタイムラインで変更履歴
Gitと連携しているので、各ドキュメントがいつ・どう変わってきたかをタイムラインで確認できます。AIに書かせた仕様の変遷を追うときにも便利です。
URL共有が可能
セルフホストなどのアクセス可能なサーバーにデプロイしていることが前提ですが、
非技術者に対してもMarkShelf上の共有したいファイルのURLを張るだけで共有できます。
使い方
Git管理されたMarkdownのあるリポジトリで
npx markshelf
これだけです。インストール不要、設定ファイル不要。読みたくなったら起動、閉じたら終わり、というライトな設計にしました。
チームで配信する: Docker + リバースプロキシ
個人のローカル閲覧だけでなく、社内ポータルやプロジェクト共通のドキュメントサーバーとして常駐させたいケースに向けて、Docker イメージも配布しています。
docker run --rm -p 3000:3000 \
-v "$PWD/docs:/docs" \
ghcr.io/skspwork/markshelf-base:latest
ここで一つ注意点があって、リバースプロキシで /wiki のような サブパスにマウントして配信したい場合、Next.js の basePath をビルド時に確定させる必要がある という制約があります。next start 後から差し替えることはできません。
そのために markshelf の Docker イメージは コンテナ起動時に BASE_PATH を見て、必要なときだけコンテナ内で再ビルドする ように作ってあります。
docker run -e BASE_PATH=/wiki -p 3000:3000 \
-v "$PWD/docs:/docs" \
ghcr.io/skspwork/markshelf-base:latest
実運用例として、私のプロジェクトでは push 時の CI/CD でセルフホストのサーバーにドキュメントフォルダをデプロイし、その上で markshelf の Docker コンテナを起動する 構成にしています。push するだけで社内向けドキュメントポータルが最新化される、という運用です。
こんな使い方も
ナレッジ管理ツールとしての移行
今のプロジェクトでは、これまで Confluence で管理していた ナレッジ系の資料も markshelf に移行してみました。
markshelf には 編集機能がない のですが、それでも書くより読む頻度が高い情報ので Confluence より markshelf に置いた方が結果的に快適と思います。
編集 GUI はもう要らないかもしれない
これは個人的な見解ですが、Markdown はこれから AI に書かせるのがメインになっていくはずです。Cursor や Claude Code に骨子を伝えれば構造化された Markdown を返してくれる時代に、人間が GUI で Markdown を編集する重要性は下がっていく気がしています。
そう考えると Markdown ツールは「読む方に振り切る」のが筋が良いのでは、というのが markshelf を使い込みながらできてきた仮説です。
CLAUDE.md と組み合わせたトレーサビリティ
機能はあえて汎用的なところに留めているので、使う側の運用次第で色々な使い方ができるツールになっていると思います。
私自身の使い方の一例として：
- CLAUDE.md にドキュメント間の依存関係を張ることをルール化している
- 仕様書から要件書、要件書から要求書へリンクが自動的に伸びる
- リンクグラフで 要求 → 要件 → 仕様 のトレーサビリティが可視化される
これは markshelf に「トレーサビリティ機能」を実装したわけではなく、リンクグラフという素朴な機能と CLAUDE.md のルール化を組み合わせた結果として実現できているものです。こうした「使い方の発見」がしやすいのが、汎用ツールに振った効能かなと感じています。
今後
個人の課題から作ったツールですが、同じ不満を持っている方には刺さる気がしています。
使ってみて「こういう機能が欲しい」「ここが使いづらい」などあれば、GitHubのIssueで気軽に教えてください。
- GitHub: https://github.com/skspwork/markshelf
- バグ報告・要望歓迎です