markitdown.ai
시작하기

변환기

마크다운 HTML 변환

마크다운 HTML 변환은 브라우저 변환기로, CommonMark와 GitHub Flavored Markdown을 안전한 HTML로 바꿉니다. 제목, 표, 할 일 목록, 코드 블록이 포함됩니다. 업로드가 없으며 같은 렌더러가 POST /v1/convert/markdown/html 뒤에서 동작합니다.

# markitdown-ai

Convert documents to clean Markdown.

## Features

- PDF, Word, and slides
- [x] Tables stay tables
- [ ] Mermaid coming later

## Install

```bash
pnpm add @markitdown-ai/sdk
```

## API

| Method | Path |
| --- | --- |
| POST | /v1/convert/{name} |
| GET | /v1/conversions/{id} |

사용 방법

Markdown을 HTML로 변환하는 방법

붙여 넣을 수 있는 것

  • 어떤 Markdown이든: CommonMark와 GitHub Flavored Markdown의 표, 할 일 목록, 취소선
  • 렌더링은 브라우저에서 일어납니다. 입력하는 동안 업로드되는 것은 없습니다
  • 미리보기, 복사, 다운로드에 계정이 필요하지 않습니다
  • 고정 크기 제한 없음. 아주 큰 문서는 브라우저 메모리에 의해 제한됩니다
마크다운 HTML 변환: 왼쪽 Markdown 편집기가 오른쪽 HTML 페이지로 바뀌는 장면

사용하는 이유

이 마크다운 HTML 변환을 쓰는 이유

CMS 필드, 정적 사이트, 이메일 편집기는 Markdown 코드가 아니라 마크업을 원합니다. 이 변환기는 의미를 주는 부분은 보존하고, 가공되지 않은 HTML을 위험하게 만들 부분은 제거합니다.

브라우저에서 실행

Markdown을 붙여 넣으면 HTML 미리보기가 로컬에서 갱신됩니다. 업로드가 없고 미리보기, 복사, 다운로드에 계정이 필요하지 않습니다.

CommonMark + GFM

제목, 목록, 링크, 인용, 코드 블록은 CommonMark를 따르고, 표, 할 일 목록, 취소선은 GitHub Flavored Markdown을 따릅니다.

기본 새니타이즈

script 태그, 인라인 이벤트 핸들러, 안전하지 않은 href·src 스킴을 제거하므로 완전히 통제하지 못하는 페이지에 붙여 넣어도 HTML이 안전합니다.

조각 또는 완전한 문서

자체 레이아웃이 있는 페이지에는 렌더링된 마크업만 복사하거나, 미리보기 스타일이 담긴 완전한 HTML 문서를 내려받으세요.

제목 앵커

각 제목에 API와 동일하게 생성되는 안정적이고 URL에 안전한 id가 붙어, 게시 후에도 목차나 직접 링크가 동작합니다.

API와 같은 엔진

이 미리보기와 POST /v1/convert/markdown/html는 같은 렌더러를 쓰므로, 여기서 복사한 HTML이 자동 호출 결과와 바이트 단위로 일치합니다.

문제

가공되지 않은 Markdown을 바로 웹 페이지에 쓸 수 없는 이유

Markdown 문법은 HTML이 아닙니다

CMS 필드, 이메일 템플릿, 정적 사이트 테마는 Markdown 코드가 아니라 마크업을 원하므로, 스타일을 입히거나 삽입하기 전에 가공되지 않은 텍스트를 변환해야 합니다.

단순한 파서는 GFM을 다루지 못합니다

표, 할 일 목록, 취소선은 GitHub Flavored Markdown 확장이라 CommonMark만 이해하는 파서는 이를 구조가 아니라 문자 그대로의 파이프와 물결표로 렌더링합니다.

신뢰할 수 없는 Markdown은 스크립트를 품을 수 있습니다

Markdown은 <script> 태그와 인라인 이벤트 핸들러를 포함한 가공되지 않은 HTML을 담을 수 있으며, 완전히 통제하지 못하는 페이지에 삽입하기 전에 이를 제거해야 합니다.

마크다운을 HTML로 변환: 깨진 복사 붙여넣기 텍스트와 깔끔한 Markdown 구조 비교

보존되는 것

이 마크다운 HTML 변환이 보존하는 것

