memd v3: Markdownディレクトリをブラウザで閲覧 -- serveモード、ライブリロード、Worker Thread並列化

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 で指定してください。