ハクソク

世界を動かす技術を、日本語で。

HNに表示: ドラッグ可能なカスタマイズ機能を持つコードとしてのダイアグラムツール

212日前原文(github.com)

概要

oxdraw は、 Mermaid記法 を用いた高品質なダイアグラム作成を支援するツール Rust製CLI と ReactベースWebインターフェース で構成 視覚的な調整を 宣言的コード としてソースに反映、 バージョン管理 と 再現性 を両立 Mermaid互換を維持しつつ、 Lucidchart並みのカスタマイズ性 を実現 AI生成ダイアグラム編集など 現代的ワークフロー にも対応

oxdrawの概要

  • oxdraw は 宣言的かつ再現可能な記法 で高品質なダイアグラム作成を実現
  • Mermaid記法 でチャートを記述、Webインターフェースで細部調整可能
  • 視覚的な変更は 宣言的コード としてソースへ保存、 バージョン管理 や 再現性 を確保
  • Mermaidファイルに コメントとして変更を保存、他ツールとの互換性維持
  • Rust製CLI で.mmdファイルを画像化、 ReactベースWebエディタ で編集

開発の背景とビジョン

  • Mermaid は手軽だが、 細かな調整が困難 でLucidchart等へ移行が必要になる課題
  • コード生成系ダイアグラム の利便性と ダイアグラムソフトの柔軟性 の両立を目指す
  • AIによる.mmdファイル生成 を活用し、 ユーザーが細部をカスタマイズ できるワークフロー
  • 複雑なアーキテクチャ図作成 や 大規模コードベースの可視化 を高速化
  • コミュニティからのフィードバックや機能要望 も歓迎

基本的な使い方

  • Cargoからインストール
    • cargo install oxdraw
  • ファイルからダイアグラムを画像化
    • oxdraw --input flow.mmd
  • インタラクティブエディタの起動
    • oxdraw --input flow.mmd --edit

CLIフラグ一覧

  • -i, --input <PATH>：Mermaidソースファイル指定（-でstdin対応）
  • -o, --output <PATH>：出力先指定、デフォルトは<input>.svg
  • --png：PNG形式で出力
  • --scale <FACTOR>：PNG出力時のスケール倍率（デフォルト10.0）
  • --edit：エディタを起動
  • --serve-host <ADDR>：エディタ時のバインドアドレス指定（デフォルト127.0.0.1）
  • --serve-port <PORT>：エディタ時のポート指定（デフォルト5151）
  • -b, --background-color <COLOR>：背景色指定（SVGのみ対応）
  • -q, --quiet：標準出力の情報メッセージ抑制

フロントエンド機能

  • ノードやエッジの削除 （Delete/Backspaceキー対応）
  • ノードごとの色指定 （ダブルクリックでリセット）
  • ノードスタイルのリセット
  • エッジの色・線種・矢印方向指定
  • エッジの制御点追加・削除によるルート調整
  • エッジスタイルのリセット （ダブルクリックで手動パス解除）
  • ノードのドラッグ で位置調整（グリッドスナップ・ガイドあり）
  • エッジハンドルやラベルハンドルのドラッグ でルート編集
  • サブグラフ単位での移動 （ノード・エッジをまとめて移動）
  • ソースパネル でMermaidファイルのミラーリング・自動保存・状態表示
  • ツールバーでの状態表示 （ロード・保存・編集中ファイルパス）

ダイアグラム描画アルゴリズム

  • パス描画アルゴリズム は最適解が一意でなく、好みが分かれる設計
    • 滑らかな線 派と、 明確なエッジ 派の両方に対応を模索
    • 重複線回避 と 線の長さのバランス も考慮
  • ノードの移動やエッジ削除時 に自動で再計算
  • 今後も改良予定

今後の展望とコミュニティへの呼びかけ

  • Mermaid.js のような宣言的生成と Lucidchart のような柔軟編集の両立を目指す
  • AIによる初稿生成 → ユーザーの細部調整 という新しいダイアグラム作成フロー
  • 建築図やコードベース可視化 の効率化を実現
  • フィードバック・機能要望 を歓迎、 GitHub Issue での提案も推奨

Hackerたちの意見

これはすごく期待できるプロジェクトだね！まさに探してたものだよ。もし宣言型のダイアグラムソリューションに、もっと情報やネストされたダイアグラムを表示するホバーポップアップ機能があったら最高だな。

└

ありがとう！それは面白そうだね。君のユースケースを理解するために確認なんだけど、これらのポップアップは自分用？それとも他の人のため？例えば、チームの誰かにリンクを送って、そのリンクでポップアップやネストのあるダイアグラムが表示されるのがいい？それとも、.mmdファイルを送って、相手がCLIを使ってポップアップやネストをサポートするウェブインターフェースを開ければ十分？後者はすぐに追加できそうだけど、前者はngrokとかクラウドソリューションを使ってユーザーが自分で使えるようにするか、もしくはダイアグラムをスタンドアロンのHTMLファイルとしてエクスポートする方法を考えるかも。そうすれば、送る相手がCLIをインストールしてなくてもポップアップやホバーができるよ。

