Markdown Viewer

2ペイン構成のMarkdownプレビューアプリケーション。左ペインにフォルダツリー、右ペインに選択ファイルのプレビューを表示します。

目的

• ローカルのMarkdownファイル（最大500ファイル）を効率的に閲覧
• frontmatterメタデータの可視化
• リアルタイム検索とファイル監視
• PRサマリーやドキュメントの一覧管理に最適

画面イメージ

• Claude CodeでダミーのMarkdownファイルを作成し表示

主な機能

✅ 2ペインレイアウト

• 左: フォルダツリー（折りたたみ可能）
• 右: Markdownプレビュー + メタデータ表示

✅ 検索フィルタ

• ファイル名/パス/本文で検索
• リアルタイム絞り込み

✅ 自動監視

• ファイル変更を2秒間隔で検知
• 選択状態を維持して自動更新

✅ メタデータ表示

• frontmatterから title, repo, PR番号, author, date, labels を抽出
• 外部PRへのリンクボタン

✅ エラーハンドリング

• 大容量ファイル（10MB超）の警告
• 文字エンコーディング自動判定（UTF-8 → Shift-JIS → fallback）
• 権限エラーの詳細表示

セットアップ

必要な環境

• Python 3.13+
• macOS / Linux / Windows

インストール（コピペで実行）

# リポジトリに移動
cd /Users/taka110/Desktop/hc2025_md_viewer

# 仮想環境を作成
python3.13 -m venv .venv

# 仮想環境を有効化
source .venv/bin/activate

# 依存パッケージをインストール
pip install -r requirements.txt

起動方法

方法1: 起動スクリプト（推奨）

./start.sh

ダブルクリックでも起動可能です。

方法2: 手動起動

# 仮想環境を有効化
source .venv/bin/activate

# アプリケーション起動
streamlit run app.py

ブラウザが自動で開き、http://localhost:8501 でアクセスできます。

データの配置

ディレクトリ構造

hc2025_md_viewer/
├── data/                    # Markdownファイルを配置
│   ├── 2025-10/
│   │   ├── pr-summary-2025-10-01.md
│   │   └── pr-summary-2025-10-02.md
│   └── docs/
│       └── setup.md
├── app.py
├── start.sh
└── requirements.txt

ファイル命名規約

推奨形式: YYYY-MM-DD_repo_pr123_title.md

例:

• 2025-10-01_backend_pr456_add-auth.md
• 2025-10-05_frontend_pr789_fix-layout.md

frontmatter仕様

各Markdownファイルの先頭に以下の形式で記述:

---
title: Pull Request Summary
repo: my-org/my-repo
pr: 123
author: taka110
date: 2025-10-01
url: https://github.com/my-org/my-repo/pull/123
labels: [bug, enhancement]
---

# 本文

ここにMarkdownコンテンツを記述...

frontmatterフィールド

フィールド	型	必須	説明	例
title	string	○	タイトル	"Add authentication"
repo	string	-	リポジトリ名	"my-org/backend"
pr	integer	-	PR番号	123
author	string	-	作成者	"taka110"
date	string	-	日付 (YYYY-MM-DD)	"2025-10-01"
url	string	-	外部リンク	"https://github.com/..."
labels	array	-	ラベル	["bug", "p1"]

フォールバック:

• frontmatterがない場合は本文のみ表示
• フィールドが欠けている場合は該当項目を非表示

サンプルファイルの作成

mkdir -p data/2025-10

cat > data/2025-10/sample.md << 'EOF'
---
title: サンプルPRサマリー
repo: example/repo
pr: 1
author: user
date: 2025-10-01
url: https://github.com/example/repo/pull/1
labels: [feature, backend]
---

# 概要

これはサンプルのPRサマリーです。

## 変更内容

- 機能Aを追加
- バグBを修正

## テスト

- ユニットテスト追加
- 手動テスト完了
EOF

除外パターン

以下のディレクトリ/ファイルは自動でスキャン対象外:

.git, .svn, .hg
node_modules, bower_components
__pycache__, .venv, venv, env
.pytest_cache, .mypy_cache, .tox, .eggs
dist, build, target, out
.vscode, .idea, .fleet
.cache, tmp, temp
.DS_Store, Thumbs.db

使い方

1. 起動: ./start.sh を実行
2. フォルダ選択: 左ペインのフォルダをクリックして展開
3. ファイル選択: ファイル名をクリックして右ペインにプレビュー表示
4. 検索: 上部の検索ボックスにキーワードを入力
5. 監視: 「自動監視」トグルをONにするとファイル変更を自動検知

ショートカット

• 検索クリア: 検索ボックス右の「✕」ボタン
• 更新: 右上の「🔄 Refresh」ボタン
• PRリンク: メタデータ下の「🔗 Pull Requestを開く」ボタン

既知の制限

ファイルサイズ

• 10MB以上のファイルはプレビュー不可
  • 警告メッセージが表示されます
  • エディタで直接開くことを推奨

文字エンコーディング

• UTF-8を推奨
• Shift-JISは自動変換を試行
• その他のエンコーディングは文字化けする可能性あり

UI制約

• ファイル選択にボタンを使用（Streamlitの制約）
• キーボード操作は未対応

トラブルシューティング

アプリが起動しない

# 依存パッケージを再インストール
source .venv/bin/activate
pip install --upgrade -r requirements.txt

dataディレクトリが見つからない

# dataディレクトリを作成
mkdir -p data
echo "# Test" > data/test.md

# アプリ内で「🔄 Refresh」ボタンをクリック

ポート8501が使用中

# 既存のプロセスを終了
lsof -ti:8501 | xargs kill -9

# または別のポートで起動
streamlit run app.py --server.port 8502

文字化けが発生する

• ファイルをUTF-8で保存し直す
• または以下のコマンドで変換:

iconv -f SHIFT-JIS -t UTF-8 input.md > output.md

技術スタック

• フレームワーク: Streamlit 1.39.0
• 言語: Python 3.13+
• 主要ライブラリ:
  • streamlit-autorefresh: ファイル監視
  • os, re: ファイル操作・正規表現

ディレクトリ構成

hc2025_md_viewer/
├── app.py                   # メインアプリケーション
├── start.sh                 # 起動スクリプト
├── requirements.txt         # 依存パッケージ
├── utils/
│   ├── __init__.py
│   └── file_scanner.py     # ファイルスキャナー
├── data/                   # Markdownファイル配置先
└── .venv/                  # 仮想環境

ライセンス

このプロジェクトは個人利用・学習目的で作成されています。

作成者

Claude Code で生成されました。