마크다운 파일 하나가 글로 꽂히는 마법: 클로드 코드로 구축한 자동화 파이프라인

이 글을 읽으면 마크다운 파일 하나가 워드프레스 글로 발행되는 흐름과, 이 방식이 내 블로그에 맞는지 고르는 기준을 알 수 있다. 요약 세 줄이다.

• 글의 원본이 워드프레스 서버 안에만 있다면, 서버가 사라질 때 글도 같이 사라진다. 원본은 내 폴더에 두는 게 먼저다.
• 마크다운 파일 하나에 제목·키워드·슬러그·이미지를 다 적어 두면, 명령 한 줄로 검증부터 발행까지 끝난다.
• 급하면 아래 판단표로 바로 가면 된다. 글 수에 따라 관리자 화면이 나을 때도 있다.

관리자 화면 대신 마크다운으로 쓰는 이유

마크다운으로 쓰면 서버가 사라져도 글이 남는다. 워드프레스 자동 발행을 시작한 계기도 편의가 아니라 원본을 어디에 둘 것인가라는 질문이었다.

나는 seoin.dev와 donbrief.com 두 블로그를 클로드 코드(터미널에서 쓰는 AI 코딩 도구)로 만들었다. 터미널은 화면의 버튼 대신 글로 명령을 적어 넣는 창이다. 글은 전부 옵시디언(마크다운 메모 앱) 폴더에 파일로 있고, 스크립트가 그 파일을 읽어 올린다.

이 방식의 가치는 서버가 사라진 날 알았다. 2편에 적었듯이 2026년 8월 16일 호스팅 트라이얼 만료로 서버가 통째로 삭제됐다. 복구까지 2~3일이 걸렸지만 글 6편과 허브 페이지, 슬러그, 이미지가 전부 옵시디언에 있었다. 잃은 콘텐츠는 없었다.

서버는 소모품이고 원본은 내 폴더에 있다. 이 한 줄이 마크다운 발행의 이유다.

관리자 화면에서 쓰면 원본이 데이터베이스(글과 설정을 담아 두는 워드프레스의 저장 공간) 안에만 남는다. 백업이 없으면 서버와 운명을 같이한다. 마크다운은 그냥 파일이라 iCloud든 Git(파일의 변경 이력을 저장해 두는 도구)이든 어디에나 복사된다.

마크다운 파일이 글이 되는 여섯 단계

이 여섯 단계를 알아 두면 발행이 어디서 멈췄는지 바로 찾을 수 있다. 사람이 손을 대는 곳은 첫 단계와 마지막 확인뿐이고, 나머지는 스크립트가 처리한다.

1. 마크다운 작성. 파일 맨 위 frontmatter(글의 속성을 적는 머리말)에 키워드, 슬러그, 메타디스크립션, 출처, 이미지, 카테고리를 적는다.
2. 검증 게이트. 필수 항목 누락, H1(글의 대제목) 개수, 이미지 alt(대체 텍스트) 누락, 영문이 아닌 슬러그를 error로 막고, SEO와 AEO 점수를 각각 0~100점으로 낸다.
3. REST API(프로그램이 워드프레스와 데이터를 주고받는 통로) 업로드. 마크다운을 HTML로 바꾸고 본문 이미지를 WebP(용량이 작은 이미지 형식)로 변환해 미디어에 올린 뒤 URL을 바꿔 넣는다.
4. Rank Math(SEO 플러그인) 메타 기록. 글 데이터와 함께 SEO 제목·설명·포커스 키워드를 같이 보낸다.
5. 대표 이미지 지정. 미리 만든 1200×630 썸네일을 미디어로 올려 대표 이미지로 등록한다.
6. 업로드 후 재조회. 글을 API로 다시 읽어 상태·슬러그·메타가 요청대로 저장됐는지 확인하고, 마크다운 머리말에 워드프레스 ID·링크·점수를 되돌려 적는다.

6번 재조회를 넣은 이유는 워드프레스가 요청을 조용히 바꿔 저장하는 경우가 있어서다. 슬러그가 대표적이고, 뒤의 함정 두 개 절에서 사고로 다시 나온다.

