memd v3: serveサブコマンドでローカルHTTPサーバー起動させるようにした

v3を出した

主な変更点は serve サブコマンドの追加。

serveサブコマンド

memd serve でローカルHTTPサーバーを起動し、ディレクトリ内の .md ファイルをブラウザでHTML表示できるようにするやつ。

$ memd serve --dir ./docs --port 3000
memd serve
  Directory: /home/ubuntu/docs
  Theme:     nord
  URL:       http://localhost:3000/

v2の --html オプションはstdoutに吐く一回きりの出力だったが、serveモードはディレクトリ単位でmdファイルを配信する常駐サーバー。ドキュメントディレクトリを丸ごとブラウザで確認したい場合に便利。

主な機能:

サイドバー – 同一ディレクトリ内の .md ファイル一覧をサイドバーに表示。
--watch ライブリロード – ファイル変更をSSEで検知してブラウザを自動リロード
Worker Thread並列レンダリング – Mermaid SVGの変換をworker_threadsで並列化。
ETag/304キャッシュ + gzip圧縮 – 変更がなければ304を返し、gzip結果もキャッシュ
静的ファイル配信 – 画像(png, jpg, gif, svg, webp, ico, avif)とCSSを配信。mdからの画像参照がそのまま表示される
ディレクトリリスティング – index.md がない場合はファイル一覧を表示

使い方

# カレントディレクトリをserve
$ memd serve

# ディレクトリ指定 + ライブリロード
$ memd serve --dir ./docs --watch

# テーマ変更
$ memd serve --theme dracula

# ワーカー数を制限（メモリ節約）
$ memd serve --workers 1

serveモードでもテーマが反映される。--theme か MEMD_THEME で指定。

セキュリティまわり

開発用なので最低限

パストラバーサル防止
隠しファイル非公開
CSP nonce
SVGは Content-Disposition: attachment + sandboxで配信

デフォルトは 127.0.0.1 バインドなので、ローカルで使う分には問題ないと思う。

v3.1.0: beautiful-mermaid のfork

いくつかバグがありやむを得ず beautiful-mermaid を forked repo に切り替えた。

mergeされたらupstreamに戻す予定

CLIオプション一覧

Usage: memd [options] [command] [files...]

Options:
  -v, --version          output the version number
  --no-pager             disable pager (less)
  --no-mouse             disable mouse scroll in pager
  --no-color             disable colored output
  --width <number>       terminal width override
  --ascii                use pure ASCII mode for diagrams (default: unicode)
  --html                 output as standalone HTML
  --theme <name>         color theme (default: "nord")
  -h, --help             display help for command

Commands:
  serve [options]        Start HTTP server to serve .md files as HTML

serveのオプション:

Options:
  -d, --dir <path>       directory to serve (default: ".")
  -p, --port <number>    port number (default: 8888)
  --host <string>        host to bind (default: "127.0.0.1")
  --workers <number>     number of render workers (default: min(cpus-1, 4))
  --watch                watch for file changes and live-reload
  --theme <name>         color theme (default: "nord")

インストール

npm install -g memd-cli

Node.js 20以上が必要。

おわり

v2でターミナル表示とHTML出力を整えて、v3でserveモードを足した。最近大量の.mdを読む必要が増えたので、地味に便利。

Worker Threadでレンダリングを並列化したので、Mermaidダイアグラムが多いディレクトリでも遅くはないかなと思う。

メモリは1ワーカーあたり80-120MBくらいは食うのでので、気になる場合は --workers 1 で。