md-index コマンドリファレンス

2025年9月15日 結城浩×クロコ（Claude Code）

概要

md-indexは、Markdownファイル群を読み込んで、視覚的に見やすいHTMLインデックスページを生成するCLIツールです。複数のMarkdownファイルを一覧表示し、各ファイルへのリンク、サムネイル画像、ファイルサイズなどを含んだカード形式のインターフェースを提供します。生成されたHTMLはブラウザで閲覧でき、VS Codeへの直接リンクも含まれているため、素早くファイルを編集することが可能です。

コマンド構文

Usage: md-index [options] md-dir

オプション

• -o, --output FILE: 出力HTMLファイルのパス（デフォルト: /tmp/md-index/TIMESTAMP.html）
• --open: 生成後にブラウザで開く
• -v, --verbose: 詳細な出力を表示
• -h, --help: ヘルプを表示
• --version: バージョンを表示
• --search-filename KEYWORD: ファイル名にKEYWORDを含むもののみ対象
• --search-content KEYWORD: ファイル名または内容にKEYWORDを含むもののみ対象

入出力仕様

• 入力: md-dir/*.md のMarkdownファイル群
• 出力: output.html （HTMLファイル）
• md-dir/*.mdは絶対に変更しない（読み取り専用）
• output.htmlが既存ファイルの場合は上書き、ディレクトリの場合はエラー
• ファイル名に「（済み）」が含まれるファイルは除外

エラー処理

• md-dirが存在しない、またはディレクトリではない場合はエラー
• output.htmlがディレクトリの場合はエラー
• すべてのメッセージは "md-index: メッセージ" 形式で出力

機能詳細

1. 基本表示

• ページを更新日時順（新しい順）でリンク集として表示
• 更新日を薄いグレーのカードとして表示（通常のカードと同じグリッドに混在）

2. リンク情報

• ページ名: ファイル名から.md拡張子を除いたもの
• URL: カード全体がクリック可能なリンク（vscode://file/絶対パス - VS Codeで直接開く）

注意：VS Codeがインストールされており、vscode://プロトコルハンドラが設定されている必要があります。

3. 画像サムネイル

• Markdown内の画像（![](URL)形式）をサムネイルとして表示
• サムネイルサイズは統一
• サムネイルにマウスホバーすると画像をポップアップ表示

4. ファイル情報

• ファイルサイズバーで相対的なファイルサイズを表示（テキスト表示なし）

UI詳細

• 背景色: グレー (#808080)
• レスポンシブ3カラムレイアウト（1200px以上: 6カラム、768px-1199px: 3カラム、767px以下: 1カラム）
• カード全体がクリック可能なリンク
• ページ名は.md拡張子なしで表示
• 日付カード: 薄いグレー (#d0d0d0) で通常カードと同じグリッドに混在
• サムネイル: 高さ100px固定、縦横比保持、ホバー時に画面中央に拡大ポップアップ表示
• サムネイル画像パス: md-dirからの相対パス
• ファイルサイズバー: 最大ファイルを100%とする線形スケール、0%=青(hsl 240)、100%=赤(hsl 0)、高さ12px
• 常にHTMLファイル名を出力表示

使用例

デフォルト出力先に生成

md-index ~/md.private/md

指定ファイルに出力

md-index -o output.html ~/md.private/md

生成後ブラウザで開く

md-index --open ~/md.private/md

ファイル名でフィルタ

md-index --search-filename girl ~/md.private/md

ファイル名または内容でフィルタ

md-index --search-content AI ~/md.private/md

技術仕様

• 言語: Ruby
• 対象環境: macOS（MacBook）
• セキュリティ: 個人利用前提、内部構造はシンプルに
• HTML: 見やすく整形されたHTML出力

特徴

md-indexは、Markdownファイルの管理と閲覧を効率化するために設計されています。特にVS Codeとの連携により、ブラウザから直接ファイルを開いて編集できる点が大きな特徴です。検索機能も充実しており、ファイル名や内容での絞り込みが可能です。

関連記事

• md-index: テキストファイルを俯瞰するツール