2026년 8월 기준 이 파이프라인으로 seoin.dev에 12편을 올렸고, 12편째 글은 SEO 97점·AEO 94점으로 발행됐다.

검증 게이트는 80점 미만이면 발행을 막는다

검증 게이트를 두면 점수가 낮은 글이 실수로 나가는 일이 없다. 게이트는 두 가지 점수를 매긴다.

SEO 점수는 12개 항목 합산이다. 키워드 배치, 메타디스크립션, 슬러그, H2 구조, 링크, 이미지 alt, 출처 같은 항목을 본다. AEO 점수(AI 검색이 답변으로 가져가기 쉬운 구조 점수)는 9개 항목이다. 질문형 제목, H2 직후 즉답, 수치와 출처, 표, 경험 신호, Q&A를 본다.

발행 옵션을 켰을 때 SEO 점수가 80점 미만이면 업로드를 중단한다. AEO는 기본 차단 조건이 아니다. 허브 같은 중요한 글에만 엄격 옵션을 켠다.

아래는 올리지 않고 검증만 돌려 본 화면이다. 막을 오류가 없고 두 점수가 항목별로 나온다.

캡션: 검증 게이트 터미널 실제 화면, 2026-08-29 기준

규칙을 문서가 아니라 코드로 막은 이유는 문서에만 적힌 규칙이 지켜지지 않는 걸 겪었기 때문이다. H1이 두 번 들어가는 버그가 재발행 때마다 5건씩 다시 생겼다. 그래서 2026년 8월 19일에 규칙을 코드로 옮기기로 정했다. 8월 26일에는 줄표 기호도 error로 추가했다. AI 초안이 두 문장을 줄표로 잇는 버릇이 있어서다.

워드프레스 REST API와 Application Password의 역할

이 두 용어만 알면 나머지는 옵션이다. 하나는 워드프레스로 들어가는 통로이고, 하나는 그 통로를 여는 열쇠다.

워드프레스 REST API는 관리자 화면 없이 프로그램이 워드프레스와 데이터를 주고받는 통로다. 공식 REST API 핸드북은 “애플리케이션이 JSON 객체를 주고받으며 워드프레스 사이트와 상호작용하는 인터페이스”라고 정의한다. JSON은 프로그램끼리 읽기 좋게 정리한 글자 묶음이다.

핸드북 첫 화면에 이 정의가 그대로 나온다.

출처: WordPress Developer Resources, REST API Handbook (2026-08-28 캡처)

Application Password는 그 통로에 들어갈 때 쓰는 전용 비밀번호다. 로그인 비밀번호를 스크립트에 넣지 않으려고 따로 발급한다. 워드프레스 코어 공식 안내에 따르면 워드프레스 5.6(2020년 11월)부터 기본 기능이다. 24자 영문·숫자 조합이고, 사용자 프로필 편집 화면에서 발급하고 언제든 취소할 수 있다. HTTPS 사이트에서만 기본으로 켜진다.

공식 안내 화면에서 도입 시점과 24자 형식을 확인할 수 있다.

출처: Make WordPress Core, Application Passwords: Integration Guide (2026-08-28 캡처)

공식 인증 문서는 이 비밀번호를 HTTPS 위에서 Basic Auth(사용자명과 비밀번호를 요청 머리에 붙이는 방식)로 보내라고 안내한다.

여기서 막히는 게 정상이다. 발급받은 비밀번호는 홈 폴더의 환경 파일에만 둔다. 옵시디언이나 Git에는 넣지 않는다. 401 오류(인증 실패)가 나면 십중팔구 사용자명과 이 비밀번호 조합이 틀린 것이다.

발급 화면은 이렇게 생겼다. 만들어 둔 비밀번호와 폐기 버튼이 함께 보인다.

캡션: 워드프레스 프로필 실제 화면, 2026-08-29 기준

하나 더 있다. Rank Math의 SEO 메타는 기본으로는 REST API에 노출되지 않아서 서버 쪽에 여는 코드가 필요하다. 나는 4편에서 플러그인을 줄이며 이 코드를 mu-plugins 폴더(워드프레스가 항상 켜 두는 필수 플러그인 폴더)로 옮겼다.

