Headless CMS로 컨텐츠 관리하기

들어가며

포트원에서 헬프센터와 블로그를 운영하면서 컨텐츠 수정 요청이 정말 많았어요. 개발 작업 중에 “블로그 글 하나만 수정해주세요”라는 요청이 들어오면 컨텍스트 스위칭이 필요했고, 사실 컨텐츠 내용 자체는 개발자가 관여할 필요가 없는 부분인데도 기술적인 이유로 매번 개발자를 거쳐야 했죠.

무엇보다 마케팅팀이나 CS팀 같은 컨텐츠 담당자들이 직접 수정하고 싶어도 기술적 허들 때문에 매번 개발팀에 요청해야 하는 상황이 아쉬웠어요. 그래서 “컨텐츠 담당자가 직접 쉽게 수정할 수 있는 환경을 만들어보자!”는 목표로 Headless CMS 도입을 시작했습니다.

Tina CMS 선택 이유

포트원 프론트엔드 팀은 프로젝트 특성에 따라 다양한 CMS를 사용하고 있었어요. Hygraph, Webflow 등을 써봤지만, CS팀이나 마케팅팀이 직접 사용하기에는 어려움이 있었습니다. 편집 인터페이스가 복잡하거나, 배포가 어렵거나, 미리보기가 안되는 등의 문제가 있었죠.

그래서 Git 기반으로 동작하면서도 비개발자가 쉽게 사용할 수 있는 Tina CMS를 선택했어요. Strapi, Contentful 같은 서비스도 검토했지만, 별도 서버 없이 기존 Git 저장소와 통합되고 실시간 미리보기가 가능하다는 점이 가장 매력적이었습니다.

직관적인 스키마 구성과 GraphQL 지원

Tina CMS는 편집할 컨텐츠의 스키마를 코드로 직접 구성하는데, 그 방식이 매우 직관적이었어요.

const Content: Collection = {
  name: "post",
  label: "포스트",
  path: "/content/posts",
  format: "mdx", // md, mdx, yaml, json 다양한 포맷을 지원
  fields: [
    {
      type: "reference", // 다른 Schema로 등록된 데이터만 연결할 수 있도록 제한
      label: "작성자",
      name: "author",
      required: true,
      collections: ["author"],
    },
    {
      type: "string",
      label: "제목",
      name: "title",
      required: true,
      isTitle: true,
    },
    {
      type: "rich-text",
      label: "내용",
      name: "body",
      isBody: true,
      required: true,
    },
  ]
}

구성한 스키마는 CLI를 통해 GraphQL 스키마로 자동 변환되고, GraphQL 서버가 자동으로 생성돼요. 덕분에 컨텐츠를 불러오는 코드를 타입 세이프하게 작성할 수 있고, GraphQL Playground를 통해 API를 미리 테스트하기도 편했습니다.

Visual Editing의 편리함

위 화면처럼 실시간으로 컨텐츠를 편집하면서 즉시 프리뷰를 확인할 수 있어요. Visual Editing을 구현하려면 컴포넌트에 data-tina-field 속성을 추가해주면 됩니다. 이렇게 하면 편집 모드에서 해당 필드를 클릭했을 때 자동으로 편집 패널이 열려요. 아주 간단하죠?

const { data } = useTina(tinaResponse)
// ...
<h1 data-tina-field={tinaField(data, "field-name")}>
  Welcome to the PortOne's Blog!
</h1>

Git 기반 워크플로우 지원

Tina CMS의 가장 큰 장점은 Git을 데이터베이스로 사용한다는 점이에요. 모든 변경 이력이 Git에 남아서 언제든 이전 버전으로 롤백할 수 있고, 누가 언제 무엇을 수정했는지 추적하기도 쉬웠습니다. 컨텐츠를 수정하면 자동으로 커밋이 생성되고, 필요하면 PR 리뷰 프로세스도 거칠 수 있어서 기존 개발 워크플로우와 자연스럽게 통합되었어요.

