Markdown to WhatsApp Converter

Markdown을 WhatsApp의 서식 구문으로 변환합니다. 웹 페이지, npm 라이브러리, 명령줄 도구, 또는 에이전트용 MCP 서버로 사용할 수 있습니다.

➡️ 라이브 도구로 이동

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

이 도구의 목적

WhatsApp은 텍스트 서식에 비표준 구문을 사용합니다(예: *bold*, _italic_, ~strikethrough~). 이는 표준 Markdown과 비슷하지만 동일하지는 않습니다.

이 도구는 텍스트 편집기, 구글 문서 등 Markdown 소스의 텍스트를 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)

• 느슨한 항목: 한 항목의 여러 문단은 한 줄로 합쳐짐

• 항목 안의 블록 콘텐츠: 코드 블록, 인용문, 중첩 목록은 항목 아래에 각자 줄을 만들어 표시

말풍선 너비

WhatsApp 말풍선은 한 줄에 고정된 수의 고정폭 문자를 담을 수 있습니다. 기본값인 360px 폰에서는 약 26자입니다. 자신에게 코드 블록을 보내어 어디서 끊기는지 센 후, 막대의 Width에 그 값을 설정하세요(옆의 ?에도 같은 설명이 있습니다). 입력 범위는 10~80이며, 이 범위 밖의 폰은 없습니다.

이 숫자는 표가 아니라 폰의 속성이므로 모든 고정폭 콘텐츠에 적용됩니다. 표는 이 값을 넘지 않도록 단계적으로 줄어들고, 미리보기는 모든 코드 블록을 정확히 그 너비로 그려서 제거자의 WhatsApp에서 줄바꿈이 일어날 지점에 끊어 표시합니다.

표

표는 두 가지 스타일 중 하나로 렌더링되며, 문서 전체 또는 표 하나를 대상으로 UI에서 선택할 수 있습니다.

1. 자동 (기본): 고정폭 블록 안에 그려진 표. 필요한 만큼 넓어지며 말풍선보다는 넓지 않습니다. 어떠한 표 상자도 그릴 수 없는 경우에는 글머리표 목록으로 표시됩니다.

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

2. 목록: 항상 글머리표 목록으로 표시됩니다.

목록의 배치 방식

목록은 셀을 세 가지 방법으로 묶을 수 있습니다. 변환기는 헤더와 굵은 셀을 보고 추정하며, 표마다 추정 결과를 덮어쓸 수 있습니다(배치: 자동 · 행 · 열 · 쌍).

• 쌍 — 헤더와 관계없이 2열인 경우: 각 행은 key: value 형식이 됩니다. 모든 행에 헤더를 길게 나열하는 것은 거의 모든 표에서 Italy: Rome보다 읽기 나쁩니다.

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

• 열 — 첫 번째 헤더가 비어 있거나 속성 이름("Feature", "Spec", "Parameter"…)인 3개 이상의 열, 또는 첫 번째 열이 굵은 경우: 비교 대상이 열들인 비교 매트릭스이므로, 각 열이 하나의 그룹이 됩니다.

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

• 행 — 그 외의 모든 경우: 각 행이 그룹이 되고 첫 번째 셀이 그룹의 이름이 됩니다.

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

속성 단어는 단어 단위로 일치하며("Species"는 "spec"로 치지 않음), 11개 언어로 지원됩니다: 영어, 이탈리아어, 스페인어, 프랑스어, 포르투갈어, 독일어, 러시아어, 아랍어, 힌디어, 벵골어, 인도네시아어. 쌍 배치에는 정확히 두 개의 열이 필요하며, 더 넓은 표에 적용하면 행 배치로 처리됩니다.

상자 형태가 줄어드는 방식

상자는 어떤 너비에서도 그대로 그려지지는 않습니다. monoWidth에 들어맞을 때까지 모양을 줄여 가고, 어떤 것으로도 맞지 않으면 목록이 됩니다. 말풍선보다 넓은 표를 요청할 수는 없습니다.

1. 콤팩트한 전체 상자: 오른쪽, 그다음 왼쪽으로 열 단위로 패딩을 제거합니다.

2. 콤팩트 무테두리 스타일, 역시 패딩을 점차 제거합니다:

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

