마크다운 뷰어·실시간 프리뷰 사용법 (GitHub/Notion/수식)

문서를 읽는 사람의 환경을 고려하지 않고 작성하면 가독성이 크게 떨어집니다. 예를 들어 GitHub의 GFM 엔진은 개발자에게 익숙한 시스템 폰트와 좁은 행간, 그리고 회색의 두터운 인용구 바를 보여줍니다. 반면 Notion은 넉넉한 여백과 둥근 모서리, 부드러운 파스텔톤 콜아웃 블록을 사용하죠.

동일한 마크다운 텍스트라도 노션에서 볼 때는 여유로워 보이던 문단이 깃허브에서는 빽빽한 벽돌 텍스트처럼 답답하게 느껴질 수 있습니다. MarkdownHub 뷰어 상단의 테마 셀렉터로 GitHub, Notion, Classic 스타일을 번갈아 확인해 보면 줄바꿈 간격이나 제목 계층이 독자의 눈에 어떻게 비칠지 미리 가늠할 수 있습니다.

또한 좌우 분할 화면(Split View)에서 좌측 에디터와 우측 프리뷰의 스크롤이 자연스럽게 함께 움직이므로, 수백 줄에 달하는 긴 기획서나 API 명세서에서도 고쳐야 할 오타나 서식 오류의 위치를 즉각 찾아낼 수 있습니다.

시력이 피로하거나 작은 랩톱 모니터에서 작업할 때는 상단 폰트 크기 슬라이더를 이용해 13px부터 20px까지 본문 크기를 키워 편안한 시야를 확보할 수 있습니다.

💡 실무 노하우 팁

• GitHub 저장소에 올릴 README라면 GitHub 테마를 켠 상태에서 표 헤더의 정렬과 코드 블록의 가로 스크롤 발생 여부를 미리 확인해 두는 것이 좋습니다.
• 사내 위키나 노션으로 공유할 팀 문서라면 Notion 테마로 전환하여 문단 사이 여백이 너무 벌어지지 않았는지 확인하세요.
• 모바일 화면에서도 상단 탭을 통해 원본 에디터와 결과 프리뷰를 손쉽게 전환하며 문서를 검토할 수 있습니다.

수학 공식이나 논문 요약을 작성할 때 쓰이는 LaTeX 문법은 사소한 띄어쓰기 하나로 렌더링이 실패하곤 합니다. MarkdownHub는 가볍고 빠른 KaTeX 엔진을 사용하므로, 문장 중간에 들어가는 인라인 수식은 $E=mc^2$처럼 달러 하나로 감싸고, 독립된 블록 수식은 $로 감싸서 작성합니다.

자주 겪는 실수 중 하나는 시작 달러 바로 뒤나 끝 달러 바로 앞에 공백을 두는 것입니다. $ x + y $처럼 쓰면 일부 렌더러가 수식이 아닌 일반 화폐 기호($)로 착각해 렌더링을 건너뜁니다. 반드시 기호와 수식 내용 사이에 공백이 없도록 붙여 써야 합니다.

Mermaid 다이어그램을 그릴 때도 실수가 잦습니다. 백틱 3개 뒤에 mermaid를 소문자로 지정하고 순서도를 그릴 때, 노드 라벨 안에 한글이나 특수문자, 괄호가 들어가면 파서가 문법 오류를 일으키기 쉽습니다. 이럴 때는 A["한글 라벨"]처럼 라벨 텍스트를 큰따옴표로 감싸주는 것이 가장 안전합니다.

MarkdownHub는 수식이나 차트 문법에 실수가 있더라도 화면 전체가 멈추지 않고, 해당 블록 위치에만 오류 원인과 함께 원본 코드를 보여주므로 어느 줄에서 오타가 났는지 빠르게 찾아 고칠 수 있습니다.

### 1. 인라인 및 블록 수식
아인슈타인의 질량-에너지 등가 원리는 $E = mc^2$ 입니다.

정규분포 확률밀도함수 공식:
$f(x) = \frac{1}{\sigma \sqrt{2\pi}} e^{-\frac{1}{2}\left(\frac{x-\mu}{\sigma}\right)^2}$