추가로 Fully Open Source인 점, Self Hosting이 가능한 점, 쉽고 빠른 배포, 검색 기능, GA 같은 분석 도구 연동, SEO 지원 등 필요한 기능들을 모두 갖추고 있어서 더욱 매력적이었습니다.

아쉬운 점들

하지만 여느 프로젝트가 그렇듯, 사용해보면서 아쉬운 기능들도 존재했습니다.

Markdown 기반 편집의 한계

마크다운 기반이라 일반적인 에디터에서 당연하게 쓰던 기능들이 제한적이었어요.

• 공백, 들여쓰기, 문단 정렬 등의 세밀한 서식 조정이 어려움
• 특수문자 처리가 까다로움 (예: {}를 표시하려면 \{\}로 이스케이프 필요)
• Bold 처리 시 **문자열** 뒤에 공백이 있으면 적용이 안 되는 등 사소한 규칙들

이런 마크다운 특성을 비개발자가 이해하기 어려워서, 가끔 컨텐츠가 깨지면 개발자가 Raw Markdown 모드로 전환해서 직접 수정해야 하는 경우가 종종 있었습니다.

제한적인 검색 기능

Tina CMS의 기본 검색 기능이 아쉬웠어요. 특정 단어로 시작하거나 정확히 일치하는 경우만 검색되고, 단어 중간에 포함된 내용은 찾기 어려웠습니다.

다행히 Git 기반이라 컨텐츠가 실제 파일로 저장되어 있어서, 빌드 타임에 검색 인덱스를 직접 구축할 수 있었어요. 빌드 스크립트에서 컨텐츠 파일들을 파싱해 검색 인덱스를 생성하고, fuse.js로 검색을 구현했습니다.

빌드 타임에 인덱싱을 처리하니 런타임 성능도 좋고, 카테고리 매핑이나 메타데이터 처리 같은 복잡한 로직도 자유롭게 구현할 수 있었습니다.

프로젝트를 마치며 얻은 교훈

요구사항 정의의 중요성

처음 요구사항은 명확해 보였어요:

1. 편집이 쉽게 되고 쉽게 볼 수 있게 해주세요
2. 배포가 개발자 없이 되게 해주세요
3. 검색 기능 추가
4. Third Party 앱 연동

하지만 실제 사용자들이 써보니 에디터 기능에 대한 구체적인 요구사항들이 나왔어요. 마크다운이 지원하지 않는 기능들(정렬, 색상 변경, 연속 개행 등)을 계속 요청받으면서, CMS 선택 단계에서 에디터 기능을 더 꼼꼼히 검토했어야 했다는 교훈을 얻었습니다.

현실적인 타협점

완벽한 CMS는 없다는 걸 깨달았어요. 결국 우선순위에 따른 선택의 문제였습니다.

• WYSIWYG 에디터가 강력한 CMS: 커스터마이징이 어렵고 Git 워크플로우 포기
• 마크다운 기반 CMS (Tina): 에디터 기능은 제한적이지만 개발자 친화적
• 직접 구축: 완벽하게 맞출 수 있지만 개발/유지보수 비용이 큼

우리는 Git 워크플로우와 커스터마이징 가능성을 우선시했고, 에디터의 한계는 교육과 워크어라운드로 해결하기로 했습니다. 실제로 사용법을 충분히 안내한 후에는 도움 요청이 한 달에 한 번 정도로 크게 줄어들었어요.

마무리

Tina CMS는 특히 다음과 같은 팀에게 추천합니다.

• Git 기반 워크플로우를 유지하고 싶은 팀
• 별도 서버 운영 부담 없이 CMS를 도입하고 싶은 팀
• 개발자와 비개발자가 함께 컨텐츠를 관리하는 팀

처음에는 단순히 “마크다운 편집을 쉽게 하자”는 목적으로 시작했지만, 결과적으로 팀 전체의 컨텐츠 워크플로우를 혁신할 수 있었어요. 혹시 비슷한 고민을 하고 계신다면, Headless CMS 도입을 강력 추천드립니다!