3. 줄바꿈 상자, 먼저 전체 테두리, 그다음 콤팩트: 각 열은 최소한 가장 긴 단어만큼을 차지하고, 나머지 너비는 비례적으로 나누어지며 셀은 단어 단위로 줄바꿈됩니다. 행은 필요한 만큼 높이가 커지며 — 제한은 없습니다 —, 줄바꿈된 두 행이 구분선 없이는 서로 붙어 보이므로 행 사이에는 항상 구분선이 그려집니다. 셀은 행의 위쪽에 정렬됩니다.

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

4. 글머리표 목록: 가장 긴 단어조차 맞지 않을 때(긴 URL, 26자에서 5개 열 등).

상자 줄바꿈으로 높아진 것이 목록보다 나은지 여부는 미리보기에서 직접 판단할 수 있습니다. 해당 표의 패널에서 목록으로 전환하면 됩니다. 어떤 상자도 맞출 수 없는 표는 패널에 그 사실을 표시하고, 아무 영향도 주지 못하는 스타일 대신 목록 배치를 제안합니다.

표의 추가 동작

• 열 너비는 표시 셀 단위로 측정되므로 이모지와 한중일 텍스트도 정렬됩니다(✅, 日本語는 2열로 계산). 단, 폰이 허락하는 한도까지이며 해당 글리프는 폴백 폰트 소스이므로 ASCII 테두리와 달리 정렬은 최선의 노력입니다.

• 열 정렬(:---, :---:, ---:)은 상자 및 콤팩트 스타일에서 존중됩니다.

• 헤더만 있는 표는 빈 본문이나 이중 테두리 없이 렌더링됩니다.

• 셀 안의 <br>은 공백이 되고, 이스케이프된 \|는 ¦로 변환되어 가짜 열을 만들 수 없습니다.

• 테두리는 의도적으로 순수 ASCII(+-|=)입니다. WhatsApp의 고정폭 폰트에는 박스 그리기 글리프가 없습니다. 폰은 ─와 ┌를 자체 폴백 폰트에서 가져오고, 그 폰트가 주는 특정 폭을 그대로 사용하므로, 26개의 ─는 옆의 텍스트 행은 그대로인데 두 줄로 줄바꿈됩니다. +-|만이 고정폭 폰트가 실제로 폭을 보장하는 문자입니다. 그 덕분에 이스케이프된 파이프도 à와 같은 폰트의 Latin-1 문자인 ¦로 바뀌는 것입입니다.

• 행 구분셀 (기본 꺼짐)은 상자와 콤팩트 스타일에서 몸체 행 사이에 규칙을 그리며, 줄바꿈된 표는 항상 그리게 됩니다.

• 스타일, 행 기준 구분선, 목록 배치는 표별로 설정할 수 있습니다: 미리보기에서 표에마우스를 올리먼 그 표만의 컨트롤이 나타나며, 문서 기본값을 데려와 그 표에만 적용합니다. 여전히 의미가 있는 컨트롤만 표시됩니다(상자에는 구분선, 목록에는 배치). 그중에 너비는 없습니다 — 말풍선은 하나이고 모든 표가 같은 폭이기 때문입니다. 고유 설정이 있는 표는 점선 표시를 유지하는데, 상단의 컨트롤이 의도적으로 그 표를 건드리지 않기 때문입니다. 그 표의 "초기화" 버튼은 대신 상단 컨트롤로 돌려줍니다. 덮어쓰기는 표의 헤더 텍스트를 따라가므로, 그 위에 표를 추가하거나 제거해도 덮어쓰기가 이동하지 않습니다. 목록 항목이나 인용구 안에 있는 표는 항상 문서 기본값을 따릅니다.

코드 블록

펜스처리한 코드 블록과 들여쓴 코드 블록은 그대로 WhatsApp에 도달합니다. 줄바꿈이 코드 안에서는 콘텐츠이지 배치가 아니므로 변환기는 줄바꿈 포장이나 들여쓰기를 결코 다시 하지 않습니다. WhatsApp은 긴 줄을 단어 중간에서 줄바꿈하고, 채팅 말풍선은 세로 스크롤이 없습니다. 따라서 미리보기는 monoWidth에서 그 줄바꿈을 재현하며 스크롤하는 대신 받는 사람에게 보일 줄바꿈 위치를 정확히 보여줍니다.

