mdlens 0.1.0

A lightweight read-only Markdown reader with a SQLite search index.

MdLens

軽量な読み取り専用 Markdown リーダーです。

• uv と Python 3.12 で実行します。
• .md ファイルを SQLite index に登録します。
• SQL 操作は SQLAlchemy、API は FastAPI、入出力データは Pydantic で扱います。
• index がない状態でアプリを起動すると、自動で index を作成します。
• ブラウザ上で左に階層ファイル一覧、右にレンダリング済み Markdown を表示します。
• SQLite FTS を使って文字列検索できます。
• 画面上で対象フォルダを切り替えられます。
• 画面上の Sync から index を再作成できます。
• ファイルツリーは Expand / Collapse でまとめて開閉できます。

使い方

uv run mdlens index C:\path\to\markdown-folder
uv run mdlens app C:\path\to\markdown-folder

現在のフォルダを対象にする場合:

uv run mdlens index
uv run mdlens app

index ファイルは既定で対象フォルダ直下の .mdlens_index.sqlite3 に作られます。

GitHub/GitLab リポジトリ

画面上部の入力欄には、ローカルフォルダパスの代わりに GitHub/GitLab のリポジトリURLも入力できます。

https://github.com/owner/repository
github.com/owner/repository
https://gitlab.com/group/subgroup/repository

Go を押すと、対象リポジトリをOSの一時フォルダへ shallow clone し、その clone 先をMarkdownの読み取り対象にします。別のフォルダやリポジトリへ切り替えた場合、直前に使っていた一時 clone フォルダは削除されます。

この機能はローカルの git コマンドを使用するため、Git for Windows が必要です。

構成

src/mdlens/
  cli.py         # CLI、アプリ起動
  config.py      # 設定値、アプリ設定モデル
  db.py          # SQLAlchemy engine、schema、FTS 操作
  indexer.py     # Markdown 走査、index 更新
  markdown.py    # Markdown 読み込み、HTML レンダリング
  models.py      # SQLAlchemy ORM モデル
  repo_clone.py  # GitHub/GitLab clone 用一時作業領域
  repository.py  # 一覧取得、検索
  schemas.py     # Pydantic API モデル
  web.py         # FastAPI app / API
  ui.py          # ブラウザ UI

詳しい設計は docs/architecture.md を参照してください。

コマンド

uv run mdlens index [folder]
uv run mdlens app [folder]

主なオプション:

• --index PATH: index ファイルの保存先を指定します。
• --refresh: アプリ起動時に index を更新します。
• --host HOST: 待ち受け host を指定します。既定は 127.0.0.1 です。
• --port PORT: 待ち受け port を指定します。既定は 8765 です。
• --no-browser: 起動時にブラウザを開きません。

テスト

uv run --python 3.12 --group dev pytest

coverage は pyproject.toml で 90% 以上を要求しています。テスト方針は docs/testing.md にまとめています。

ドキュメント

• docs/architecture.md: アプリ構成、index 更新、API、UI の責務

• docs/testing.md: pytest 実行方法、Given/When/Then 方針、coverage 対象

• docs/publishing.md: PyPI / TestPyPI publishing guide