클로드 코드에 준 다섯 가지 조건

코드를 못 써도 조건을 정확히 말하면 스크립트가 나온다. 이 스크립트는 내가 한 줄도 직접 짜지 않았다. 클로드 코드에 조건을 말하고 결과를 검증했다.

프롬프트 원문은 기록에 남아 있지 않다. 기록에 남은 요구 조건은 다음 다섯 개다.

1. 기본은 draft(임시 저장)로 올리고, 공개는 옵션을 명시했을 때만 한다.
2. 업로드 없이 검증만 하는 dry-run 모드를 둔다.
3. 검증 오류가 나면 우회 옵션 대신 글을 고쳐서 다시 돌린다.
4. 업로드 뒤 글을 다시 읽어 저장 결과를 확인한다.
5. 성공하면 파일 머리말에 워드프레스 ID를 적어, 같은 파일을 다시 돌리면 기존 글을 수정하게 한다.

돌아보면 조건을 코드 대신 사고 시나리오로 말한 게 잘 맞았다. “실수로 공개되면 안 된다” 같은 문장이 그대로 기본값이 됐다. 조건이 좋았어도 사고는 났다.

실제로 겪은 함정 두 개, 한글 슬러그 404와 구버전 스크립트

이 두 함정을 미리 알면 같은 사고를 피할 수 있다. 두 사고 모두 날짜와 함께 기록에 남아 있고, 7편에서 다른 사고들과 함께 다시 정리한다.

한글 슬러그는 404를 냈고 영문 슬러그로 바꿨다

2026년 8월 13일, 발행된 글 2편의 URL이 전부 404였다. 404는 주소에 해당하는 글을 찾지 못했다는 뜻이다.

첫 번째 글은 한글 슬러그가 길었다. 한글을 주소용 문자로 바꾼(URL 인코딩) 길이가 200바이트 한도를 넘어 단어 중간이 잘렸다. 두 번째 글은 슬러그가 온전한데도 404였고, 캐시를 비워도 그대로였다. 당시 서버 환경에서 한글 슬러그 자체가 라우팅(주소를 글에 연결하는 처리) 문제를 일으킨다고 결론 내렸다.

둘 다 짧은 영문 슬러그로 바꾸니 즉시 정상이 됐다. 제목과 본문은 한글 그대로라 노출 걱정은 접었다.

스크립트는 3겹으로 고쳤다. 워드프레스의 한글 자동 슬러그 생성을 타지 않고 머리말의 영문 슬러그를 직접 보낸다. 업로드 전에 영문 소문자·숫자·하이픈인지 검사한다. 업로드 뒤 실제 저장된 슬러그를 다시 읽어 요청과 다르면 실패 처리한다.

발행 스크립트가 두 개 생겨 구버전을 쓴 날도 있었다

2026년 8월 26일, 발행 스크립트가 두 종류라는 걸 알았다. 정본은 옵시디언 안에 있었는데 구버전 사본이 다른 폴더에 남아 있었다. 그날 세션 초반엔 구버전인 줄 모르고 썼다.

원인은 8월 14일에 원래 스크립트가 확인되지 않아 옵시디언 안에 새 정본을 만든 결정이었다. 구버전은 실제로 남아 있었고 검증 규칙이 달랐다.

교훈은 단순하다. 스크립트가 하나뿐이라는 가정은 하지 않는다. 정본 경로를 프로젝트 허브 문서에 한 줄로 적어 두고 새 세션은 그 줄부터 읽게 했다.

관리자 화면 직접 작성 vs 마크다운 발행 판단 기준

여섯 가지 기준으로 두 방식을 비교하면 내게 맞는 쪽이 보인다. 모두가 스크립트를 만들 필요는 없다. 글 수와 이미지, 협업 형태에 따라 갈린다.

