여러분은 혹시 이런 경험이 있으십니까? 깃허브에서 프로젝트를 보다가 README 파일이 깔끔하게 정리된 것을 보고 "저건 어떻게 만든 거지?"라고 궁금해하신 적이요. 또는 노션에서 동료가 번개처럼 빠르게 문서를 작성하는 것을 보면서 "도대체 어떻게 저렇게 빨리 쓰는 거야?"라고 부러워하신 적은요. 아니면 마크다운이라는 단어를 어디선가 들어는 봤는데, 무슨 프로그래밍 언어 같은 것이라서 나와는 상관없다고 넘겨버리신 적은 없으십니까?
만약 이 중 하나라도 해당된다면, 이 책은 바로 여러분을 위해 쓴 것입니다.
마크다운은 프로그래밍 언어가 아닙니다. 코딩 능력이 전혀 필요하지 않습니다. 마크다운은 그저 글을 쓸 때 기호 몇 개를 함께 사용하여 제목, 굵은 글씨, 목록, 링크 같은 서식을 지정하는 아주 간단한 약속 체계일 뿐입니다. 여러분이 이메일을 쓸 수 있다면, 마크다운도 쓸 수 있습니다. 정말입니다.
그런데도 많은 분들이 마크다운을 어렵다고 생각하시는 이유가 있습니다. 기존의 마크다운 가이드들이 대부분 프로그래머를 대상으로 쓰여져 있기 때문이지요. "HTML 변환", "파서(parser)", "렌더러(renderer)" 같은 기술 용어가 처음부터 쏟아지면, 비전공자는 첫 페이지에서 이미 의욕을 잃어버리게 됩니다. 이 책은 그런 접근을 철저히 거부합니다. 이 책은 마크다운이라는 단어조차 처음 듣는 완전 초보자가, 이 책 한 권만으로 마크다운의 모든 핵심 문법을 이해하고 즉시 활용할 수 있도록 설계되었습니다.
이 책은 단순히 문법을 나열하는 레퍼런스 매뉴얼이 아닙니다. 왜 마크다운을 알아야 하는지부터 시작하여, 마크다운이 어떻게 탄생했는지, 어떤 원리로 작동하는지, 실제로 어떻게 쓰는지, 어디에서 활용할 수 있는지까지 -- 마크다운에 대한 모든 것을 처음부터 끝까지 완전히 이해시키는 것이 이 책의 목표입니다. 모든 문법은 에디터에서 바로 따라 할 수 있는 실습 예제와 함께 제공되며, 각 챕터 말미에는 배운 내용을 즉시 연습해볼 수 있는 실습 코너를 마련해두었습니다.
이 책을 다 읽고 나면, 여러분은 마크다운의 모든 핵심 문법을 자유자재로 사용할 수 있게 될 것입니다. 깃허브에서 전문적인 README를 작성하고, 노션에서 번개처럼 문서를 만들고, 블로그에 깔끔한 글을 올리고, AI 도구와 더 효과적으로 소통할 수 있게 될 것입니다. 그리고 무엇보다, 왜 전 세계 사람들이 마크다운에 열광하는지를 몸으로 체감하게 될 것입니다.
자, 그렇다면 지금 바로 시작하겠습니다. 준비되셨지요?
기초편
왜 마크다운인가
워드프로세서의 한계와 마크다운의 등장
여러분은 문서를 작성할 때 어떤 도구를 사용하십니까? 아마 대부분의 분들은 마이크로소프트 워드, 한글(HWP), 또는 구글 독스 같은 워드프로세서를 떠올리실 것입니다. 화면에 글자를 입력하고, 마우스로 드래그해서 선택한 다음, 도구 모음에서 굵게(B) 버튼을 클릭하면 글씨가 굵어지는 방식이지요. 이것을 전문 용어로 WYSIWYG 방식이라고 합니다. What You See Is What You Get, 즉 '보이는 대로 결과물이 나온다'는 뜻인데요, 우리가 워드프로세서에서 경험하는 바로 그 방식입니다.
그런데 이 WYSIWYG 방식에는 치명적인 한계가 몇 가지 있습니다. 얼핏 생각하면 "보이는 대로 편집하는 게 가장 편한 거 아닌가?" 하고 생각하실 수 있는데요, 현실은 전혀 그렇지 않습니다. 그 이유를 하나씩 살펴보겠습니다.
첫째, 워드프로세서로 만든 문서는 특정 프로그램에 종속됩니다. 마이크로소프트 워드로 작성한 .docx 파일은 워드가 없으면 제대로 열리지 않는 경우가 많습니다. 물론 구글 독스나 다른 프로그램에서 열 수는 있지만, 서식이 깨지거나 레이아웃이 틀어지는 일이 비일비재하지요. 여러분도 혹시 중요한 문서를 다른 컴퓨터에서 열었더니 글꼴이 바뀌어 있거나 표가 엉망이 된 경험이 있지 않으십니까? 바로 이것이 워드프로세서의 가장 큰 약점입니다.
둘째, 워드프로세서 파일은 용량이 크고 무겁습니다. .docx 파일 하나의 용량이 수백 킬로바이트에서 수 메가바이트에 달하는 것은 흔한 일입니다. 왜냐하면 워드프로세서는 글자 하나하나에 글꼴, 크기, 색상, 간격 등 수많은 서식 정보를 함께 저장하기 때문입니다. 반면에 마크다운으로 작성한 문서는 순수한 텍스트 파일이기 때문에 동일한 내용이라면 용량이 10분의 1도 안 되는 경우가 대부분이지요.
셋째, 그리고 이것이 가장 중요한 문제인데, 워드프로세서는 '글쓰기'보다 '꾸미기'에 시간을 더 쓰게 만듭니다. 여러분이 보고서를 작성한다고 가정해봅시다. 제목의 크기를 몇 포인트로 할지, 본문은 어떤 글꼴을 쓸지, 줄 간격은 얼마나 벌릴지, 들여쓰기는 어떻게 할지 -- 이런 서식 작업에 실제 글쓰기 시간만큼, 때로는 그 이상의 시간을 쏟게 되는 경험을 누구나 해보셨을 것입니다. 이것은 단순히 시간 낭비의 문제가 아닙니다. 글의 내용에 집중해야 할 에너지가 서식 조정에 빼앗기는 것이기 때문에, 결과적으로 글의 질까지 떨어뜨리는 구조적인 문제인 것입니다.
자, 그렇다면 이런 문제들을 어떻게 해결할 수 있을까요? 바로 여기서 마크다운이 등장합니다. 마크다운은 일반 텍스트에 아주 간단한 기호 몇 개만 추가하면 제목, 굵은 글씨, 목록, 링크 등의 서식이 자동으로 적용되는 경량 마크업 언어입니다. 쉽게 말해서, 워드프로세서의 굵게(B) 버튼을 클릭하는 대신에 글자 앞뒤에 별표 두 개를 붙이면 되는 것이지요. 예를 들어 굵은 글씨라고 입력하면 굵은 글씨로 표시됩니다. 이것이 전부입니다.
혹시 이렇게 생각하셨다면 큰 오산입니다 -- "에이, 그게 뭐가 편한 거야? 버튼 한 번 클릭하는 게 더 쉽잖아." 그 생각이 틀린 것은 아닙니다. 한두 번의 서식 지정이라면 마우스 클릭이 더 빠를 수도 있습니다. 하지만 문서를 본격적으로 작성하기 시작하면 상황이 완전히 달라집니다. 마크다운은 키보드에서 손을 떼지 않고 글을 쓰면서 동시에 서식을 지정할 수 있기 때문에, 글쓰기의 흐름이 끊기지 않습니다. 이것은 실제로 써보면 그 차이가 얼마나 큰지 즉시 체감할 수 있는 부분입니다.
노션, 깃허브, 블로그에서 마크다운이 필수인 이유
마크다운을 배워야 하는 가장 현실적인 이유는 바로 이것입니다 -- 이미 여러분이 사용하고 있거나 앞으로 사용하게 될 거의 모든 플랫폼이 마크다운을 기본 문서 형식으로 채택하고 있다는 사실입니다. 이것은 과장이 아닙니다. 한 번 확인해 볼까요?
먼저 깃허브(GitHub) 를 보겠습니다. 깃허브는 전 세계에서 가장 많이 사용되는 코드 저장소이자 협업 플랫폼입니다. 프로그래머가 아닌 분들도 한 번쯤은 이름을 들어보셨을 것입니다. 깃허브에서 프로젝트를 만들면 가장 먼저 해야 하는 일이 바로 README.md 파일을 작성하는 것인데요, 이 .md 확장자가 바로 마크다운 파일을 의미합니다. 프로젝트의 설명, 설치 방법, 사용법 등을 마크다운으로 작성하면 깃허브가 자동으로 예쁘게 렌더링해서 보여줍니다. 다시 말해, 깃허브를 사용하려면 마크다운은 선택이 아니라 필수인 것입니다.
다음으로 노션(Notion) 을 살펴보겠습니다. 노션은 문서 작성, 프로젝트 관리, 데이터베이스 등 다양한 기능을 하나로 합친 올인원 생산성 도구로, 최근 몇 년 사이에 폭발적으로 사용자가 늘어난 플랫폼이지요. 노션에서 글을 쓸 때 슬래시(/) 명령어를 사용하면 다양한 블록을 추가할 수 있는데, 이 과정에서 마크다운 문법이 그대로 작동합니다. 제목을 만들 때 # 을 입력하면 즉시 제목 블록으로 변환되고, 으로 감싸면 굵은 글씨가 되는 식이지요. 마크다운을 알면 노션에서의 작업 속도가 2배 이상 빨라진다고 해도 과언이 아닙니다.
그 밖에도 옵시디언(Obsidian) 이라는 개인 지식 관리 도구는 아예 마크다운 파일을 기반으로 동작하고, 디스코드(Discord) 에서 채팅할 때도 마크다운 문법으로 글자를 꾸밀 수 있으며, 레딧(Reddit) 에서 게시글을 작성할 때도 마크다운이 사용됩니다. 기술 블로그를 운영하는 플랫폼인 벨로그(Velog) 나 티스토리의 마크다운 모드, 정적 사이트 생성기인 지킬(Jekyll) 이나 휴고(Hugo) 도 마크다운을 핵심 포맷으로 사용하지요.
어떻습니까? 이제 왜 마크다운이 필수인지 감이 좀 오시지요? 마크다운은 더 이상 프로그래머들만의 전유물이 아닙니다. 글을 쓰고, 문서를 만들고, 온라인에서 소통하는 모든 사람에게 필요한 기본 리터러시, 즉 기초 소양이 된 것입니다.
마크다운을 모르면 놓치는 것들
마크다운을 모르면 구체적으로 어떤 손해를 보게 될까요? 이 질문에 대한 답은 매우 현실적입니다.
첫째, 협업에서 뒤처집니다. 요즘 IT 업계뿐만 아니라 많은 산업에서 깃허브, 노션, 슬랙(Slack) 같은 도구를 활용한 협업이 표준이 되고 있습니다. 이런 도구들의 공통점이 무엇인지 아시겠습니까? 바로 마크다운을 기본 문서 포맷으로 사용한다는 것입니다. 마크다운을 모르면 팀원들이 작성한 문서를 이해하기 어렵고, 자신이 작성한 문서는 서식 없이 밋밋하게 보여서 전문성이 떨어져 보이게 됩니다.
둘째, 생산성에서 큰 차이가 납니다. 앞서 말씀드린 것처럼 마크다운은 키보드만으로 글쓰기와 서식 지정을 동시에 할 수 있기 때문에, 워드프로세서로 같은 문서를 만드는 것보다 체감상 1.5배에서 2배 정도 빠릅니다. 하루에 30분씩만 아껴도 한 달이면 15시간이 절약되는 셈이지요. 이 시간을 더 생산적인 일에 투자할 수 있다는 것은 결코 작은 차이가 아닙니다.
셋째, AI 시대에 마크다운은 더욱 중요해지고 있습니다. 2026년 현재, ChatGPT나 Claude 같은 대규모 언어 모델(LLM)들은 대부분 마크다운 형식으로 답변을 출력합니다. AI가 생성한 텍스트를 제대로 읽고, 편집하고, 활용하려면 마크다운 문법을 알아야 합니다. 뿐만 아니라 AI에게 구조적인 프롬프트를 작성할 때도 마크다운을 활용하면 훨씬 더 정확한 결과를 얻을 수 있지요. 바로 이런 이유 때문에 마크다운은 AI 시대의 필수 언어라고까지 불리는 것입니다.
넷째, 자신의 콘텐츠를 어디서든 자유롭게 활용할 수 있습니다. 마크다운 파일은 순수한 텍스트 파일이기 때문에 어떤 운영체제에서든, 어떤 프로그램에서든 열 수 있습니다. 워드프로세서처럼 특정 소프트웨어에 종속되지 않으므로, 10년 후에도 20년 후에도 동일하게 열어볼 수 있는 것이지요. 마크다운으로 작성한 콘텐츠는 블로그에도, 이메일에도, 전자책에도, 기술 문서에도 즉시 활용할 수 있습니다. 한 번 작성하면 어디서든 쓸 수 있는 진정한 범용 포맷인 것입니다.
자, 여기까지 왜 마크다운을 알아야 하는지에 대해 살펴보았습니다. 핵심을 정리하면, 마크다운은 이미 전 세계 디지털 글쓰기의 표준이 되었으며, 이를 모르면 협업, 생산성, AI 활용 등 여러 영역에서 뒤처지게 된다는 것입니다. 하지만 다행히도 마크다운은 놀라울 정도로 배우기 쉽습니다. 그 이유를 다음 장에서 마크다운의 탄생 배경과 함께 자세히 알아보겠습니다.
마크다운은 어떻게 탄생했는가
존 그루버와 에런 스워츠, 마크다운을 만들다
마크다운은 2004년, 존 그루버라는 한 블로거의 불만에서 시작되었습니다. 존 그루버(John Gruber)는 미국의 기술 블로거이자 UI 디자이너로, 'Daring Fireball'이라는 유명 블로그를 운영하고 있었습니다. 그는 블로그에 글을 쓰는 것을 무척 좋아했지만, 한 가지 커다란 불편함이 있었습니다. 웹에 글을 올리려면 HTML이라는 마크업 언어로 서식을 일일이 지정해야 했던 것이지요.
여기서 잠깐, HTML이란 무엇인지 간단히 짚고 넘어가겠습니다. HTML은 HyperText Markup Language의 약자로, 웹페이지를 만드는 데 사용되는 표준 언어입니다. 예를 들어 웹에서 굵은 글씨를 표시하려면 <strong>굵은 글씨</strong> 이렇게 써야 합니다. 제목을 만들려면 <h1>제목</h1> 이런 식이지요. 여러분이 보시기에 어떻습니까? 이런 태그들이 글 중간에 잔뜩 섞여 있으면 글을 쓰는 것도 힘들지만, 무엇보다 자기가 쓴 글을 다시 읽을 때 내용이 눈에 잘 들어오지 않습니다. 바로 이 지점이 존 그루버의 핵심적인 불만이었습니다.
존 그루버는 훗날 이렇게 회고했습니다 -- HTML을 알고 있었기 때문에 기술적으로 글을 쓰는 데 문제는 없었지만, 시간이 지나면서 점점 번거롭게 느껴졌고, 무엇보다 HTML 태그 때문에 자기 글을 교정하기가 어려웠다고 말이지요. 그래서 그는 결심합니다. "일반 텍스트로 쓰는데 서식도 지정할 수 있고, 그 텍스트 자체만 봐도 어떤 서식이 적용될지 직관적으로 알 수 있는 문법을 만들겠다"고 말입니다.
이 프로젝트에 결정적인 역할을 한 또 한 명의 인물이 있습니다. 바로 에런 스워츠(Aaron Swartz) 입니다. 에런 스워츠는 당시 불과 17~18세의 나이였지만, RSS 규격 개발에 참여하고, 크리에이티브 커먼즈(Creative Commons) 설립에 기여하는 등 인터넷 기술 분야에서 이미 천재적인 활약을 보이고 있던 프로그래머이자 인터넷 활동가였습니다. 존 그루버는 에런 스워츠를 자신의 '사운딩 보드', 즉 아이디어를 주고받는 파트너로 삼아 마크다운의 문법을 다듬어 나갔습니다.
그리하여 2004년 12월 17일, 존 그루버는 자신의 블로그 Daring Fireball에 마크다운의 규격 문서와 함께 Markdown.pl이라는 펄(Perl) 스크립트를 공개합니다. 이 스크립트는 마크다운 문법으로 작성된 텍스트를 HTML로 자동 변환해주는 프로그램이었습니다. 이것이 마크다운의 공식적인 탄생 순간이지요.
마크다운이라는 이름 자체에도 철학이 담겨 있습니다. 'Markup'이라는 단어를 비틀어 'Markdown'으로 명명한 것인데요, 'Mark up'이 태그를 달아 올린다는 의미라면, 'Mark down'은 그 반대로 최대한 태그를 줄여 내린다는 의미를 담고 있습니다. 즉, 마크다운의 이름 자체가 "복잡한 마크업을 최대한 단순하게 낮추겠다"는 철학을 선언하고 있는 셈이지요.
HTML과 마크다운의 관계
많은 분들이 오해하시는 것 중 하나가, 마크다운이 HTML을 대체하는 것이라고 생각하시는 점입니다. 혹시 그렇게 생각하셨다면, 이 부분은 명확히 짚고 넘어가야 합니다. 마크다운은 HTML을 대체하는 것이 아니라, HTML을 더 쉽게 작성하기 위한 도구입니다.
이것을 이해하려면 마크다운이 실제로 어떻게 작동하는지 알아야 합니다. 여러분이 마크다운으로 # 제목이라고 쓰면, 마크다운 변환기가 이것을 <h1>제목</h1>이라는 HTML 코드로 자동 변환합니다. 굵은 글씨는 <strong>굵은 글씨</strong>로 변환되지요. 다시 말해, 마크다운은 HTML의 앞단에서 작동하는 일종의 '속기법'이라고 생각하시면 됩니다.
이 관계를 일상적인 비유로 설명해보겠습니다. HTML이 정식 공문서를 작성하는 것이라면, 마크다운은 메모장에 빠르게 요점을 적는 것과 같습니다. 메모장의 내용을 기반으로 정식 공문서를 자동으로 만들어주는 비서가 있다고 상상해보세요. 여러분은 메모만 하면 되고, 비서가 알아서 공문서 양식에 맞춰 완성해주는 것이지요. 이때 메모가 마크다운이고, 공문서가 HTML이며, 비서가 마크다운 변환기인 것입니다.
따라서 마크다운의 존재가 HTML의 가치를 떨어뜨리는 것은 전혀 아닙니다. 오히려 마크다운 덕분에 HTML을 몰라도 웹에서 구조적인 문서를 만들 수 있게 된 것이므로, 마크다운은 HTML의 접근성을 획기적으로 낮춘 공신이라고 할 수 있습니다.
한 가지 재미있는 점은, 마크다운 문서 안에서 HTML 태그를 직접 사용하는 것도 가능하다는 것입니다. 마크다운 문법만으로는 표현하기 어려운 복잡한 서식이 필요할 때, HTML 태그를 그대로 삽입하면 마크다운 변환기가 이를 그대로 통과시켜줍니다. 이처럼 마크다운과 HTML은 서로 적대적인 관계가 아니라, 상호 보완적인 관계인 것이지요.
왜 전 세계가 마크다운을 선택했는가
마크다운이 2004년에 등장한 이후, 불과 20여 년 만에 전 세계 디지털 글쓰기의 사실상 표준이 된 것은 결코 우연이 아닙니다. 그 이유를 깊이 들여다보면, 마크다운의 성공에는 매우 명확한 원리가 있습니다.
첫 번째 이유는 극단적인 단순함입니다. 마크다운의 핵심 문법은 10개 남짓에 불과합니다. 제목을 만드는 # 기호, 굵게를 만드는 기호, 기울임을 만드는 * 기호, 목록을 만드는 - 기호, 링크를 만드는 [] () 기호 정도만 기억하면 일상적인 문서 작성에 필요한 서식의 대부분을 해결할 수 있습니다. 이렇게 배우기 쉬운 문법 체계가 진입 장벽을 극적으로 낮춘 것이지요.
두 번째 이유는 가독성입니다. 존 그루버가 마크다운을 설계할 때 가장 중시한 원칙이 바로 이것이었습니다 -- "렌더링하지 않은 원문 상태에서도 읽기 쉬워야 한다." 예를 들어 HTML에서 <h1>제목</h1>이라고 쓰면 태그가 눈에 거슬리지만, 마크다운에서 # 제목이라고 쓰면 # 기호가 자연스럽게 "이것은 제목입니다"라고 알려주면서도 글 읽기를 방해하지 않습니다. 이메일을 쓸 때 중요한 단어를 별표로 감싸는 습관은 인터넷 초창기부터 있었는데, 마크다운은 바로 이런 자연스러운 관습을 문법으로 체계화한 것입니다.
세 번째 이유는 플랫폼 독립성입니다. 마크다운 파일은 확장자가 .md인 순수 텍스트 파일입니다. 윈도우에서도, 맥에서도, 리눅스에서도, 심지어 스마트폰의 메모장 앱에서도 열 수 있습니다. 특정 프로그램이 없으면 열지 못하는 .docx나 .hwp 파일과는 근본적으로 다른 것이지요. 이 플랫폼 독립성이 깃허브, 레딧, 스택 오버플로우 같은 글로벌 플랫폼들이 마크다운을 선택한 결정적인 이유이기도 합니다.
네 번째 이유는 확장성입니다. 마크다운의 기본 문법은 매우 단순하지만, 필요에 따라 기능을 추가할 수 있도록 설계되었습니다. 존 그루버는 의도적으로 중괄호 {} 같은 기호를 문법에 사용하지 않았는데, 이는 나중에 각 플랫폼이 자기만의 확장 기능을 추가할 수 있도록 여지를 남겨둔 것이었습니다. 실제로 깃허브는 GFM(GitHub Flavored Markdown)이라는 확장 규격을 만들어 테이블, 체크리스트, 취소선 같은 기능을 추가했고, 2014년에는 CommonMark라는 표준 규격이 등장하여 마크다운의 모호했던 부분들을 명확하게 정의하게 되었지요.
이처럼 마크다운은 단순히 "쉬워서" 유행한 것이 아닙니다. 단순함, 가독성, 플랫폼 독립성, 확장성이라는 네 가지 핵심 요소가 맞물려서 전 세계적으로 채택된 것입니다. 그리고 이 네 가지 요소는 곧 여러분이 마크다운을 배울 때 느끼게 될 장점이기도 합니다. 자, 이제 마크다운의 배경을 충분히 이해하셨으니, 다음 장에서는 실제로 마크다운을 써볼 수 있는 실습 환경을 준비해보겠습니다.
실습 환경 준비
추천 온라인 에디터 소개
마크다운을 배우는 가장 빠른 방법은 직접 써보는 것입니다. 그런데 아직 마크다운이 무엇인지도 잘 모르는 상태에서 에디터 프로그램을 설치하고 설정하는 것은 부담스러울 수 있지요. 그래서 이 장에서는 아무것도 설치할 필요 없이, 웹 브라우저만 열면 바로 마크다운을 연습할 수 있는 온라인 에디터를 소개해드리겠습니다. 여러분은 이 중 하나를 골라서 열어놓고, 이 책의 내용을 따라 하면서 실습하시면 됩니다.
첫 번째로 추천드리는 에디터는 StackEdit입니다. 주소는 stackedit.io 이고, 접속하면 별도의 회원가입이나 로그인 없이 바로 마크다운 편집을 시작할 수 있습니다. StackEdit의 가장 큰 장점은 화면이 왼쪽과 오른쪽으로 나뉘어 있다는 점입니다. 왼쪽에 마크다운 문법으로 글을 입력하면, 오른쪽에 그 결과가 실시간으로 렌더링되어 나타납니다. 즉, 여러분이 # 제목이라고 입력하는 순간 오른쪽 화면에 큰 제목이 나타나는 것이지요. 이 '실시간 미리보기' 기능이 마크다운을 처음 배우는 분들에게는 가장 중요한 기능입니다. 왜냐하면 자신이 입력한 문법이 실제로 어떻게 보이는지 즉시 확인할 수 있기 때문이지요.
StackEdit는 GFM(GitHub Flavored Markdown)과 CommonMark 등 다양한 마크다운 규격을 지원하고, 수학 수식(LaTeX), 다이어그램, 이모지까지 입력할 수 있습니다. 또한 구글 드라이브, 드롭박스, 깃허브와 연동하여 작성한 문서를 저장할 수도 있어서, 나중에 마크다운에 익숙해진 후에도 계속 사용할 수 있는 본격적인 에디터이기도 합니다. 왕초보에게 가장 강력하게 추천하는 에디터입니다.
두 번째로 추천드리는 에디터는 Dillinger입니다. 주소는 dillinger.io 이고, StackEdit와 마찬가지로 웹 브라우저에서 바로 사용할 수 있습니다. Dillinger의 특징은 인터페이스가 매우 깔끔하고 단순하다는 것인데요, 화면이 딱 두 개의 패널로 나뉘어 편집 영역과 미리보기 영역만 보여주기 때문에 초보자가 헤맬 여지가 거의 없습니다. 드롭박스, 구글 드라이브, 원드라이브, 깃허브 등과 연동이 가능하고, 작성한 마크다운 파일을 HTML이나 PDF로 내보내는 기능도 제공합니다.
세 번째로 소개해드릴 에디터는 Markdown Live Preview입니다. 주소는 markdownlivepreview.dev 이고, 이름 그대로 마크다운을 입력하면 실시간으로 미리보기를 제공하는 아주 심플한 도구입니다. 회원가입도 필요 없고, 접속하면 바로 왼쪽 패널에 마크다운을 입력하고 오른쪽에서 결과를 확인할 수 있습니다. 다른 부가 기능은 최소한이지만, 순수하게 마크다운 문법만 연습하고 싶을 때 가장 부담 없이 사용할 수 있는 에디터라고 할 수 있습니다.
아니, 이것 중에 어떤 걸 써야 해? 너무 많은데?
걱정하지 마세요. 처음 시작하시는 분이라면 StackEdit를 여시면 됩니다. 나머지는 나중에 취향에 따라 바꿔보시면 되는 것이고, 지금 당장은 하나만 열어서 이 책을 따라 하시면 충분합니다.
에디터 화면 구성과 사용법
자, 그렇다면 실제로 StackEdit에 접속해서 화면 구성을 살펴보겠습니다. 웹 브라우저를 열고 주소창에 stackedit.io 를 입력한 뒤 엔터를 누르세요. 메인 페이지가 나타나면 'Start Writing' 또는 편집 화면으로 진입하는 버튼을 클릭합니다.
편집 화면에 들어오면 크게 두 개의 영역이 보입니다. 왼쪽이 편집 영역(Editor)이고, 오른쪽이 미리보기 영역(Preview) 입니다. 편집 영역에는 마크다운 문법 그대로의 텍스트가 표시되고, 미리보기 영역에는 그 텍스트가 실제로 렌더링된 결과가 표시됩니다. 이 두 영역의 스크롤은 서로 동기화되어 있어서, 왼쪽에서 아래로 스크롤하면 오른쪽도 같은 위치로 따라옵니다.
편집 영역 상단에는 도구 모음(Toolbar)이 있는데, 여기에는 굵게, 기울임, 링크 삽입 등의 버튼이 있습니다. 하지만 이 버튼들은 마크다운 문법을 모르는 사람을 위한 보조 도구일 뿐이고, 우리는 이 책에서 문법을 직접 배울 것이므로 도구 모음은 무시하셔도 됩니다. 오히려 도구 모음에 의존하지 않고 직접 문법을 타이핑하는 것이 마크다운을 가장 빨리 익히는 방법입니다.
화면 왼쪽 가장자리에는 파일 탐색기와 같은 사이드바가 있을 수 있는데, 이것은 여러 개의 마크다운 파일을 관리하는 기능입니다. 지금은 신경 쓰지 않으셔도 됩니다. 중요한 것은 오직 편집 영역에 마크다운을 입력하고, 미리보기 영역에서 결과를 확인하는 것, 이 두 가지뿐입니다.
Dillinger를 사용하시는 분도 화면 구성은 거의 동일합니다. 왼쪽에 편집, 오른쪽에 미리보기 -- 이 구조는 대부분의 온라인 마크다운 에디터가 공통으로 채택하고 있는 표준적인 레이아웃이지요.
첫 번째 마크다운 문서 작성해보기
이제 정말로 마크다운을 처음 써보겠습니다. 아직 문법을 본격적으로 배우지는 않았지만, 맛보기로 아주 간단한 것만 해볼 것이니 긴장하지 마세요.
StackEdit(또는 여러분이 선택한 에디터)의 편집 영역에 있는 기존 텍스트를 모두 지우고, 다음과 같이 입력해보세요.
# 나의 첫 번째 마크다운 문서
안녕하세요! 이것은 제가 처음으로 작성하는 마크다운 문서입니다.
## 오늘 배운 것
마크다운은 *정말 쉽습니다*.
## 다음에 배울 것
- 제목 만들기
- 글씨 꾸미기
- 목록 만들기입력을 마쳤으면 오른쪽 미리보기 영역을 확인해보세요. 어떻습니까? # 뒤에 쓴 텍스트가 큰 제목으로 표시되고, ## 뒤에 쓴 텍스트는 좀 더 작은 제목으로 표시되는 것을 확인할 수 있을 것입니다. 별표 두 개로 감싼 '마크다운 문서'는 굵은 글씨로 나타나고, 별표 하나로 감싼 '정말 쉽습니다'는 기울어진 글씨로 나타나지요. 그리고 - 뒤에 쓴 항목들은 깔끔한 목록으로 정리되어 보일 것입니다.
이것이 마크다운의 전부입니다 -- 물론, 과장입니다. 이보다 더 많은 문법이 있습니다. 하지만 핵심적인 원리는 방금 여러분이 직접 체험한 그대로입니다. 기호를 붙이면 서식이 적용된다. 이것만 기억하시면 됩니다.
혹시 결과가 제대로 나타나지 않는다면, 다음 사항을 확인해보세요. # 기호 뒤에 반드시 한 칸의 공백을 넣으셨는지, 기호와 글자 사이에 불필요한 공백이 없는지, 그리고 - 기호 뒤에도 한 칸의 공백이 있는지 확인하시면 대부분의 문제가 해결됩니다. 마크다운에서는 이 '공백 한 칸'이 생각보다 중요한 역할을 하는데, 이 부분은 이후 장에서 더 자세히 다루겠습니다.
축하합니다! 여러분은 방금 생애 첫 마크다운 문서를 작성하셨습니다. 이제 실습 환경도 갖추었으니, 다음 장부터 본격적으로 마크다운의 핵심 원리와 문법을 하나씩 정복해 나가겠습니다.
마크다운 핵심 원리
기호 하나로 서식을 지정하는 원리
마크다운 문법의 근본 원리는 놀라울 정도로 단순합니다 -- 특정 기호를 특정 위치에 놓으면, 그 기호가 서식으로 변환된다는 것입니다. 이것이 마크다운의 대원칙이자, 여러분이 이 책 전체를 통해 가장 먼저 이해해야 할 핵심 개념입니다.
이 원리를 더 쉽게 이해하기 위해 비유를 하나 들어보겠습니다. 여러분이 친구에게 손편지를 쓴다고 가정해봅시다. 중요한 단어는 밑줄을 긋고, 제목은 크게 쓰고, 여러 가지를 나열할 때는 앞에 동그라미를 찍는 것이 자연스럽지요. 마크다운은 바로 이런 자연스러운 관습을 디지털 세계에서 체계화한 것입니다. 손편지에서 밑줄을 긋는 대신 별표 두 개를 붙이고, 제목을 크게 쓰는 대신 # 기호를 앞에 놓고, 동그라미 대신 - 기호를 사용하는 것뿐이지요.
그렇다면 왜 하필 이런 기호들을 선택한 것일까요? 그 이유는 앞서 설명한 마크다운의 핵심 철학과 연결됩니다. "렌더링하지 않은 원문 상태에서도 서식의 의도가 직관적으로 드러나야 한다"는 것이지요. # 기호를 보면 '뭔가 강조하는 것' 같은 느낌이 들고, 별표로 감싸면 '특별히 강조하는 것' 같은 느낌이 들고, - 기호를 쭉 나열하면 '목록' 같은 느낌이 듭니다. 이처럼 기호 자체가 서식의 의미를 암시하도록 설계된 것이 마크다운 문법의 가장 뛰어난 점이라고 할 수 있습니다.
마크다운 문법은 크게 두 가지 유형으로 나눌 수 있습니다.
첫 번째는 블록 요소입니다. 블록 요소는 문서의 큰 구조를 결정하는 것으로, 제목, 문단, 목록, 인용문, 코드 블록 등이 여기에 해당합니다. 블록 요소의 특징은 기호가 줄의 맨 앞에 위치한다는 것입니다. 예를 들어 # 기호는 줄의 맨 앞에 놓아야 제목으로 인식되고, - 기호도 줄의 맨 앞에 놓아야 목록 항목으로 인식됩니다.
두 번째는 인라인 요소입니다. 인라인 요소는 문장 안에서 특정 단어나 구절의 서식을 변경하는 것으로, 굵게, 기울임, 인라인 코드, 링크 등이 여기에 해당합니다. 인라인 요소의 특징은 기호가 텍스트를 감싸는 형태로 사용된다는 것입니다. 예를 들어 굵게는 별표 두 개로 텍스트를 감싸고, 기울임은 별표 하나로 감쌉니다.
이 두 가지 유형만 구분할 수 있으면, 마크다운 문법의 전체 체계가 한눈에 들어오게 됩니다. 반드시 기억해두세요.
마크다운 문법의 전체 구조 한눈에 보기
마크다운의 핵심 문법은 크게 7가지 범주로 나눌 수 있습니다. 아직 각각의 세부 문법은 배우지 않았지만, 전체 그림을 먼저 머릿속에 넣어두면 이후에 개별 문법을 배울 때 '아, 이것은 전체 구조에서 이 자리에 해당하는 것이구나'라고 이해할 수 있어서 학습 효율이 크게 올라갑니다. 두괄식으로 먼저 전체를 조감하고, 이후 각론으로 파고드는 방식이지요.
첫 번째 범주는 제목(Header) 입니다. 문서의 구조를 잡는 가장 기본적인 요소로, # 기호를 사용합니다. #의 개수에 따라 제목의 단계가 달라지는데, #이 하나면 가장 큰 제목, 여섯 개면 가장 작은 제목이 됩니다. 이것만 알면 문서의 뼈대를 세울 수 있습니다.
두 번째 범주는 텍스트 강조 입니다. 굵게(), 기울임(*), 취소선(~~) 등이 여기에 해당합니다. 문장 안에서 특정 단어나 구절을 시각적으로 강조할 때 사용합니다.
세 번째 범주는 목록(List) 입니다. 순서 없는 목록(-, *, +)과 순서 있는 목록(1., 2., 3.)으로 나뉩니다. 정보를 체계적으로 나열해야 할 때 필수적인 요소이지요.
네 번째 범주는 링크와 이미지 입니다. 하이퍼링크는 텍스트 형식으로, 이미지는 형식으로 삽입합니다. 웹 문서에서 빠질 수 없는 요소이지요.
다섯 번째 범주는 인용문(Blockquote) 입니다. > 기호를 줄 앞에 놓으면 인용문이 됩니다. 다른 사람의 말을 인용하거나, 특정 내용을 강조하여 별도의 블록으로 표시할 때 사용합니다.
여섯 번째 범주는 코드(Code) 입니다. 인라인 코드는 백틱(`) 하나로, 코드 블록은 백틱 세 개(```)로 감쌉니다. 프로그래밍과 관련된 문서를 작성할 때 특히 중요하지만, 일반 문서에서도 명령어나 파일명 등을 표시할 때 유용합니다.
일곱 번째 범주는 테이블(Table) 입니다. 파이프(|) 기호와 하이픈(-)을 조합하여 표를 만듭니다. 이것은 기본 마크다운에는 없었으나, GFM 등의 확장 규격에서 추가된 기능이지요.
어떻습니까? 이렇게 전체 구조를 먼저 보니, "아, 마크다운에서 배워야 할 것은 결국 이 7가지뿐이구나"라는 생각이 드시지 않습니까? 실제로 그렇습니다. 마크다운은 7가지 범주의 문법만 알면 됩니다. 각각의 세부 문법도 기호 한두 개를 기억하는 것이 전부이니, 전체 학습량이 놀라울 정도로 적은 것이지요.
렌더링이란 무엇인가
마크다운을 배우면서 가장 자주 듣게 될 단어 중 하나가 바로 '렌더링(Rendering)'입니다. 이 개념을 확실히 이해해두어야 이후 내용을 따라가는 데 혼란이 없으므로, 여기서 명확하게 짚고 넘어가겠습니다.
렌더링이란, 마크다운 문법으로 작성된 원본 텍스트를 실제 서식이 적용된 최종 화면으로 변환하여 보여주는 과정을 말합니다. 쉽게 비유하자면, 건축의 설계도와 완공된 건물의 관계를 생각하시면 됩니다. 마크다운으로 작성한 텍스트는 설계도이고, 렌더링된 결과물은 완공된 건물인 것이지요. 설계도에는 '#'이나 '' 같은 기호들이 보이지만, 완공된 건물(렌더링된 화면)에서는 이 기호들이 사라지고 대신 큰 제목이나 굵은 글씨가 나타나는 것입니다.
앞서 StackEdit에서 실습할 때 보셨던 것을 떠올려보세요. 왼쪽 편집 영역에는 # 제목이라고 기호가 그대로 보였지만, 오른쪽 미리보기 영역에서는 기호가 사라지고 큰 제목이 표시되었지요. 왼쪽이 원본(마크다운 소스)이고, 오른쪽이 렌더링 결과인 것입니다.
이 개념을 이해하는 것이 중요한 이유가 있습니다. 마크다운 문서를 작성할 때, 여러분이 보는 것은 항상 '원본'입니다. 기호가 섞여 있는 텍스트를 보면서 글을 쓰게 됩니다. 하지만 이 문서를 최종적으로 읽는 사람이 보는 것은 '렌더링 결과'이지요. 따라서 마크다운을 잘 쓰려면 원본 상태에서 "이 기호가 렌더링되면 어떻게 보일까?"를 머릿속으로 그릴 수 있어야 합니다. 처음에는 어렵게 느껴질 수 있지만, 실습을 몇 번만 해보면 자연스럽게 감이 잡히는 부분이니 걱정하지 마세요.
또 한 가지 알아두어야 할 것은, 렌더링 결과는 플랫폼마다 약간씩 다를 수 있다는 점입니다. 같은 마크다운 문법을 사용해도 깃허브에서 렌더링한 결과와 노션에서 렌더링한 결과가 글꼴이나 간격, 색상 등에서 차이가 있을 수 있습니다. 이것은 마크다운 자체의 문제가 아니라, 각 플랫폼이 적용하는 CSS 스타일이 다르기 때문입니다. 마크다운은 "이것은 제목입니다", "이것은 굵은 글씨입니다"라고 구조만 지정할 뿐, 실제로 어떤 글꼴로, 어떤 크기로, 어떤 색상으로 보여줄지는 각 플랫폼이 결정하는 것이지요.
자, 여기까지 마크다운의 핵심 원리를 모두 살펴보았습니다. 기호로 서식을 지정한다는 대원칙, 블록 요소와 인라인 요소라는 두 가지 유형, 7가지 핵심 범주, 그리고 렌더링의 개념까지 이해하셨다면, 이제 개별 문법을 배울 준비가 완료된 것입니다. 다음 장부터 드디어 본격적인 문법 정복에 들어갑니다.
핵심 문법편
제목과 문단 -- 글의 뼈대 세우기
제목(헤더) 만들기
문서를 작성할 때 가장 먼저 해야 할 일은 무엇입니까? 바로 제목을 정하고, 문서의 구조를 잡는 것입니다. 마크다운에서는 # 기호를 사용하여 제목을 만드는데, 이것을 '헤더(Header)'라고 부릅니다. 마크다운의 모든 문법 중에서 가장 자주 쓰이고, 가장 먼저 배워야 할 문법이지요.
사용법은 극도로 간단합니다. 줄의 맨 앞에 # 기호를 넣고, 한 칸 띄운 다음, 제목으로 쓸 텍스트를 입력하면 됩니다. 그런데 여기서 중요한 점이 하나 있습니다. # 기호의 개수에 따라 제목의 단계(레벨)가 달라집니다. # 하나면 1단계 제목(가장 큰 제목), ## 두 개면 2단계 제목, ### 세 개면 3단계 제목, 이런 식으로 최대 ###### 여섯 개까지 사용할 수 있습니다.
실제로 에디터에 입력해보겠습니다.
# 1단계 제목 (가장 큰 제목)
## 2단계 제목
### 3단계 제목
#### 4단계 제목
##### 5단계 제목
###### 6단계 제목오른쪽 미리보기를 확인해보세요. #이 하나인 제목이 가장 크게 표시되고, #이 늘어날수록 제목의 크기가 점점 작아지는 것을 확인하실 수 있을 것입니다. 이것은 HTML의 <h1> ~ <h6> 태그와 정확히 대응됩니다. # 하나가 <h1>, ## 두 개가 <h2>, 이런 식이지요.
아니, 그냥 글씨 크기만 달라지는 거잖아? 그걸 왜 6단계나 나눠놓은 거야?
좋은 질문입니다. 제목 단계를 나누는 것은 단순히 글씨 크기를 조절하기 위한 것이 아닙니다. 제목 단계는 문서의 논리적 구조를 결정합니다. 1단계 제목은 문서 전체의 제목이고, 2단계 제목은 큰 챕터의 제목이며, 3단계 제목은 그 안의 소주제, 4단계는 더 세부적인 항목, 이런 식으로 문서의 계층 구조를 형성하는 것이지요. 마치 책의 목차가 "1부 > 1장 > 1절 > 가항"으로 나뉘는 것과 같은 원리입니다.
이 구조가 중요한 현실적인 이유가 있습니다. 많은 플랫폼에서 마크다운 문서의 헤더를 자동으로 읽어서 목차(Table of Contents, TOC)를 생성해줍니다. 깃허브의 README 파일에서 헤더 구조대로 목차가 자동 생성되는 것이 대표적인 예이지요. 따라서 헤더를 논리적으로 잘 구성해두면 문서의 가독성뿐만 아니라 탐색성까지 크게 향상됩니다.
헤더를 사용할 때 반드시 기억해야 할 규칙이 두 가지 있습니다. 첫째, # 기호와 제목 텍스트 사이에 반드시 공백 한 칸을 넣어야 합니다. #제목이라고 붙여 쓰면 헤더로 인식되지 않는 경우가 많습니다. 둘째, 헤더 단계를 건너뛰지 마세요. 1단계 제목 바로 아래에 3단계 제목이 오면 문서 구조가 논리적으로 맞지 않게 됩니다. 1단계 → 2단계 → 3단계 순서로 자연스럽게 내려가는 것이 올바른 사용법입니다.
문단 나누기와 줄바꿈
마크다운에서 문단을 나누는 방법은 의외로 많은 초보자가 헷갈려하는 부분입니다. 워드프로세서에서는 엔터(Enter) 키를 한 번 누르면 줄이 바뀌고, 두 번 누르면 문단이 나뉘지요. 하지만 마크다운에서는 조금 다르게 작동합니다.
마크다운에서 새로운 문단을 시작하려면, 빈 줄을 하나 넣어야 합니다. 즉, 엔터 키를 두 번 눌러서 빈 줄이 하나 생기면 그때 비로소 새로운 문단으로 인식됩니다. 이것을 에디터에서 직접 확인해보겠습니다.
이것은 첫 번째 문단입니다.
이것은 두 번째 문단입니다.위와 같이 입력하면, 미리보기에서 두 문장이 서로 다른 문단으로 표시되는 것을 확인할 수 있습니다. 그런데 만약 빈 줄 없이 엔터를 한 번만 누르면 어떻게 될까요?
이것은 첫 번째 줄입니다.
이것은 두 번째 줄입니다.이렇게 입력하면, 놀랍게도 두 줄이 하나의 문단으로 합쳐져서 한 줄로 표시됩니다. 이것은 마크다운 초보자가 가장 자주 당황하는 부분인데요, 마크다운에서 단순히 엔터를 한 번 누르는 것은 '줄바꿈'이 아니라 '같은 문단 내의 연속된 텍스트'로 처리되기 때문입니다.
그렇다면 문단을 나누지 않고 단순히 줄만 바꾸고 싶을 때는 어떻게 해야 할까요? 이때는 줄 끝에 공백 두 칸을 넣거나, <br> HTML 태그를 사용합니다. 줄 끝에 공백 두 칸을 넣는 방법은 눈에 보이지 않아서 실수하기 쉽기 때문에, 개인적으로는 <br> 태그를 사용하는 것을 권장합니다. 하지만 가장 흔하게 사용되는 방법은 역시 빈 줄을 넣어서 새 문단을 시작하는 것이므로, "문단을 나누려면 빈 줄 하나"라는 규칙만 확실히 기억하시면 충분합니다.
수평선으로 구역 나누기
문서가 길어지면 내용을 시각적으로 구분해야 할 때가 있습니다. 이때 사용하는 것이 바로 수평선(Horizontal Rule)입니다. 마크다운에서 수평선을 만드는 방법은 매우 간단합니다. 하이픈(-), 별표(), 또는 밑줄(_) 중 하나를 세 개 이상 연속으로 입력하면 됩니다.
---
***
___위의 세 가지 방법 중 어느 것을 사용해도 결과는 동일합니다. 미리보기에서 가로로 길게 뻗은 선이 나타나는 것을 확인하실 수 있을 것입니다. 실무에서는 --- (하이픈 세 개)를 가장 많이 사용하는데, 타이핑하기 가장 편하기 때문이지요.
수평선은 보통 글의 주제가 크게 전환될 때, 또는 부록이나 참고사항을 본문과 구분할 때 사용합니다. 다만, 너무 자주 사용하면 오히려 문서가 산만해 보일 수 있으므로, 정말 필요한 경우에만 절제해서 사용하는 것이 좋습니다.
주의할 점이 하나 있는데, 수평선을 입력할 때는 반드시 앞뒤로 빈 줄을 넣어주세요. 특히 수평선 바로 위에 텍스트가 있으면, 일부 마크다운 변환기에서 수평선이 아닌 2단계 제목으로 해석할 수 있습니다. 이것은 마크다운의 대체 헤더 문법 때문인데요, 세부적인 내용은 지금 단계에서 알 필요는 없고, "수평선 앞뒤로 빈 줄 넣기"만 기억하시면 됩니다.
지금 당장 연습해보기
여기까지 배운 내용을 바로 실습해봅시다. StackEdit를 열고 다음 내용을 직접 타이핑해보세요.
# 나의 자기소개서
## 기본 정보
안녕하세요, 저는 마크다운을 배우고 있는 초보자입니다.
오늘 처음으로 마크다운 문법을 배웠습니다.
## 오늘 배운 것
오늘은 제목 만드는 법과 문단 나누는 법을 배웠습니다.
### 제목
제목은 # 기호로 만들 수 있습니다.
### 문단
문단을 나누려면 빈 줄을 넣으면 됩니다.
---
## 마치며
마크다운은 정말 쉽습니다!입력을 마쳤으면 미리보기를 확인하세요. 제목의 단계가 제대로 구분되는지, 문단이 올바르게 나뉘는지, 수평선이 제대로 표시되는지 확인해보세요. 혹시 기대한 대로 나타나지 않는 부분이 있다면, # 뒤의 공백, 빈 줄의 유무, 수평선 앞뒤의 빈 줄을 점검해보시기 바랍니다. 이 세 가지를 확인하면 대부분의 문제가 해결됩니다.
강조와 서식 -- 텍스트 꾸미기
볼드체와 이탤릭체
글을 쓸 때 특정 단어나 문구를 강조하고 싶은 경우는 정말 많습니다. 워드프로세서에서는 텍스트를 드래그해서 선택한 다음 도구 모음의 B(굵게) 버튼이나 I(기울임) 버튼을 클릭하지요. 마크다운에서는 이것을 별표(*) 기호만으로 해결합니다.
굵은 글씨(볼드체)를 만들려면, 강조하고 싶은 텍스트를 별표 두 개로 감싸면 됩니다. 에디터에서 직접 입력해보세요.
이것은 굵은 글씨입니다미리보기를 확인하면 이것은 굵은 글씨입니다라고 굵게 표시되는 것을 볼 수 있습니다. 별표 대신 밑줄 두 개(텍스트)를 사용해도 동일한 결과를 얻을 수 있지만, 실무에서는 별표 두 개를 압도적으로 많이 사용합니다.
기울어진 글씨(이탤릭체)를 만들려면, 별표 하나로 감싸면 됩니다.
*이것은 기울어진 글씨입니다*미리보기에서 이것은 기울어진 글씨입니다라고 기울어져서 표시되는 것을 확인할 수 있지요. 역시 밑줄 하나(텍스트)를 사용해도 되지만, 별표가 더 보편적입니다.
그렇다면 굵으면서 동시에 기울어진 글씨를 만들려면 어떻게 해야 할까요? 별표 세 개로 감싸면 됩니다.
*이것은 굵고 기울어진 글씨입니다*정리하면, 별표 하나 = 기울임, 별표 두 개 = 굵게, 별표 세 개 = 굵게 + 기울임입니다. 이 규칙은 매우 직관적이어서 한 번만 외우면 잊어버리기 어렵습니다.
한 가지 주의할 점이 있습니다. 별표와 텍스트 사이에 공백이 있으면 안 됩니다. 이것은 틀림 처럼 별표와 텍스트 사이에 공백을 넣으면 굵게 처리되지 않는 경우가 많습니다. 반드시 이것이 맞음처럼 별표가 텍스트에 딱 붙어 있어야 합니다.
취소선과 기타 서식
취소선은 텍스트에 가로줄을 긋는 서식으로, 틸데(~) 기호 두 개로 텍스트를 감싸면 됩니다. 이것은 기본 마크다운 문법에는 없었지만, GFM(GitHub Flavored Markdown)에서 추가된 확장 문법이며, 현재 대부분의 마크다운 렌더러가 지원합니다.
~~이것은 취소선입니다~~미리보기를 확인하면 ~~이것은 취소선입니다~~처럼 텍스트 위에 가로줄이 그어진 것을 볼 수 있습니다. 취소선은 가격 변경을 표시하거나("~~기존가 50,000원~~ → 신규가 39,000원"), 수정된 내용을 표시할 때("~~어제의 계획~~ 오늘의 현실") 유용하게 사용됩니다.
그 밖에 마크다운에서 자주 사용되는 서식으로는 인라인 코드가 있습니다. 백틱() 하나로 텍스트를 감싸면 고정폭 글꼴로 표시되는데, 이것은 프로그래밍 코드나 명령어, 파일명 등을 본문 중간에 표시할 때 사용합니다. 예를 들어 "설정 파일은 config.json`에 있습니다"라고 쓰면, config.json 부분이 코드 형태로 구분되어 표시되지요. 인라인 코드에 대해서는 이후 코드 챕터에서 더 자세히 다루겠습니다.
인용문 활용하기
인용문(Blockquote)은 다른 출처의 텍스트를 인용하거나, 특정 내용을 시각적으로 구분하여 강조할 때 사용하는 서식입니다. 사용법은 매우 간단한데, 줄의 맨 앞에 > 기호를 넣으면 됩니다.
> 이것은 인용문입니다.
> 인용문은 이렇게 여러 줄에 걸쳐 작성할 수 있습니다.미리보기를 확인하면, 텍스트 왼쪽에 세로줄이 생기고 들여쓰기가 적용된 형태로 표시될 것입니다. 이것이 인용문의 기본적인 모습이지요.
인용문 안에 다시 인용문을 넣을 수도 있는데, 이를 중첩 인용문이라고 합니다.
> 이것은 첫 번째 레벨 인용문입니다.
>> 이것은 두 번째 레벨 인용문입니다.
>>> 이것은 세 번째 레벨 인용문입니다.기호를 하나 추가할 때마다 인용의 깊이가 한 단계씩 들어가는 것이지요. 실무에서는 보통 두 단계까지만 사용하고, 세 단계 이상은 가독성이 떨어지므로 거의 사용하지 않습니다.
인용문은 꼭 다른 사람의 말을 인용할 때만 쓰는 것은 아닙니다. 주의사항, 팁, 참고 정보 등을 본문과 시각적으로 구분할 때도 매우 유용합니다. 예를 들어 이 책에서도 독자의 가상 질문을 표시할 때 인용문을 사용하고 있지요.
인용문 안에서는 다른 마크다운 문법도 자유롭게 사용할 수 있습니다. 제목, 굵은 글씨, 목록 등을 인용문 안에 넣을 수 있어서 표현력이 매우 풍부해집니다.
지금 당장 연습해보기
에디터를 열고 다음을 직접 타이핑하여 결과를 확인해보세요.
# 텍스트 서식 연습
## 강조 표현
이 문장에서 중요한 부분은 굵게 표시합니다.
*기울임*을 사용하면 약간 다른 느낌을 줄 수 있습니다.
*굵으면서 기울어진* 표현도 가능합니다.
## 취소선
~~이것은 더 이상 유효하지 않은 정보입니다~~
## 인용문
> 마크다운의 창시자 존 그루버는 이렇게 말했습니다.
> 쉽게 읽을 수 있고, 쉽게 쓸 수 있는 일반 텍스트 형식이 목표였다고요.
>> 이것은 중첩된 인용문입니다.미리보기에서 각 서식이 올바르게 적용되는지 확인해보세요. 특히 별표 개수에 따라 서식이 어떻게 달라지는지, 취소선이 제대로 표시되는지, 인용문의 시각적 구분이 명확한지 주목하시기 바랍니다.
목록 -- 정보를 정리하는 기술
순서 없는 목록
정보를 체계적으로 정리할 때 가장 유용한 도구가 바로 목록(List)입니다. 마크다운에서 목록을 만드는 방법은 두 가지가 있는데, 먼저 순서 없는 목록부터 살펴보겠습니다.
순서 없는 목록(Unordered List)은 줄의 맨 앞에 하이픈(-), 별표(), 또는 플러스(+) 기호를 넣고 한 칸 띄운 다음 내용을 입력하면 됩니다.에디터에서 직접 입력해보세요.
- 사과
- 바나나
- 딸기미리보기를 확인하면, 각 항목 앞에 동그란 점(불릿)이 붙어서 깔끔한 목록으로 표시되는 것을 볼 수 있습니다. 하이픈 대신 별표(*)나 플러스(+)를 사용해도 결과는 완전히 동일합니다. 실무에서는 하이픈(-)을 가장 많이 사용하므로, 하이픈으로 통일하여 익히시는 것을 권장합니다.
목록 안에 하위 목록을 넣을 수도 있는데, 이것을 중첩 목록이라고 합니다. 하위 목록을 만들려면 해당 항목 앞에 공백 두 칸 또는 탭(Tab) 한 번을 넣어 들여쓰기를 하면 됩니다.
- 과일
- 사과
- 바나나
- 채소
- 당근
- 브로콜리미리보기를 확인하면, '사과'와 '바나나'가 '과일' 아래에 들여쓰기되어 하위 항목으로 표시되는 것을 볼 수 있습니다. 이처럼 중첩 목록을 활용하면 정보의 계층 구조를 시각적으로 표현할 수 있어서 매우 유용합니다.
순서 있는 목록
순서가 중요한 정보를 나열할 때는 순서 있는 목록(Ordered List)을 사용합니다. 숫자 뒤에 마침표(.)를 찍고 한 칸 띄운 다음 내용을 입력하면 됩니다.
1. 첫 번째 단계
2. 두 번째 단계
3. 세 번째 단계미리보기를 확인하면 각 항목 앞에 1, 2, 3 숫자가 순서대로 붙어서 표시됩니다. 여기서 한 가지 재미있는 사실이 있는데요, 마크다운에서 순서 있는 목록의 번호는 실제로 몇 번을 입력하든 상관없이, 렌더링될 때 자동으로 순서대로 매겨진다는 점입니다.
1. 첫 번째
1. 두 번째
1. 세 번째위와 같이 전부 1번으로 입력해도, 렌더링 결과는 1, 2, 3으로 자동 정렬됩니다. 이것은 나중에 목록 항목의 순서를 바꾸거나 중간에 새 항목을 추가할 때 번호를 일일이 수정할 필요가 없다는 뜻이므로, 실무에서 매우 편리한 기능이지요. 다만, 가독성을 위해 원본에서도 올바른 번호를 매기는 것이 일반적인 관례입니다.
순서 있는 목록도 중첩이 가능합니다. 들여쓰기 규칙은 순서 없는 목록과 동일합니다. 그리고 순서 있는 목록과 순서 없는 목록을 섞어서 사용하는 것도 가능합니다.
1. 아침 루틴
- 기상
- 세수
- 아침 식사
2. 오후 루틴
- 점심 식사
- 업무
3. 저녁 루틴
- 운동
- 독서이처럼 순서 있는 목록의 하위 항목으로 순서 없는 목록을 넣으면, 단계별 정보를 매우 깔끔하게 정리할 수 있습니다.
체크리스트 만들기
체크리스트(Task List)는 할 일 목록이나 체크 항목을 만들 때 사용하는 문법입니다. 이것은 기본 마크다운에는 없었지만 GFM에서 추가된 확장 문법으로, 현재 깃허브, 노션 등 대부분의 플랫폼에서 지원합니다.
사용법은 순서 없는 목록의 - 기호 뒤에 대괄호 한 쌍을 추가하는 것입니다. 빈 대괄호 [ ]는 미완료 항목을, 대괄호 안에 x를 넣은 [x]는 완료 항목을 나타냅니다.
- [ ] 마크다운 기초 문법 배우기
- [x] 에디터 설치하기
- [ ] 첫 번째 문서 작성하기
- [x] 온라인 에디터 접속하기미리보기를 확인하면, 각 항목 앞에 체크박스가 나타나고, [x]로 표시한 항목은 체크가 되어 있는 것을 볼 수 있습니다. 일부 플랫폼(특히 깃허브)에서는 렌더링된 체크박스를 클릭하여 실시간으로 완료/미완료를 전환할 수도 있지요.
아, 그러면 이거 노션에서도 쓸 수 있는 거야?
네, 노션에서도 체크리스트 문법이 작동합니다. 다만 노션은 자체적인 /todo 블록도 제공하고 있어서, 마크다운 문법과 노션의 고유 기능 중 편한 것을 선택해서 사용하시면 됩니다. 두 가지 방법을 다 알고 있으면 상황에 따라 더 빠른 방식을 선택할 수 있으니, 마크다운 체크리스트 문법도 반드시 알아두시는 것이 좋습니다.
지금 당장 연습해보기
에디터를 열고 다음을 직접 작성해보세요. 순서 없는 목록, 순서 있는 목록, 중첩 목록, 체크리스트를 모두 활용하는 연습입니다.
# 이번 주 계획
## 할 일 목록
- [ ] 마크다운 전자책 완독
- [x] 온라인 에디터 세팅
- [ ] 깃허브 계정 만들기
## 학습 순서
1. 제목과 문단
2. 텍스트 강조
3. 목록
- 순서 없는 목록
- 순서 있는 목록
- 체크리스트
4. 링크와 이미지
5. 코드와 테이블
## 준비물
- 노트북 또는 데스크톱
- 웹 브라우저(크롬 권장)
- 인터넷 연결
- 이 전자책
- 연습할 시간 30분모든 목록이 미리보기에서 올바르게 표시되는지 확인해보세요. 특히 중첩 목록의 들여쓰기가 제대로 적용되는지, 체크리스트의 체크박스가 정상적으로 표시되는지 꼼꼼히 확인하시기 바랍니다.
고급 문법편
링크와 이미지 -- 콘텐츠 연결하기
하이퍼링크 삽입
웹 문서의 가장 큰 특징은 다른 문서로의 연결, 즉 하이퍼링크가 가능하다는 것입니다. 마크다운에서 하이퍼링크를 만드는 방법은 대괄호와 소괄호를 조합하는 것인데, 처음 보면 조금 복잡해 보일 수 있지만 원리를 이해하면 매우 직관적입니다.
기본 문법은 표시할 텍스트 형식입니다. 대괄호 [] 안에 화면에 보여줄 텍스트를 넣고, 바로 뒤에 이어서 소괄호 () 안에 이동할 웹 주소를 넣으면 됩니다.
[구글](https://www.google.com)
[네이버](https://www.naver.com)미리보기를 확인하면 '구글'과 '네이버'라는 텍스트가 링크로 변환되어 클릭할 수 있는 상태가 된 것을 볼 수 있습니다. 클릭하면 해당 웹사이트로 이동하지요.
이 문법의 구조를 한 번 더 분해해서 보겠습니다. 대괄호는 '사용자가 보는 것'이고, 소괄호는 '기계가 보는 것'이라고 기억하시면 됩니다. 대괄호 안의 텍스트는 화면에 표시되어 사용자가 읽게 되는 것이고, 소괄호 안의 URL은 실제로 이동할 주소로서 렌더링 후에는 보이지 않게 되는 것이지요.
링크에 마우스를 올렸을 때 나타나는 툴팁(제목)을 추가할 수도 있습니다. 소괄호 안에서 URL 뒤에 공백을 넣고 따옴표로 감싼 텍스트를 추가하면 됩니다.
[구글](https://www.google.com "세계 최대 검색 엔진")이렇게 하면 마우스를 링크 위에 올렸을 때 "세계 최대 검색 엔진"이라는 툴팁이 표시됩니다. 자주 사용되는 기능은 아니지만, 알아두면 유용한 경우가 있습니다.
또한 URL을 그대로 링크로 만들고 싶을 때는 꺽쇠 괄호(<>)로 감싸면 됩니다.
<https://www.google.com>이렇게 하면 URL 자체가 그대로 클릭 가능한 링크로 표시됩니다. GFM에서는 꺽쇠 괄호 없이 URL만 입력해도 자동으로 링크로 변환되는 자동 링크(Autolink) 기능을 지원하지만, 모든 마크다운 변환기가 이를 지원하는 것은 아니므로 명시적으로 표기하는 것이 안전합니다.
이미지 삽입
마크다운에서 이미지를 삽입하는 문법은 링크 문법과 거의 동일합니다. 차이점은 단 하나, 맨 앞에 느낌표(!)를 추가한다는 것뿐입니다.
여기서 '대체 텍스트'는 이미지가 로딩되지 않을 때 대신 표시되는 텍스트이자, 시각 장애인이 스크린 리더를 사용할 때 읽히는 텍스트입니다. 웹 접근성을 위해 매우 중요한 요소이므로, 가능하면 이미지의 내용을 간결하게 설명하는 텍스트를 넣어주는 것이 좋습니다.
실제 예시를 보겠습니다.
이렇게 입력하면 미리보기 영역에 마크다운 로고 이미지가 표시됩니다. 물론 이미지 URL이 실제로 접근 가능한 주소여야 이미지가 정상적으로 표시되지요.
링크 문법과 이미지 문법의 관계를 정리하면 이렇습니다 -- 링크는 텍스트이고, 이미지는 입니다. 느낌표가 하나 추가된 것뿐이지요. 이 둘의 관계를 기억하면 절대 헷갈리지 않습니다. 왜 느낌표일까요? "이봐, 여기 이미지가 있다!"고 알려주는 느낌이라고 기억하시면 됩니다.
링크와 이미지의 고급 활용
이미지에 링크를 걸 수 있다는 사실을 아시면, 표현의 폭이 크게 넓어집니다. 이미지를 클릭하면 특정 웹사이트로 이동하게 만드는 것인데, 문법은 링크의 대괄호 안에 이미지 문법을 넣는 것입니다.
[](링크URL)처음 보면 복잡해 보이지만, 분해하면 간단합니다. 바깥의 은 링크이고, 안의 은 이미지입니다. 즉, "링크로 표시할 텍스트 자리에 이미지를 넣은 것"이지요.
또 하나 알아두면 유용한 것이 참조 스타일 링크입니다. 문서 안에 같은 URL이 여러 번 등장하는 경우, 매번 전체 URL을 쓰는 것은 비효율적이고 원본 텍스트의 가독성도 떨어뜨립니다. 이때 참조 스타일을 사용하면 깔끔하게 정리할 수 있습니다.
[구글][1]은 세계 최대 검색 엔진이고, [네이버][2]는 한국 최대 검색 엔진입니다.
[1]: https://www.google.com
[2]: https://www.naver.com본문에서는 [텍스트][참조ID] 형식으로 짧게 쓰고, 문서 하단에 [참조ID]: URL 형식으로 실제 주소를 모아두는 방식입니다. 이렇게 하면 본문의 가독성이 크게 향상되고, URL을 수정해야 할 때 하단의 한 곳만 바꾸면 되므로 유지보수에도 유리합니다.
지금 당장 연습해보기
에디터를 열고 다음을 직접 작성해보세요.
# 링크와 이미지 연습
## 유용한 링크 모음
마크다운을 더 배우고 싶다면 [CommonMark 공식 사이트](https://commonmark.org)를 방문해보세요.
온라인 에디터로는 [StackEdit](https://stackedit.io)를 추천합니다.
## 이미지 삽입
아래는 위키피디아의 마크다운 아이콘입니다.
## 자동 링크
바로 방문하려면: <https://stackedit.io>링크가 클릭 가능한 상태로 표시되는지, 이미지가 올바르게 나타나는지 확인해보세요. 이미지가 표시되지 않는다면 URL이 정확한지, 인터넷 연결이 되어 있는지 확인해보시기 바랍니다.
코드와 테이블 -- 전문 문서 작성하기
인라인 코드와 코드 블록
마크다운이 프로그래머들 사이에서 폭발적으로 인기를 얻은 가장 큰 이유 중 하나는 코드를 아름답게 표시하는 기능 때문입니다. 하지만 이 기능은 프로그래머만을 위한 것이 아닙니다. 일반 문서에서도 명령어, 파일명, 변수명, 설정값 등을 본문과 구분하여 표시할 때 매우 유용하게 사용되지요.
먼저 인라인 코드(Inline Code) 부터 보겠습니다. 인라인 코드는 문장 안에 짧은 코드나 명령어를 삽입할 때 사용합니다. 백틱(`) 하나로 텍스트를 감싸면 됩니다. 백틱은 키보드에서 숫자 1 왼쪽, ESC 키 바로 아래에 있는 키입니다. 물결표(~)와 같은 키에 있지요.
설정 파일을 수정하려면 `config.json` 파일을 열어주세요.
터미널에서 `npm install` 명령어를 실행합니다.미리보기를 확인하면, 백틱으로 감싼 부분이 고정폭 글꼴로, 약간 다른 배경색을 가진 형태로 표시되는 것을 볼 수 있습니다. 이렇게 하면 일반 텍스트와 코드/명령어를 시각적으로 명확하게 구분할 수 있지요.
다음으로 코드 블록(Code Block) 을 보겠습니다. 여러 줄에 걸친 코드를 표시하려면 백틱 세 개(```)를 사용합니다. 시작 줄에 백틱 세 개를 입력하고, 코드를 작성한 다음, 마지막 줄에 다시 백틱 세 개를 입력하면 됩니다.
function hello() {
console.log("Hello, Markdown!");}
미리보기에서 코드 전체가 별도의 블록으로 표시되고, 고정폭 글꼴이 적용되며, 들여쓰기가 그대로 유지되는 것을 확인할 수 있습니다.
여기서 한 가지 더 알아두면 매우 유용한 기능이 있습니다. 시작하는 백틱 세 개 바로 뒤에 프로그래밍 언어의 이름을 적으면, 해당 언어에 맞는 구문 강조(Syntax Highlighting)가 적용됩니다.
```python
def hello():
print("Hello, Markdown!")
function hello() {
console.log("Hello, Markdown!");
}
이렇게 하면 예약어, 문자열, 주석 등이 서로 다른 색상으로 표시되어 코드의 가독성이 크게 향상됩니다. python, javascript, html, css, java, c, bash 등 거의 모든 주요 프로그래밍 언어가 지원됩니다.
프로그래밍을 하지 않는 분이라도 이 기능을 활용할 수 있습니다. 예를 들어 JSON 설정 파일이나 터미널 명령어를 문서에 포함시킬 때 코드 블록을 사용하면 깔끔하게 표시할 수 있지요.
### 테이블 작성법
테이블(표)은 데이터를 행과 열로 구조화하여 보여줄 때 사용하는 문법입니다. 이것은 기본 마크다운에는 없었지만 GFM에서 추가된 확장 문법으로, 현재 대부분의 마크다운 플랫폼에서 지원합니다.
테이블은 파이프(|) 기호로 열을 구분하고, 하이픈(-)으로 헤더와 본문 사이를 구분합니다. 파이프 기호는 키보드에서 백스페이스(Backspace) 키 왼쪽의 \ 키를 Shift와 함께 누르면 입력됩니다.| 기호 | 용도 | 예시 |
|---|---|---|
| # | 제목 | # 제목 |
| ** | 굵게 | 굵게 |
| * | 기울임 | 기울임 |
| - | 목록 | - 항목 |
| > | 인용문 | > 인용 |
미리보기를 확인하면, 깔끔한 표가 생성된 것을 볼 수 있습니다. 첫 번째 줄이 테이블의 헤더(제목 행)이고, 두 번째 줄의 `---`가 헤더와 본문을 구분하는 구분선이며, 세 번째 줄부터가 데이터 행입니다.
테이블 정렬도 가능합니다. 구분선에서 콜론(:)의 위치에 따라 정렬 방향이 결정됩니다.| 왼쪽 정렬 | 가운데 정렬 | 오른쪽 정렬 |
|---|---|---|
| 데이터 | 데이터 | 데이터 |
| 왼쪽 | 가운데 | 오른쪽 |
`:---`는 왼쪽 정렬, `:---:`는 가운데 정렬, `---:`는 오른쪽 정렬을 의미합니다. 숫자 데이터는 오른쪽 정렬, 텍스트는 왼쪽 정렬, 제목은 가운데 정렬로 하는 것이 일반적인 관례이지요.
> 아니, 이거 작성하기 너무 번거롭지 않아? 파이프를 일일이 맞추려면 시간이 엄청 걸릴 것 같은데?
솔직히 말씀드리면, 마크다운 테이블은 원본 상태에서 정렬을 맞추는 것이 다소 번거로운 것은 사실입니다. 하지만 실제로는 파이프의 위치가 정확하게 맞지 않아도 렌더링에는 문제가 없습니다. 각 셀의 내용만 파이프로 제대로 구분되어 있으면 렌더링 결과는 동일하지요. 그리고 StackEdit 같은 에디터에는 테이블 자동 정렬 기능이 있고, 온라인 테이블 생성기를 활용하면 더욱 쉽게 테이블을 만들 수 있습니다.
### 이스케이프 문자
마크다운에서 #, *, -, [ ] 같은 기호들은 특별한 의미를 가진 문법 기호로 사용됩니다.*그런데 만약 이런 기호를 서식이 아닌 일반 텍스트로 그대로 표시하고 싶다면 어떻게 해야 할까요? 예를 들어 "가격은 $100이고, 할인율은 50%입니다"라고 쓸 때 * 기호를 그대로 보여주고 싶다면 말이지요.
이때 사용하는 것이 이스케이프 문자(Escape Character)입니다. 마크다운에서 이스케이프 문자는 백슬래시()입니다. 특별한 의미를 가진 기호 앞에 백슬래시를 놓으면, 그 기호가 문법으로 해석되지 않고 일반 텍스트로 표시됩니다.이것은 제목이 아닙니다
이것은 기울어지지 않습니다
이것은 목록이 아닙니다
미리보기를 확인하면, # 기호가 제목으로 변환되지 않고 그대로 표시되고, * 기호도 기울임으로 변환되지 않는 것을 볼 수 있습니다.
이스케이프가 가능한 기호는 다음과 같습니다 -- 백슬래시(), 백틱(`), 별표(*), 밑줄(_), 중괄호(\{ \}), 대괄호([ ]), 소괄호(( )), 해시(#), 플러스(+), 하이픈(-), 마침표(\.), 느낌표(\!), 파이프(\|) 등입니다. 실무에서 가장 자주 이스케이프해야 하는 기호는 별표(*)와 해시(#)이므로, 이 두 가지만 확실히 기억해두시면 대부분의 상황에서 문제없이 해결할 수 있습니다.
#### 지금 당장 연습해보기
에디터를 열고 다음을 직접 작성해보세요.코드와 테이블 연습
인라인 코드
마크다운에서 굵은 글씨를 만들려면 텍스트 문법을 사용합니다.
코드 블록
아래는 HTML로 "Hello"를 출력하는 코드입니다.
```html
Hello, World!
마크다운으로 변환되기 전의 HTML입니다.
```
마크다운 문법 정리 테이블
| 서식 | 문법 | 결과 |
|---|---|---|
| 굵게 | 텍스트 | 텍스트 |
| 기울임 | 텍스트 | 텍스트 |
| 취소선 | ~~텍스트~~ | ~~텍스트~~ |
이스케이프 연습
마크다운에서 # 기호를 그대로 표시하려면 앞에 백슬래시를 붙입니다.
별표도 이스케이프할 수 있습니다.
코드 블록이 올바르게 표시되는지, 테이블이 깔끔하게 렌더링되는지, 이스케이프가 정상 작동하는지 확인해보세요.
## GFM 확장 문법
### GFM이란 무엇인가
앞서 마크다운의 역사를 설명할 때, 존 그루버의 원래 마크다운 규격에는 몇 가지 부족한 점이 있었다고 말씀드렸습니다. 테이블, 취소선, 체크리스트 같은 기능이 없었던 것이지요. 이 빈자리를 채운 것이 바로 GFM, 즉 GitHub Flavored Markdown입니다.
GFM은 깃허브가 2009년경부터 사용하기 시작한 마크다운의 확장 규격인데요, 2017년에 공식적인 규격 문서를 발표하면서 명실상부한 마크다운 확장 표준으로 자리 잡았습니다. GFM은 CommonMark를 기반으로 하고 있으며, CommonMark의 모든 문법을 그대로 포함하면서 추가적인 기능을 확장한 것입니다. 쉽게 말해서, GFM은 기본 마크다운의 상위 호환 버전이라고 이해하시면 됩니다.
GFM이 중요한 이유는 단순히 깃허브에서만 사용되기 때문이 아닙니다. 현재 대부분의 마크다운 에디터와 플랫폼이 GFM 규격을 기본적으로 지원합니다. StackEdit, Dillinger, VS Code, 노션, 옵시디언, 디스코드, 레딧, 벨로그, 티스토리 등 여러분이 마크다운을 사용하게 될 거의 모든 곳에서 GFM 문법이 작동한다고 보시면 됩니다. 따라서 GFM의 확장 문법을 아는 것은 선택이 아니라 필수인 것이지요.
앞선 챕터들에서 이미 GFM 확장 문법 중 일부를 배웠다는 사실을 눈치채셨습니까? 취소선(~~)과 체크리스트(- [ ])가 바로 GFM의 확장 기능입니다. 테이블(|) 역시 GFM에서 추가된 것이지요. 이번 챕터에서는 아직 다루지 않은 나머지 GFM 확장 문법들을 살펴보겠습니다.
### 각주, 자동 링크, 이모지
각주(Footnote)는 본문에 번호를 매기고, 문서 하단에 해당 번호의 상세 설명을 추가하는 기능입니다. 학술 논문이나 블로그에서 출처를 밝히거나 부연 설명을 할 때 유용하지요.마크다운은 2004년에 탄생했습니다1.
1존 그루버와 에런 스워츠가 공동으로 개발했습니다.
본문에서 `1`이라고 쓰면 그 위치에 각주 번호가 표시되고, 문서 하단에 `[^1]:` 뒤에 쓴 내용이 각주 설명으로 나타납니다. 각주 번호는 1, 2, 3처럼 숫자를 사용해도 되고, `[^note]`처럼 의미 있는 식별자를 사용해도 됩니다. 다만, 모든 마크다운 렌더러가 각주를 지원하는 것은 아니므로, 사용하시는 플랫폼에서 지원 여부를 먼저 확인하시는 것이 좋습니다.
자동 링크(Autolink)는 URL이나 이메일 주소를 자동으로 클릭 가능한 링크로 변환해주는 기능입니다. 기본 마크다운에서는 `<URL>` 형식으로 꺽쇠 괄호를 써야 했지만, GFM에서는 URL을 그냥 입력해도 자동으로 링크가 됩니다.기본 마크다운: https://www.google.com
GFM 자동 링크: https://www.google.com
두 경우 모두 렌더링 결과는 클릭 가능한 링크로 동일하게 표시됩니다. 자동 링크 기능 덕분에 URL을 공유할 때 별도의 문법을 쓸 필요 없이 그냥 주소만 붙여넣으면 되어 매우 편리하지요.
이모지(Emoji)는 마크다운 문서에 감정이나 시각적 요소를 추가할 수 있는 기능입니다. 콜론(:) 사이에 이모지 코드를 넣으면 해당 이모지가 표시됩니다.:smile: :thumbsup: :heart: :rocket: :star:
이렇게 입력하면 각각 웃는 얼굴, 엄지 위로, 하트, 로켓, 별 이모지로 변환됩니다. 사용 가능한 이모지 코드는 수백 가지에 달하는데, 깃허브의 이모지 치트시트를 검색하면 전체 목록을 확인할 수 있습니다. 이모지는 깃허브의 커밋 메시지나 이슈에서 특히 많이 사용되지요.
### GFM 확장 문법 실전 활용
GFM 확장 문법이 가장 빛을 발하는 곳은 역시 깃허브의 README 파일입니다. README.md는 프로젝트의 얼굴이라고 할 수 있는 문서로, 프로젝트를 방문한 사람이 가장 먼저 읽게 되는 문서입니다. 잘 작성된 README는 테이블로 기능 목록을 정리하고, 체크리스트로 개발 진행 상황을 보여주며, 코드 블록으로 설치 방법을 제시하고, 이모지로 시각적 재미를 더합니다.
또한 깃허브의 이슈(Issue)와 풀 리퀘스트(Pull Request)에서도 GFM 문법을 자유롭게 사용할 수 있습니다. 버그를 보고할 때 코드 블록으로 에러 메시지를 첨부하고, 체크리스트로 재현 단계를 정리하면 의사소통의 효율이 크게 올라가지요.
GFM에서 제공하는 또 다른 유용한 기능으로는 경고 블록(Alerts) 이 있습니다. 이것은 비교적 최근에 추가된 기능으로, 다음과 같은 형식으로 사용합니다.[!NOTE]
유용한 참고 정보입니다.
[!TIP]
선택적인 도움말 정보입니다.
[!IMPORTANT]
성공을 위해 반드시 알아야 할 중요 정보입니다.
[!WARNING]
잠재적 문제를 방지하기 위한 주의사항입니다.
[!CAUTION]
위험한 결과를 초래할 수 있는 부분에 대한 경고입니다.
이 경고 블록들은 깃허브에서 각기 다른 색상과 아이콘으로 렌더링되어 시각적으로 매우 눈에 띕니다. NOTE는 파란색, TIP은 녹색, IMPORTANT는 보라색, WARNING은 노란색, CAUTION은 빨간색으로 표시되지요. 기술 문서를 작성할 때 독자에게 중요한 정보를 전달하는 데 매우 효과적인 도구입니다.
#### 지금 당장 연습해보기
에디터에서 다음을 직접 작성하여 GFM 확장 문법을 연습해보세요.GFM 확장 문법 연습
각주
마크다운은 2004년에 처음 공개되었습니다1.
GFM은 CommonMark를 기반으로 합니다2.
1존 그루버가 Daring Fireball 블로그에서 공개
22017년 깃허브에서 공식 규격 발표
이모지
이 프로젝트가 마음에 드셨다면 :star:을 눌러주세요!
기여를 환영합니다 :thumbsup:
체크리스트
GFM 기본 개념 이해
각주 문법 학습
이모지 코드 암기
경고 블록 활용
마크다운 문법 총정리 테이블
| 범주 | 문법 | GFM 확장 여부 |
|---|---|---|
| 제목 | # | 기본 |
| 굵게 | ** | 기본 |
| 취소선 | ~~ | GFM |
| 체크리스트 | - [ ] | GFM |
| 테이블 | 파이프 | GFM |
| 각주 | 1 | GFM |
깃허브에 계정이 있다면, 새 저장소를 만들어 README.md 파일에 위 내용을 넣어보는 것도 훌륭한 연습이 됩니다. 깃허브에서 직접 렌더링된 결과를 확인하면 실전 감각이 크게 향상되지요.
# 활용편
## 마크다운 에디터 선택 가이드
### 데스크톱 에디터 비교
앞서 실습 환경 준비 챕터에서 온라인 에디터를 소개해드렸는데, 마크다운을 본격적으로 활용하게 되면 데스크톱 에디터의 필요성을 느끼시게 됩니다. 온라인 에디터는 빠르게 시작할 수 있는 장점이 있지만, 인터넷 연결이 필수적이고, 파일 관리나 확장 기능 면에서 한계가 있기 때문이지요.
데스크톱 마크다운 에디터 중에서 가장 널리 알려진 것은 비주얼 스튜디오 코드(Visual Studio Code, VS Code) 입니다. VS Code는 마이크로소프트에서 만든 무료 코드 에디터인데, 마크다운 미리보기 기능이 기본으로 내장되어 있습니다. 마크다운 파일(.md)을 열고 Ctrl+Shift+V(맥에서는 Cmd+Shift+V)를 누르면 미리보기 패널이 열립니다. VS Code의 가장 큰 장점은 무료이면서도 기능이 강력하고, 확장 프로그램을 통해 마크다운 관련 기능을 무한히 추가할 수 있다는 것입니다. 프로그래밍을 병행하는 분이라면 VS Code가 최적의 선택이지요.
Typora는 또 다른 인기 있는 마크다운 에디터입니다. Typora의 가장 특별한 점은 편집과 미리보기를 하나의 화면에 통합한 'WYSIWYM(What You See Is What You Mean)' 방식을 채택했다는 것인데요, 마크다운 문법을 입력하는 순간 바로 렌더링된 형태로 변환되어 표시됩니다. 예를 들어 `# 제목`이라고 타이핑하면 즉시 큰 제목으로 바뀌지요. 이 방식은 마크다운의 '원본'과 '결과'를 따로 볼 필요 없이 깔끔한 화면에서 글쓰기에 집중할 수 있다는 장점이 있습니다. 다만, Typora는 유료(약 14.99달러, 일회 구매)라는 점을 참고하세요.
옵시디언(Obsidian) 은 마크다운 에디터인 동시에 강력한 개인 지식 관리(PKM) 도구입니다. 옵시디언의 핵심 개념은 '지식의 연결'인데, 마크다운 파일 간에 링크를 만들어 지식의 네트워크를 구축할 수 있습니다. 개인 메모, 연구 노트, 위키 등을 마크다운으로 관리하고 싶은 분에게 최적의 도구이지요. 개인 사용은 무료이고, 파일이 모두 로컬에 .md 형태로 저장되므로 데이터 소유권도 완전히 사용자에게 있습니다.
마크텍스트(MarkText) 는 오픈소스 무료 마크다운 에디터로, Typora와 유사한 실시간 렌더링 방식을 제공합니다. 윈도우, 맥, 리눅스 모든 운영체제에서 사용 가능하고, 다양한 테마를 지원하며, CommonMark와 GFM을 모두 지원합니다. 무료이면서 깔끔한 에디터를 원하는 분에게 좋은 선택이 될 수 있습니다.
### 모바일 및 크로스플랫폼 에디터
마크다운의 큰 장점 중 하나는 플랫폼을 가리지 않는다는 것입니다. 데스크톱에서 작성한 마크다운 파일을 모바일에서 이어서 편집하거나, 태블릿에서 시작한 글을 노트북에서 완성하는 것이 가능하지요. 이를 위해서는 크로스플랫폼을 지원하는 에디터가 필요합니다.
노션(Notion) 은 이미 많은 분들이 사용하고 계실 텐데, 마크다운 문법을 지원하는 대표적인 크로스플랫폼 도구입니다. 웹, 데스크톱 앱, 모바일 앱 모두에서 사용 가능하고, 마크다운 문법을 입력하면 자동으로 노션의 블록 형식으로 변환됩니다. 다만 노션은 순수 마크다운 에디터가 아니라 올인원 생산성 도구이므로, 마크다운 파일 자체를 관리하는 것과는 다소 다른 개념이라는 점을 이해하셔야 합니다.
iA Writer는 미니멀 디자인의 마크다운 에디터로, 맥과 iOS에서 사용할 수 있습니다. 극도로 깔끔한 인터페이스와 Focus Mode(집중 모드)가 특징인데, 현재 편집 중인 문장 외의 모든 텍스트를 흐리게 처리하여 글쓰기에 집중할 수 있도록 도와줍니다. 직업적으로 글을 쓰는 작가나 블로거 사이에서 인기가 높은 에디터이지요.
심플노트(Simplenote) 는 완전히 무료인 크로스플랫폼 메모 앱으로, 각 메모에서 마크다운 모드를 활성화할 수 있습니다. 모든 데이터가 클라우드에 동기화되므로 어떤 기기에서든 동일한 내용에 접근할 수 있고, 버전 히스토리 기능으로 이전 버전을 복원하는 것도 가능합니다. 간단한 마크다운 메모를 여러 기기에서 동기화하고 싶을 때 매우 유용합니다.
### 실전 환경 세팅 가이드
에디터를 선택했으면 이제 실전 환경을 세팅할 차례입니다. 어떤 에디터를 선택하든 다음 세 가지만 확인하시면 됩니다.
첫째, 마크다운 미리보기 기능이 작동하는지 확인하세요. VS Code라면 Ctrl+Shift+V로 미리보기 패널을 열 수 있어야 하고, Typora나 MarkText라면 타이핑하는 즉시 렌더링이 되어야 합니다. 옵시디언이라면 읽기 모드와 편집 모드를 전환할 수 있어야 하지요.
둘째, 파일 저장 위치를 정해두세요. 마크다운 파일은 텍스트 파일이기 때문에 어디에 저장해도 상관없지만, 나중에 파일을 찾기 쉽도록 전용 폴더를 하나 만들어두는 것을 권장합니다. 예를 들어 '내문서/마크다운' 같은 폴더를 만들고, 모든 .md 파일을 여기에 저장하는 것이지요.
셋째, 문자 인코딩이 UTF-8로 설정되어 있는지 확인하세요. 대부분의 현대 에디터는 기본값이 UTF-8이므로 별도 설정이 필요 없지만, 만약 한글이 깨져서 표시된다면 인코딩 설정을 UTF-8로 변경해주시면 됩니다. UTF-8은 전 세계 거의 모든 문자를 표현할 수 있는 표준 인코딩 방식으로, 한글, 영어, 일본어, 중국어 등 어떤 언어의 텍스트도 정상적으로 표시해줍니다.
이 세 가지만 확인하면 실전 환경 세팅은 완료입니다. 복잡하지 않지요? 마크다운의 가장 큰 미덕 중 하나가 바로 이 단순함입니다. 특별한 설정이나 복잡한 초기화 과정 없이, 에디터 하나만 있으면 바로 글쓰기를 시작할 수 있다는 것이지요.
## 플랫폼별 마크다운 활용법
### 깃허브에서 마크다운 쓰기
깃허브는 마크다운과 가장 밀접하게 연결된 플랫폼이라고 해도 과언이 아닙니다. 깃허브에서 마크다운이 사용되는 곳은 실로 다양합니다. README.md 파일은 물론이고, 이슈(Issue), 풀 리퀘스트(Pull Request), 위키(Wiki), 디스커션(Discussions), 커밋 메시지, 릴리스 노트까지 -- 깃허브에서 텍스트를 입력하는 거의 모든 곳에서 마크다운이 사용됩니다.
깃허브에서 마크다운을 가장 효과적으로 활용하는 방법을 몇 가지 소개하겠습니다. 우선 README.md 파일은 프로젝트의 첫인상을 결정하는 매우 중요한 문서입니다. 잘 작성된 README에는 프로젝트의 소개, 주요 기능, 설치 방법, 사용법, 기여 가이드 등이 포함되어야 합니다. 이때 제목, 목록, 코드 블록, 테이블, 이미지 등 다양한 마크다운 문법을 종합적으로 활용하면 깔끔하고 전문적인 README를 작성할 수 있지요.
깃허브의 이슈에서는 버그 보고서나 기능 요청을 작성하는데, 이때 마크다운의 코드 블록을 사용하여 에러 메시지나 코드 조각을 첨부하고, 체크리스트로 재현 단계를 정리하면 의사소통이 훨씬 효율적이 됩니다. 또한 깃허브는 이슈 번호를 자동으로 링크해주는 기능이 있어서, `#42`라고 쓰면 42번 이슈로의 링크가 자동 생성됩니다. 이 역시 GFM의 확장 기능 중 하나이지요.
### 노션과 옵시디언에서의 마크다운
노션에서 마크다운을 활용하는 방법은 크게 두 가지가 있습니다. 첫째는 노션 에디터에서 직접 마크다운 문법을 타이핑하는 것이고, 둘째는 마크다운 파일을 노션으로 가져오기(Import)하는 것입니다.
노션 에디터에서 마크다운 단축키를 사용하면 작업 속도가 크게 빨라집니다. 예를 들어 줄의 맨 앞에서 `# `을 입력하면 즉시 제목 블록으로 변환되고, `**`로 텍스트를 감싸면 볼드체가 됩니다. `/`를 입력하면 다양한 블록 유형을 선택할 수 있는 슬래시 명령어 메뉴가 나타나지요. 마크다운을 알고 있으면 이 모든 작업을 마우스 없이 키보드만으로 수행할 수 있어서, 노션 사용 효율이 비약적으로 향상됩니다.
옵시디언은 마크다운 파일 그 자체를 기반으로 작동하는 도구이기 때문에, 마크다운을 아는 것이 옵시디언 활용의 전제 조건이라고 할 수 있습니다. 옵시디언의 가장 특별한 기능은 위키링크(Wikilinks) 인데, 대괄호 두 개로 다른 노트의 이름을 감싸면 해당 노트로의 링크가 자동 생성됩니다. 예를 들어 `[[마크다운 기초]]`라고 쓰면 '마크다운 기초'라는 노트로의 링크가 만들어지지요. 이 기능은 엄밀히 말하면 표준 마크다운 문법은 아니지만, 옵시디언 생태계에서 핵심적으로 사용되는 확장 기능입니다.
옵시디언에서 한 가지 더 알아두면 좋은 것은, 옵시디언의 모든 노트가 .md 파일로 로컬 컴퓨터에 저장된다는 점입니다. 이것은 여러분의 데이터가 특정 서비스에 종속되지 않는다는 것을 의미합니다. 옵시디언을 더 이상 사용하지 않게 되더라도, 여러분의 모든 노트는 .md 파일로 남아 있어서 다른 에디터에서 즉시 열어볼 수 있습니다. 이것이 마크다운의 플랫폼 독립성이 실제로 발휘되는 대표적인 사례이지요.
### 블로그와 기술문서 작성 실전
블로그를 운영하고 싶다면 마크다운은 거의 필수적으로 알아야 할 도구입니다. 현재 기술 블로그를 운영하는 데 가장 많이 사용되는 플랫폼과 도구들은 대부분 마크다운을 기본 작성 포맷으로 채택하고 있기 때문입니다.
정적 사이트 생성기(Static Site Generator, SSG) 라는 것을 들어보셨습니까? 지킬(Jekyll), 휴고(Hugo), 개츠비(Gatsby), 넥스트 같은 도구들이 대표적인데, 이들은 마크다운으로 작성한 글을 자동으로 HTML 웹페이지로 변환해주는 프로그램입니다. 여러분이 마크다운으로 글만 쓰면, SSG가 알아서 블로그 디자인을 입히고, 목차를 만들고, 네비게이션을 구성해주는 것이지요. 깃허브 페이지(GitHub Pages)를 이용하면 무료로 호스팅까지 가능합니다.
한국에서 기술 블로그를 시작하기 가장 쉬운 방법은 벨로그(Velog) 를 이용하는 것입니다. 벨로그는 마크다운 에디터를 기본으로 제공하며, 회원가입만 하면 즉시 마크다운으로 글을 써서 발행할 수 있습니다. 코드 블록의 구문 강조도 자동으로 지원하고, 시리즈 기능으로 연재글을 묶을 수도 있지요.
기술 문서(Technical Documentation) 작성에서도 마크다운은 표준적인 도구로 자리 잡았습니다. 대표적인 예가 깃북(GitBook)과 독사우루스(Docusaurus)인데, 이들은 마크다운으로 작성한 문서를 자동으로 깔끔한 기술 문서 사이트로 변환해줍니다. 많은 오픈소스 프로젝트와 기업들이 이런 도구를 사용하여 API 문서, 사용자 가이드, 개발자 문서를 작성하고 있지요.
## 마크다운 변환 실전
### 왜 변환이 필요한가
마크다운으로 문서를 작성하는 것은 매우 편리하지만, 현실에서는 마크다운 파일을 그대로 공유할 수 없는 상황이 꽤 많습니다. 예를 들어 회사에 보고서를 제출해야 할 때 .md 파일을 보내면 상사가 열어볼 수 없을 수도 있고, 클라이언트에게 제안서를 보낼 때도 PDF 형식이 훨씬 전문적으로 보입니다. 블로그에 글을 올리려면 HTML 형식이 필요하고, 인쇄물을 만들 때도 마크다운 원본으로는 불가능하지요.
> 아니, 그러면 처음부터 워드로 쓰지 왜 마크다운으로 쓰는 거야?
이런 의문을 가지실 수 있는데, 매우 합리적인 질문입니다. 하지만 답은 명확합니다. 마크다운으로 '작성'하고, 필요에 따라 다른 형식으로 '변환'하는 것이 가장 효율적인 워크플로우이기 때문입니다. 마크다운으로 쓰면 글쓰기 자체에 집중할 수 있고, 작성이 끝난 후에 용도에 맞는 형식으로 변환하면 되니까요. 한 번 작성한 마크다운 원본을 PDF로도, HTML로도, DOCX로도, 심지어 프레젠테이션 슬라이드로도 변환할 수 있습니다. 원본은 하나지만 결과물은 여러 형식으로 만들 수 있는 것이지요. 이것이야말로 마크다운의 진정한 힘이라고 할 수 있습니다.
### 주요 변환 도구와 사용법
마크다운을 다른 형식으로 변환하는 도구 중 가장 강력하고 널리 알려진 것은 판독(Pandoc)입니다. Pandoc은 존 맥팔레인(John MacFarlane)이 개발한 오픈소스 문서 변환 도구로, '문서 변환의 만능칼'이라는 별명을 가지고 있습니다. 마크다운을 PDF, HTML, DOCX, EPUB, LaTeX, 프레젠테이션 슬라이드 등 수십 가지 형식으로 변환할 수 있지요.
Pandoc을 사용하려면 컴퓨터에 설치해야 하는데, 공식 사이트인 pandoc.org에서 운영체제에 맞는 설치 파일을 다운로드하여 설치하면 됩니다. 설치 후에는 터미널(명령 프롬프트)에서 명령어를 입력하여 변환을 실행합니다.
예를 들어 마크다운 파일을 HTML로 변환하려면 터미널에서 다음과 같이 입력합니다.
```bash
pandoc input.md -o output.html마크다운 파일을 PDF로 변환하려면 다음과 같이 입력합니다.
pandoc input.md -o output.pdf마크다운 파일을 워드 문서(DOCX)로 변환하려면 다음과 같이 입력합니다.
pandoc input.md -o output.docx어떻습니까? 명령어가 매우 단순하지요. pandoc 입력파일 -o 출력파일 -- 이것이 전부입니다. 출력 파일의 확장자에 따라 Pandoc이 자동으로 적절한 형식으로 변환해줍니다.
터미널이나 명령어 입력이 부담스러운 분들을 위한 대안도 있습니다. 앞서 소개한 에디터들 중 상당수가 자체적인 변환 기능을 제공합니다. Typora는 파일 메뉴에서 내보내기(Export)를 선택하면 PDF, HTML, DOCX 등으로 바로 변환할 수 있고, StackEdit에서도 HTML이나 PDF로 내보내는 것이 가능합니다. VS Code에서는 Markdown PDF 같은 확장 프로그램을 설치하면 단축키 하나로 PDF 변환이 됩니다.
온라인 변환 도구도 있습니다. mdtopdf.pro 같은 웹사이트에서는 마크다운 텍스트를 붙여넣거나 .md 파일을 업로드하면 PDF로 변환해서 다운로드할 수 있습니다. 설치할 필요 없이 웹 브라우저에서 바로 사용할 수 있어서 간편하지요.
변환 실전 워크플로우
실무에서 마크다운 변환을 활용하는 구체적인 워크플로우를 살펴보겠습니다. 가장 흔한 시나리오 세 가지를 예로 들겠습니다.
첫 번째 시나리오는 보고서 작성입니다. 먼저 마크다운으로 보고서의 내용을 작성합니다. 이때 서식 걱정 없이 내용에만 집중하면 됩니다. 내용 작성이 완료되면 Pandoc이나 에디터의 내보내기 기능을 사용하여 PDF 또는 DOCX로 변환합니다. 필요에 따라 CSS 스타일시트를 적용하면 회사의 브랜딩에 맞는 디자인을 입힐 수도 있지요. 이 워크플로우의 핵심은 '작성'과 '꾸미기'를 완전히 분리한다는 것입니다. 글을 쓰는 동안에는 서식에 신경 쓰지 않고, 변환 단계에서 한꺼번에 디자인을 적용하는 것이지요.
두 번째 시나리오는 블로그 발행입니다. 마크다운으로 블로그 글을 작성한 후, 이를 HTML로 변환하거나 블로그 플랫폼에 직접 업로드합니다. 지킬이나 휴고 같은 정적 사이트 생성기를 사용한다면, 마크다운 파일을 지정된 폴더에 넣기만 하면 자동으로 블로그 포스트로 변환되어 발행됩니다. 벨로그나 미디엄 같은 플랫폼에서는 마크다운을 직접 붙여넣으면 되지요.
세 번째 시나리오는 기술 문서 배포입니다. API 문서나 사용자 가이드를 마크다운으로 작성한 후, 독사우루스(Docusaurus)나 깃북(GitBook)을 사용하여 웹 기반 문서 사이트로 변환합니다. 이렇게 하면 검색 기능, 네비게이션, 다국어 지원 등이 자동으로 추가된 전문적인 문서 사이트를 만들 수 있습니다. 문서의 원본은 마크다운 파일로 깃허브에 관리되므로, 버전 관리와 협업도 자연스럽게 이루어지지요.
이처럼 마크다운은 단순히 '텍스트를 쓰는 도구'가 아니라, 다양한 형식의 결과물을 만들어내는 출발점으로서의 역할을 합니다. 마크다운 하나만 잘 알면, PDF 보고서도, 웹페이지도, 전자책도, 프레젠테이션도 만들 수 있다는 것이지요. 반드시 기억해두시기 바랍니다.
완성편
실수와 해결법
가장 흔한 실수 모음
마크다운은 배우기 쉬운 언어이지만, 초보자라면 누구나 한 번쯤 겪는 전형적인 실수들이 있습니다. 이 실수들을 미리 알아두면 불필요한 좌절을 피할 수 있으므로, 하나씩 짚어보겠습니다.
첫 번째로 가장 많이 하는 실수는 # 기호 뒤에 공백을 넣지 않는 것입니다. #제목이라고 붙여 쓰면 대부분의 마크다운 렌더러에서 제목으로 인식하지 않습니다. 반드시 # 제목처럼 # 뒤에 공백 한 칸을 넣어야 합니다. 이것은 마크다운에서 가장 기본적이면서도 가장 자주 빠뜨리는 규칙이지요. 다른 블록 요소들도 마찬가지입니다. 목록을 만들 때 - 항목에서 - 뒤의 공백, 인용문을 만들 때 > 텍스트에서 > 뒤의 공백도 반드시 필요합니다.
두 번째 실수는 문단 사이에 빈 줄을 넣지 않는 것입니다. 앞서 설명한 것처럼, 마크다운에서 엔터를 한 번만 누르면 같은 문단 내의 연속된 텍스트로 처리됩니다. 새로운 문단을 시작하려면 반드시 빈 줄을 하나 넣어야 합니다. 이것을 모르면 "분명히 두 줄로 쓴 것 같은데 왜 한 줄로 붙어버리지?"라는 의문에 빠지게 되지요.
세 번째 실수는 인라인 문법에서 기호와 텍스트 사이에 공백을 넣는 것입니다. 블록 요소(#, -, >)에서는 기호 뒤에 공백이 필요하지만, 인라인 요소(, , ~~)에서는 반대로 기호와 텍스트가 붙어 있어야 합니다. `텍스트 `처럼 공백을 넣으면 굵게 처리되지 않습니다. `텍스트`처럼 딱 붙여야 합니다.
네 번째 실수는 중첩 목록에서 들여쓰기를 잘못하는 것입니다. 하위 목록을 만들려면 공백 두 칸 또는 네 칸으로 들여쓰기를 해야 하는데, 공백이 한 칸이면 들여쓰기가 인식되지 않고, 다섯 칸이면 코드 블록으로 처리될 수 있습니다. 에디터에서 탭(Tab) 키를 사용하면 이 문제를 쉽게 피할 수 있지요.
다섯 번째 실수는 링크 문법에서 대괄호와 소괄호를 혼동하는 것입니다. [텍스트](URL)이 올바른 순서인데, (텍스트)[URL]이나 [텍스트][URL](참조 스타일이 아닌 경우) 등으로 잘못 쓰는 경우가 있습니다. "대괄호가 먼저, 소괄호가 나중" -- 이 순서를 기억하는 팁은, 알파벳에서 대문자(ABC)가 소문자(abc)보다 먼저 나오는 것과 같다고 외우시면 됩니다. 대괄호 → 소괄호, 이 순서이지요.
여섯 번째 실수는 코드 블록에서 백틱의 개수를 틀리는 것입니다. 인라인 코드는 백틱 하나(`), 코드 블록은 백틱 세 개(```)입니다. 백틱 두 개를 쓰면 어정쩡한 결과가 나올 수 있습니다. 또한 코드 블록의 시작 백틱 세 개와 끝 백틱 세 개는 반드시 각각 독립된 줄에 있어야 합니다.
트러블슈팅 가이드
마크다운 문서에서 문제가 발생했을 때 가장 먼저 해야 할 일은, 원본(소스)과 렌더링 결과를 비교하는 것입니다. 미리보기에서 기대한 대로 표시되지 않는 부분이 있다면, 원본에서 해당 부분의 문법을 꼼꼼히 확인해보세요.
문제를 진단할 때는 다음의 체크포인트를 순서대로 확인하시면 대부분의 문제를 해결할 수 있습니다.
첫째, 공백을 확인합니다. 블록 요소(#, -, >, 숫자.)의 기호 뒤에 공백이 있는지, 인라인 요소(, *, ~~)의 기호와 텍스트 사이에 불필요한 공백이 없는지 확인합니다.
둘째, 빈 줄을 확인합니다. 문단과 문단 사이, 제목과 본문 사이, 수평선 앞뒤에 빈 줄이 있는지 확인합니다. 마크다운에서 빈 줄은 "여기서 구분이 일어난다"는 신호 역할을 하므로, 빈 줄이 빠지면 서식이 의도대로 적용되지 않을 수 있습니다.
셋째, 기호의 쌍이 맞는지 확인합니다. 로 시작했으면 반드시 로 끝나야 하고, 로 시작했으면 로 끝나야 합니다. 특히 글이 길어지면 닫는 기호를 빼먹는 실수가 잦아지므로, 서식이 이상하게 표시되면 기호의 쌍부터 확인하세요.
넷째, 플랫폼별 차이를 의심합니다. 같은 마크다운 문법이라도 깃허브, 노션, 옵시디언, VS Code 등에서 렌더링 결과가 약간 다를 수 있습니다. 특히 각주, 경고 블록, 이모지 같은 확장 기능은 플랫폼에 따라 지원 여부가 다를 수 있으므로, 사용하시는 플랫폼의 마크다운 지원 범위를 확인해보시는 것이 좋습니다.
다섯째, 인코딩 문제를 확인합니다. 한글이 깨져 보이거나 특수문자가 이상하게 표시된다면, 파일의 문자 인코딩이 UTF-8로 설정되어 있는지 확인하세요. 대부분의 현대 에디터는 기본값이 UTF-8이지만, 간혹 다른 인코딩으로 저장된 파일을 열 때 문제가 발생할 수 있습니다.
마크다운 습관화를 위한 30일 실행 플랜
마크다운을 배우는 것보다 더 중요한 것은 마크다운을 습관으로 만드는 것입니다. 아무리 문법을 다 외웠더라도 실제로 쓰지 않으면 금방 잊어버리게 됩니다. 반대로 매일 조금씩이라도 마크다운으로 글을 쓰면, 한 달 후에는 의식하지 않아도 자연스럽게 마크다운 문법이 손에서 나오게 되지요.
다음은 30일 동안 마크다운을 습관화하기 위한 실행 플랜입니다. 매일 10~15분이면 충분합니다.
1주차(1~7일)는 기본 문법 체화 기간입니다. 매일 하나의 마크다운 파일을 새로 만들어서, 그날 배운 내용이나 생각을 마크다운으로 정리하세요. 제목, 굵은 글씨, 목록 -- 이 세 가지 문법만 집중적으로 사용합니다. 첫 주의 목표는 이 세 가지 문법이 손에 익는 것입니다. 회의록, 일기, 할 일 목록 등 무엇이든 좋습니다. 중요한 것은 매일 쓰는 것이지요.
2주차(8~14일)는 확장 문법 적용 기간입니다. 기본 문법에 더해 링크, 이미지, 코드 블록, 인용문을 활용하기 시작합니다. 이 시기에 추천하는 활동은 기존에 워드프로세서로 작성한 문서를 마크다운으로 다시 작성해보는 것입니다. 이미 내용은 완성되어 있으니 오로지 마크다운 문법 적용에만 집중할 수 있어서 효율적인 연습이 됩니다.
3주차(15~21일)는 실전 활용 시작 기간입니다. 깃허브에 저장소를 만들어 README.md를 작성하거나, 노션에서 마크다운 단축키를 적극적으로 활용하거나, 블로그에 마크다운으로 글을 써서 발행해보세요. 실제 플랫폼에서 마크다운을 사용하면 "내가 쓴 마크다운이 실제로 어떻게 보이는구나"하는 감각이 생기고, 자신감도 크게 향상됩니다.
4주차(22~30일)는 고급 활용 및 자동화 기간입니다. 테이블, GFM 확장 문법, 변환 도구 등을 활용하여 더 복잡한 문서를 작성해보세요. Pandoc으로 마크다운을 PDF나 HTML로 변환해보고, 정적 사이트 생성기로 블로그를 만들어보는 것도 이 시기에 도전해볼 만합니다. 이 단계까지 오면 마크다운이 이미 여러분의 기본 글쓰기 도구로 자리 잡았을 것입니다.
이 30일 플랜에서 가장 중요한 원칙은 '매일 쓰기'입니다. 한 번에 많이 쓰는 것보다, 조금씩이라도 매일 마크다운을 사용하는 것이 습관화에 훨씬 효과적입니다. 하루에 세 줄짜리 메모를 마크다운으로 쓰는 것도 충분합니다. 핵심은 빈도이지, 양이 아닙니다. 반드시 명심하세요.
마치며
여러분은 이 책을 통해 마크다운의 처음부터 끝까지를 모두 걸어오셨습니다. 마크다운이라는 단어조차 낯설었던 시작점에서, 이제는 제목을 만들고, 글씨를 꾸미고, 목록을 정리하고, 링크와 이미지를 삽입하고, 코드 블록과 테이블을 만들고, GFM 확장 문법까지 다룰 수 있게 되었지요. 더 나아가 다양한 에디터를 비교하고, 플랫폼별 활용법을 이해하고, 마크다운을 PDF와 HTML로 변환하는 방법까지 배우셨습니다.
이 모든 것을 가능하게 한 핵심 원리를 한 문장으로 압축하면 이렇습니다 -- "기호를 놓으면 서식이 된다." 마크다운의 모든 문법은 이 한 문장으로 귀결됩니다. # 을 놓으면 제목이 되고, ** 를 놓으면 굵은 글씨가 되고, - 를 놓으면 목록이 됩니다. 이보다 더 단순한 원리가 있을까요?
하지만 솔직하게 말씀드리겠습니다. 이 책을 읽는 것만으로는 마크다운을 '안다'고 할 수 없습니다. 진짜 마크다운을 아는 것은, 생각이 떠오를 때 자연스럽게 # 기호를 찍고, 강조하고 싶은 단어에 무의식적으로 별표를 감싸는 경지에 도달하는 것이지요. 그리고 그 경지는 오직 반복적인 사용을 통해서만 도달할 수 있습니다.
그래서 여러분에게 당부드리고 싶은 것은 지금 당장 마크다운으로 무언가를 쓰기 시작하라는 것입니다. 거창한 것일 필요는 없습니다. 오늘의 할 일 목록을 마크다운으로 써보세요. 내일은 회의록을 마크다운으로 정리해보세요. 모레는 블로그에 마크다운으로 글을 써서 올려보세요. 이렇게 하루에 10분씩만 투자하면, 한 달 후에는 마크다운이 이미 여러분의 기본 글쓰기 도구가 되어 있을 것입니다.
2004년에 존 그루버와 에런 스워츠가 마크다운을 만들 때의 목표는 "이메일을 쓰듯이 쉽게 웹 문서를 작성하는 것"이었습니다. 그로부터 20여 년이 지난 지금, 마크다운은 그 소박한 목표를 훨씬 넘어서 전 세계 디지털 글쓰기의 사실상 표준이 되었습니다. 깃허브에서, 노션에서, 블로그에서, AI 도구에서, 기술 문서에서, 개인 노트에서 -- 마크다운은 어디에나 있습니다. 그리고 이제 여러분도 그 세계의 일원이 되었습니다.
마크다운과 함께하는 여러분의 글쓰기가 더 빠르고, 더 깔끔하고, 더 즐거워지기를 진심으로 응원합니다. 축하합니다, 여러분은 이제 마크다운을 완전히 정복하셨습니다!
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.