워드프레스 블로그를 Hugo나 11ty, Obsidian으로 옮기려고 관리 화면에서 '도구'의 '내보내기'를 누르면, 나오는 것은 마크다운이 아니라 XML 파일입니다. 여기서 손이 멈추는 분이 많을 것입니다. 이전 경로는 하나가 아니며, 글 수와 손에 있는 환경에 따라 가장 빠른 길이 달라집니다. 이 글에서는 3가지 경로를 비교하고, 각각의 절차와 놓치기 쉬운 후처리까지 정리합니다.
어떤 경로로 이전할까
먼저 결론 판단표입니다.
- 수십~수백 건을 한꺼번에 이전하고 싶다. 로컬에서 Node.js를 실행할 수 있다 — 경로 A(wordpress-export-to-markdown)
- 서버 쪽에서 모두 끝내고 싶다. 플러그인을 추가할 수 있는 관리자 권한이 있다 — 경로 B(내보내기 플러그인)
- 대상은 몇 개 글뿐. Node.js도 플러그인도 쓸 수 없거나, 외부로 유출하면 안 되는 글을 다룬다 — 경로 C(브라우저 안 변환, 무료·가입 불필요·업로드 없음)
경로 C는 '이전'이라기보다 '변환'에 가까운 손쉬운 수단이지만, 초안 하나만 먼저 옮기고 싶다거나 퇴사자가 남긴 사내 워드프레스에서 글을 구하고 싶다는 상황에서는 가장 빠릅니다.
내보낸 XML이 그대로 마크다운이 되지 않는 이유
워드프레스 관리 화면에서 '도구'에서 '내보내기'를 실행하면 WordPress eXtended RSS(WXR)라고 부르는 XML 파일새 탭에서 열립니다이 다운로드됩니다. 글·고정 페이지·카테고리·태그·댓글 등을 한꺼번에 담는 형식이며, 본문은 이 XML 안에 HTML로 들어 있습니다. 즉 내보내기 직후 상태는 'XML 껍데기 속 HTML'이며, 마크다운까지는 두 단계 변환이 필요합니다.
게다가 블록 에디터(구텐베르크)로 쓴 글의 본문에는 블록 구분이 HTML 주석으로 직렬화되어 있습니다. 워드프레스 공식 블록 에디터 설계 문서새 탭에서 열립니다에 나온 대로, 문단 하나가 다음과 같은 형태로 저장됩니다.
<!-- wp:paragraph -->
<p>블록의 세계에 오신 것을 환영합니다.</p>
<!-- /wp:paragraph -->
[gallery] 같은 쇼트코드도 본문에 그대로 남아 있습니다. 이 3개 층(XML 껍데기·블록 주석·쇼트코드)을 어떻게 처리하느냐가 경로 선택의 핵심입니다.
이전 전에 확인 - 무엇이 남고 무엇이 사라지는가
어떤 경로를 택하든 본문(제목·문단·목록·링크·표·코드 블록)은 마크다운이 됩니다. 차이가 나는 것은 메타데이터입니다.
- 게시일·슬러그·카테고리·태그는 WXR에 포함됩니다. 경로 A는 이것을 frontmatter로 써 주지만, 경로 C는 복사한 본문 HTML만 다루므로 frontmatter는 직접 붙여야 합니다
- 독자 댓글은 어떤 경로로도 마크다운 파일이 되지 않습니다. 이전 후에도 표시하고 싶다면 정적 사이트용 댓글 서비스로 바꾸는 작업이 별도로 필요합니다
- 커스텀 필드의 처리는 도구에 따라 다릅니다. 이전 후에 필요한 값이 있다면 어떤 필드를 쓰고 있는지 미리 목록으로 정리해 두세요
경로 A - wordpress-export-to-markdown으로 일괄 변환
사실상 표준으로 쓰이는 도구가 wordpress-export-to-markdown새 탭에서 열립니다입니다. WXR 파일을 입력으로 받아 글마다 frontmatter가 붙은 마크다운 파일을 생성하고, 본문 속 이미지도 내려받아 참조를 고쳐 줍니다(기능 목록은 저장소 README에 있습니다).
- 관리 화면의 '도구'에서 '내보내기'를 열고 '모든 콘텐츠'를 선택해 XML을 내려받습니다.
- Node.js가 설치된 환경에서 명령을 실행합니다.
npx wordpress-export-to-markdown
대화형 마법사가 실행되어 입력 파일 위치·출력 위치·폴더 구성(--post-folders / --date-folders)·파일명에 날짜 붙이기(--prefix-date)·이미지 저장 방식(--save-images)·frontmatter에 넣을 필드(--frontmatter-fields) 등을 고를 수 있습니다. 글 수가 많을수록 이 일괄 처리의 효과가 커집니다.
경로 B - 플러그인으로 내보내기
서버 쪽에서 모두 끝내고 싶다면 Static Site Exporter(구 Jekyll Exporter)새 탭에서 열립니다 같은 내보내기 플러그인이 있습니다. 글과 고정 페이지를 YAML frontmatter가 붙은 마크다운으로 만들어 ZIP으로 묶어 주므로 Jekyll이나 Hugo에 그대로 옮기기 쉬운 형식입니다.
주의할 점은 두 가지입니다. 플러그인을 추가하려면 관리자 권한이 필요하다는 것, 그리고 같은 플러그인 페이지에도 적혀 있듯 규모가 큰 사이트에서는 웹 화면 실행이 타임아웃되기 쉬워 명령줄 실행이 권장된다는 것입니다. 호스팅에 따라서는 PHP 메모리 한도에 걸리기도 합니다.
경로 C - 브라우저만으로 변환하기
몇 개 글뿐이라면 환경 구축이 필요 없는 브라우저 안 변환이 가장 빠릅니다. 입력을 꺼내는 방법은 두 가지입니다.
- 블록 에디터에서 글을 열고 오른쪽 위 옵션에서 '코드 편집기'로 전환해 본문 HTML을 복사한다. 이 HTML에는
<!-- wp:paragraph -->같은 블록 주석이 들어 있습니다 - 공개된 페이지를 브라우저로 열고 개발자 도구 등으로 글 부분의 HTML을 복사한다. 렌더링된 HTML이므로 블록 주석은 없고, 대신 테마가 붙인 래퍼 요소가 함께 옵니다
복사했다면 HTML to Markdown에 붙여넣고 실행하기만 하면 됩니다.
예를 들어 코드 편집기에서 복사한 다음 HTML을 붙여넣으면,
<!-- wp:heading -->
<h2 class="wp-block-heading">Migrating the archive</h2>
<!-- /wp:heading -->
<!-- wp:image -->
<figure class="wp-block-image size-large"><img src="https://example.com/wp-content/uploads/2024/03/diagram.png" alt="Architecture diagram" class="wp-image-42"/><figcaption class="wp-element-caption">Figure 1: the old stack</figcaption></figure>
<!-- /wp:image -->
출력은 이렇게 됩니다.
## Migrating the archive
Figure 1: the old stack
블록 주석과 wp-block-* class, 인라인 style은 사라지고 제목·이미지는 마크다운 문법으로 바뀝니다. figcaption의 캡션은 이미지 아래에 평문으로 남습니다. <pre class="wp-block-code"> 코드 블록은 펜스 코드로, 표는 파이프 표로 바뀝니다. 쇼트코드는 HTML이 아니므로 변환되지 않고, \[gallery ids="12,13,14"\]처럼 대괄호가 이스케이프된 평문으로 남습니다(후처리 절에서 다룹니다).
변환은 모두 브라우저 안의 JavaScript로 완결되며, 붙여넣은 내용은 어디로도 전송되지 않습니다. 사내 워드프레스의 글이나 미공개 초안을 다룰 때, 업로드형 변환 서비스와의 차이가 여기서 드러납니다.
이전 후 후처리 체크리스트
어떤 경로를 거치든 다음 4가지는 마지막에 손을 대게 됩니다.
- 쇼트코드 정리.
[gallery][caption]이나 플러그인 고유 쇼트코드는 마크다운으로 바뀌지 않고 남습니다. 속성 유무나 감싸는 형태 등 모양이 일정하지 않으므로 일괄 치환보다 에디터에서[를 검색해 하나씩 판단하는 편이 안전합니다 - 이미지 옮기기. 경로 C에서는 이미지 URL이
wp-content/uploads를 그대로 가리킵니다. 이전 대상에 이미지를 내려받아 URL을 고쳐 씁니다.srcset이나loading="lazy"속성은 변환 시 사라지므로, 필요하다면 이전 대상 쪽에서 다시 붙여야 합니다 - 내부 링크 수정. 옛 도메인이나 고유주소 구조(
?p=123형식 등)를 가리키는 링크를 이전 대상의 URL 규칙에 맞춥니다 - frontmatter 부여. 제목·날짜·태그를 YAML로 맨 앞에 붙입니다. 정적 사이트 생성기(SSG)마다 형식이 다르므로 대상 SSG의 문서에서 확인하세요
비교 - 3가지 경로 구분해 쓰기
| 경로 | 적합한 규모 | 필요 환경 | 메타데이터 | 이미지 |
|---|---|---|---|---|
| A: wordpress-export-to-markdown새 탭에서 열립니다 | 수십~수백 건 일괄 이전 | Node.js + WXR 내보내기 | frontmatter에 자동 기록 | 내려받아 참조 수정 |
| B: 내보내기 플러그인 | 서버 쪽에서 끝내고 싶을 때 | 관리자 권한(플러그인 추가) | frontmatter에 자동 기록 | 플러그인에 따라 다름 |
| C: HTML to Markdown | 몇 개 글만 이전 | 브라우저만(무료·가입 불필요) | 직접 부여 | URL은 남고 수동으로 옮김 |
자주 묻는 질문
Node.js 없이 워드프레스 글을 마크다운으로 만들 수 있나요?
가능합니다. 플러그인을 추가할 수 있다면 경로 B, 안 된다면 경로 C입니다. 글을 코드 편집기 보기로 바꿔 HTML을 복사하고 HTML to Markdown에 붙여넣으면 환경 구축 없이 마크다운을 얻을 수 있습니다.
구텐베르크의 블록 주석은 변환 후에도 남나요?
FormatArc의 변환에서는 <!-- wp:paragraph --> 같은 HTML 주석이 출력에 남지 않습니다. 참고로 이 주석은 코드 편집기에서 복사한 HTML에만 들어 있으며, 공개된 페이지에서 복사한 HTML에는 애초에 포함되어 있지 않습니다.
이미지도 함께 이전할 수 있나요?
경로 A는 본문 속 이미지를 내려받아 참조를 고쳐 쓰는 기능을 갖고 있습니다(README새 탭에서 열립니다 기재). 경로 C는 변환만 하므로 이미지 URL은 원래 사이트를 그대로 가리킵니다. 몇 개 글뿐이라면 이미지를 수동으로 저장하고 URL을 고쳐 쓰는 편이 현실적입니다.
비공개 초안이나 사내 워드프레스 글을 외부 도구에 붙여도 안전한가요?
서버로 전송하는 방식의 도구는 붙여넣은 순간 내용이 손을 떠납니다. FormatArc는 브라우저 안에서만 처리하며 전송 자체가 일어나지 않습니다.
클래식 에디터로 쓴 오래된 글도 같은 절차로 이전할 수 있나요?
가능합니다. 클래식 에디터의 본문은 블록 주석이 없는 순수 HTML이라 오히려 변환이 단순합니다. 경로 A·B·C 모두 클래식 에디터 글을 다룰 수 있습니다.
정리
워드프레스에서 마크다운으로의 이전은 규모와 환경에 따라 경로가 정해집니다. 수백 건을 한꺼번에 이전한다면 wordpress-export-to-markdown, 서버 쪽에서 끝내고 싶다면 내보내기 플러그인, 몇 개 글뿐이고 환경 구축 없이 기밀도 다뤄야 한다면 HTML to Markdown의 브라우저 안 변환이 가장 빠릅니다. 어떤 경로를 택하든 쇼트코드 정리·이미지 옮기기·내부 링크 수정·frontmatter 부여까지를 이전 범위에 포함해 계획하세요.