기준	관리자 화면 직접 작성	마크다운 + 스크립트
글 수	월 몇 편, 가끔 쓰는 블로그	주 여러 편, 두 사이트 이상 운영
이미지	글당 1~2장, 손으로 올려도 부담 없음	매 글 WebP 변환·대표 이미지·alt 검사 필요
협업	혼자 쓰고 혼자 올림	AI가 초안을 쓰거나 여러 사람이 파일로 주고받음
원본 보관	워드프레스 안, 백업 플러그인에 의존	내 폴더가 원본, 서버는 복제본
SEO 검증	Rank Math 점수를 눈으로 확인	게이트가 발행 전에 자동 차단
초기 비용	없음	스크립트 제작과 사고 대응 며칠

처음 블로그를 열고 월 몇 편만 쓴다면 관리자 화면이 맞다. 반대로 1편처럼 두 사이트를 같은 방식으로 굴리거나 AI에게 초안을 맡기는 순간부터는 파일 기반이 낫다.

서버는 소모품이고 원본은 내 폴더에 있다는 원칙만은 어느 쪽을 고르든 지키는 편이 좋다.

자주 묻는 질문

이 파이프라인을 설명하면 꼭 나오는 질문 네 가지다.

비개발자도 워드프레스 자동 발행 스크립트를 만들 수 있을까?

만들 수 있다. 조건을 말할 수 있으면 된다. 나도 코드를 쓰지 않고 앞에서 정리한 다섯 개 조건을 클로드 코드에 말했다. 다만 터미널 열기, Application Password 발급, 환경 파일 작성은 직접 해야 한다. 터미널이 처음이라면 클로드 코드 사용법부터 보는 편이 빠르다.

노션에서 바로 워드프레스로 올릴 수는 없을까?

마크다운으로 내보내면 된다. 내 파이프라인은 마크다운 파일을 읽는다. 노션 글을 마크다운으로 내보내 같은 폴더에 두면 같은 스크립트를 탄다. 머리말 항목은 직접 채워야 한다. 노션 API를 직접 붙이는 방식은 해 보지 않아 확인이 필요하다.

예약 발행은 어떻게 하나?

내 스크립트는 예약을 다루지 않는다. draft·publish·private 세 상태만 다루고 예약 시각 지정은 넣지 않았다. 예약이 필요하면 draft로 올린 뒤 관리자 화면에서 시각을 지정하거나, 스크립트 실행 자체를 정해진 시각에 돌리면 된다.

관리자 글 목록의 예약됨 탭을 열면 예약된 글과 시각을 한 번에 볼 수 있다.

캡션: 워드프레스 글 목록 실제 화면, 2026-08-29 기준

이미지는 어떻게 넣나?

본문에 표준 마크다운 이미지 문법으로 로컬 파일을 가리키면 된다. 스크립트가 WebP로 바꾸고 가로 최대 1200px로 줄여 올린 뒤 주소를 바꿔 넣는다. 대표 이미지는 CC0(저작권 제한 없이 쓸 수 있는 라이선스) 3D 아이콘에 제목을 얹는 별도 스크립트로 만든다.

정리

• 워드프레스 자동 발행의 진짜 목적은 원본을 서버 밖에 두는 것이다. 서버가 사라져도 글은 남는다
• 흐름은 마크다운 → 검증 게이트 → REST API 업로드 → Rank Math 메타 → 대표 이미지 → 재조회, 여섯 단계
• REST API는 프로그램이 워드프레스와 데이터를 주고받는 통로, Application Password는 그 전용 24자 비밀번호
• 함정 둘(한글 슬러그 404·구버전 스크립트)은 업로드 뒤 재조회와 정본 경로 명시로 막았다
• 월 몇 편이면 관리자 화면, 주 여러 편이거나 AI 초안이면 마크다운 + 스크립트

오늘 5분 과제는 하나, 지금 블로그 글의 원본이 서버 밖 어디에 있는지 확인하는 것이다.

다음 편은 워드프레스 SEO 설정 순서다. 시리즈 전체는 바이브코딩으로 워드프레스 블로그 만들기 허브에 있다.

마크다운 발행을 다른 도구로 해 본 경험이 있으면 댓글로 알려 주기 바란다.