### 2. Mermaid 시스템 흐름도
```mermaid
flowchart LR
    A["마크다운 원문"] --> B{"렌더러 엔진"}
    B -->|수식 표현식| C["KaTeX"]
    B -->|다이어그램| D["Mermaid"]
    B -->|서식 복사| E["MS Word / Notion"]
```

⚠️ 실무 주의사항

• Mermaid 코드 블록 내부에 한글이나 괄호 기호를 넣을 때는 라벨을 반드시 큰따옴표로 묶어주어야 파싱 에러를 예방할 수 있습니다.
• 분수(\frac{a}{b})나 행렬 수식을 작성할 때 닫는 중괄호가 누락되지 않았는지 꼼꼼히 확인하세요.

마크다운을 쓰면서 가장 난감한 순간은 마크다운을 지원하지 않는 곳에 작업물을 넘겨야 할 때입니다. 열심히 작성한 텍스트를 그냥 복사해서 MS Word, 구글 닥스, 또는 사내 아웃룩 메일에 붙여넣으면 온갖 샵(#)과 별표(**), 파이프(|) 기호가 그대로 드러나 동료들에게 성의 없는 문서로 보이기 십상입니다.

MarkdownHub 뷰어의 [서식 복사] 기능은 단순 텍스트가 아니라 브라우저가 화면에 그려낸 시각 스타일(HTML 구조, 폰트 굵기, 색상, 인라인 CSS)을 클립보드의 text/html 데이터로 묶어 전달합니다.

이렇게 복사된 데이터는 Word나 Google Docs에 붙여넣을 때 브라우저에서 보던 제목 크기, 굵은 글씨, 코드 블록의 배경색이 그대로 유지됩니다. 특히 표(Table)의 경우, 셀마다 경계선 스타일(border: 1px solid #cbd5e1)을 인라인으로 심어주기 때문에 워드에 붙여넣었을 때 선이 날아가서 글자만 공중에 떠 있는 현상을 방지해 줍니다.

다크 모드를 켠 상태에서 복사하더라도 붙여넣을 대상 문서가 흰색 종이라는 점을 고려하여, 클립보드로 들어가는 서식은 인쇄에 적합한 표준 라이트 테마 스타일로 자동 변환되어 저장됩니다.

첫째, 샵(#) 기호 뒤 스페이스 누락: #제목처럼 샵과 글자 사이에 공백이 없으면 표준 규격에서는 제목 태그가 아니라 일반 텍스트 해시태그로 취급합니다. 반드시 # 제목 형태로 한 칸 띄워야 합니다.

둘째, 줄바꿈의 착각: 마크다운 표준 사양에서는 키보드의 엔터(Enter) 한 번을 줄바꿈이 아닌 단순 공백 한 칸으로 해석합니다. 실제 줄바꿈을 적용하려면 문장 끝에 스페이스를 2번 치거나 문단 사이에 빈 줄을 하나 더 두어야 합니다. (MarkdownHub 뷰어 설정에서는 엔터 한 번으로 줄바꿈이 되는 GFM Soft Break 옵션도 지원합니다.)

셋째, 코드 블록 언어 지정: 백틱 3개(```)로 코드를 감쌀 때 여는 백틱 옆에 python, typescript, sql 같은 언어명을 소문자로 적어주지 않으면 구문 강조(Syntax Highlighting) 색상이 적용되지 않아 가독성이 떨어집니다.

넷째, 표 셀 안에서 엔터 입력: 표의 셀 안에서 다음 줄로 넘어가려고 엔터를 누르면 행 전체가 분리되어 표가 망가집니다. 셀 안에서 줄을 바꾸고 싶다면 엔터 대신 <br> 태그를 사용해야 합니다.

다섯째, 이미지 상대 경로 오기: 로컬 컴퓨터의 파일 경로(file:///C:/Users/...)를 적어두면 내 화면에서는 보일지 몰라도 웹에 배포하거나 타인에게 보냈을 때 엑스박스로 뜹니다. 반드시 웹에 호스팅된 주소나 깃허브 저장소 상대 경로를 적어야 합니다.

💡 실무 노하우 팁

• 하단 통계 표시줄에서 글자 수, 공백 제외 글자 수, 단어 수와 함께 예상 읽기 시간을 확인하면서 보고서 분량이 너무 길어지지 않게 조절해 보세요.