마크다운 문법 완전 정복: 초보자도 10분이면 마스터하는 실전 가이드

마크다운 문법을 배우고 싶은데 어디서부터 시작해야 할지 막막하신가요? 블로그를 운영하거나 개발 문서를 작성할 때 HTML은 너무 복잡하고, 워드 프로세서는 기능이 과하다고 느끼셨을 겁니다. 마크다운은 바로 이런 고민을 해결해주는 완벽한 도구입니다.

마크다운은 2004년 John Gruber와 Aaron Swartz가 개발한 경량 마크업 언어로, 누구나 쉽게 읽고 쓸 수 있는 텍스트 포맷을 제공합니다. 복잡한 HTML 태그 없이도 깔끔한 문서를 만들 수 있어서 개발자부터 블로거, 기술 문서 작성자까지 전 세계 수백만 명이 매일 사용하고 있습니다. 특히 GitHub, Notion, Discord 같은 플랫폼에서 기본 문법으로 채택되면서 필수 스킬로 자리잡았습니다.

이 글에서는 마크다운의 핵심 문법부터 실전 활용법까지 체계적으로 정리했습니다. 프로그래밍 경험이 전혀 없어도 괜찮습니다. 10분만 투자하면 오늘부터 바로 마크다운으로 문서를 작성할 수 있습니다.

1. 마크다운이란 무엇인가

1. 마크다운의 탄생 배경과 철학

   • 마크다운은 웹 콘텐츠를 더 쉽고 빠르게 작성하기 위해 만들어진 텍스트 포맷입니다. John Gruber는 HTML의 복잡함을 줄이면서도 문서의 가독성을 최대한 유지하는 것을 목표로 했습니다. 실제로 마크다운 문서는 변환하지 않아도 그 자체로 읽기 편한 구조를 가지고 있습니다.
   • Aaron Swartz가 2002년에 개발한 ATX 개념에서 영감을 받아, 2004년 완성된 마크다운은 "읽기 쉽고 쓰기 쉬운" 문서 작성 도구라는 명확한 철학을 담고 있습니다. 특수 문자와 간단한 문법만으로 문서 구조를 표현할 수 있어, 누구나 5분이면 기본 문법을 익힐 수 있습니다.
   • 마크다운은 단순히 텍스트를 HTML로 변환하는 도구가 아닙니다. 텍스트 자체가 의미를 가지도록 설계되어, 마크다운 파일을 그대로 읽어도 내용을 완벽하게 이해할 수 있습니다. 이런 특징 덕분에 버전 관리 시스템에서도 변경 사항을 쉽게 추적할 수 있습니다.

2. 마크다운의 핵심 특징

   • 마크다운은 일반 텍스트 편집기에서 작성할 수 있어 별도의 소프트웨어가 필요 없습니다. 메모장, VS Code, Sublime Text 등 어떤 에디터에서든 바로 사용할 수 있습니다. 파일 확장자는 .md 또는 .markdown을 사용합니다.
   • HTML로 변환이 간단하면서도 필요할 때는 HTML 태그를 직접 삽입할 수 있어 확장성이 뛰어납니다. Pandoc 같은 도구를 사용하면 PDF, DOCX, LaTeX 등 다양한 형식으로도 변환할 수 있습니다.
   • 플랫폼 독립적이라는 점도 큰 장점입니다. GitHub, GitLab, Reddit, Stack Overflow, Notion, Obsidian 등 수많은 플랫폼에서 마크다운을 지원하므로, 한 번 배워두면 여러 곳에서 활용할 수 있습니다.

3. 마크다운 vs HTML vs 워드 프로세서

   • HTML은 강력하지만 배우기 어렵고 작성이 번거롭습니다. 태그를 열고 닫는 과정에서 실수가 생기기 쉽고, 코드가 복잡해지면 가독성이 떨어집니다. 마크다운은 HTML의 복잡함 없이 핵심 기능만 제공하여 빠른 작성이 가능합니다.

   • Microsoft Word 같은 워드 프로세서는 기능이 풍부하지만 과도하게 복잡합니다. 간단한 문서를 작성하는데 무거운 프로그램을 실행할 필요가 없고, 파일 형식 호환성 문제도 발생합니다. 마크다운은 순수 텍스트이므로 어디서든 열고 수정할 수 있습니다.

   • 마크다운은 두 도구의 장점을 결합했습니다. 워드 프로세서처럼 직관적이면서도 HTML처럼 웹에서 바로 사용할 수 있습니다. 특히 프로그래밍 코드를 포함한 기술 문서 작성에는 마크다운이 최적의 선택입니다.

   • 마크다운을 쉽게 이해할 수 있는 영상 - The Only Markdown Crash Course You Will Ever Need

