마크다운(Markdown) 문서를 작성할 때 기존 에디터들은 대부분 좌측의 원본 편집 창과 우측의 미리보기 창으로 나누어진 분할 화면 구조를 사용합니다. 이 방식은 모니터 가로 공간을 절반 이상 소모하며, 글을 쓰는 동안 원문과 결과물을 오가는 시선 분산과 시각적 피드백 지연을 유발합니다.
MarkText는 이러한 분할 화면의 단점을 개선한 오픈소스 마크다운 전용 에디터입니다. MIT 라이선스로 배포되는 크로스 플랫폼 애플리케이션으로, 키보드 입력과 동시에 마크다운 문법을 visual 요소로 변환하는 실시간 위지윅(WYSIWYG) 라이브 프리뷰 엔진을 제공합니다. CommonMark 및 GitHub Flavored Markdown(GFM) 규격을 지원하며, KaTeX 기반 수학 수식, Mermaid.js 다이어그램, 집중 모드, PDF·HTML 및 Pandoc 연동 변환까지 지원합니다.
※ 이 가이드는 MarkText v0.17.1 및 최신 버전 기준으로 작성되었습니다.
목차
1. MarkText 핵심 스펙 및 아키텍처 특징
MarkText는 Electron과 Vue.js, 가상 DOM 기반 Snabbdom 커스텀 코어로 제작된 마크다운 전문 편집기입니다.
2. MarkText 5단계 마크다운 문서 작성 파이프라인
MarkText에서 문서를 입력하고 인라인 시각화 렌더링을 거쳐 최종 외부 파일로 출력하기까지의 파이프라인입니다.
MarkText의 파이프라인은 텍스트 작성 중 불필요한 컨텍스트 스위칭을 제거하는 데 초점을 맞추고 있습니다.
- 원문 입력 (Raw Syntax Entry): 마크다운 표준 규칙(
#,**,-, ```)을 입력합니다. - 라이브 렌더링 (Real-time Live Preview): 입력 직후 Snabbdom 가상 DOM 코어가 AST(추상 구문 트리)를 분석하여 해당 커서 줄을 제외한 영역을 인라인 visual 요소로 즉시 전환합니다.
- 수식 및 차트 파싱 (KaTeX & Mermaid Parsing): LaTeX 수학 기호 및 Mermaid 블록을 감지하면 클라이언트 스크립트가 SVG 벡터 및 수식 폰트로 자동 랜더링합니다.
- 테마 및 모드 적용 (Custom Theme & Focus): 다크/라이트 테마 선택과 함께 주변 문단을 흐리게 처리하는 집중 모드나 커서 위치를 중앙에 고정하는 타자기 모드를 가동합니다.
- 멀티 포맷 내보내기 (Export & Publish): 완결된 마크다운 문서를 PDF, HTML, 또는 Pandoc CLI 기반 Word(.docx) 파일로 변환합니다.
3. 실시간 라이브 프리뷰(WYSIWYG)와 소스코드 모드 및 집중 편집 모드
MarkText는 전통적인 마크다운 편집기들과 차별화되는 세 가지 핵심 편집 모드를 탑재하고 있습니다.
📍 파일 › 설정 › 시각적 편집 모드 전환
실시간 위지윅(WYSIWYG) 라이브 프리뷰
# 제목을 입력하고 Enter를 누르면 기호가 사라지면서 즉시 스타일이 적용된 제목 헤더로 변환됩니다. **강조** 텍스트는 강조로 표시되며, 커서를 다시 해당 텍스트 위에 올려놓으면 수정 가능한 원본 마크다운 문법 기호가 재출현합니다. 이를 통해 WYSIWYG 고유의 직관적 시각 환경과 마크다운 고유의 빠른 키보드 입력 속도를 모두 유지합니다.
💡 꿀팁 마크다운 문법 대신 `Ctrl + Shift + P`로 명령어 팔레트를 실행하면 표 삽입, 수식 블록, 인용구 등을 GUI 메뉴에서 바로 추가할 수 있습니다.
소스코드 모드 (Source Code Mode)
전체 마크다운 원문 코드만 확인하거나 일괄 정규식 편집을 수행할 때는 소스코드 모드로 전환합니다.
- 단축키:
Ctrl + /(macOS:Cmd + /) - 특징: 라이브 렌더링이 일시 정지되며 순수 텍스트 편집기 형태로 모든 마크다운 태그가 노출됩니다.
집중 모드 (Focus Mode) 및 타자기 모드 (Typewriter Mode)
긴 글 작성 시 집중력을 유지하기 위한 기능입니다.
- 집중 모드 (
Ctrl + Shift + F): 현재 커서가 위치한 단락만 밝게 표시하고 상하단 주변 문단들을 반투명하게 어둡게 처리합니다. - 타자기 모드 (
Ctrl + Shift + T): 줄바꿈이나 타이핑 시 화면 스크롤이 자동으로 조정되어 현재 편집 중인 줄을 모니터 수평 중앙에 고정합니다.
4. KaTeX 수학 수식 및 Mermaid 다이어그램 시각화 작성
MarkText는 학술 논문, 기술 문서, 시스템 아키텍처 설계를 위한 웹 표준 렌더링 엔진을 내장하고 있습니다.
KaTeX 수학 수식 작성법
인라인 수식은 $ 기호로 감싸고, 독립적인 블록 수식은 $$ 기호로 감싸서 입력합니다.
1) 인라인 수식 입력
이차방정식의 근의 공식은 $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$ 입니다.커서를 밖으로 이동하면 KaTeX 엔진이 수식을 선명한 Vector 폰트로 즉시 렌더링합니다.
2) 블록 수식 입력 (Ctrl + Shift + M)
$$
\lim_{n \to \infty} \left(1 + \frac{1}{n}\right)^n = e
$$Mermaid.js 다이어그램 작성법
코드 블록 언어로 mermaid를 지정하면 순서도, 시퀀스 다이어그램, 상태도, ERD를 직관적으로 그릴 수 있습니다.
flowchart TD
A[사용자 마크다운 입력] --> B{MarkText AST 파서}
B -->|수식 기호| C[KaTeX 렌더러]
B -->|차트 코드| D[Mermaid.js 엔진]
C --> E[실시간 WYSIWYG 화면 출력]
D --> E⚠️ 참고 Mermaid 다이어그램 블록 편집 시 오타가 발생하면 'Diagram Syntax Error' 경고문이 표시됩니다. 문법 오류를 수정하면 정상 다이어그램으로 즉시 복구됩니다.
5. 고급 문서 내보내기(PDF/HTML/Pandoc) 및 이미지 관리 설정
MarkText는 완성된 마크다운 문서를 다양한 외부 발표 및 보관용 규격으로 변환하는 강력한 내보내기(Export) 환경을 지원합니다.
📍 파일 › 내보내기 (Export) › PDF / HTML / Pandoc
PDF 및 HTML 내보내기
- PDF 내보내기: 현재 설정된 테마 스타일(Cadmium, Material Dark 등)과 수식, Mermaid 다이어그램이 그대로 고해상도 PDF 벡터 문서로 인쇄 변환됩니다. 머리글(Header), 바닥글(Footer), 페이지 번호 삽입 옵션을 지정할 수 있습니다.
- HTML 내보내기: 웹 브라우저에서 바로 열람할 수 있도록 CSS 스타일시트와 임베디드 리소스가 포함된 단일
.html파일로 저장됩니다.
Pandoc CLI 연동을 통한 MS Word(.docx) / EPUB 변환
Pandoc 오픈소스 오픈 변환 툴이 시스템에 설치되어 있다면 MarkText에서 직접 MS Word 문서를 생성할 수 있습니다.
- Pandoc 설치:
# Windows (winget 사용 시) winget install JohnMacFarlane.Pandoc # macOS (Homebrew 사용 시) brew install pandoc - Pandoc 바이너리 경로 연결:
📍 File › Preferences › Export › Pandoc Path
`pandoc.exe` 실행 파일 경로를 지정합니다. - 내보내기 실행:
📍 File › Export › Word (.docx)
이미지 자동 관리 및 업로드 설정
클립보드에서 스크린샷 이미지를 Ctrl + V로 붙여넣을 때 동작 방식을 설정합니다.
📍 File › Preferences › Image
- 상대 경로 로컬 저장:
Copy images to designated folder선택 후./assets또는./images로 경로를 설정하면 문서와 동일한 폴더에 이미지 파일이 자동으로 복사 저장됩니다. - 클라우드 호스팅 자동 업로드: PicGo, GitHub Repository, Imgur API 등과 연동하여 붙여넣은 이미지를 클라우드 서버에 업로드하고 웹 URL 링크로 자동 교체할 수 있습니다.
6. 실무 생산성을 높이는 핵심 단축키 모음
MarkText의 실무 작업 속도를 높여주는 단축키 안내표입니다.
한눈에 보는 실행 체크리스트
✅ 핵심 정리 체크리스트
- ☑️ 공식 GitHub(marktext/marktext) release에서 사용 환경에 맞는 최신 버전을 다운로드합니다.
- ☑️ `Ctrl + /` 단축키를 이용해 WYSIWYG 라이브 프리뷰와 소스코드 편집 모드를 상호 전환해봅니다.
- ☑️ `File › Preferences › Image` 메뉴에서 붙여넣기 이미지 저장 폴더를 `./images` 로컬 상대 경로로 설정합니다.
- ☑️ KaTeX 수식(`$`, `$$`)과 Mermaid 차트 코드 블록을 작성하여 정상적으로 인라인 시각화되는지 확인합니다.
- ☑️ Pandoc CLI를 설치하고 `File › Preferences › Export`에 경로를 연결하여 DOCX 문서 내보내기를 설정합니다.
자주 묻는 질문 (FAQ)
Q1. MarkText는 무료로 상업적 프로젝트나 업무에 사용할 수 있나요?
네, MarkText는 오픈소스 라이선스 중 가장 자유도가 높은 MIT License로 공개되어 있습니다. 개인적인 노트 작성은 물론 기업 및 기관 내 상업용 마크다운 기술 문서 작성에도 제한 없이 무료로 활용할 수 있습니다.
Q2. Pandoc 내보내기 시 'Pandoc binary not found' 오류가 발생합니다.
Pandoc 실행 파일이 시스템 PATH 환경변수에 등록되어 있지 않거나 MarkText 기본 설정에서 경로를 찾지 못할 때 발생합니다. Terminal이나 PowerShell에서 `winget install JohnMacFarlane.Pandoc` 또는 `brew install pandoc`으로 설치를 완료한 후, 📍 File › Preferences › Export › Pandoc Path 항목에 pandoc.exe 전체 절대 경로를 직접 지정하면 해결됩니다.
Q3. 문서에 이미지를 붙여넣었을 때 원본 파일 용량이 커지는 문제 해결 방법은 무엇인가요?
기본 설정 상태에서는 이미지가 Base64 텍스트 문자열로 마크다운 원문에 그대로 인코딩될 수 있습니다. 📍 File › Preferences › Image 설정 창에서 Copy images to designated folder 옵션을 켜고 상대 경로(./assets)를 지정하면 이미지 파일이 별도 화상 디렉터리에 복사되고 문서에는 가벼운 상대 링크만 유지됩니다.
마무리하며
MarkText는 분할 창 방식이 유발하던 시선 분산을 제거하고 타이핑하는 순간 최종 결과물을 시각적으로 확인할 수 있는 라이브 프리뷰 마크다운 편집기입니다. KaTeX 수식 표현과 Mermaid 다이어그램, 다채로운 내보내기 옵션을 기반으로 마크다운 작업 효율성을 보장합니다.