마크다운 입문: 기초부터 시작하는 마크다운 가이드

마크다운은 입력한 기호를 구조화된 문서로 바꿔 주는 일반 텍스트 서식 문법으로, 핵심 문법은 약 10분이면 배울 수 있습니다. John Gruber가 Aaron Swartz의 도움을 받아 2004년 3월에 공개했고, 22년이 지난 지금도 GitHub의 README 파일, Obsidian의 노트, Reddit의 게시물을 서식화하는 데 쓰이고 있습니다. 전체 시스템은 두 부분으로 이루어집니다. .md 확장자로 저장된 텍스트 파일과 그 텍스트를 HTML로 변환하는 프로세서입니다. 아래의 모든 내용은 이 두 부분 위에 세워져 있습니다.

마크다운이란?

*마크다운이란 #, , > 같은 눈에 보이는 문자로 일반 텍스트에 서식 지시를 더하는, 2004년에 등장한 경량 마크업 언어입니다. 줄 맨 앞의 #는 제목을 만듭니다. 단어를 별표 두 개로 감싸면 굵게 표시됩니다. 하이픈은 글머리 기호를 시작합니다. 최초 릴리스는 Markdown.pl이라는 단일 Perl 스크립트로, Gruber의 사이트 Daring Fireball에 공개되었습니다.

HTML과 LaTeX를 비롯한 무거운 마크업 언어는 태그와 명령으로 콘텐츠를 감싸 원본 파일을 어지럽힙니다. 마크다운은 정반대의 길을 택했습니다. Gruber는 "변환하기 전의 마크다운 파일이 일반 텍스트 그대로 깔끔하게 읽혀야 한다"는 하나의 목표를 중심으로 문법을 설계했습니다. ## Pricing이라는 줄은 마크다운을 한 번도 들어 본 적 없는 사람에게도 제목으로 보입니다. 이 가독성 덕분에 이 포맷은 2004년의 블로그에서 2008년의 GitHub, 2010년의 Stack Overflow, 그리고 2010년대의 Obsidian과 Joplin 같은 노트 앱으로 퍼져 나갔습니다.

마크다운과 WYSIWYG 편집기의 차이

Microsoft Word나 Google Docs 같은 WYSIWYG 편집기는 도구 모음 버튼으로 서식을 적용하고 그 명령을 숨기지만, 마크다운은 모든 명령을 문자 그대로 파일 안에 남겨 둡니다. WYSIWYG는 "what you see is what you get(보이는 대로 얻는다)"의 약자입니다. Word에서는 문구를 선택하고 굵게 버튼을 클릭하며, 그 결정은 눈에 보이지 않는 바이너리 XML로 파일에 저장됩니다. 마크다운에서는 **launch date**라고 입력하며, 별표 두 쌍 자체가 곧 서식입니다.

차이는 저장할 때 드러납니다. .docx 파일은 Word, LibreOffice, Pages를 중심으로 한 몇 안 되는 프로그램에서만 제대로 열립니다. 마크다운 파일은 Notepad부터 vim, VS Code까지 1970년대 이후 출시된 어떤 텍스트 편집기에서도 열립니다. 많은 마크다운 편집기는 화면 분할 실시간 미리보기로 시각적 간극을 메웁니다. 왼쪽 창에는 원본 문법이, 오른쪽 창에는 렌더링된 결과가 표시되고 키를 누를 때마다 갱신됩니다. Word의 즉각적인 피드백과 일반 텍스트의 투명성을 동시에 얻는 셈입니다.

마크다운을 사용하는 이유

작성자들이 마크다운을 선택하는 실용적인 이유는 네 가지입니다. 이동성, 플랫폼 독립성, 미래 보장성, 그리고 폭넓은 지원 범위입니다. 네 가지 모두 일반 텍스트라는 토대에서 나옵니다.

• 이동성. 마크다운 파일은 변환 없이 애플리케이션 사이를 오갑니다. iA Writer에서 초안을 쓰고, VS Code에서 수정하고, Ghost로 발행합니다. 파일의 형태는 전혀 바뀌지 않습니다. .docx나 .pages 같은 독점 형식은 콘텐츠를 한 업체의 생태계에 가둡니다.
• 플랫폼 독립성. 마크다운은 Windows 11, macOS, Linux, iOS, Android에서 완전히 동일하게 동작합니다. 파일이 UTF-8 텍스트이므로 2026년에 휴대폰으로 입력한 메모가 데스크톱에서도 바이트 하나 다르지 않게 열립니다.
• 미래 보장성. 소프트웨어는 사라져도 텍스트 파일은 살아남습니다. 1990년에 워드프로세서 시장을 지배했던 WordPerfect의 옛 파일은 오늘날 복구 프로젝트의 대상입니다. 2004년의 마크다운 파일은 지금도 1초 안에 열립니다. 20년 이상 보관해야 하는 논문, 계약서, 책 원고에는 중요한 문제입니다.
• 폭넓은 지원 범위. GitHub, GitLab, Reddit, Discord, Notion, Slack 등 여러 플랫폼이 마크다운 입력을 지원합니다. 문법을 한 번만 배우면 이 모든 곳에서 활용할 수 있습니다.

