Astro 블로그는 글을 어떻게 발행할까, CMS 없이 운영해본 과정

고스트에서 Astro로 블로그를 옮긴 뒤 가장 많이 달라진 것은 글을 발행하는 방법입니다. 고스트에서는 관리자 화면에 로그인해 제목과 본문을 쓰고 발행 버튼을 누르면 끝났습니다. 지금은 프로젝트 안에 Markdown 파일을 만들고, 사이트 전체를 한 번 빌드한 뒤 서버에 올립니다.

설명만 들으면 이전보다 복잡해 보입니다. 저도 관리자 화면이 없는 블로그를 직접 운영할 수 있을지 처음에는 감이 오지 않았습니다. 하지만 AI 코딩 도구에게 원하는 글과 수정 내용을 말로 설명하는 방식으로 작업해보니, 현재는 오히려 이 흐름이 더 단순하게 느껴집니다.

이 글은 Astro의 모든 배포 방법을 설명하는 설치 안내가 아닙니다. 고스트에서 Astro로 이전한 뒤 minml에서 실제로 글 한 편을 작성하고 확인해 공개하는 과정을 기록한 글입니다.

글 한 편은 Markdown 파일 하나입니다

현재 minml의 글은 데이터베이스가 아니라 프로젝트 안의 .md 파일로 저장됩니다. 파일 위쪽에는 제목, 주소, 설명, 발행일과 대표 이미지 같은 정보가 있고, 그 아래에는 실제 본문이 있습니다.

---
title: "글 제목"
slug: "article-address"
description: "글 설명"
publishedAt: "2026-07-31 02:40:00"
---

여기부터 본문을 작성합니다.

처음에는 이 형식이 관리자 화면보다 불편할 것 같았습니다. 그러나 글과 설정이 같은 파일에 있으니 백업 상태를 이해하기 쉬웠습니다. 어떤 글의 제목이나 주소를 바꾸려면 그 파일을 열어 확인하면 됩니다. 이미지를 어디에서 불러오는지도 본문이나 파일 상단에서 바로 찾을 수 있습니다.

Astro의 콘텐츠 컬렉션에는 글마다 같은 항목을 갖추었는지 검사하는 스키마를 둘 수 있습니다. minml도 제목과 주소, 날짜 같은 필드를 정해두었습니다. 필요한 항목을 빼먹거나 형식을 잘못 쓰면 빌드 과정에서 발견할 수 있다는 점이 마음에 들었습니다.

실제 작성은 AI에게 말로 요청합니다

제가 매번 Markdown 문법과 파일 경로를 직접 입력하는 것은 아닙니다. Claude Code나 Codex에 글의 주제와 제 경험을 전달하고 초안을 요청합니다. 결과를 읽어본 뒤 사실과 다른 부분, 말투가 어색한 부분, 빠진 경험을 다시 설명하며 수정합니다.

작업 방식은 대략 다음과 같습니다.

1. 제가 실제로 겪은 일과 결론을 먼저 전달합니다.
2. AI가 기존 글의 문체와 구조를 확인하고 초안을 만듭니다.
3. 가격, 정책, 소프트웨어 지원 범위처럼 바뀔 수 있는 내용은 공식 문서로 다시 확인합니다.
4. 제가 하지 않은 경험이나 지나친 단정이 들어가면 삭제합니다.
5. 기존 글과 겹치지 않는지, 자연스럽게 연결할 글이 있는지 확인합니다.

AI가 글을 빨리 만들어준다는 점은 분명 편합니다. 하지만 발행 책임까지 AI가 가져가는 것은 아닙니다. 특히 “무조건”, “반드시”, “이렇게 하면 승인된다” 같은 문장은 실제 근거가 있는지 다시 봅니다. 이번에 애드센스 재신청을 준비하며 기존 글을 고친 이유도 여기에 있습니다. 구체적인 점검 항목은 두 번 거절 뒤 정리한 애드센스 체크리스트에 기록했습니다.

로컬 화면에서 먼저 확인합니다

파일을 저장했다고 바로 공개하지 않습니다. 개발 서버를 실행하면 실제 사이트와 비슷한 화면을 내 컴퓨터에서 먼저 볼 수 있습니다. 지금 minml의 로컬 주소가 127.0.0.1:4321인 것도 이 과정 때문입니다.

이 단계에서는 다음을 확인합니다.

• 제목과 설명이 의도한 대로 표시되는가
• 문단과 표, 코드 블록이 모바일에서도 읽기 쉬운가
• 대표 이미지가 깨지지 않는가
• 내부 링크가 존재하는 주소를 가리키는가
• 이전 글과 디자인의 결이 어색하지 않은가

CMS의 미리보기 기능과 목적은 비슷합니다. 차이는 관리자 화면 안에서 보는 것이 아니라, 실제 빌드에 가까운 웹사이트를 로컬에서 연다는 점입니다. 디자인도 함께 수정했다면 글 하나만 보지 않고 목록, 소개, 문의 같은 주변 페이지도 확인합니다.