プロジェクトのリリースお疲れ様！宣言型の構文で関係性を定義して、レイアウトをカスタマイズできるのは確かにニーズを満たしてるね。プロジェクトのCargo.tomlファイルにはMITライセンスって書いてあるけど、リポジトリにライセンスファイルがないから、GitHubではプロジェクトのライセンスが表示されないんだ。ライセンスファイルを追加して、コードや設定を掘り下げなくても見えるようにしてほしいな。

└

ツールの普及を図りたいなら、ホスティングして使いやすくすることを考えてみて。サーバーサイドのコードに依存してるから、安い静的ホスティングは選択肢にならないね。

└

指摘してくれてありがとう！ライセンスファイルを追加したよ。

PlantUMLがこの厄介な問題を解決してくれたらいいのに。

これは本当に必要だよね。私はほとんどのダイアグラムにPlantUMLを使ってるけど、5つ以上のコンポーネントがあると、レイアウトを調整するのに20～30%の時間を費やしてる。コメントを埋め込んで、それをレイアウトエンジンに組み込むのは面白いアプローチだね。特定のコンポーネントの座標を固定して、レイアウトエンジンにそれをハード制約として処理させることができれば、私の問題がたくさん解決すると思ってた。これはそのアプローチに似てるね。これが欲しい理由は、GUIツールを使って完全に手動で管理されたダイアグラムに移行するのは避けたいから。ソース管理と簡単に統合できないし、コードを変更するコミットが、そのコードのアーキテクチャダイアグラムも変更するようにしたいんだ。そうすれば、コードレビューの一部になって、全体のプロセスにうまく統合できるから。

└

PlantUMLを使ってるんだけど、GitLabのマークダウン、ウィキ、MDドキュメント、PRコメントでもレンダリングできるからね。でも、GitHubでホストされてるプロジェクトにはMermaidを使わなきゃいけない。pumlでレイアウトを調整する手間、例えば要素を見えない接続やグループでペアにしたり、クラスダイアグラムの矢印からダッシュを追加したり削除したりするのが面倒なんだけど、Mermaidはその点で劣ってるから楽になった。Mermaidはいつもベータ版みたいに感じるし、GitHubがpumlのサポートリクエストを無視してる理由がわからない（1）。ダイアグラムをコードとして採用するのは大手ベンダーがサポートしてるものに依存してるみたいで、彼らはあまり気にしてないのかも。もしかしたら、mermaidchartが公式のvscodeプラグインを作ったからかもしれないけど、誰が知ってるんだろう。改善が必要だとは思うけど、第三の標準を作ることが解決策だとは思えない。私が望んでるのは、要素に重みを割り当てて、レンダラーに作業を任せること（oxdrawみたいにxとyの座標を設定するのではなく）。[1] https://github.com/orgs/community/discussions/10111

こんにちは、ロハン。これは本当に素晴らしいね。もし中間データを入力と出力として公開するパラメータを含められたら、プロセスのステップで実行してデータを出力したり、事前に準備したデータでステップから実行できるようになるよ。他の人が君の成果を基にして、他のダイアグラムやレンダリングを作れるようになるんだ。

└

こんにちは、ありがとう！中間データってどういう意味かよくわからないんだけど？これは異なるコンポーネントのために計算された位置データのこと？

プライベートなMacPortsポートを作ったんだけど、もし頻繁に使うようなら、メインのMacPortsポートリポに貢献するかも。私の視点からすると、欠けてるのはGitタグやGitHubリリースがCargoリリースに関連付けられてないことかな。今は明示的なリリース（9ccd9bf53f9a309ccda42b5c17e9c1056493fb90があなたの0.1.0リリースポイントだと思ってる）を使って回避してる。npm10で十分だと思ってるし、今はMacPortsでnode22をインストールしてるよ。[1] https://github.com/halostatue/ports [2] https://github.com/macports/macports-ports [3] https://github.com/halostatue/ports/commit/e7331a7fcae362b0d...

└

ありがとう！

ありがとう！めっちゃクールだね。ボタンが見当たらないんだけど（今はモバイルで、パソコンでしっかり確認するつもり） -- ノードを追加するボタンってあるの？コードダイアグラムでずっと欲しかった機能は「下流ノードを折りたたむ」なんだけど、これってあなたの範囲外かもね（それにメルメイド？）。

└

こんにちは、今のところその機能は追加してないから、今のやり方は.mmdテキストを編集することになるよ。でも、あなたの言う通り、それはいい機能だと思う。下流ノードを折りたたむのは、他の人がこのスレッドでアニメーションのリクエストをしてたのとも関連すると思う。実装はいつかできるはずだよ！

ステロイドを使ったdotみたいな感じ？変数やクリーンな構文があって、でも似たような前提？

そういえば、mermaidjsにはレイアウトエンジンの概念があるんだよね - https://www.npmjs.com/package/@mermaid-js/layout-elk あなたのアルゴリズムをmermaidjsの（より良い）自動レイアウトエンジンとして実装することを考えたことある？

すごいプロジェクトだね！Mermaid.jsをベースにしたのは、今一番人気のある宣言型ダイアグラムライブラリだから、いい選択だと思うよ。もっと多様な宣言型ダイアグラムのアプローチがD2 Language [0] にあるから、複雑なダイアグラムタイプをサポートする時にはチェックしてみると面白いかも。