# markdown-to-whatsapp [Health: Active] **Category:** πŸ’¬ Communication **Repository:** https://github.com/drsound/markdown-to-whatsapp **GitHub Stars:** 0 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/markdown-to-whatsapp ## Description Convert Markdown into WhatsApp formatting: tables drawn to fit the phone's monospace width. ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "markdown-to-whatsapp": { "command": "npx", "args": ["-y","markdown-to-whatsapp"] } } ``` ## Documentation & README # Markdown to WhatsApp Converter [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![tests](https://github.com/drsound/markdown-to-whatsapp/actions/workflows/test.yml/badge.svg)](https://github.com/drsound/markdown-to-whatsapp/actions/workflows/test.yml) [![npm](https://img.shields.io/npm/v/markdown-to-whatsapp.svg)](https://www.npmjs.com/package/markdown-to-whatsapp) Convert standard Markdown into WhatsApp's formatting syntax β€” as a web page, an npm library, a command line tool or an MCP server for agents. **[➑️ Go to the Live Tool](https://drsound.github.io/markdown-to-whatsapp/)** `npm i markdown-to-whatsapp` Β· `npx markdown-to-whatsapp mcp` [![Screenshot of the app](https://raw.githubusercontent.com/drsound/markdown-to-whatsapp/main/docs/assets/screenshot.png)](https://drsound.github.io/markdown-to-whatsapp/) --- ## Purpose of this tool WhatsApp uses a non-standard syntax for text formatting (e.g., `*bold*`, `_italic_`, `~strikethrough~`). This is similar, but not identical, to standard Markdown. This tool provides a simple way to convert text from Markdown sources (like text editors, Google Docs, etc.) into the format that WhatsApp expects, saving the need for manual correction. The entire conversion process runs locally in your browser using JavaScript, and the parser ships with the page. **No data is ever sent to a server** β€” the only request that leaves the page is for the font. ## Supported conversions The script uses the [marked](https://github.com/markedjs/marked) library for proper AST-based parsing and handles: ### Text styles * **Bold:** `**text**` β†’ `*text*` * **Italic:** `*text*` or `_text_` β†’ `_text_` * **Strikethrough:** `~~text~~` β†’ `~text~` * **Inline code:** `` `code` `` β†’ `` `code` `` * **Bold+Italic:** `***text***` β†’ `_*text*_` (preserves both styles) ### Headings Headings are converted to bold text with level-specific emoji prefixes: * `# H1` β†’ `*πŸ“Œ H1*` * `## H2` β†’ `*🟠 H2*` * `### H3` β†’ `*🟑 H3*` * And so on... The emoji prefix can be turned off in the UI (Headings Β· Emoji), leaving plain `*Title*`. ### Lists * **Unordered lists:** Uses `*` prefix with `β—¦` for nested levels * Level 1: `* Item` * Level 2: `* β—¦ Item` * Level 3: `* β—¦ β—¦ Item` * **Ordered lists:** Preserves numbering, with `β—¦` marking nested levels * `1. A` / `β—¦ 1. A1` / `β—¦ β—¦ 1. A1a` / `2. B` * **Task lists:** `- [x]` β†’ `β˜‘`, `- [ ]` β†’ `☐`, also inside ordered lists (`1. β˜‘ done`) * **Loose items:** multiple paragraphs of one item are joined on a single line * **Block content in items:** code blocks, blockquotes and nested lists are emitted on their own lines below the item ### Bubble width A WhatsApp bubble fits a fixed number of monospace characters on one line β€” about **26** on a 360 px phone, which is the default. Measure yours by sending yourself a code block and counting where it breaks, then set **Width** in the bar to that (the `?` next to it says the same). The field accepts 10 to 80: no phone is outside that range. The number is a property of the phone, not of any one table, so it governs everything monospace: tables degrade to stay under it, and the preview draws every code block exactly that wide, wrapping where the recipient's WhatsApp will wrap. ### Tables A table is rendered in one of **two styles**, chosen in the UI for the whole document or for 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 β€” and the bulleted list 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 the bold cells, and the guess can be overridden per table (Layout: Auto Β· Rows Β· Columns Β· Pairs): * **Pairs** β€” 2 columns, whatever the headers: each row is a `key: value` line. Spelling the headers out on every row reads worse than `Italy: Rome` in nearly every table. ``` * *CPU:* Intel Xeon * *RAM:* 64 GB * *Storage:* 1 TB SSD ``` * **Columns** β€” 3+ columns whose first header is empty or names a property ("Feature", "Spec", "Parameter"…), or whose first column is bold: a comparison matrix, where the things compared are the columns, so each column becomes a group. ``` * *Proxmox* * β—¦ _Kernel:_ KVM * β—¦ _License:_ AGPL v3 * *ESXi* * β—¦ _Kernel:_ VMkernel * β—¦ _License:_ Proprietary ``` * **Rows** β€” everything else: one group per row, labelled by its first cell. ``` * *Product:* Laptop * β—¦ _Price:_ $999 * β—¦ _Stock:_ 50 * *Product:* Smartphone * β—¦ _Price:_ $599 * β—¦ _Stock:_ 100 ``` The property words are matched word by word ("Species" does not count as "spec") in **11 languages**: English, Italian, Spanish, French, Portuguese, German, Russian, Arabic, Hindi, Bengali, and Indonesian. Pairs need exactly two columns; asked for on a wider table, it reads as Rows. **How the box degrades** The box is not drawn at any width: it degrades until it fits `monoWidth`, and becomes a list when nothing does. There is no way to ask for a table wider than the 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 shared proportionally and cells are word-wrapped. Rows grow as tall as they need β€” there is no limit β€” and a rule is always drawn between them, since two wrapped rows without one 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 the list is a judgement the preview lets you make: that table's own panel switches it to List. A table that cannot fit any box says so in its panel and offers the list layout instead of a style that could not change 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 come from a fallback font too, 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 a doubled border. * `
` 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 wraps 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 separator** and the **list layout** can be set **per table**: hovering a table in the preview reveals its own 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 bubble, and it is the same for every table. 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 does not move them. A table nested inside a list item or a blockquote always follows the document default. ### Code blocks Fenced and indented blocks reach WhatsApp verbatim: the converter never re-wraps or re-indents them, since 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, and shows exactly where the recipient will see the break. ### Other elements * **Links:** `[text](https://github.com/drsound/markdown-to-whatsapp/blob/HEAD/url)` β†’ `text (url)`; autolinks, ``, `[url](https://github.com/drsound/markdown-to-whatsapp/blob/HEAD/url)` and `` 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:** ``/`` β†’ `*`, ``/`` β†’ `_`, ``/`` β†’ `~`, `` β†’ `` ` ``, `
` β†’ newline; comments and other tags are stripped * **HTML blocks:** tags removed, block boundaries turned into newlines, entities decoded * **Blockquotes:** Preserves `>` prefix, 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/](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"** to open a chat with the message ready via `wa.me`. A very long message does not fit in a link β€” browsers cut URLs past a few thousand characters β€” so Share steps aside and says to copy instead. The interface follows the **operating system's light or dark theme**; the header toggle overrides it and that choice is remembered. The options bar has one section per kind of content, each shown only while the text contains it: **Bubble** (the width, when there is a table or a code block), **Tables** (style and separator) and **Headings** (the 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 rather than removed, so the bar keeps its shape. The 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 published on npm as **`markdown-to-whatsapp`** (Node 20 or newer). The options are the ones described above, with the same names and defaults, and are listed in full at the end of this section. ### Library ```bash npm install markdown-to-whatsapp ``` ```js 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 ```bash 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`, plus `-h, --help` and `-v, --version`. Output goes to stdout; a bad option says why on stderr and exits 2. ### MCP server The package runs as a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio, so an agent can convert text itself β€” which matters for tables: counting columns against a 26-character bubble is what a model gets wrong and this tool gets right. ```bash claude mcp add markdown-to-whatsapp -- npx -y markdown-to-whatsapp mcp ``` or, for Claude Desktop and other clients that take a JSON configuration: ```json { "mcpServers": { "markdown-to-whatsapp": { "command": "npx", "args": ["-y", "markdown-to-whatsapp", "mcp"] } } } ``` It exposes one tool, **`convert_markdown_to_whatsapp`**, taking `markdown` plus the optional `monoWidth`, `tableFormat`, `listLayout`, `rowSeparator` and `headingEmojis`. The text comes back as the tool's content, and the structured result carries it as `text` together with `tables`: one entry per table with `key`, `columns`, `fitsBox`, `asList` and `listLayout`, so the agent can tell which tables became a box and which a list. The tool is read-only and idempotent. ### Options Options are `tableFormat` (`auto` | `list`), `monoWidth`, `rowSeparator`, `headingEmojis`, `listLayout` (`auto` | `rows` | `columns` | `pairs`), and `tableOverrides` β€” either an array indexed by the table's position in the document or an object keyed by the table's `key` (its header texts joined with `|`, plus `#2`, `#3`… for repeated headers), each entry overriding any of the others for that table alone. The page exposes `listLayout` per table only. The older names are still accepted on input: `tableThreshold` for `monoWidth`, and `ascii` / `always` for `tableFormat` (`ascii` never drew a box wider than the bubble, so it maps to `auto`). When both the old and the new name are given, the new one wins and the old is dropped. `borderStyle`, which used to choose Unicode box drawing, is accepted and ignored. ## Development ### Running tests Node 20 or newer, from the repository root: ```bash npm install npm test ``` The test suite uses file-based testing: * `tests/inputs/*.md` - Markdown input files * `tests/inputs/*.json` - optional per-fixture converter options (e.g. `{ "monoWidth": 40 }`) * `tests/expected/*.txt` - Expected WhatsApp output plus a few invariants: the vendored parser matches the installed one, `convertToBlocks` reports the right source lines, the package entry is the page script. Tests also run in CI on every push and pull request (`.github/workflows/test.yml`). ### Project structure * `docs/converter.js` - the converter itself: a pure ES module, DOM-free, options passed as a parameter. It is both the script the page imports and the entry point of the npm package (`exports["."]`), so there is one copy and no build step. It exposes `convertTextToWhatsapp(markdown, options)`, `convertToBlocks(markdown, options)` β€” the same conversion with the top-level blocks kept apart and each one tagged with the table it came from, which is what per-table options are built on β€” and the `mdContainsTable` / `mdContainsHeading` / `mdContainsCode` queries the UI uses to show an option only when it applies. Each block of `convertToBlocks` reports the source `line` it starts on β€” what keeps the two panels scrolling together β€” and each table block also its `key`, `columns`, `fitsBox` (a box is possible), `asList` (what was written) and `listLayout`, so the interface can offer exactly the choices left. * `docs/ui.js` - page wiring: theme, contextual options, WhatsApp preview, scroll sync between the panels, copy and share * `docs/index.html`, `docs/style.css` - markup and hand-written stylesheet (no CSS framework) * `docs/vendor/` - the ES build of [marked](https://github.com/markedjs/marked), copied from `node_modules` by `npm run vendor`; the page's import map resolves `marked` to it * `bin/markdown-to-whatsapp.js` - the command line tool; `bin/mcp.js` - the MCP server it starts on `mcp`, loaded only then so converting a file never loads the protocol SDK * `scripts/vendor.js` - copies the marked ES build into `docs/vendor/` (`npm run vendor`) * `tests/` - the fixtures and the runner ### The marked dependency The [marked](https://github.com/markedjs/marked) version is pinned to **18.0.10** in `package.json`, and the copy the page loads from `docs/vendor/` is checked against it by the test suite, so the page, the package and the tests always parse Markdown the same way. To bump it: change the pin, `npm install`, `npm run vendor`, `npm test`. ### Publishing ```bash npm test npm pack --dry-run # docs/converter.js, bin/, README, LICENSE β€” nothing else npm publish ``` ### Local development ```bash cd docs python3 -m http.server 8080 # Open http://localhost:8080 ``` ## License MIT, see the LICENSE file.