빌드는 발행 전 전체 검사에 가깝습니다

화면이 괜찮아 보이면 npm run build로 사이트를 빌드합니다. Astro는 기본적인 정적 사이트에서 배포할 HTML과 자산을 dist 폴더에 만듭니다.

이 과정이 중요한 이유는 새 글만 저장하는 것이 아니라 사이트 전체가 다시 만들어지기 때문입니다. 잘못된 콘텐츠 형식이나 코드 오류가 있으면 서버에 올리기 전에 빌드가 실패합니다. 물론 빌드 성공이 모든 링크와 문장까지 완벽하다는 뜻은 아닙니다. 그래서 minml에서는 생성된 페이지 수, 내부 경로와 로컬 이미지 파일도 별도로 확인합니다.

저는 이 단계를 “발행 버튼을 누르기 전 검사”라고 생각합니다. 고스트에서는 응용 프로그램이 방문자의 요청을 받아 페이지를 보여줬지만, 현재 구조에서는 미리 만들어진 HTML이 배포됩니다. 따라서 빌드 결과만 온전하면 글을 보여주기 위해 별도의 블로그 데이터베이스가 계속 실행될 필요가 없습니다.

서버에는 완성된 결과물을 교체합니다

minml은 호스팅 서비스의 자동 배포 대신 기존 서버를 계속 사용하고 있습니다. 로컬에서 빌드를 마친 결과물을 서버의 새 릴리스 폴더에 올리고, 정상 여부를 확인한 뒤 현재 사이트가 가리키는 위치를 새 릴리스로 바꿉니다.

기존 파일 위에 하나씩 덮어쓰지 않는 이유는 배포 중간의 섞인 상태를 방문자에게 보여주고 싶지 않기 때문입니다. 새 결과물이 모두 준비된 다음 한 번에 전환하면 문제가 생겼을 때 이전 릴리스로 돌아가기도 쉽습니다.

배포가 끝난 뒤에는 홈페이지와 새 글만 확인하지 않습니다. 사이트맵에 포함된 주소가 열리는지, 기존 글 주소가 유지되는지, 다른 웹사이트가 같은 서버에서 정상적으로 동작하는지도 확인합니다. 같은 서버를 쓴다고 해서 관련 없는 사이트까지 작업 범위로 잡는 것은 아닙니다.

관리자 화면이 없는 대신 얻은 것과 잃은 것

Astro 방식이 누구에게나 더 편한 것은 아닙니다. 휴대전화에서 바로 로그인해 글을 쓰고 발행하려면 고스트 같은 CMS가 훨씬 자연스럽습니다. 여러 명이 역할을 나눠 글을 작성하거나 예약 발행, 멤버십과 뉴스레터를 운영할 때도 완성된 관리 기능이 유리합니다.

반면 지금의 저에게는 다음 장점이 더 크게 느껴집니다.

• 글과 설정, 디자인을 한 프로젝트에서 함께 백업할 수 있습니다.
• 사용하지 않는 관리자 프로그램과 데이터베이스를 계속 운영하지 않아도 됩니다.
• 글 주소와 페이지 구조를 직접 통제할 수 있습니다.
• 수정 내역을 파일 단위로 확인하고 이전 상태와 비교하기 쉽습니다.
• 원하는 검사 과정을 배포 전에 추가할 수 있습니다.

불편한 점도 분명합니다. 글을 바꿀 때마다 다시 빌드하고 배포해야 하며, 관리자 화면이 기본으로 제공되지 않습니다. 지금까지 큰 불편을 느끼지 않은 이유는 이 과정을 AI 도구와 함께 진행하고 있기 때문입니다. AI가 없었다면 저도 매번 명령과 파일 구조를 직접 다루는 방식은 선택하지 않았을 가능성이 큽니다.

지금의 결론

CMS를 버렸다고 해서 발행 과정 자체가 사라진 것은 아닙니다. 관리자 화면의 발행 버튼이 Markdown 작성 → 로컬 확인 → 빌드 → 배포 → 운영 확인이라는 눈에 보이는 과정으로 바뀌었습니다.

단계는 늘었지만 각 단계에서 무엇이 일어나는지 알 수 있다는 점이 좋습니다. 글은 파일로 남고, 오류는 공개 전에 찾을 수 있으며, 서버에는 완성된 결과물만 올립니다. 블로그를 직접 통제하고 싶었던 제 목적에는 이 방식이 잘 맞습니다.

다만 “Astro가 CMS보다 무조건 낫다”는 결론은 아닙니다. 관리 화면이 필요한 사람에게는 CMS가 맞고, 파일과 배포를 직접 관리하고 싶은 사람에게는 정적 사이트가 맞습니다. 중요한 것은 유행하는 도구를 고르는 일이 아니라, 실제로 계속 글을 쓸 수 있는 운영 방식을 고르는 일이라고 생각합니다.

참고한 공식 문서

• Astro에서 Markdown 사용하기
• Astro 콘텐츠 컬렉션
• Astro 사이트 빌드와 배포