돌려받는 Markdown과 그것을 정리하는 법
최종 확인
변환이 주는 것은 Markdown 파일이지 완성된 문서가 아닙니다. 여기서는 무엇이 나오는지, 어느 부분을 믿어도 되는지, 그리고 그 파일이 저장소나 위키, 노트 보관함에 들어가기 전에 해 둘 값어치가 있는 몇 가지 편집을 짧게 정리합니다.
읽는 데 5분
출력물의 정체
이 변환기는 GitHub Flavored Markdown을 내놓습니다. GitHub, GitLab, Obsidian, Notion 가져오기, 그리고 대부분의 정적 사이트 생성기가 쓰는 방언으로, CommonMark에 몇 가지가 더해진 것입니다. 여기서 중요한 추가분은 파이프 표입니다.
이 선택은 의도적입니다. 순수 CommonMark에는 표 문법이 아예 없어서, 그것을 목표로 삼는 변환기는 표를 버리거나 날 HTML을 뱉는 수밖에 없습니다. GFM 표는 글자 그대로도 읽히고, Markdown이 통하는 거의 모든 곳에서 이해됩니다.
여정을 견디는 것들
| 제목 | 살아남음 — 상대적 글꼴 크기에서 #, ##, ###로 |
|---|---|
| 문단 | 살아남음 — 세로 간격에서 |
| 굵게와 기울임 | 살아남음 — 글꼴 자체의 굵기와 기울기에서 |
| 글머리 목록 | 살아남음 — 줄 앞의 글머리 기호에서 |
| 번호 목록 | 살아남음 — 줄 앞의 숫자에서 |
| 표 | 단순한 직사각형만, GFM 파이프 표로 |
| 인라인 code | 살아남음 — 고정폭 조각에서 |
| 링크 | PDF에 실제 링크 주석이 있는 경우 살아남음 |
| 이미지 | 사라짐 — 결과물은 글과 구조뿐 |
| 각주 | 쪽 끝의 본문으로. 연결되지는 않음 |
| 수식 | 이루는 글자 그대로. LaTeX로 바뀌지 않음 |
| 색과 글꼴 | 사라짐 — Markdown에 표현할 수단이 없음 |
매번 해 둘 값어치가 있는 다섯 가지 편집
변환된 파일 대부분은 같은 몇 가지 작업을 필요로 합니다. 몇 분이면 되고, 검색만 되는 파일과 읽히는 파일을 가릅니다.
- 제목 층위를 바로잡으십시오. 크기 기준이 만든 단계는 국소적으로는 맞고 전체로는 들쭉날쭉합니다. H1이 셋인데 H2가 하나도 없는 문서가 나올 수 있습니다. 제목만 훑어보고, 중첩이 문서의 실제 얼개와 맞도록 다시 매기십시오.
- 쪼개진 문단을 다시 이으십시오. 줄 간격이 넉넉한 문서는 문단을 줄 끝에서 끊습니다. 짧은 줄이 쌓인 것처럼 읽히니, 이어 붙이고 남은 빈 줄을 지우십시오.
- 하이픈 분철을 고치십시오. 오른쪽 여백에서 하이픈으로 맞춘 글은 낱말을 두 줄에 걸쳐 자릅니다. 파일에서 하이픈 바로 뒤에 줄바꿈이 오는 곳을 찾으십시오.
- 모든 표를 확인하십시오. Markdown의 열 수를 원본과 맞춰 세고 마지막 줄을 보십시오. 끝줄이 가장 흔한 희생자입니다. 형태를 잃은 표는 고치는 것보다 다시 입력하는 편이 대체로 빠릅니다.
- 쪽 장식을 지우십시오. 반복되는 머리말과 꼬리말은 찾아내어 제거되지만, 쪽마다 장 제목이 달라지는 식으로 변하는 문서라면 조각이 남을 수 있습니다.
표에 관한 참고
GFM 파이프 표는 모든 줄의 칸 수가 같아야 하고, 머리글 아래 구분 줄이 표 전체의 열 수를 정합니다. 변환기가 어느 한 줄을 잘못 세면 표는 무효가 되고, 파이프 기호가 그대로 보이는 글자 그대로의 텍스트로 나타납니다.
눈에 보이는 실패라는 점은 다행입니다. 나중에 알아차리는 대신 즉시 보입니다. 다음 표는 깨져 있습니다.
| 지역 | Q1 | Q2 |
| --- | --- | --- |
| 북부 | 120 | 140 |
| 남부 | 95 |
| 동부 | 88 | 102 |고치는 법
빠진 칸을 채우십시오. 원래 칸이 비어 있었다면 비운 채로 두면 됩니다. 모든 줄은 구분 줄과 같은 수의 파이프를 가져야 합니다.
| 지역 | Q1 | Q2 |
| --- | --- | --- |
| 북부 | 120 | 140 |
| 남부 | 95 | |
| 동부 | 88 | 102 |이스케이프, 그리고 출력에 가끔 역슬래시가 보이는 이유
Markdown은 평범한 글에도 나오는 글자에 뜻을 부여합니다. 별표는 강조, 밑줄도 강조, 줄 맨 앞의 우물 정자는 제목, 줄 앞의 숫자와 마침표는 목록 항목입니다.
그 글자들이 문서에서 그 자체로 쓰인 경우 — 각주 표시, 밑줄이 든 변수 이름, 정말로 “1985.”로 시작하는 줄 — 역슬래시로 이스케이프하지 않으면 문서가 보이는 방식이 조용히 달라집니다. 출력의 역슬래시는 대개 오류가 아니라 변환기가 조심한 결과입니다.
역슬래시가 거슬린다면 지워도 안전합니다. 다만 지운 뒤 그 줄이 어떻게 보이는지 확인하십시오.
파일이 다음에 가는 곳
Markdown은 일반 텍스트이고, 애초에 변환하는 이유가 바로 그것입니다. grep으로 찾을 수 있고, diff로 견줄 수 있으며, 텍스트 파일을 열 수 있는 무엇이든 오십 년 뒤에도 읽을 수 있습니다.
저장소라면 트리에 넣고 코드 리뷰에 맡기십시오. 노트 보관함이라면 제목 층위를 먼저 확인하십시오. 대부분의 보관함이 거기서 얼개를 만듭니다. 정적 사이트라면 생성기가 요구하는 front matter를 더하십시오. PDF에 없는 이상 어떤 변환기도 지어낼 수 없습니다. 언어 모델에 넣을 것이라면 검색용 PDF 준비 안내서를 보십시오. 우선순위가 다른 별개의 작업입니다.