5강. 마크다운이란?
0. 학습 목표
→ 마크다운 기호가 문서 구조로 바뀌는 과정을 확인하고, 이 과정에서 사용할 문법 범위를 정합니다.
0.1 이번 글에서 다룰 내용
4강에서 첫 노트를 만들 때 #을 붙인 줄이 제목이 되고 -를 붙인 줄이 목록이 되는 것을 봤습니다.
그 기호 규칙의 이름이 마크다운입니다.
3강에서는 워드 문서의 서식 정보가 word/styles.xml이라는 별도 파일에 들어 있고, 그것을 읽어 화면에 조립하는 프로그램이 있어야 문서를 볼 수 있다는 것을 확인했습니다. 마크다운은 서식을 별도 파일에 두지 않고 글자 사이에 기호로 적습니다. 그러면 그 기호를 누가 문서 구조로 바꿔 주는가가 오늘의 확인 대상입니다.
오늘은 브라우저에서 변환 결과를 두 번 확인하고, 그 결과를 근거로 이 과정에서 쓸 문법의 범위를 정합니다. 문법을 직접 입력해 노트를 쓰는 것은 6강에서 합니다.
0.2 이번 강의 실습 내용
- 웹 브라우저
- 3강에서 확인한 내용(워드 문서에
unzip -l을 실행했을 때 나온 파일 목록) - 4강에서 만든
study-log노트(마지막 과제 기록에 사용합니다)
설치할 프로그램은 없습니다.
1. CommonMark 변환기로 마크다운 기호가 HTML 구조로 바뀌는 것 확인하기
→ 변환기에 예시 문서를 입력해 #과 -가 각각 어떤 HTML 태그로 바뀌는지 확인합니다.
1.1 확인용 문서를 변환기에 입력해 HTML 결과 확인하기
CommonMark에서 제공하는 변환기를 사용합니다. 마크다운을 입력하면 변환 결과를 보여 주는 웹 페이지입니다.
- 브라우저에서
https://spec.commonmark.org/dingus/를 엽니다. - 입력 칸에 다음 내용을 그대로 입력합니다. 화면은 왼쪽이 입력, 오른쪽이 변환 결과이며 결과를 HTML로 볼지 화면 모양으로 볼지 선택하는 탭이 있습니다. 화면 배치는 바뀔 수 있으므로 다르게 보이면 강사의 안내를 따르세요.
# 확인용 문서
- 첫 번째 항목
- 두 번째 항목
| 기호 | 역할 |
|---|---|
| # | 제목 |
- 결과를 HTML로 보는 탭을 선택합니다.
#이 붙은 줄이<h1>으로,-가 붙은 줄이<li>로 바뀌어 있습니다.<h1>은 문서의 큰 제목을,<li>는 목록의 한 항목을 뜻하는 표시입니다.
여기서 확인할 것은 이 변환이 무엇을 근거로 이루어졌는가입니다. 이 페이지를 열기 위해 아무것도 설치하지 않았고, 변환기가 받은 것은 입력한 글자뿐입니다. 서식 정보가 든 별도 파일도 없었는데 제목과 목록이 구분되었습니다. 양식과 형식이 문서 밖의 프로그램이 아니라 문서 안의 글자로 들어 있기 때문입니다.
1.2 워드 문서와 마크다운의 서식 처리 방식을 표로 비교하기
3강에서 확인한 것과 나란히 놓으면 다음과 같습니다.
| 구분 | 워드 문서 | 마크다운 |
| 서식 정보가 있는 곳 | 압축 묶음 안의 별도 파일 | 본문 글자 사이의 기호 |
| 구조를 알아보려면 | 그 형식을 해석하는 프로그램이 필요하다 | 기호 규칙만 알면 된다 |
| 확인한 방법 | unzip -l로 내부 파일 목록을 봐야 했다 |
설치 없이 웹 페이지에 붙여 넣으니 바로 구조가 나왔다 |
4강에서 만든 노트를 Obsidian에서 Ctrl+E로 읽기 모드로 바꿨을 때 화면 뒤에서 일어난 일도 이 변환입니다. Obsidian은 이 변환을 하는 여러 프로그램 중 하나일 뿐입니다.
2. 표 문법이 다르게 처리되는 이유를 확인하고 사용할 문법 정하기
→ 표가 변환되지 않는 이유를 규칙 범위의 차이로 판단하고, 이 과정에서 기준으로 삼을 문법 범위를 정합니다.
2.1 표가 변환되지 않는 이유 확인하기
같은 결과에서 표 부분을 봅니다. 제목과 목록과 달리 표는 표로 변환되지 않고, 세로줄 기호가 그대로 있는 문단으로 처리됩니다.
문법을 틀리게 쓴 것이 아닙니다. 이 변환기는 CommonMark 규칙만 따르는데 CommonMark에는 표 문법이 없기 때문입니다. 같은 내용을 GitHub에 올리면 표로 표시됩니다. GitHub은 표 문법이 추가된 규칙을 쓰기 때문입니다.
마크다운 규칙은 세 단계로 정리되어 왔고, 지금은 이름과 표 처리 여부만 구분해 두면 됩니다.
| 이름 | 역할 | 표와 체크리스트 |
| 원문 사양(2004년) | 존 그루버(John Gruber)가 처음 공개한 규칙 | 없음 |
| CommonMark | 해석이 갈리던 부분을 없앤 규칙 | 없음 |
| GitHub Flavored Markdown(GFM) | CommonMark를 그대로 포함하고 문법을 추가한 규칙 | 있음 |
앞에서 표가 변환되지 않은 이유가 이 표에 있습니다. 사용한 변환기가 CommonMark 규칙을 따랐기 때문입니다. GFM은 CommonMark에 표, 체크리스트, 취소선, 주소 자동 링크를 더한 것입니다.
2.2 이 과정에서 사용할 문법 범위를 GitHub Flavored Markdown으로 정하기
여기서 판단 하나가 나옵니다. 앞으로 "내 화면에서는 표로 보이는데 다른 데서는 안 보인다"는 상황을 만나면, 오타를 찾기 전에 그 화면이 어느 범위의 규칙을 쓰는지를 먼저 확인하면 됩니다.
💡 핵심: 표 표시가 화면마다 다르면 오타를 찾기 전에 그 화면이 어느 범위의 마크다운 규칙을 쓰는지부터 확인합니다.
이 과정에서 작성하는 노트는 10강에서 GitHub에 올라가고 15강에서 GitHub Pages로 게시됩니다. 그래서 이 과정은 표와 체크리스트가 포함된 범위, 즉 GitHub Flavored Markdown을 기준으로 삼습니다. Obsidian도 표와 체크리스트를 표시하므로 편집 화면과 게시 결과가 어긋나지 않습니다.
2.3 참고 자료 확인하기
마크다운은 존 그루버가 2004년에 공개했고, 공식 페이지는 이 형식을 "a text-to-HTML conversion tool for web writers"(웹에 글을 쓰는 사람을 위한, 텍스트를 HTML로 바꾸는 도구)로 설명합니다. 규칙이 적어 여러 서비스가 그대로 채택했고, 이 과정에서도 6강의 Obsidian 노트, 7강부터 9강까지의 Claude 질문과 답변, 10강의 저장소 소개 문서, 12강과 13강의 Colab 텍스트 셀, 15강의 GitHub Pages 게시에서 같은 표기를 계속 사용합니다.
💡 참고
- CommonMark 변환기:
https://spec.commonmark.org/dingus/ - 마크다운 원문 사양:
https://daringfireball.net/projects/markdown/ - CommonMark와 이 규칙을 사용하는 서비스 목록:
https://commonmark.org - GitHub 작성 안내 문서(문법이 기억나지 않을 때 찾아볼 곳):
https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
3. 오늘 확인한 내용을 점검하고 스스로 확인할 과제 수행하기
→ 세 가지 질문으로 오늘 확인한 것을 점검하고, 과제로 study-log 노트에 결과를 기록합니다.
3.1 세 가지 질문으로 오늘 확인한 내용 점검하기
다음 세 질문에 답할 수 있으면 5강에서 확인해야 할 것을 확인한 것입니다. 답이 막히면 해당 절에서 다시 확인하세요.
- 아무것도 설치하지 않은 웹 페이지가
#을 제목으로 바꿀 수 있었던 이유는 무엇입니까? 3강에서 워드 문서를 열 때와 무엇이 다릅니까? - 같은 표 문장이 어떤 화면에서는 표로 보이고 어떤 화면에서는 그렇지 않은 이유는 무엇입니까?
- 이 과정에서 기준으로 삼는 문법 범위는 어느 것이고, 그렇게 정한 이유는 무엇입니까?
3.2 스스로 확인할 과제로 study-log 노트에 결과 기록하기
강의에서 확인한 것은 #과 - 두 기호입니다. 나머지는 직접 확인해 보세요.
- 참고 자료의 GitHub 작성 안내 문서를 열어 아직 써 보지 않은 기호를 하나 고릅니다.
- 그 기호를 사용한 문장을 변환기(
https://spec.commonmark.org/dingus/)에 입력하고 HTML 결과에서 어떤 표시로 바뀌는지 확인합니다. - 4강에서 만든
study-log노트에 다음 한 줄을 추가합니다. 고른 기호, 바뀐 HTML 표시, 변환되었는지 여부를 적습니다.
- 5강 과제: `>`를 입력했더니로 바뀌었다. CommonMark 변환기에서 변환되었다.
지금까지 만든 study-log 노트 상태
study-notes/notes/
├── study-plan.md # 🗸 4강에서 작성 완료
└── study-log.md # ✏️ 5강 과제 한 줄 추가
변환되지 않는 기호를 골랐다면 그것도 확인 결과입니다. 그 기호가 GFM에만 있는 문법인지 앞의 표를 근거로 판단해 함께 적으세요.
✔ 정리: 아무것도 설치하지 않은 변환기가 #과 -를 각각 <h1>과 <li>로 바꾸는 것을 확인했고, 표가 변환되지 않은 이유가 오타가 아니라 CommonMark와 GFM의 규칙 범위 차이라는 것을 판단했으며, 이 과정에서 쓸 문법 범위를 GitHub Flavored Markdown으로 정했습니다.
오늘 확인한 것은 기호가 바뀌는 원리와 기준 범위입니다. 그 기호를 직접 입력해 노트를 완성하는 것은 다음 강의에서 합니다.
→ 다음 개별 강의
6강에서는 오늘 확인한 문법을 직접 입력합니다. 배부받은 reference 폴더의 markdown-syntax 노트에 문법이 절별로 정리되어 있으므로, 그 노트를 보면서 하나씩 입력하고 읽기 모드에서 표시 결과를 확인합니다. 마지막에는 배운 문법을 모두 사용해 1강 내용을 정리한 노트를 직접 작성합니다.