위키독스(WikiDocs) 전자책 마크다운 작성 및 MCP 활용 노하우
위키독스 전자책을 쓰며 익힌 마크다운 렌더링 규칙과, MCP로 책을 관리할 때의 노하우를 정리했습니다.
안녕하세요! 최근 위키독스(WikiDocs)에서 파이썬 생태계 관련 전자책을 대대적으로 리팩토링하고 작성하면서 쌓인 위키독스 마크다운 작성 및 MCP 활용 노하우를 공유하고자 합니다.
위키독스의 마크다운 렌더러는 일반적인 깃허브(GitHub) 마크다운과 약간 다른 고유의 규칙들이 있습니다. 이를 무시하면 PDF 전자책 변환 시 에러가 나거나 화면 렌더링 레이아웃이 깨질 수 있으므로 꼭 주의해야 합니다.
위키독스 마크다운 작성 핵심 규칙 (렌더링 충돌 방지)
1. 이모지(Emoji) 및 수평선 사용 금지
위키독스 환경에서는 문서를 PDF 전자책으로 변환할 때 본문에 이모지(심지어 코드 블록 내의 이모지도 포함)가 포함되어 있으면 변환 오류가 발생할 확률이 높습니다. 또한, 수평선 긋기(---, ***, ___) 문법은 렌더링 과정에서 테이블 구분자 등으로 오인되어 문서 레이아웃이 깨지는 원인이 될 수 있으므로 절대 사용하지 않는 것이 좋습니다.
2. 리스트 작성 전 빈 줄(Blank Line) 필수
리스트 기호(*, -, 1.)를 시작하기 직전에는 반드시 빈 줄(엔터)을 하나 넣어야 정상적인 리스트 형태로 렌더링됩니다. 일반 텍스트에 이어서 바로 다음 줄에 리스트 기호를 쓰면 그냥 텍스트의 일부로 인식될 수 있습니다.
3. 하위(중첩) 리스트는 스페이스 4칸 들여쓰기 위키독스의 들여쓰기 규칙은 꽤 엄격합니다. 하위 리스트(Nested list)를 만들 때는 스페이스 2칸이나 탭(Tab) 대신 스페이스 4칸을 사용해야만 깔끔하고 일관되게 중첩 리스트 구조가 그려집니다.
4. 단순 굵은 글씨 대신 올바른 헤딩(Heading) 태그 사용
섹션이나 소제목을 시각적으로 강조하기 위해 단순히 텍스트에 볼드체(**소제목**)를 적용하는 것은 권장되지 않습니다. 구조적으로 탄탄한 문서와 자동 목차(TOC) 생성을 위해, 반드시 의미에 맞는 헤딩 태그(####, #####)를 사용하여 계층 구조를 명확히 만들어 주는 것이 좋습니다.
5. 코드 블록 외부에서 역슬래시 문자로 따옴표 이스케이프 금지
위키독스는 코드 블록 외부의 일반 텍스트 영역에서 역슬래시 기호 사용을 엄격히 제한합니다. 마크다운 링크 타이틀 등을 작성할 때 큰따옴표를 이스케이프 처리하기 위해 [\"타이틀\"]처럼 작성하면 역슬래시 문자가 그대로 화면에 노출됩니다. 역슬래시는 오직 인라인 코드 블록이나 코드 영역 내부에서만 사용하세요.
6. 기존 이미지 링크 보존 및 가짜 이미지 삽입 금지
기존에 작성된 문서를 리팩토링하거나 업데이트할 때, 저자가 의도적으로 배치한 이미지 링크(예: )가 있다면 실수로 지우지 않도록 반드시 원본 그대로 유지해야 합니다. 또한,  (로고 대체) 처럼 실제로 존재하지 않는 가짜(Dummy) 이미지 링크나 플레이스홀더를 임의로 삽입하는 것은 절대 금지됩니다. 반드시 실제 존재하는 유효한 이미지 링크만 사용해야 합니다.
7. PDF 변환에 취약한 특수 기호 사용 자제
➔ 와 같은 화살표 특수 기호는 브라우저에서는 잘 보일지 몰라도, PDF 전자책으로 변환할 때 렌더링되지 않거나 글자가 깨질 위험이 있습니다. 이러한 특수 기호 대신 키보드로 쉽게 입력할 수 있는 일반 텍스트 기호(예: ->)를 사용하는 것이 훨씬 안전합니다.
MCP 기반 전자책 관리 워크플로우
LLM이나 MCP 툴을 사용하여 전자책 구조를 수정하거나 페이지를 업데이트할 때는 다음과 같은 워크플로우 패턴이 매우 효과적입니다.
- 구조 파악 먼저: 책 전체의 내용을 한꺼번에 불러오면 컨텍스트 토큰이 심하게 낭비되므로,
get_book_toc도구를 사용하여 책의 목차와 트리 구조(페이지 ID, 부모-자식 관계)를 가볍게 먼저 파악합니다. - 선택적 조회 및 수정: 트리 구조를 통해 타겟을 정한 후,
get_page로 필요한 페이지의 본문만 읽어옵니다. 그리고update_page를 호출하여 수정을 가합니다. 이때 굳이 수정이 필요 없는 속성(예:parent_id,open_yn)은 파라미터로 전달하지 않는 것이 더 안전합니다. - 대량 페이지 이동: 목차를 대대적으로 개편할 시, 타겟 페이지들의
parent_id를 일괄적으로 변경해주면 하위 페이지들을 통째로 다른 챕터로 옮기거나 새로운 레거시(Legacy) 보관소로 손쉽게 이주시킬 수 있습니다.
이러한 몇 가지 규칙들만 잘 지켜도 렌더링이 깨지는 스트레스 없이 우아하고 깔끔하게 위키독스 전자책을 작성하실 수 있습니다. 위키독스를 기반으로 책을 집필하시는 모든 저자 분들과, 자동화 봇을 만드시는 분들께 유용한 팁이 되기를 바랍니다!
이 글은 위키독스 블로그에 처음 실었습니다.
댓글 0
첫 댓글을 남겨 주세요.
Google로 로그인하고 댓글 남기기