마크다운이 처리되는 원리

마크다운은 4단계 파이프라인을 거쳐 서식이 적용된 문서가 됩니다. .md 파일을 작성하면 프로세서가 이를 해석하고, HTML을 출력하며, 브라우저가 그 HTML을 렌더링합니다. 파서 또는 구현체라고도 불리는 프로세서는 모든 마크다운 애플리케이션 안에서 돌아가는 엔진입니다. 대표적인 프로세서로는 markdown-it, marked, cmark, Pandoc이 있으며, cmark는 일반적인 문서를 10밀리초 안에 변환합니다.

도구마다 이 파이프라인을 드러내는 정도가 다릅니다. 실시간 미리보기를 제공하는 온라인 편집기는 키를 누를 때마다 2단계부터 4단계를 보이지 않게 실행합니다. Hugo 같은 정적 사이트 생성기는 빌드 명령 한 번으로 수백 개의 파일에 같은 파이프라인을 적용합니다. 파이프라인 자체는 결코 변하지 않으며, 출력된 HTML은 어떤 CSS 스타일시트와도 결합할 수 있고 Pandoc 같은 도구를 거쳐 PDF, EPUB, .docx로도 변환됩니다.

마크다운은 어디에 쓰일까요?

마크다운이 담당하는 대표적인 용도는 일곱 가지입니다. 웹사이트, 노트, 문서, 책, 프레젠테이션, 이메일, 기술 문서입니다. 10분 만에 배운 같은 문법이 이 일곱 가지 모두에 통합니다.

웹사이트

Hugo, Jekyll, Eleventy 같은 정적 사이트 생성기는 마크다운 파일 폴더에서 웹사이트 전체를 만들어 냅니다. 2008년에 출시된 Jekyll은 GitHub Pages와 무료 호스팅을 뒷받침합니다. 콘텐츠 플랫폼도 마크다운을 받아들입니다. Ghost는 자체 마크다운 편집기를 제공하고, WordPress는 블록 편집기를 통해 마크다운을 지원합니다. 블로그 글 하나가 곧 .md 파일 하나이며, Git 같은 버전 관리 시스템이 모든 수정 내역을 추적합니다.

노트와 문서

Obsidian, Joplin, Bear, Simplenote 같은 노트 앱은 모든 노트를 마크다운으로 저장합니다. 특히 Obsidian은 각 vault를 자신의 디스크에 있는 .md 파일 폴더로 보관하므로, 5,000개짜리 노트 모음도 표준 도구로 검색할 수 있습니다. 편지, 회의록, 과제 같은 단발성 문서라면 마크다운 편집기에서 곧바로 PDF나 HTML로 내보낼 수 있고, 그 PDF는 인쇄하거나 이메일에 첨부하거나 어디든 업로드할 수 있습니다.

책과 프레젠테이션

Leanpub은 마크다운 파일 폴더를 PDF와 EPUB 형식의 완성된 전자책으로 만들어 주며, Pandoc은 명령줄에서 같은 일을 합니다. 이 방식으로 장편 소설과 300페이지짜리 기술 서적을 출간한 저자들도 있습니다. 슬라이드가 필요하다면 Marp나 Remark 같은 도구가 마크다운 파일을 프레젠테이션 덱으로 변환합니다. --- 구분자 하나가 슬라이드 한 장이 되므로, 40장을 일일이 손으로 서식화한 PowerPoint 파일보다 훨씬 빠르게 수정할 수 있습니다.

이메일과 기술 문서

Markdown Here 같은 브라우저 확장 프로그램은 Gmail을 비롯한 웹메일 안에서 마크다운을 서식이 적용된 HTML 이메일로 변환합니다. 기술 문서는 마크다운의 본고장입니다. GitHub은 모든 저장소 상단에 README.md를 렌더링하고, MkDocs, Docusaurus, Read the Docs 같은 생성기는 .md 소스 파일로 완전한 문서 사이트를 구축합니다. Meta가 2017년에 공개한 Docusaurus는 일반 마크다운 페이지 위에 버전 관리와 검색 기능을 더합니다.