기타 요소

• 링크: [text](url) → (url); autolink, <https://x>, [url](url) 및 <me@x.com>은 중복이나 mailto: 노출 없이 URL/주소만 표시됩니다.

• HTML 엔티티: 10진수, 16진수 및 흔한 이름 엔티티 — Latin-1 문자, 구두점, 기호(´café → café, © — ©, A — A). 그보다 드문 참조(그리스어, 수학 기호)는 그대로 두며 리뷰합니다.

• 인라인 HTML: <b>/<strong> — *, <i>/<em> → _, <s>/<del> → ~, <code> → `, <br> → 줄바꿈, 주석과 그 외 태그는 제거됩니다.

• HTML 블록: 태그가 제거되고 블록 경계는 줄바으로 바고, 엔티티도 디컫딩됩니다.

• 인용문: > 접두사를 유지하며 중첩(> > nested)을 지원합니다.

• 코드 블록: 세 개의 백틱으로 그대로 보존되며, 내용 안의 백틱은 ˋˋˋ로 바뀌어 미리 닫히지 않습니다.

• 수평선: --- → ──────────────?? (원문의 정확한 문자).

• 탈출 문자: 유니코드 유사 문자(∗, ＿, ∼)를 이용해 WhatsApp이 서식으로 오해하지 못하게 합니다.

WhatsApp 관련 처리

• 부분 단어 서식은 무시됩니다: super**bold**ly → superboldly(WhatsApp은 단어 중간 서식을 지원하지 않습니다.)

• 구두점은 경계로 허용됩니다: **Name**: value → *Name*: value, (**x**) 및 **end**.에서도 동일합니다.

사용 방법

1. 웹 페이지를 엽니다: https://drsound.github.io/markdown-to-whatsapp/

2. .md 파일을 왼쪽 패널에 붙여넣거나, 입력하거나, 드래그 앤 드롭하세요. "예제 사용해 보기"를 누르면 샘플 메시지로 채워집니다.

3. 오른쪽 패널은 메시지를 실제 WhatsApp 말풍선 안에 보여줍니다. 받는 사람이 보게 될 그대로이며, "원시 구문 보기"는 복사될 텍스트를 보여줍주 있습니다. 두 패널은 스크롤이 연동되는데, 마이기도 곳에 있는 패널이 주도가 되고며, 타자하는 동안 미리보기가 사용자 포인터를 따라갑니다.

4. "WhatsApp용으로 복사" 또는 버튼 "WhatsApp로 공유"를 눌러 wa.me 링준로 메시지가 준비된 채샡을 엽니다. 아주 긴 메시지는 URI에 들어갈 수 없습니다 — 브라우저는 수천 지자의 URL을 잘라 버리기 때문에 — 그러므로 "공유"는 제쳐두고 "복사"하라고 말합니다.

인터페이스는 운영체제의 라이트/다크 테마를 따릅니다. 헤더의 토글로 이를 바꾸고 선택을 저장합니다. 옵션 바에는 내용 종류별 섹션이 있으며, 텍스트에 해당 내용이 있을 때만 표시됩니다: 말풍선(표나 코드 블록일 때의 너비), 표(스타일, 구분선), 제목(이모지 접두사). 다른 설정이 무의미하게 만든 컨트롤(목록 스타일에서 분할, 맞는 폭 텍스트가 없을 때는 너비)은 제거하는 대신 그 자리에 흐리게 표시하여 바 형태를 유지합니다. 옵션은 테마와 함께 localStorage에 저장됩니다. 표별 선택 항목은 저장되지 않습니다. 그것은 변환 중인 텍스트에 속하기 때문입니다.

코드, 셸 또는 에이전트에서 사용

동일한 변환기가 npm에 markdown-to-whatsapp(Node 20 이상)으로 배포됩니다. 옵션은 위에 기술된 것과 동일하며, 같은 이름과 기본값을 가지며, 이 섹션 끝에 전체가 나열됩니다.

라이브러리

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 });

명령줄

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, 그 위 -h, --help 및 -v, --version. 출력은 stdout로, 잘못된 옵션이 있으면 stderr로 사유를 출력하고 종료 코드 2로 종료됩니다.

MCP 서버

이 패키지는 Model Context Protocol 서버로 stdio에서 실행되므로, 에이전트가 텍스트를 자체 변환할 수 있습티다. 표 텁이블에서 중요합니다: 26 자 말풍선에 열 수를 세는 것은 모델이 틀리고 이 도구가 맞히는 일입니다.

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

또는 Claude Desktop 및 JSON 구성을 사용하는 다른 클라이언트의 경우:

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

하나의 도구, **convert_markdown_to_whatsapp**를 노출하며, markdown과 선택적 매개변수 monoWidth, tableFormat, listLayout, rowSeparator, headingEmojis를 받습니다. 텍스트는 도구의 콘텐츠로 반환되고, 구조화된 결과에는 그 텍스트가 text로 담기며 tables가 함께 포함됩니다. 각 테이블마다 key, columns, fitsBox, asList, listLayout 항목이 하나씩 있어, 에이전트는 어떤 테이블이 박스가 되었고 어떤 테이블이 목록이 되었는지 알 수 있습니다. 이 도구는 읽기 전용이며 멱등적입니다.

Options

옵션으로는 tableFormat (auto | list), monoWidth, rowSeparator, headingEmojis, listLayout (auto | rows | columns | pairs) 및 tableOverrides가 있습니다. tableOverrides는 문서에서의 테이블 위치로 인덱싱된 배열이거나, 테이블의 key(헤더 텍스트를 |로 연결한 값, 반복되는 헤더에는 #2, #3…이 붙음)로 키를 지정하는 객체입니다. 각 항목은 해당 테이블에 대해서만 다른 옵션을 재정의합니다. 페이지는 테이블별로 listLayout만 노출합니다.

이전 이름은 입력에서 계속 허용됩니다. monoWidth에는 tableThreshold, tableFormat에는 ascii / always입니다 (ascii는 말풍선보다 넓은 박스를 그리지 않았으므로 auto로 매핑됩니다). 이전 이름과 새 이름이 함께 주어지면 새 이름이 우선하고 이전 이름은 무시됩니다. 한때 유니코드 박스 그리기를 선택하던 borderStyle도 허용되지만 무시됩니다.

Development

Running tests

Node 20 이상, 리포지토리 루트에서:

npm install
npm test

테스트 스위트는 파일 기반 테스트를 사용합니다:

• tests/inputs/*.md - Markdown 입력 파일

• tests/inputs/*.json - 픽스처별 선택적 변환기 옵션 (예: { "monoWidth": 40 })

• tests/expected/*.txt - 기대되는 WhatsApp 출력

그리고 몇 가지 불변 조건이 더 있습니다. 벤더된(vendored) 파서가 설치된 것과 일치하고, convertToBlocks가 올바른 소스 줄을 보고하며, 패키지 진입점이 페이지 스크립트라는 점입니다.

테스트는 CI에서 모든 푸시와 풀 리퀘스트에 대해서도 실행됩니다 (.github/workflows/test.yml).

프로젝트 구조

• docs/converter.js - 변환기 자체입니다: 순수한 ES 모듈, DOM 불필요, 옵션은 매개변수로 전달됩니다. 페이지가 가져오는 스크립트이자 npm 패키지의 진입점(exports["."])이므로 복사본이 하나이고 빌드 단계가 없습니다. convertTextToWhatsapp(markdown, options)를 노출하고, convertToBlocks(markdown, options)는 동일한 변환이지만 최상위 블록을 분리된 채로 유지하고 각 블록에 그 블록이 속한 테이블을 태그합니다. 테이블별 옵션은 바로 이 값으로 구축됩니다. 또한 mdContainsTable / mdContainsHeading / mdContainsCode 쿼리를 노출하여 UI가 해당 옵션이 맞는 경우에만 옵션을 표시합니다. convertToBlocks의 각 블록은 해당 블록이 시작되는 소스 line을 보고하고 — 두 패널을 함께 스크롤되게 유지해 주는 정보입니다. — 각 테이블 블록도 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/m~arkdown~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 파일을 참고하세요.