기술블로그를 Gatsby로 만든 이유

안녕하세요. 오렌지아이 백엔드 개발자 정기주입니다.

사실 작년 입사 이후부터 기술 블로그에 대한 필요성과 흥미를 개인적으로 계속 가지고 있었어요. 단순히 외부에 '좋은 기술 쓰고 있다'를 보여주려는 목적보다는, 내부적으로 기술을 공유하고 전파하는 문화를 만들어보고 싶다는 마음이 컸죠. 그 과정에서 어떤 프레임워크를 쓸까?를 고민하다가, Next.js가 사내 프론트 프레임워크로 주력 사용되고 있음에도, 조금 다른 방향에서 접근해보고 싶었어요.

단순 정적 페이지라면, 굳이 SSR까지 필요할까? 그렇다면 빌드 최적화가 잘 되어 있는 프레임워크는 뭐가 있을까? 바로 그때 떠오른 게 Gatsby였습니다.

콘텐츠는 자주 바뀌지 않고, 정적 페이지로 충분히 구성 가능하고, 빌드 타임이 Next.js보다 빠른 구조를 가질 수 있다면? 여기에 개발자가 직접 마크다운(MDX)으로 문서를 작성하고, 리액트 컴포넌트를 재사용할 수 있다면 훨씬 더 유연한 기술 기록 플랫폼이 될 수 있겠다는 확신이 들었습니다.

왜 시작했을까?

기술 블로그라는 게 단순히 멋있어 보이려고 만드는 건 아니잖아요. 처음엔 그런 유혹이 없진 않았지만, 실제로 우리 팀 안에서 반복되는 질문들, 흘러가버리는 팁들, 그리고 온보딩 문서에 쓰긴 애매하지만 공유하고 싶은 깨달음들이 쌓이면서 이런 생각이 들었어요.

우리가 쌓는 노하우를 좀 더 잘 보이게 만들 수 없을까?

문서를 작성하고 정리하는 건 꾸준함이 필요한 일이죠. 그런데 만약 그 과정이 재미있거나, 혹은 결과물이 보기 좋아서 뿌듯하다면? 그런 사이클을 조직 안에 만들 수 있다면 좋겠다고 생각했습니다.

그 시작이 바로 Gatsby 기반의 기술 블로그였습니다. 처음에는 개인적으로 해보다가, 사내에서의 니즈와도 맞닿아 있어서 슬쩍 MVP를 만들어 공유해봤고 본격적으로 기술 블로그 플랫폼을 구축하게 됐어요.

왜 Gatsby였을까?

사내 프론트엔드 프레임워크는 주로 Next.js를 쓰고 있습니다. 사실 Next.js도 충분히 훌륭하죠. 그런데 ‘기술 블로그’라는 특수한 목적에는 Gatsby가 훨씬 더 잘 맞는다는 판단이 들었어요.

정적 콘텐츠에 최적화된 구조

Gatsby는 태생부터 정적인 콘텐츠를 다루기 위해 설계된 프레임워크입니다. 문서가 많고 자주 바뀌지 않으며, SEO를 중요하게 여기는 사이트에 아주 적합하죠.

• 대부분의 기술 블로그 글은 한 번 작성되면 거의 수정이 없습니다.
• 모든 콘텐츠를 사전 렌더링해서 HTML로 출력합니다.
• 이 HTML은 CDN을 통해 빠르게 서빙됩니다.

Next.js도 getStaticProps 등으로 SSG를 지원하지만, 기본은 SSR 중심이고, 라우팅과 데이터 의존성을 세밀하게 컨트롤하려면 꽤 손이 많이 갑니다. 그에 반해 Gatsby는 기본이 SSG이기 때문에 구조가 심플하고, 블로그나 문서 기반 서비스에 특화돼 있어요.

글을 쓰고 커밋만 하면 바로 배포되는 구조, 너무 매력적이지 않나요?

MDX로 글을 쓴다는 것

Markdown만으로도 충분하긴 합니다. 하지만 기술 블로그는 코드 블럭, 다이어그램, 혹은 동적인 시각화 컴포넌트를 종종 포함하죠. Gatsby에서는 .mdx를 쓰면 마크다운 문서 안에 리액트 컴포넌트를 자연스럽게 넣을 수 있습니다.

# 이건 제목입니다

<CustomDiagram title="My Architecture" />