마크다운 플레이버: CommonMark와 GFM

마크다운 플레이버란 문법의 특정 변형을 말하며, 가장 중요한 두 가지는 2014년에 명세화된 CommonMark와 2017년에 명세화된 GitHub Flavored Markdown입니다. 2004년 Gruber의 릴리스는 중첩 목록의 들여쓰기 방식 같은 세부 사항을 정의하지 않은 채 남겨 두었고, 초기 프로세서들은 서로 다른 출력을 내놓았습니다. 같은 파일이 도구에 따라 다르게 표시된 것입니다.

CommonMark가 이 문제를 해결했습니다. John MacFarlane과 Jeff Atwood가 참여한 워킹 그룹이 2014년 9월에 발표한 CommonMark 명세는 600개가 넘는 테스트 케이스로 모든 해석 규칙을 고정했습니다. Stack Overflow는 2020년 6월에 렌더링을 CommonMark로 전환했습니다.

GitHub Flavored Markdown, 줄여서 GFM은 GitHub이 2017년 3월에 공식화한 CommonMark의 엄격한 상위 집합입니다. 표, 작업 목록, 취소선, 자동 링크, 언어 태그가 있는 펜스 코드 블록이라는 다섯 가지 확장을 추가합니다. 제품 페이지에 "마크다운 지원"이라고 적혀 있다면 어떤 플레이버를 뜻하는지 확인해야 합니다. GFM 표는 CommonMark만 지원하는 도구에서는 그냥 파이프 문자로 표시되기 때문입니다. 2026년 기준 가장 안전한 기본값은 GFM이며, 이 사이트의 편집기가 렌더링하는 플레이버이기도 합니다.

오늘 바로 마크다운을 시작하는 방법

브라우저 기반 마크다운 편집기를 열고 # 뒤에 제목을 입력하면 그것이 여러분의 첫 마크다운입니다. 설치할 것도, 만들어야 할 계정도 없습니다. 분할 창 편집기는 입력하는 동안 렌더링 결과를 보여 주므로, 마크다운 사용법을 익히는 가장 빠른 피드백 루프가 됩니다.

가장 자주 쓰는 다섯 가지 요소부터 시작하십시오. 제목의 #, **bold**, *italic*, 목록의 -, 링크의 [text](url)입니다. 이 다섯 가지면 일상적인 서식의 약 90%를 처리할 수 있습니다. 회의록이나 할 일 목록처럼 실제 문서를 다시 써 보며 연습하고, 결과를 .md 파일로 저장해 보십시오. 그다음에는 기본 문법 가이드가 9가지 핵심 요소 전체를, 확장 문법 가이드가 GFM 표, 각주, 작업 목록을 다룹니다.

자주 묻는 질문

마크다운을 쓰려면 소프트웨어를 설치해야 하나요?

웹 브라우저면 충분합니다. 온라인 마크다운 편집기는 설치 없이 작성, 미리보기, 내보내기를 모두 처리합니다. 나중에 필요해지면 Obsidian, iA Writer, VS Code 같은 데스크톱 애플리케이션이 오프라인 접근과 로컬 파일 관리 기능을 더해 줍니다.

마크다운 파일은 어떤 확장자를 쓰나요?

마크다운 파일은 .md 확장자를 쓰며, 덜 쓰이는 대안으로 .markdown도 있습니다. 둘 다 완전히 동일한 일반 텍스트를 담고 있고, cmark부터 Pandoc까지 모든 마크다운 프로세서가 두 확장자를 모두 받아들입니다.

마크다운 사용법을 배우는 데 얼마나 걸리나요?

핵심 5가지 요소는 약 10분이면 배우고, 9가지 요소로 이루어진 기본 문법 전체도 한자리에서 익힐 수 있습니다. 표와 작업 목록 같은 GFM 확장은 15분 정도가 더 걸립니다. 제대로 된 서식을 갖추는 데 몇 주가 걸리는 LaTeX와 비교해 보십시오.

CommonMark와 GFM의 차이는 무엇인가요?

CommonMark는 핵심 마크다운 해석을 표준화한 2014년의 기본 명세이고, GFM은 표, 작업 목록, 취소선, 자동 링크, 펜스 코드 블록을 추가한 GitHub의 2017년 상위 집합입니다. 유효한 CommonMark 문서는 모두 유효한 GFM 문서이기도 하므로, GFM 기준으로 작성하는 것이 실용적인 선택입니다.