Docusaurus와 Mintlify 비교

문서 사이트를 만들면서 Docusaurus와 Mintlify를 나란히 놓고 봤다. 둘 다 OpenAPI 명세를 바탕으로 API 문서를 동적으로 생성할 수 있다는 공통점이 있었고, 그 외에는 결이 꽤 달랐다.

Docusaurus를 먼저 만져봤다

Docusaurus는 정적 사이트 생성기(SSG, 빌드 시점에 HTML을 만들어두는 방식)다. React 기반이라 React 문법과 MDX(마크다운에 JSX를 섞어 쓸 수 있는 포맷)로 페이지를 자유롭게 짤 수 있고, 문서뿐 아니라 블로그·랜딩페이지 같은 다양한 용도로 쓸 수 있다.

설치는 공식 템플릿 classic을 TypeScript로 받아왔다.

npx create-docusaurus@latest my-website classic --typescript

실행은 패키지 매니저에 맞춰 npm run start 또는 yarn start로 띄운다. 내부적으로는 docusaurus start CLI가 호출된다.

구조는 크게 문서, 사이드바, 페이지 정도로 잡고 보면 됐다. 기능을 플러그인 단위로 잘게 쪼개 둬서, 필요한 것만 골라 붙이는 방식이었다.

전체 설정은 docusaurus.config.ts 한 곳에서 한다. 플러그인 셋팅, 문서 구조 관리, 테마 같은 항목이 여기 모여 있다. 동적 파일 생성이나 문서 구조 설정을 위해 프로젝트 디렉토리 경로가 자주 등장하는데, id나 경로를 잘못 적으면 그대로 에러가 났다. docusaurus.config.ts에 적은 내용은 yarn start 시점에 적용된다.

플러그인 중 하나로 Swagger에서 쓰는 openapi.json 파일을 기반으로 API 문서 파일을 Docusaurus 프로젝트에 동적으로 생성해봤다. API try-it-out 같은 테스트 UI는 Docusaurus 코어에서는 지원하지 않지만, 커뮤니티 플러그인 docusaurus-plugin-openapi-docs(PaloAltoNetworks)를 붙이면 가능했다.

Mintlify는 결이 다른 SaaS였다

Mintlify는 정적 생성기가 아니라 문서 플랫폼(SaaS)이다. 플러그인 아키텍처 자체가 없고, API Playground·검색·기본 컴포넌트가 플랫폼에 내장돼 있다.

설정은 docs.json 파일 한 개로 한다. 사전 정의된 테마(mint·maple·palm·willow·linden·almond) 중 하나를 고르고, 거기에 색상·폰트·로고를 얹는 방식이라 코드로 직접 테마를 짜는 자유도는 낮은 대신 셋업이 가볍다.

페이지는 MDX 파일로 작성하고, 그 안에서 Mintlify가 제공하는 컴포넌트(Accordion, Card, Callout 등)를 가져다 쓸 수 있다. 배포는 Mintlify 대시보드를 통해 이뤄지는데, 연결한 GitHub 레포지토리에 푸시하면 자동 반영된다.

OpenAPI 파일을 넣어두면 API 명세 페이지를 동적으로 만들어주는 것도 같았고, 거기에 더해 try-it-out 형태로 직접 호출해볼 수 있는 API Playground가 기본으로 붙어 있었다.

나란히 놓고 본 차이

둘 다 OpenAPI 명세를 받아 API 문서를 동적으로 만들어주는 점은 똑같아서, 이 항목은 결정 기준이 못 됐다. 차이가 났던 건 그 이후였다. 테마와 페이지 구조를 코드로 직접 짜고 싶고, 배포 환경을 골라야 하는 상황이라면 Docusaurus 쪽이 손이 더 갔다. 반대로 API Playground 같은 기능을 따로 붙이지 않고 빠르게 띄우고 싶다면 Mintlify가 셋업 비용이 낮았다.