디자인 시스템이나 공통 컴포넌트를 만들어두면 문서 작성이 반복될수록 점점 더 편해지고, 문서를 코딩하듯 재사용 가능한 상태로 만들 수 있습니다.

문서도 결국 코드라는 철학에 딱 들어맞는 방식이에요.

플러그인 생태계가 강력하다

Gatsby의 생태계는 생각보다 방대하고 탄탄합니다. 특히 블로그나 기술 문서 관련 플러그인은 이미 아주 잘 다듬어져 있어서 큰 커스터마이징 없이도 꽤 괜찮은 결과물을 빠르게 만들 수 있었어요.

• gatsby-plugin-mdx — MDX 파서
• gatsby-plugin-image — 이미지 최적화 및 lazy-load
• gatsby-plugin-feed — RSS 피드 자동 생성
• gatsby-plugin-sitemap — 검색엔진용 sitemap 구성
• gatsby-plugin-google-gtag — GA 연동

특히 SEO 메타 태그나 OG 이미지, 트위터 카드 같은 걸 손쉽게 붙일 수 있어서, 내부 직원뿐만 아니라 외부 검색 유입이 필요한 팀이라면 꽤 유용합니다.

빌드 타임에 강한 구조

문서가 많아지면 빌드 시간이 걱정되기도 하죠. Gatsby는 기본적으로 GraphQL로 정적 데이터 구조를 선언해서 빌드 타임을 명확히 제어할 수 있어요. 필요한 정보만, 필요한 방식으로 가져오게 되니 예측 가능한 퍼포먼스를 유지할 수 있습니다.

또, 빌드와 배포 파이프라인이 GitHub Actions로 자연스럽게 붙기 때문에, 내부 워크플로우와도 잘 맞았어요.

실제로 어떻게 만들었는가

아무리 좋은 도구도, 직접 써봐야 진짜를 알 수 있다

실제 구현 과정은 굉장히 단순하게 시작했습니다. 오히려 어떤 기능을 ‘안 넣을지’를 고민하는 게 더 어려웠던 것 같아요.

디렉토리 구조는 이렇게:

src/
├── content/
│   ├── tech/
│   └── culture/
├── components/
├── templates/
├── pages/
└── styles/

주요 흐름

1. gatsby-config.ts에 MDX, 이미지, 파일시스템 소스 설정
2. gatsby-node.ts에서 createPages로 슬러그 기반 라우팅 처리
3. 카테고리별로 글 목록 페이지 생성 (/tech, /culture 등)
4. MDX 파일에 메타데이터 추가 (title, tags, slug 등)
5. TailwindCSS 기반의 반응형 디자인 적용
6. GitHub Actions를 통해 PR 머지 시 자동 배포되도록 설정

---

Gatsby를 쓴다고 해서 모든 게 해결되진 않습니다. 콘텐츠가 없으면 기술 블로그는 그냥 껍데기일 뿐이니까요. 하지만 구조가 잘 잡혀있으면, 그 껍데기를 채우는 건 훨씬 쉬워집니다.

정리하자면:

• Gatsby는 정적 기술 블로그에 정말 잘 맞는 구조를 갖고 있다
• 사내 기술 공유 문화를 위한 첫 걸음으로 구축하기 매우 적합하다
• 무엇보다 개발자에게 친숙한 방식으로 기술을 기록하고 아카이빙할 수 있다

기술 블로그는 그냥 있어보이려고 만드는 게 아니라, 조직의 기술 체력을 다지고, 배운 걸 잊지 않도록 기록하는 공간입니다. 그리고 그 기록은 공유될 때 가장 큰 힘을 발휘합니다.

오늘의 작은 공유가, 내일의 큰 문제를 막아줄지도 모릅니다. 기술 공유, 결국 조직의 체력을 만든다

진짜 마무리하며 🙈

기술 공유를 통해 스스로를 돌아보고, 더 나은 동료 개발자들과 연결될 수 있는 접점이 되기를 기대합니다.

앞으로도 다양한 주제의 글을 기록하고 공유하면서,
조직의 기술력과 개발 문화를 자연스럽게 드러낼 수 있는 공간으로 키워나가겠습니다. 🙏🏻🙏🏻

---

기술 블로그를 고민 중이신가요?
그렇다면 Gatsby도 한 번쯤 고려해보시길 추천드려요 👋🏻