제목과 인라인 텍스트
ATX 및 setext 제목, 강조, 링크, 인용은 CommonMark를 따르며, 각 제목에는 텍스트에서 생성된 URL 안전 id도 붙습니다.Source: CommonMark Spec
표, 할 일 목록, 취소선
GitHub Flavored Markdown 표는 <table> 요소로, [ ]와 [x] 항목은 체크박스로, ~~텍스트~~는 <del>로 변환됩니다.Source: GitHub Flavored Markdown Spec
새니타이즈된 마크업
가공되지 않은 <script> 태그, 인라인 이벤트 핸들러, http·https·mailto 밖의 href·src 값은 HTML을 반환하기 전에 제거됩니다.Source: HTML Living Standard
코드 블록
펜스 코드 블록은 내용과 언어 태그를 유지하며, 브라우저 미리보기 자체는 구문 강조 테마를 적용하지 않습니다.Source: CommonMark Spec
원본의 가공되지 않은 HTML
다른 HTML 태그를 포함한 Markdown도 같은 새니타이저를 거치므로, 포함된 태그가 신뢰할 수 있는 마크업으로 취급되지 않습니다.Source: HTML Living Standard

검증된 마크다운 HTML 변환 발췌· https://markitdown.ai/blog/why-pdfs-break-llms

<h2 id="what-actually-goes-wrong">What actually goes wrong</h2><p>When teams pipe documents straight into an LLM or a retrieval index, a few failure modes show up again and again:</p><ul><li><strong>Reading order breaks.</strong> Multi-column layouts interleave. A two-column page becomes "line 1 left, line 1 right, line 2 left, line 2 right…", so a sentence a human reads top-to-bottom arrives at the model scrambled.</li><li><strong>Tables collapse.</strong> Copy-paste turns a table into a loose run of numbers. The relationship between a header and its cell — the entire point of a table — is gone.</li><li><strong>Headings disappear.</strong> The visual hierarchy (this is a section, this is a subsection) is encoded as font size and weight, not structure. Strip the styling and you get one undifferentiated wall of text.</li><li><strong>Noise creeps in.</strong> Page numbers, running headers, hyphenated line breaks, and stray ligatures end up inline, polluting prompts and embeddings alike.</li></ul><p>Read more in the <a href="https://markitdown.ai/blog/why-pdfs-break-llms">full article</a>.</p>

사용 사례

마크다운 HTML 변환 사용 사례

대상은 마크업을 원하는데 원본이 여전히 Markdown일 때, 이 변환기가 중간 단계가 됩니다.

문서와 정적 사이트

README나 지식 베이스의 Markdown 글을 정적 사이트 생성기나 CMS 필드가 기대하는 HTML로 변환하세요.

이메일과 뉴스레터 초안

Markdown으로 메시지를 쓰고 HTML로 변환한 뒤, 실제로 발송하는 이메일 편집기에 조각을 붙여 넣으세요.

LLM 응답 정리

ChatGPT, Claude, Gemini는 Markdown을 반환합니다. 티켓이나 위키 페이지처럼 별표 대신 마크업을 렌더링하는 대상에는 HTML로 변환해 넣으세요.

렌더링을 자동화하는 개발자

Markdown을 저장하지만 HTML을 제공하는 프로세스에서 렌더링 엔드포인트를 호출하세요. 서비스마다 Markdown 라이브러리를 추가할 필요가 없습니다.

마크다운 HTML 변환기: 렌더링된 HTML 페이지를 웹사이트, 이메일, 문서에 활용

API

개발자를 위한 마크다운 HTML 변환 API

렌더링은 동기로 실행되고 0크레딧이 듭니다. 그래도 요금제의 분당 요청 한도에는 포함됩니다. Markdown을 텍스트로 보내거나 저장한 .md 파일을 참조해 API 키와 함께 POST /v1/convert/markdown/html로 보내면, 안전한 HTML이 같은 응답으로 돌아옵니다.

API 가이드 읽기
curl -X POST https://api.markitdown.ai/v1/convert/markdown/html \  -H "x-api-key: mdai_…" \  -H "Content-Type: application/json" \  -d '{ "text": "# Notes\n\nHello **world**." }'

가이드

문서와 정적 사이트

대부분의 문서 도구는 Markdown을 편집 가능한 원본으로 두고 빌드하거나 미리 볼 때만 HTML을 생성합니다. 이 변환기로 그 생성 단계를 따로 확인할 수 있습니다. 사이트 생성기가 읽을 같은 Markdown을 붙여 넣고, 변경을 확정하기 전에 제목, 표, 코드 블록이 테마가 기대하는 대로 나오는지 확인하세요. CMS 필드가 HTML을 받지만 작성자가 Markdown으로 작업하는 경우에도 유용합니다. 한 번 변환해 조각을 붙여 넣고, 생성된 마크업을 손으로 고치는 대신 다음 개정을 위해 Markdown 원본을 계속 편집하세요.

  • Markdown 파일을 진실의 원천으로 유지하고 HTML은 빌드 결과물로 다루세요.
  • 렌더링된 출력을 이 페이지 미리보기 스타일이 아니라 실제 사이트 테마와 비교하세요.
  • 생성된 HTML을 손으로 패치하지 말고 원본을 편집할 때마다 변환을 다시 실행하세요.