2. 마크다운 기본 문법 익히기

1. 헤딩으로 문서 구조 만들기

   • 헤딩은 # 기호로 표현하며, 개수에 따라 1단계부터 6단계까지 제목을 만들 수 있습니다. # 제목은 가장 큰 H1 헤딩이 되고, ## 제목은 H2, ### 제목은 H3 방식입니다. 문서 전체 제목에는 H1을 하나만 사용하고, 주요 섹션에는 H2를, 하위 섹션에는 H3를 사용하는 것이 좋습니다.
   • 헤딩을 제대로 활용하면 문서의 계층 구조가 명확해져서 독자가 내용을 빠르게 파악할 수 있습니다. 많은 마크다운 에디터는 헤딩을 기반으로 자동 목차를 생성해주므로, 긴 문서를 작성할 때 특히 유용합니다.
   • 주의할 점은 #과 제목 텍스트 사이에 공백을 반드시 넣어야 한다는 것입니다. #제목은 작동하지 않고 # 제목처럼 써야 합니다. 또한 헤딩 레벨을 건너뛰지 말고 순차적으로 사용하는 것이 접근성 측면에서 좋습니다.

2. 텍스트 강조하기

   • 이탤릭체는 *텍스트* 또는 _텍스트_로 만들 수 있습니다. 두 방식 모두 동일하게 작동하므로 편한 것을 선택하면 됩니다. 볼드체는 별표나 언더스코어를 두 개 사용하여 텍스트 또는 __텍스트__로 표현합니다.
   • 취소선은 물결표 두 개로 감싸서 ~~텍스트~~로 만들 수 있습니다. 이는 GitHub Flavored Markdown(GFM)에서 추가된 기능으로, 모든 마크다운 파서가 지원하는 것은 아니지만 널리 사용됩니다.
   • 강조를 조합할 수도 있습니다. _굵은 이탤릭_처럼 작성하면 볼드와 이탤릭이 동시에 적용됩니다. 하지만 과도한 강조는 오히려 가독성을 해치므로, 정말 중요한 내용에만 사용하는 것이 좋습니다.

3. 리스트로 정보 정리하기

   • 순서 없는 리스트는 -, *, + 중 하나를 줄 앞에 붙여서 만듭니다. 세 기호 모두 동일하게 작동하지만, 하나의 문서에서는 일관된 기호를 사용하는 것이 좋습니다. 대부분의 개발자들은 -를 선호합니다.
   • 순서 있는 리스트는 1., 2., 3. 처럼 숫자와 점을 사용합니다. 흥미롭게도 실제 숫자 순서는 중요하지 않습니다. 모두 1.로 시작해도 자동으로 순서가 매겨집니다. 하지만 가독성을 위해 올바른 순서로 작성하는 것을 권장합니다.
   • 중첩 리스트는 들여쓰기로 만듭니다. 스페이스 2개 또는 4개, 혹은 탭을 사용하여 하위 항목을 표현할 수 있습니다. 리스트 안에 단락이나 코드 블록을 넣을 때도 적절한 들여쓰기를 유지해야 합니다.

3. 링크와 이미지 삽입하기

