Markdown to WhatsApp Converter

標準的な Markdown を WhatsApp の書式構文に変換します。ウェブページ、npm ライブラリ、コマンドラインツール、またはエージェント向け MCP サーバーとして利用できます。

➡️ ライブツールへ移動

npm i markdown-to-whatsapp · npx markdown-to-whatsapp mcp

このツールの目的

WhatsApp はテキスト書式に非標準の構文を使用します（例: *bold*, _italic_, ~strikethrough~）。これは標準的な Markdown に似ていますが、同一ではありません。

このツールは、Markdown ソース（テキストエディタ、Google Docs など）のテキストを WhatsApp が期待する形式に変換する簡単な方法を提供し、手動修正の手間を省きます。

変換処理はすべてブラウザ内で JavaScript によってローカルに実行され、パーサーはページに同梱されています。データがサーバーに送信されることは一切ありません。ページから外部へ送信されるリクエストはフォントの取得のみです。

Related MCP server: AI Group Markdown to Word MCP Server

対応する変換

このスクリプトは marked ライブラリを使用して、適切な AST ベースの解析を行います。

テキストスタイル

• 太字: **text** → *text*

• 斜体: *text* または _text_ → _text_

• 取り消し線: ~~text~~ → ~text~

• インラインコード: `code` → `code`

• 太字+斜体: ***text*** → _*text*_（両方のスタイルを維持）

見出し

見出しは、レベルごとの絵文字プレフィックス付き太字テキストに変換されます:

• # H1 → *📌 H1*

• ## H2 → *🟠 H2*

• ### H3 → *🟡 H3*

• 以下同様...

絵文字プレフィックスは UI（見出し · 絵文字）でオフにでき、その場合は単純な *Title* にになります。

リスト

• 番号なしリスト: ネストレベルには * プレフィックスと ◦ を使用します

  • レベル 1: * Item

  • レベル 2: * ◦ Item

  • レベル 3: * ◦ ◦ Item

• 番号付きリスト: 番号を維持し、ネストレベルは ◦ で示します

  • 1. A / ◦ 1. A1 / ◦ ◦ 1. A1a / 2. B

• タスクリスト: - [x] → ☑、- [ ] → ☐。番号付きリストの中でも同様です（1. ☑ done）

• ゆるいアイテム: 1つのアイテムの複数目落は単一行に結合されます

• アイテム内のブロックコンテンツ: コードブロック、引用、入れ子リストは、アイテムの下の独立した行に出力されます

バブルの幅

WhatsApp の吹き出しに1行で表示できる等幅文字数は固定されています。既定値である 360 px 電話では約 26 文字です。自分宛てにコードブロックを送信し、どこで折り返されるかを数えて、バーの Width にその値を設定してください（隣の ? にも同じことが書かれています）。このフィールドには 10 から 80 までを受け付けます。この範囲外の電話はありません。

この数値は特定のテータブルに属するものではなく、電話機自体とモノスぺース文字に関するため、あらゆる等幅要素に適用されます。テーブルはこの基準に収まるように縮小され、プレビューは各コードブロックをちょうどその幅で描画し、受信相手の WhatsApp と同じ位置で折り返しを再現します。

対応する変換

スクリプトは marked ライブラリによる適切な ATS ベースの解析を行い、以下を処理します。

※ 上記の「対応する変換」は、すでに上の節で扱ったかもしれません。まあ、この README の原文で「Supported conversions」→「対応する変換」と訳します。

テキストスタイル

• 太字: **text** → *text*

• 斜体: *text* または _text_ → _text_

• 取り消し線: ~~text~~ → ~text~

• インラインコード: `code` → `code`

• 太字+斜体: ***text*** → _*text*_（両方のスタイルを維持）

見出し

見出しはレベルごとの絵文字プレフィックスを付けた太字に変換されます:

• # 📌 H1`

• ## H2 → *🟠 H2*

• ### H3 → *🟡 H3*

• それ以外のレベルも同様...

絵文字プレフィックスは、画面右上の UI（見出し · 絵文字）でオフにでき、そのままの *Title* にできます。

リスト

