マークダウンプレビューCLI「mdpv」を作った

#cli #typescript #markdown

何を作ったか

マークダウンファイルをブラウザでプレビューできるCLIツール「mdpv」を作りました。

https://www.npmjs.com/package/mdpv

npm install -g mdpv
mdpv file.md

これだけで、マークダウンファイルがブラウザでGitHub風にレンダリングされます。

特徴

  • Mermaid図のサポート - フローチャートやシーケンス図がそのまま表示される
  • GitHub風のスタイル - 見慣れた見た目でプレビューできる
  • ライブリロード - ファイルを保存すると自動でブラウザが更新される

demo ターミナルからmdpvでブラウザプレビューを起動する様子

ちなみに、上記のデモで使用しているsample.mdは以下のような内容になってます。 :::details sample.mdの内容

# mdpv

A CLI tool to preview Markdown files with **Mermaid diagrams** in your browser.

## Features

- GitHub-flavored Markdown
- Mermaid diagram support
- Live reload on file changes

## How it works

```mermaid
sequenceDiagram
    participant User
    participant Server
    participant Browser

    User->>Server: mdpv sample.md
    Server->>Browser: Open localhost:3000
    Browser->>Server: Request HTML
    Server-->>Browser: Render Markdown

    User->>Server: Edit & Save file
    Server->>Browser: Reload
    Browser-->>User: Updated view
```

## Flowchart Example

```mermaid
graph LR
    A[Markdown] --> B[mdpv]
    B --> C[Browser Preview]
    C --> D{Edit file?}
    D -->|Yes| B
    D -->|No| E[Done]
```

## Code Block

```typescript
import { startServer } from './server';

startServer('sample.md', 3000);
```

## Table

| Feature     | Supported |
| ----------- | --------- |
| Markdown    | Yes       |
| Mermaid     | Yes       |
| Live Reload | Yes       |

:::

なぜ作ったか

最近、専らClaude Codeを使って開発をしているのですが、仕様や設計を一緒に考えていき、最終的にマークダウンに書き出すことが多いです。

Claude Codeはマークダウンの中でマーメイド記法を使用し、ワークフローの流れを示したり、シーケンス図を書いたりしてくれますが、何故か私の環境ではVSCodeの拡張機能が上手く動作せず、マーメイドが表示されなくてフラストレーションが溜まってました。

そこで、シンプルに「さっとCLIから起動してブラウザで確認できる」というシンプルなCLIを作ってしまおうと考えました。もちろん、Claude Codeを使ってです。

どう実現したか

技術スタック

  • TypeScript - 好きなので採用しました
  • Node.js標準のHTTPサーバー - 軽量に保つため
  • WebSocket (ws) - ライブリロードの実現
  • chokidar - ファイル変更の監視
  • marked + mermaid.js - ブラウザ側でのレンダリング

仕組み

  1. CLIでMarkdownファイルを指定して起動
  2. HTTPサーバーが立ち上がり、HTMLを返す
  3. ブラウザ側でmarked.jsがMarkdownをパース、mermaid.jsが図をレンダリング
  4. WebSocketでサーバーとブラウザを接続
  5. chokidarがファイル変更を検知 → WebSocket経由で reload を送信 → ブラウザがリロード
flowchart LR
    subgraph Server
        CLI[CLI]
        Watcher[chokidar]
    end
    subgraph Browser
        Marked[marked.js]
        Mermaid[mermaid.js]
    end
    File[.md file]

    CLI -->|HTTP| Browser
    CLI <-->|WebSocket| Browser
    File -->|watch| Watcher
    Watcher -->|reload| CLI

おわりに

結局、VSCodeの拡張機能で全然良いんですが、今はAIがすごいので簡単なものなら「作ってしまう」というのも選択肢の一つだなと思いました。

CDNからjsをロードしているので、現状はインターネットに接続する必要がありますが、また時間があったらバンドルの設定を行なってオフラインでも使えるようにします。

npmにpublishしているので、よければ使ってみてください。

https://github.com/YutoKitano13/mermaid-md-preview