1. 하이퍼링크 만들기

   • 기본 링크 문법은 [표시할 텍스트](URL) 형식입니다. 예를 들어 [Google](https://www.google.com)은 "Google"이라는 텍스트에 구글 홈페이지 링크를 걸어줍니다. 링크 텍스트는 명확하고 설명적으로 작성하는 것이 좋습니다.
   • 참조 스타일 링크를 사용하면 문서 가독성을 높일 수 있습니다. [텍스트][참조] 형식으로 작성하고, 문서 하단에 [참조]: URL을 정의합니다. 같은 링크를 여러 번 사용할 때 특히 유용합니다.
   • URL을 그대로 링크로 만들고 싶다면 <URL> 형식을 사용하거나, 대부분의 마크다운 파서는 URL을 자동으로 링크로 변환해줍니다. 이메일 주소도 <email@example.com> 형식으로 링크를 만들 수 있습니다.

2. 이미지 삽입하기

   • 이미지 문법은 링크와 비슷하지만 앞에 느낌표를 붙입니다. ![대체 텍스트](이미지 URL) 형식으로 작성하면 이미지가 삽입됩니다. 대체 텍스트는 이미지를 불러올 수 없을 때 표시되며, 접근성과 SEO에도 중요합니다.
   • 로컬 이미지를 사용할 때는 상대 경로를 지정할 수 있습니다. ![스크린샷](./images/screenshot.png) 처럼 작성하면 같은 폴더 구조 내의 이미지를 참조합니다. 이는 문서를 다른 곳으로 옮길 때 링크가 깨지지 않도록 도와줍니다.
   • 이미지에 링크를 걸고 싶다면 이미지 문법을 링크 문법으로 감싸면 됩니다. [![대체텍스트](이미지URL)](링크URL) 형식으로 작성하면 클릭 가능한 이미지가 만들어집니다.

3. 내부 링크로 문서 탐색 개선하기

   • 같은 문서 내의 다른 섹션으로 이동하는 내부 링크를 만들 수 있습니다. [섹션 이름](#헤딩-텍스트)처럼 작성하되, 헤딩 텍스트는 소문자로 변환하고 공백은 하이픈으로 바꿔야 합니다. 예를 들어 "마크다운 기본 문법"은 #마크다운-기본-문법이 됩니다.
   • 긴 문서에서 목차를 만들 때 내부 링크가 특히 유용합니다. 문서 상단에 주요 섹션으로 바로 이동할 수 있는 링크 목록을 만들면 사용자 경험이 크게 향상됩니다.
   • 일부 마크다운 파서는 헤딩에 자동으로 ID를 생성하므로, 정확한 형식을 확인하려면 변환된 HTML을 살펴보는 것이 좋습니다. GitHub에서는 한글 헤딩도 자동으로 링크 ID로 변환해줍니다.

4. 코드와 인용구 작성하기

1. 인라인 코드 표시하기

   • 문장 중간에 코드를 넣을 때는 백틱()으로 감싸면 됩니다. 예를 들어 "변수를 선언할 때는 let이나 const`를 사용하세요"처럼 작성할 수 있습니다. 인라인 코드는 기술 문서에서 함수명, 변수명, 명령어 등을 강조할 때 사용합니다.
   • 코드 안에 백틱을 포함해야 한다면 백틱을 두 개 사용하여 감쌀 수 있습니다. `코드`처럼 작성하면 내부의 백틱이 문자 그대로 표시됩니다.
   • 인라인 코드는 자동으로 등폭 글꼴로 표시되고 배경색이 적용되어 일반 텍스트와 명확하게 구분됩니다. 이는 독자가 코드와 설명을 쉽게 구별할 수 있게 도와줍니다.

2. 코드 블록 만들기

   • 여러 줄의 코드를 표시할 때는 백틱 세 개로 감쌉니다. 시작 백틱 뒤에 언어 이름을 적으면 문법 강조(syntax highlighting)가 적용됩니다. 예를 들어 ```python 다음 줄부터 파이썬 코드를 작성하고 ```로 닫으면 됩니다.
   • 지원하는 언어는 파서마다 다르지만, javascript, python, java, css, html, bash 같은 주요 언어는 대부분 지원합니다. 문법 강조는 코드의 가독성을 크게 높여주므로 반드시 언어를 명시하는 것이 좋습니다.
   • 들여쓰기로도 코드 블록을 만들 수 있습니다. 각 줄을 스페이스 4개 또는 탭 1개로 들여쓰면 코드 블록으로 인식됩니다. 하지만 이 방법은 문법 강조를 지원하지 않아 백틱 방식이 더 선호됩니다.

3. 인용구로 중요 내용 강조하기

   • 인용구는 > 기호를 줄 앞에 붙여서 만듭니다. 여러 줄을 인용할 때는 각 줄마다 >를 붙이거나, 첫 줄에만 붙이고 빈 줄로 구분할 수 있습니다. 인용구는 주로 다른 출처의 텍스트를 인용하거나 중요한 주의사항을 표시할 때 사용합니다.
   • 중첩 인용구도 만들 수 있습니다. > > 처럼 > 기호를 여러 개 사용하면 인용구 안에 또 다른 인용구를 만들 수 있습니다. 이는 이메일 스레드처럼 계층적인 인용이 필요할 때 유용합니다.
   • 인용구 안에서도 다른 마크다운 문법을 모두 사용할 수 있습니다. 헤딩, 리스트, 코드 블록 등을 인용구 안에 포함시킬 수 있어 복잡한 내용도 효과적으로 표현할 수 있습니다.

5. 표와 수평선 활용하기

1. 표로 데이터 정리하기

   • 마크다운 표는 파이프(|)와 하이픈(-)으로 만듭니다. 첫 줄은 헤더, 두 번째 줄은 구분선, 그 다음부터 데이터 행입니다. 가장 간단한 형태는 | 제목1 | 제목2 |, | --- | --- |, | 데이터1 | 데이터2 | 입니다.
   • 정렬도 지정할 수 있습니다. 구분선에서 :---는 왼쪽 정렬, :---:는 가운데 정렬, ---:는 오른쪽 정렬을 의미합니다. 숫자 데이터는 오른쪽 정렬, 텍스트는 왼쪽 정렬이 일반적입니다.
   • 표 작성이 번거롭다면 온라인 표 생성기를 활용할 수 있습니다. Tables Generator 같은 도구를 사용하면 엑셀처럼 데이터를 입력하고 마크다운 코드를 자동으로 생성할 수 있습니다. 복잡한 표일수록 이런 도구가 시간을 크게 절약해줍니다.

2. 수평선으로 섹션 구분하기

   • 수평선은 하이픈, 별표, 언더스코어를 3개 이상 연속으로 입력하면 만들어집니다. ---, ***, ___ 모두 동일한 결과를 만듭니다. 수평선은 문서의 주제가 크게 바뀔 때 시각적 구분선으로 사용합니다.
   • 수평선 위아래로 빈 줄을 넣는 것이 좋습니다. 일부 파서는 빈 줄이 없으면 수평선을 제대로 인식하지 못할 수 있습니다. 또한 헤딩과 혼동되지 않도록 주의해야 합니다.
   • 과도하게 사용하면 문서가 산만해 보일 수 있으므로, 정말 필요한 곳에만 사용하는 것이 좋습니다. 보통 문서 전체에서 2-3개 정도만 사용하는 것이 적절합니다.

3. 체크리스트로 할 일 관리하기

   • GitHub Flavored Markdown은 체크리스트 기능을 제공합니다. - [ ]는 체크되지 않은 항목, - [x]는 체크된 항목을 만듭니다. 이는 프로젝트 관리나 할 일 목록 작성에 매우 유용합니다.
   • 체크리스트는 일반 리스트와 결합할 수 있습니다. 중첩 리스트로 만들어 하위 작업을 표시하거나, 체크리스트 항목에 추가 설명을 덧붙일 수 있습니다.
   • GitHub Issues나 Pull Request에서 체크리스트를 사용하면 실제로 클릭하여 체크 상태를 변경할 수 있습니다. 이는 팀 협업에서 작업 진행 상황을 추적하는 데 효과적입니다.

6. 마크다운 실전 활용 전략

1. 블로그와 기술 문서 작성하기

   • 마크다운은 블로그 플랫폼에서 널리 사용됩니다. Jekyll, Hugo, Gatsby 같은 정적 사이트 생성기는 모두 마크다운을 기본으로 지원합니다. 마크다운으로 글을 작성하면 별도의 편집기 없이도 Git으로 버전 관리를 할 수 있어 편리합니다.
   • 기술 문서 작성에는 마크다운이 최적입니다. 코드 예제를 쉽게 삽입할 수 있고, 문서 구조를 명확하게 표현할 수 있습니다. Sphinx, MkDocs, Docusaurus 같은 문서 생성 도구들도 마크다운을 지원합니다.
   • README 파일은 모든 GitHub 프로젝트에 필수입니다. 프로젝트 소개, 설치 방법, 사용 예제를 마크다운으로 작성하면 다른 개발자들이 쉽게 이해할 수 있습니다. 잘 작성된 README는 프로젝트의 성공에 큰 영향을 미칩니다.

2. 협업 도구에서 마크다운 활용하기

   • Notion, Obsidian, Roam Research 같은 노트 앱들은 마크다운을 기본 문법으로 사용합니다. 마크다운을 익혀두면 이런 도구들을 훨씬 효율적으로 사용할 수 있습니다. 특히 Obsidian은 순수 마크다운 파일로 저장되어 데이터 이식성이 뛰어납니다.
   • Slack, Discord, Microsoft Teams 같은 메신저에서도 마크다운을 지원합니다. 메시지에 코드 블록을 넣거나 텍스트를 강조할 때 마크다운을 사용하면 의사소통이 더 명확해집니다.
   • Jira, Trello, Asana 같은 프로젝트 관리 도구들도 마크다운을 지원합니다. 이슈 설명이나 코멘트를 작성할 때 마크다운을 사용하면 정보를 체계적으로 전달할 수 있습니다.

3. 마크다운 에디터와 도구 추천

   • VS Code는 마크다운 작성에 최고의 에디터입니다. 실시간 미리보기, 문법 강조, 자동완성 기능을 기본 제공하며, 수많은 확장 프로그램으로 기능을 추가할 수 있습니다. Markdown All in One, Markdown Preview Enhanced 같은 확장을 설치하면 더욱 강력해집니다.
   • Typora는 WYSIWYG 방식의 마크다운 에디터입니다. 마크다운 문법을 입력하면 즉시 렌더링되어 워드 프로세서처럼 사용할 수 있습니다. 초보자에게 특히 추천하는 도구입니다.
   • 온라인 도구로는 StackEdit, Dillinger, HackMD가 있습니다. 별도 설치 없이 브라우저에서 바로 사용할 수 있고, 클라우드 저장과 공유 기능을 제공합니다. 빠른 테스트나 협업 작성에 유용합니다.

7. 마크다운 전체 문법 한 눈에 보기 | 심플 그 자체다

마크다운 문법 전체 정리표

구분	문법	결과 예시
제목	# 제목1 ## 제목2 ### 제목3 #### 제목4 ##### 제목5 ###### 제목6	크기가 다른 6단계 제목
강조	**굵게** 또는 __굵게__ *기울임* 또는 _기울임_ ~~취소선~~ *굵게+기울임*	굵게 기울임 취소선 굵게+기울임
목록	- 항목 또는 * 항목 또는 + 항목 1. 순서 항목 2. 순서 항목	• 비순서 목록 1. 순서 목록
링크	[텍스트](URL) [텍스트](URL "제목") <URL>	클릭 가능한 링크
이미지	 	이미지 표시
인용	> 인용문 >> 중첩 인용	인용 블록
코드	`인라인 코드` ```언어 코드블록 ```	코드 또는 코드 블록
수평선	--- 또는 *** 또는 ___	가로 구분선
표	| 헤더1 | 헤더2 | |----|----| | 내용1 | 내용2 |	표 형식
체크박스	- [ ] 미완료 - [x] 완료	☐ 미완료 ☑ 완료
각주	텍스트[^1] [^1]: 각주 내용	각주 참조
정의 목록	용어 : 정의	용어와 정의 쌍
이스케이프	\* \_ \# \[ \] 등	특수문자 그대로 표시
줄바꿈	문장 끝 공백 2개 또는 <br>	강제 줄바꿈
HTML	<태그>내용</태그>	HTML 태그 직접 사용

이 표는 마크다운의 기본 문법부터 확장 문법까지 포괄적으로 정리한 것입니다. 일부 확장 문법(체크박스, 각주, 정의 목록 등)은 사용하는 마크다운 파서에 따라 지원 여부가 다를 수 있습니다.

8. 마크다운 문법을 배울 수 있는 사이트

1. 직접 실습하며 하나하나 문법을 배우는 사이트
   • 마크다운 튜토리얼 - markdown tutorial
   • 정말 놀라운 사이트 입니다...ㄷㄷ
2. 마크다운 튜토리얼 사이트
   • 마크다운 랭 - markdown lang

9. FAQ

Q: 마크다운을 배우는 데 얼마나 걸리나요? A: 기본 문법은 10-15분이면 충분히 익힐 수 있습니다. 헤딩, 강조, 리스트, 링크 같은 핵심 기능만 알아도 대부분의 문서를 작성할 수 있습니다. 고급 기능들은 필요할 때마다 찾아보면서 자연스럽게 익히게 됩니다. 실제로 사용하면서 배우는 것이 가장 빠른 방법이므로, 오늘부터 간단한 메모나 문서를 마크다운으로 작성해보세요.

Q: 마크다운으로 작성한 문서를 PDF로 변환할 수 있나요? A: 네, 여러 방법이 있습니다. Pandoc은 마크다운을 PDF, DOCX, HTML 등 다양한 형식으로 변환해주는 강력한 도구입니다. VS Code의 Markdown PDF 확장을 사용하면 클릭 한 번으로 PDF를 생성할 수 있습니다. Typora 같은 에디터도 내장된 PDF 내보내기 기능을 제공합니다. 온라인에서는 Markdown to PDF 같은 웹 서비스를 이용할 수도 있습니다.

Q: GitHub Flavored Markdown(GFM)은 일반 마크다운과 어떻게 다른가요? A: GFM은 GitHub에서 사용하는 마크다운의 확장 버전입니다. 기본 마크다운에 표, 취소선, 체크리스트, 자동 링크, 이모지 같은 기능을 추가했습니다. 코드 블록에서 문법 강조도 지원하며, 이슈 번호나 커밋 해시를 자동으로 링크로 변환해줍니다. GFM은 GitHub뿐만 아니라 GitLab, Bitbucket 등 많은 플랫폼에서 표준으로 채택되었습니다.

Q: 마크다운으로 프레젠테이션을 만들 수 있나요? A: 네, Marp, reveal.js, Slidev 같은 도구를 사용하면 마크다운으로 슬라이드를 만들 수 있습니다. 일반 마크다운 문법으로 작성하고, 수평선으로 슬라이드를 구분하면 됩니다. 코드 예제가 많은 기술 프레젠테이션에 특히 유용하며, 버전 관리와 협업도 쉽게 할 수 있습니다. VS Code의 Marp 확장을 설치하면 실시간 미리보기를 보면서 슬라이드를 작성할 수 있습니다.

Q: 마크다운의 한계는 무엇인가요? A: 마크다운은 의도적으로 기능을 제한했기 때문에 복잡한 레이아웃이나 정교한 디자인은 어렵습니다. 표의 셀 병합, 이미지 크기 조절, 폰트 색상 변경 같은 기능은 기본적으로 지원하지 않습니다. 이런 경우 HTML을 직접 삽입하거나 CSS를 사용해야 합니다. 하지만 이런 제약이 오히려 콘텐츠에 집중하게 만들어주며, 대부분의 문서 작성에는 충분한 기능을 제공합니다.

10. 마무리

위에서 설명한 마크다운 문법과 활용법을 정리하면 다음과 같습니다.

핵심 요약:

• 마크다운은 누구나 10분이면 배울 수 있는 간단한 텍스트 포맷으로, HTML 지식 없이도 깔끔한 문서를 작성할 수 있습니다.
• 헤딩, 강조, 리스트, 링크, 이미지, 코드 블록 같은 핵심 문법만 알아도 대부분의 문서 작성이 가능합니다.
• GitHub, Notion, Discord 등 수많은 플랫폼에서 마크다운을 지원하므로, 한 번 배워두면 여러 곳에서 활용할 수 있습니다.
• 블로그, 기술 문서, README, 노트 작성 등 다양한 용도로 사용할 수 있으며, PDF나 HTML로 쉽게 변환할 수 있습니다.
• VS Code, Typora 같은 훌륭한 에디터들이 마크다운 작성을 더욱 편리하게 만들어줍니다.

오늘부터 마크다운으로 문서를 작성해보세요. 처음에는 기본 문법만 사용하다가 점차 고급 기능을 추가하면 됩니다. 마크다운을 익히는 가장 좋은 방법은 직접 사용하는 것입니다. 간단한 메모나 할 일 목록부터 시작해서, 블로그 글이나 프로젝트 문서로 확장해나가세요. 마크다운은 당신의 문서 작성 효율을 크게 높여줄 것입니다.