• 順序なしリスト: 入れ子レベルには \* プレフィックスと ◦ を使います

  • レベル 1: * アイテム

  • レベル 2: * ◦ アイテム

  • レベル 3: * ◦ ◦ アイテム

• 順序付きリスト: 番号を保持し、入れ子レベルには ◦ を使います

  • 1. A / ◦ 1. A1 / ◦ ◦ 1. A1a / 2. B

• タスクリスト: - [x] → ☑、- [ ] → ☐。順序付きリストの内でも使えます（1. ☑ 完了）

• 非整列アイテム: 1つのアイテムの複数段落は1行に結合されます

• アイテム内のブロックコンテンツ: コードブロック、引用、入れ子リストはアイテムの下の別の行に出力されます

バブルの幅

WhatsApp のバブルは1行に収まる等幅文字数が固定です。既定（360 px の端末）では約 26 文字です。正確な値は、自分宛にコードブロックを送ってどこで折り返されるかを数え、バーの 幅 に設定してください（隣の ? にも同じことが書かれています）。このフィールドは 10 から 80 まで受け入れます。この範囲外の端末はありません。

この数値は端末固有のもので、個々のテーブルのものではありません。したがって等幅領域のすべてに影響します。テーブルはこれに収まるよう縮小され、プレビューはすべてのコードブロックをその幅とおりに描画し、受信側の WhatsApp で折り返される位置を正確に示します。

テーブル

テーブルは2つのスタイルのいずれかで表示されます。UI でドキュメント全体またはテーブルごとに選択できます。

1. Auto（既定）: 等幅ブロック内に描画される罫線テーブルで、必要な幅を取り、バブルの幅を超え大きくなりません。どうしても描画できないときは箇条書きリストになります。

   +--------+-------------+
   | Name   | Description |
   +========+=============+
   | Value  | Details     |
   +--------+-------------+

2. List: 常に箇条書きリストです。

リストのレイアウト

リストはセルを3つの方法でグループ化します。変換器はヘッダーと太字セルから推定し、その推定はテーブルごとに変更できます（Layout: Auto · Rows · Columns · Pairs）。

• Pairs — ヘッダーに関係なく、列が2つの場合。各行は key: value の1行になります。すべての行にヘッダーを繰り返すと、ほぼすべてのテーブルで Italy: Rome と比べて読みにくくなります。

  * *CPU:* Intel Xeon
  * *RAM:* 64 GB
  * *Storage:* 1 TB SSD

• Columns — 最初のヘッダーが空欄、または "Feature"・"Spec"・"Parameter" などのプロパティ名になっていて、列数が3つ以上の場合、または最初の列が太字の場合。比較する対象が列である比較マトリクステーブルとなるため、各列が1つのグループになります。

  * *Proxmox*
  * ◦ _Kernel:_ KVM
  * ◦ _License:_ AGPL v3
  * *ESXi*
  * ◦ _Kernel:_ VMkernel
  * ◦ _License:_ Proprietary

• Rows — それ以外の場合。行ごとに1つのグループになり、行の最初のセルがラベルになります。

  * *Product:* Laptop
  * ◦ _Price:_ $999
  * ◦ _Stock:_ 50
  * *Product:* Smartphone
  * ◦ _Price:_ $599
  * ◦ _Stock:_ 100

プロパティワードは 11言語（英語、イタリア語、スペイン語、フランス語、ポルトガル語、ドイツ語、ロシア語、アラビア語、ヒンディー語、ベンガル語、インドネシア語）で単語単位で照合されます（"Species" は "spec" とは見なされません）。Pairs は列数がちょうど 2列のときだけ意味を持ち、それより広いテーブルで指定された場合は Rows として扱われます。

罫線ボックスの縮小

ボックスは。

Tables

A data table is drawn in one of two styles, chosen in the UI for the whole document or one table at a time:

1. Auto (default): a drawn table inside a monospace block, as wide as it needs and never wider than the bubble; the bulleted list is used when no box can be drawn at all.

   +--------+-------------+
   | Name   | Description |
   +========+=============+
   | Value  | Details     |
   +--------+-------------+

2. List: always the bulleted list.

How the list is laid out

A list can group the cells in three ways. The converter guesses from the headers and bold cells, and the guess can be overridden per table (Layout: Auto).:

* *CPU:* Intel Xeon
* *RAM:* 64 GB
* *Storage:* 1 TB SSD

* *Proxmox*
* ◦ _Kernel:_ KVM
* ◦ _License:_ AGPL v3
* *ESXi*
* ◦ _Kernel:_ VMkernel
* ◦ _License:_ Proprietary

* *Product:* Laptop
* ◦ _Price:_ $999
* ◦ _Stock:_ 50
* *Product:* Smartphone
* ◦ _Price:_ $599
* ◦ _Stock:_ 100

How the box degrades

The box is not simply drawn at any width: it degrades until it fits, and becomes a list when even the smallest possible version doesn’t fit. There is no way to request a table wider than the available bubble.

1. Full box, removing padding column by column (right-side first, then left-side).

2. Compact borderless style, again removing padding progressively:

    Head1|Head2       |Head-N
   ------+------------+------
    A    |BBBBBBBBBBBB|C

3. Wrapped box, full borders first and then compact: each column gets at least its longest word, the remaining width is distributed proportionally, and cells are word-wrapped. Rows grow as tall as needed, with a rule always drawn between them since wrapped rows would otherwise run into each other. Cells align to the top of their row.

   +---------+--------------+
   | Feature | Notes here   |
   +=========+==============+
   | Alpha   | short note   |
   +---------+--------------+
   | Beta    | a slightly   |
   |         | longer note  |
   +---------+--------------+

4. Bulleted List, when not even the longest words fit — a long URL, five columns at 26 characters.

Whether a tall wrapped box reads better than a list is a judgment the preview lets you make: that table's small panel switches it to List. A table that cannot fit in box says so in its panel and offers the list layout instead of a style that can’t present anything.

Additional table behaviour

• Column widths are measured in display cells, so emoji and CJK text stay aligned (✅, 日本語 count as two columns) — as far as the phone allows: those glyphs still come from a fallback font, so the alignment is best effort, unlike the ASCII borders.

• Column alignment (:---, :---:, ---:) is honoured in the box and compact styles.

• Header-only tables render without an empty body or doubled border.

• <br> inside a cell becomes a space, and an escaped \| becomes ¦ so it cannot fake an extra column.

• Borders are plain ASCII (+-|=), on purpose. WhatsApp's monospace font has no box-drawing glyphs: a phone takes ─ and ┌ from whatever fallback font it has, at whatever width that font gives them, and a rule of 26 of them will wrap onto two lines while the text rows next to it do not. +-| are the only characters whose width a monospace font actually promises — which is also why the escaped pipe becomes ¦, a Latin-1 character from the same font as à.

• Row separator (default off): draws a rule between body rows in every boxed and compact style; a wrapped table draws it regardless.

• The style, the row all separator and the list layout can be set per table: hovering a table in the preview reveals controls, which start from the document default and override it for that table only, showing only the ones that still apply (the separator on a box, the layout on a list). The width is not among them — there is one real bubble for everything. A table carrying its own settings keeps a dashed mark, since the controls at the top of the panel deliberately leave it alone — its "reset" button hands it back to them. Overrides follow the table by its header text, so adding or removing a table above doesn’t move them. A table nested inside a list item or a blockquote always follows the document default.

Code blocks

Fenced and indented code blocks reach WhatsApp verbatim: the converter never re-wraps or re-indents them, because a line break inside code is content, not layout. WhatsApp wraps long lines by itself, mid-word, and a chat bubble has no horizontal scroll — so the preview reproduces that wrap at monoWidth instead of scrolling, showing exactly where the recipient will see the break.

Other elements

