블로그에 글 쓰는 마찰 줄이기 — Pages CMS 연동

이 사이트를 Astro로 옮긴 뒤로 글이 잘 안 쌓이고 있었습니다. 원인은 단순했어요 — 글 한 편 올리는 데 마찰이 너무 컸습니다. Pages CMS를 붙여서 그 마찰을 줄였고, 그 과정을 짧게 기록해둡니다.

어디서 막혔나

Astro의 콘텐츠 컬렉션은 읽고 빌드하는 쪽은 정말 깔끔합니다. 문제는 쓰는 쪽이었어요. 짧은 노트 하나를 올리는 흐름이 이랬습니다.

에디터를 연다 → src/content/posts/ 아래에 새 .md를 만든다
프론트매터를 채운다 (date 형식, category 값, tags 배열…)
본문을 쓴다
커밋하고 푸시한다

타이핑은 5분인데 주변 일이 5분 더 걸렸어요. 이동 중에 떠오른 한 줄을 적고 싶을 때 노트북을 켜고 git을 만지작거리고 있을 자신이 없었습니다.

후보들

Notion이나 별도 헤드리스 CMS(Contentful, Sanity 등)도 고민했지만, 마크다운 파일이 git에 그대로 남는다는 지금 구조의 장점을 포기하고 싶지 않았어요. 글의 원본이 내 레포 안에 있어야 백업·이전·검색이 다 단순해집니다.

그래서 조건이 좁혀졌습니다.

GitHub에 있는 마크다운을 직접 편집할 수 있을 것 — 별도 DB 없이
프론트매터를 폼으로 다룰 수 있을 것 — date, category, tags를 매번 손으로 안 적게
무료·오픈소스일 것 — 1인 사이트에 월 구독이 또 늘어나는 건 피하고 싶었어요
모바일에서도 그럭저럭 쓸 만할 것

Pages CMS가 이 네 가지를 다 채웠습니다. 구조는 단순해요 — Pages CMS는 내 GitHub 레포의 파일을 편집하는 웹 에디터고, 서버는 내 콘텐츠를 들고 있지 않습니다. 저장 = 커밋입니다.

`.pages.yml` 하나면 끝

설정은 레포 루트에 .pages.yml 하나를 두는 것뿐이었어요. 이 파일이 컬렉션의 스키마를 정의합니다.

content:
  - name: posts
    label: 글
    type: collection
    path: src/content/posts
    fields:
      - { name: title, label: 제목, type: string, required: true }
      - { name: description, label: 한 줄 설명, type: text, required: true }
      - { name: date, label: 발행일, type: date, required: true, default: now }
      - name: category
        label: 카테고리
        type: select
        default: note
        options:
          values:
            - { value: note, label: 노트 }
            - { value: project, label: 프로젝트 }
            - { value: learning, label: 학습 }
      - { name: tags, label: 태그, type: string, list: true }
      - { name: draft, label: 임시저장, type: boolean, default: true }
      - { name: body, label: 본문, type: rich-text }

핵심은 이거예요.

**path** — 컬렉션이 어느 폴더의 파일을 다루는지
**fields** — 프론트매터의 각 필드를 어떤 입력으로 보여줄지
**type: rich-text** — 본문을 마크다운 위에 얹은 노션 비슷한 에디터로 편집

projects 컬렉션도 같은 방식으로 한 번 더 정의해두면, 글과 작업물을 같은 CMS에서 함께 관리할 수 있습니다.

인증과 저장 흐름

pagescms.org에 GitHub로 로그인하면, 권한을 준 레포가 자동으로 잡힙니다. 거기서 글을 쓰고 Save를 누르면 Pages CMS가 내 레포에 커밋을 만들어요. 직접 푸시 권한이 필요한 만큼, 어떤 레포에 접근 가능한지는 GitHub의 fine-grained token으로 좁혀두는 게 좋습니다.

커밋이 들어가면 그 다음은 기존 배포 파이프라인 그대로입니다. 이 사이트는 git push가 들어가면 자동 빌드·배포되도록 잡혀 있어서, 글 쓰기 → 저장 → 잠시 후 사이트에 반영까지 한 흐름으로 묶였어요.

Draft 플래그 — 가장 잘 쓴 디테일

스키마에 draft: boolean을 넣고 기본값을 true로 잡았습니다. Astro 쪽에서는 콘텐츠 컬렉션을 읽을 때 draft !== true인 글만 노출되도록 필터링합니다.

덕분에 흐름이 이렇게 됐어요.

CMS에서 글을 쓰는 동안에는 draft 상태로 저장 — 사이트엔 안 보임
글이 완성되면 draft 체크를 풀고 다시 저장 — 그 커밋이 곧 발행

지금 이 글도 그 상태로 시작했고, 본문을 다듬는 중에는 사이트에 안 나타납니다. 실수로 미완성 글이 노출되는 사고가 구조적으로 막혀요.

트레이드오프

당연히 단점도 있었습니다.

미리보기가 약합니다 — Pages CMS의 에디터는 마크다운 렌더링 미리보기는 보여주지만, 내 사이트의 실제 타이포·스타일로는 보여주지 않아요. 정확한 모습은 빌드된 사이트에서 확인해야 합니다.
rich-text 출력이 100% 깔끔하진 않습니다 — 가끔 의도와 다르게 줄바꿈이나 빈 줄이 들어와요. 완성 직전에 한 번 raw 마크다운으로 점검하는 단계를 두는 게 안전합니다.
모바일 편집은 가능은 한데 쾌적하진 않습니다 — 짧은 노트엔 충분하지만, 코드 블록이 많은 글은 여전히 데스크탑이 편해요.

그래도 *“글을 쓰기 시작하는 비용”*이 확연히 낮아진 게 가장 큰 변화입니다.

배운 것

마찰의 위치를 정확히 찾기. 글이 안 쌓이는 원인이 글감이 없어서가 아니라 시작 비용이 높아서였다는 걸 분명히 하니, 해결책이 자연스럽게 좁혀졌습니다.
DB 없는 CMS가 의외로 강력하다. 파일이 곧 데이터고, git이 곧 이력이에요. 헤드리스 CMS의 무거움 없이 폼 기반 편집만 빌리는 구조가 1인 사이트엔 잘 맞습니다.
스키마는 한 번에 욕심내지 않기. 처음엔 필드를 최소한으로 잡고, 글이 쌓이면서 부족한 게 보일 때 하나씩 추가하는 게 결국 깔끔했어요.

다음에 해볼 것

이미지 워크플로우 정리 — 지금은 public/images에 직접 올리는데, CMS에서 업로드 → 본문 삽입까지 한 번에 되도록 다듬어보고 싶어요.
태그 자동완성 — 지금은 string 배열이라 오타가 나면 새 태그가 됩니다. 기존 태그를 자동완성하게 바꿀 예정.
글 외 콘텐츠로 확장 — projects 컬렉션을 같은 흐름으로 굴려보고, 잘 되면 읽은 책이나 짧은 메모 컬렉션도 추가해볼 생각입니다.

가장 좋아진 건 짧은 글의 비용이 낮아졌다는 점이에요. 긴 회고 글만 쓰던 공간에, 한 줄 발견이나 짧은 노트도 같이 쌓이기 시작했으면 합니다.