새니타이즈

Markdown은 가공되지 않은 HTML을 포함할 수 있고, 그 HTML에는 <script> 태그나 onclick 같은 인라인 이벤트 핸들러가 들어 있을 수 있습니다. 이 변환기가 결과를 반환하기 전에 그런 마크업은 새니타이저를 거쳐 script 요소를 제거하고 "on"으로 시작하는 모든 속성을 없애며 http, https, mailto 링크와 이미지 소스만 허용합니다. 살아남는 것은 의미 구조—제목, 문단, 목록, 표, 링크, 이미지, 코드—이며 장식 스타일이 아닙니다. 조각 출력에는 클래스나 CSS 파일을 주입하지 않습니다. 완전한 문서 다운로드는 미리보기에서 보이는 테마를 더해 파일이 단독으로 제대로 열리게 합니다.

조각 또는 완전한 페이지

조각은 <html> 또는 <head> 태그 없이 안쪽 마크업—제목, 문단, 표—만 담습니다. CMS 콘텐츠 필드나 자식 요소를 렌더링하는 컴포넌트처럼 자체 문서 구조와 스타일을 이미 정의한 페이지에 속합니다. 완전한 문서는 doctype, 제목, 작은 스타일시트를 더해 브라우저에서 바로 열거나 단독으로 저장할 수 있게 합니다. 조각을 기대하는 콘텐츠 필드에 완전한 문서를 붙여 넣는 것은 흔한 실수입니다. 브라우저가 그래도 렌더링할 수는 있지만 중첩된 <html>·<head> 태그는 그곳에서 유효하지 않고 조각을 기대하는 이후 도구를 혼란스럽게 할 수 있습니다.

더 많은 Markdown 변환기

Need it in your code? Use the developer API. Converting at scale? See plans and pricing.

FAQ

마크다운 HTML 변환 FAQ

마크다운 HTML 변환은 어떻게 동작하나요?

Markdown을 붙여 넣거나 입력하면 변환기가 POST /v1/convert/markdown/html와 같은 렌더러로 브라우저에서 로컬로 안전한 HTML을 렌더링합니다. 입력하는 동안 업로드되는 것은 없습니다.

마크다운 HTML 변환은 GitHub Flavored Markdown을 지원하나요?

네. 표, 할 일 목록, 취소선은 GitHub Flavored Markdown 명세를 따르며 CommonMark의 제목, 목록, 링크, 코드도 함께 처리합니다.

출력 HTML은 새니타이즈되나요?

네. script 태그, 인라인 이벤트 핸들러, 안전하지 않은 href·src 스킴을 제거하므로 완전히 통제하지 못하는 페이지에 붙여 넣어도 안전합니다.

조각 대신 완전한 HTML 문서를 받을 수 있나요?

네. 미리보기 스타일이 담긴 완전한 문서를 고르거나, 자체 레이아웃이 있는 페이지에는 조각만 복사하세요.

마크다운 HTML 변환에 계정이 필요한가요?

아니요. 렌더링이 브라우저에서 로컬로 실행되므로 미리보기, 복사, 다운로드가 로그인 없이 동작합니다.

입력하는 동안 API를 호출하나요?

아니요. 입력은 로컬에 머뭅니다. API는 스크립트에서처럼 POST /v1/convert/markdown/html를 직접 호출할 때만 실행됩니다.

변환하는 Markdown에 크기 제한이 있나요?

업로드하는 것이 없으므로 고정된 업로드 한도가 없습니다. 매우 큰 문서에서는 실질적인 한도가 브라우저 메모리에 달려 있습니다.

코드에서 Markdown을 HTML로 변환할 수 있나요?

네. Markdown을 텍스트로, 또는 저장한 .md 파일을 API 키와 함께 /v1/convert/markdown/html로 보내세요. 0크레딧입니다. /developers를 확인하세요.

Markdown을 원하는 곳에서 HTML로 변환하세요.

무료로 사용해 보세요. 가입이 필요 없습니다.

시작하기변환기 열기