• Links: [text](url) → text (url); autolinks (<https://x>, [url](url), <me@x.com>) render as the bare URL or address — no duplication, no mailto: leak.

• HTML entities: decimal and hexadecimal references plus the common named ones — Latin-1 letters, punctuation and symbols (café → café, © → ©, A → A). Rarer references (Greek, mathematical) are left as written.

• Inline HTML: <b> / <strong> → *, <i> / <em> → _, <s> / <del> → ~, <code> → `, and <br> → newline; comments and other tags are stripped.

• HTML blocks: tags removed, block boundaries become newlines, entities decoded.

• Blockquotes: retains the > prefix and supports nesting (> > nested).

• Code blocks: preserved with triple backticks; a triple backtick inside the content is replaced with ˋˋˋ so it cannot close the block early.

• Horizontal rules: --- → ───────────────

• Escape characters: uses Unicode look-alikes (∗, ＿, ∼) so WhatsApp won’t interpret them as formatting.

WhatsApp-specific handling

• Partial-word formatting is ignored: super**bold**ly → superboldly (WhatsApp doesn't support mid-word formatting).

• Punctuation is a valid boundary: **Name**: value → *Name*: value, and so are (**x**) and **end**..

How to use

1. Open the web page: https://drsound.github.io/markdown-to-whatsapp/

2. Paste, type or drop a .md file into the left panel; “Try an example” fills it with a sample message.

3. The right panel shows the message in a WhatsApp bubble, exactly as the recipient will see it; “view raw syntax” shows the text that will be copied. The two panels scroll together — whichever is under the pointer leads — and while you type the preview follows the cursor.

4. “Copy for WhatsApp” or “Share on WhatsApp” opens a chat via wa.me with the message ready. A very long message doesn’t fit in a URL — browsers cut URLs after a few thousand characters — so Share steps aside and asks you to copy instead.

The interface follows the operating system’s light or dark theme, with a header toggle to override it. The options bar has one section per kind of content, each shown only while the text uses that kind: Bubble (the width, when there is a table or a code block), Tables (style and separator), and Headings (emoji prefix). A control that another setting makes pointless — the separator in List style, the width with nothing monospace to draw — is dimmed in place, not removed, so the bar keeps its shape. Options are stored in localStorage along with the theme. Per-table choices are not stored: they belong to the text being converted.

Use it from code, the shell, or an agent

The same converter is available on npm as markdown-to-whatsapp (Node 20 or newer). Its options are the same as described above, with the same names and defaults, and are listed at the end of this section.

Library

npm install markdown-to-whatsapp

import { convertTextToWhatsapp, convertToBlocks } from 'markdown-to-whatsapp';

convertTextToWhatsapp('# Hi **there**');
// → '*📌 Hi there*'

convertTextToWhatsapp(markdown, { monoWidth: 30, tableFormat: 'auto', headingEmojis: false });

// The same conversion with the blocks kept apart: each has the source `line` it starts on,
// and each table its `key`, `columns`, `fitsBox`, `asList` and `listLayout`
const { text, blocks } = convertToBlocks(markdown, { monoWidth: 30 });

Command line

npx markdown-to-whatsapp notes.md                  # a file…
cat notes.md | npx markdown-to-whatsapp            # …or stdin
npx markdown-to-whatsapp notes.md --width 32 --tables list --no-emoji
npx markdown-to-whatsapp notes.md --json           # the blocks, for scripting
npx markdown-to-whatsapp --help

--width (10–80), --tables auto|list, --layout auto|rows|columns|pairs, --separator, --no-emoji, --json; also -h, --help and -v, --version. Output goes to stdout; a invalid option says why on stderr and exits with status 2.

MCP server

The package also runs as a Model Context Protocol server over stdio, so an agent can call the conversion itself. This especially matters for tables: counting columns against a 26-character bubble is exactly a thing models get wrong and this tool gets right.

claude mcp add markdown-to-whatsapp -- npx -y markdown-to-whatsapp mcp

or, for Claude Desktop and other clients that take a JSON configuration:

{
  "mcpServers": {
    "markdown-to-whatsapp": {
      "command": "npx",
      "args": ["-y", "markdown-to-whatsapp", "mcp"]
    }
  }
}

convert_markdown_to_whatsapp という 1 つのツールを公開し、markdown に加えて任意の monoWidth、tableFormat、listLayout、rowSeparator、headingEmojis を受け取ります。テキストはツールのコンテンツとして返され、構造化された結果にはそのテキストが text として、tables とともに格納されます。tables の各エントリはテーブルごとのもので、key、columns、fitsBox、asList、listLayout を持ちます。これにより、エージェントはどのテーブルがボックスになり、どのテーブルがリストになったかを判別できます。このツールは読み取り専用で、冪等です。

オプション

オプションは tableFormat（auto | list）、monoWidth、rowSeparator、headingEmojis、listLayout（auto | rows | columns | pairs）、および tableOverrides です。tableOverrides には、ドキュメント内でのテーブルの位置をインデックスとする配列か、テーブルの key（ヘッダーテキストを | で連結した文字列。ヘッダーが繰り返される場合は #2、#3 … を付加）をキーとするオブジェクトを指定でき、各エントリはそのテーブルだけに対して他のオプションを上書きします。ページは listLayout をテーブル単位でのみ公開します。

従来の名前も入力時に受け付けられます。monoWidth には tableThreshold、tableFormat には ascii / always が使えます（ascii は吹き出しの幅を超えるボックスを描画しなかったため、auto にマッピングされます）。古い名前と新しい名前の両方が指定された場合、新しい名前が優先され、古い名前は破棄されます。Unicode ボックス描画を選択するために使われていた borderStyle は受け付けられますが、無視されます。

開発

テストの実行

Node 20 以降で、リポジトリのルートから実行します:

npm install
npm test

テストスイートはファイルベースのテストを使用します:

• tests/inputs/*.md - Markdown の入力ファイル

• tests/inputs/*.json - オプションのフィクスチャ別コンバーターオプション（例: { "monoWidth": 40 }）

• tests/expected/*.txt - 期待される WhatsApp 出力

さらに、いくつかの不変条件があります。vendor 済みパーサーがインストール済みパーサーと一致すること、convertToBlocks が正しいソース行を報告すること、パッケージのエントリがページのスクリプトであることです。

テストは、すべてのプッシュとプルリクエストで CI でも実行されます（.github/workflows/test.yml）。

プロジェクト構成

• docs/converter.js - 変換器本体: DOM に依存しない純粋な ES モジュールで、オプションはパラメータとして渡されます。これはページが import するスクリプトであると同時に npm パッケージのエントリポイント（exports["."]）でもあるため、コピーは 1 つで、ビルドステップはありません。convertTextToWhatsapp(markdown, options) と、トップレベルのブロックを分離して各ブロックにどのテーブル由来かをタグ付けした同じ変換を行う convertToBlocks(markdown, options)（このタグ付けがテーブル単位オプションの土台になる）、そして UI がオプションを適用可能な場合にだけ表示するために使う mdContainsTable / mdContainsHeading / mdContainsCode クエリを公開しています。convertToBlocks の各ブロックは、それが始まるソースコードの line を報告し、これが 2 つのパネルのスクロールを同期させています。また、各テーブルブロックは key、columns、fitsBox（ボックス化が可能）、asList（何が書き出されたか）、listLayout も報告するため、インターフェースは残された選択肢だけを正確に提示できます。

• docs/ui.js - ページの配線: テーマ、コンテキストに応じたオプション、WhatsApp プレビュー、パネル間のスクロール同期、コピーと共有

• docs/index.html、docs/style.css - マークアップと手書きのスタイルシート（CSS フレームワーク不使用）

• docs/vendor/ - marked の ES ビルド。npm run vendor によって node_modules からコピーされます。ページの import map は marked をこれに解決します

• bin/markdown-to-whatsapp.js - コマンドラインツール。bin/mcp.js - それが mcp で起動する MCP サーバー。そのときだけ読み込まれるため、ファイルの変換ではプロトコル SDK が読み込まれることはありません

• scripts/vendor.js - marked の ES ビルドを docs/vendor/ にコピーします（npm run vendor）

• tests/ - フィクスチャとランナー

marked の依存関係

marked のバージョンは package.json で 18.0.10 に固定されています。ページが docs/vendor/ から読み込むコピーがそれと一致することはテストスイートによってチェックされるため、ページ、パッケージ、テストは常に同じ方法で Markdown を解析します。バージョンを上げるには、ピンを変更し、npm install、npm run vendor、npm test を実行します。

公開

npm test
npm pack --dry-run   # docs/converter.js, bin/, README, LICENSE — nothing else
npm publish

ローカル開発

cd docs
python3 -m http.server 8080
# Open http://localhost:8080

ライセンス

MIT、LICENSE ファイルを参照してください。