현대적인 개발자 대상 문서를 구축할 때 많은 엔지니어링 및 테크니컬 라이팅 팀이 Mintlify를 채택하고 있습니다. 복잡한 프론트엔드 라우팅이나 커스텀 CSS 스타일시트를 직접 유지보수하는 대신, Mintlify는 '코드형 문서(Docs-as-Code)' 철학을 바탕으로 사이트 전체의 시각적 요소와 정보 구조를 저장소 루트에 위치한 단일 설정 파일인 docs.json(이전 규격의 mint.json)으로 일원화합니다. 팀은 렌더링 엔진 내부 코드를 수정할 필요 없이, 버전 관리되는 JSON 파일 안에서 전역 브랜드 자산, 계층형 사이드바, 접이식 그룹, 그리고 상단 탭 그룹을 선언적으로 정의할 수 있습니다.
본 가이드에서는 기술 문서 팀이 docs.json을 사용하여 브랜드 비주얼을 반영하고, 탐색하기 쉬운 사이드바를 설계하며, 멀티 섹션 탭 그룹을 구성하는 구체적인 실무 방법을 상세히 다룹니다.
1. 핵심 설정 아키텍처: docs.json 설계 규격
모든 Mintlify 사이트는 프로젝트 루트 디렉터리의 docs.json에 의해 제어됩니다. 최신 docs.json 스키마는 레이아웃 테마, 내비게이션 트리, 인터랙티브 API 콘솔, 타사 분석 도구 설정을 하나의 일관된 데이터 구조로 결합합니다.
스키마 검증 및 파일 경로 해석 규칙
VS Code 등 주요 에디터에서 자동 완성 및 실시간 구문 검증, 필드 도움말을 활성화하려면 docs.json 최상단에 공식 스키마를 선언하는 것이 좋습니다.
{
"$schema": "https://mintlify.com/docs.json",
"name": "Acme 개발자 허브",
"theme": "maple"
}
기술 문서 팀이 준수해야 할 핵심 파일 경로 규칙은 다음과 같습니다.
- 확장자 생략 경로 선언:
navigation배열에 지정하는 페이지 경로는 저장소 루트 기준 상대 경로이며,.mdx또는.md확장자를 생략합니다. 예를 들어"pages": ["getting-started/quickstart"]는 실제 파일getting-started/quickstart.mdx를 가리킵니다. - Git 기반 협업 워크플로: 내비게이션 구조의 변경, 신규 페이지 추가, 브랜드 컬러 수정은 모두 Git 브랜치와 Pull Request를 통해 코드 리뷰 및 프리뷰 배포 파이프라인을 거칩니다.
- 웹 에디터와의 양방향 동기화: 브라우저 기반 Mintlify 웹 에디터를 선호하는 문서 작성자가 드래그 앤 드롭으로 페이지 순서를 바꾸면, 시스템이 자동으로 Git 커밋을 생성하여
docs.json에 반영합니다.
2. 커스텀 브랜딩 및 시각적 정체성 설정
Mintlify는 복잡한 CSS 오버라이드 없이도 기업의 브랜드 디자인 가이드라인을 문서 포털에 충실히 반영할 수 있도록 지원합니다. 브랜딩 설정은 주로 docs.json의 최상위 필드에 구성됩니다.
레이아웃 테마(Theme)
Mintlify는 theme 속성을 통해 다양한 사전 제작 레이아웃 테마를 제공합니다.
mint: 널리 검증된 클래식 레이아웃으로, 일반적인 소프트웨어 및 오픈소스 문서에 적합합니다.maple: 현대적이고 정돈된 미학을 제공하여 AI 도구 및 SaaS 플랫폼에서 주로 선택됩니다.palm: 정보 밀도가 높고 체계적인 구조로, 핀테크 및 엔터프라이즈급 대규모 플랫폼에 알맞습니다.willow: 주변 요소를 최소화하여 글 읽기에 집중할 수 있는 미니멀 테마입니다.- 이외에도
linden,almond,aspen,sequoia,luma등을 지원합니다.
브랜드 컬러 및 다크 모드 최적화
colors 객체를 통해 브랜드의 핵심 색상을 지정합니다. Mintlify는 라이트 모드와 다크 모드 전반에서 시각적 가독성과 대비를 자동으로 보정합니다.
"colors": {
"primary": "#2563EB",
"light": "#60A5FA",
"dark": "#1D4ED8"
}
primary: 라이트 모드에서 활성 메뉴, 링크, 주요 인터랙션 버튼에 적용되는 핵심 브랜드 컬러입니다.light: 어두운 배경의 다크 모드에서 높은 가독성을 확보하기 위해 적용되는 강조 컬러입니다.dark: 두 모드 공통으로 마우스 호버(Hover) 상태 및 보조 액션 요소에 사용됩니다.
듀얼 모드 로고 및 파비콘(Favicon)
배경 밝기에 상관없이 선명한 로고를 보여주기 위해 라이트 모드와 다크 모드용 SVG 파일을 각각 지정하고, 클릭 시 이동할 URL을 설정합니다.
"logo": {
"light": "/images/logo-light.svg",
"dark": "/images/logo-dark.svg",
"href": "https://acme.com"
},
"favicon": "/images/favicon.svg"
logo.href를 생략하면 로고를 클릭했을 때 문서 사이트의 첫 페이지로 자동 이동합니다.
타이포그래피, 아이콘 및 배경 장식
- 폰트 지정:
fonts설정에서 Google Fonts의 폰트 패밀리명(예:"Inter"또는"Fira Code")을 지정하면 별도 설치 없이 비동기 로드됩니다. 자체 호스팅되는.woff2파일 경로를 지정할 수도 있으며, 제목(fonts.heading)과 본문(fonts.body) 서체를 개별 설정할 수 있습니다. - 아이콘 라이브러리: Mintlify는 Font Awesome, Lucide, Tabler 아이콘을 지원합니다.
"icons": { "library": "lucide" }를 선언하면 내비게이션 노드에서"book-open"과 같은 아이콘 이름을 직접 사용할 수 있으며, 인라인 SVG나 이모지도 지원합니다. - 배경 장식:
"background": { "decoration": "gradient" }또는"grid"설정을 통해 캔버스에 세련된 그라디언트나 그리드 패턴을 입힐 수 있습니다. - 테마 모드 고정: 브랜드 규정상 다크 모드만을 고정해야 하는 경우
"appearance": { "default": "dark", "strict": true }를 설정하여 사용자 측 모드 전환 토글을 숨길 수 있습니다.
3. 사이드바 내비게이션 구축: 그룹, 중첩 및 루트 페이지
사이드바는 독자가 기술 문서를 체계적으로 탐색하도록 돕는 핵심 내비게이션입니다. Mintlify에서는 navigation 객체 하위의 계층형 트리로 사이드바를 구성합니다.
기본 그룹과 아이콘 그룹
그룹(Group)은 기능적으로 연관된 문서들을 하나의 명명된 섹션으로 묶어줍니다. 그룹명(group)과 문서 목록(pages)으로 정의합니다.
"navigation": {
"groups": [
{
"group": "시작하기",
"icon": "rocket",
"pages": [
"quickstart",
"installation",
"authentication"
]
}
]
}
계층형 중첩 구조 및 기본 접힘 제어
문서 분량이 늘어나면 단일 평면 목록은 가독성을 떨어뜨립니다. Mintlify에서는 부모 그룹의 pages 배열 내에 자식 그룹을 중첩하여 배치할 수 있습니다.
사이드바가 지나치게 길어지는 것을 방지하기 위해 expanded 불리언 속성으로 중첩 그룹의 초기 접힘 상태를 제어합니다.
{
"group": "코어 아키텍처",
"icon": "cpu",
"pages": [
"architecture/overview",
{
"group": "데이터 스토리지",
"icon": "database",
"expanded": false,
"pages": [
"architecture/storage/relational",
"architecture/storage/caching"
]
},
{
"group": "보안 및 규정 준수",
"icon": "shield-check",
"tag": "NEW",
"pages": [
"architecture/security/rbac",
"architecture/security/encryption"
]
}
]
}
참고: 사이드바의 최상위 메인 그룹은 항상 펼쳐진 상태로 표시되며, expanded 속성은 중첩된 하위 그룹의 접힘/펼침을 제어합니다.
클릭 가능한 그룹 헤더와 루트 페이지(root)
기본적으로 사이드바의 그룹 제목을 클릭하면 하위 항목이 접히거나 펼쳐집니다. 하지만 그룹 제목 자체가 해당 주제의 전체 개요 페이지로 동작해야 하는 경우가 많습니다.
root 속성을 지정하면 그룹 제목을 특정 MDX 페이지와 연결할 수 있습니다.
{
"group": "API 레퍼런스",
"root": "api/overview",
"pages": [
"api/users",
"api/billing",
"api/webhooks"
]
}
사용자가 사이드바에서 "API 레퍼런스"를 클릭하면 오른쪽 화면에 api/overview.mdx가 렌더링되면서 하위 엔드포인트 목록이 함께 표시됩니다.
자동 디렉터리 인덱스(directory)
개요 페이지마다 수동으로 목차나 카드 링크를 만들 필요 없이, Mintlify는 root 페이지를 가진 그룹에 directory 자동 생성 레이아웃을 제공합니다.
directory에서 지원하는 값:
"card": 하위 페이지들을 제목과 요약이 포함된 클릭 가능한 가로 카드 형태로 렌더링합니다."accordion": 접이식 아코디언 패널 형태로 하위 목록을 정리합니다."none": 자동 인덱스 생성을 비활성화합니다(기본값).
directory 속성은 하위 계층으로 자동 상속되므로, 상위 섹션에 "directory": "card"를 설정하고 특정 세부 기술 문서에서만 "directory": "none"으로 재정의할 수 있습니다.
4. 탭 그룹(Tabs)을 활용한 멀티 도메인 분할
하나의 개발자 포털이 제품 가이드, 상세 API 레퍼런스, 다양한 언어별 SDK, 릴리스 노트를 모두 담고 있을 때, 이를 하나의 사이드바에 나열하면 심각한 인지 부하가 발생합니다. 상단 탭 그룹(Tabs)은 문서를 수평적 최상위 도메인으로 분할해 줍니다.
사이트 수준의 상단 내비게이션 탭
각 탭은 독립된 섹션으로 동작하며, 탭마다 고유한 URL 경로와 독립적인 사이드바 트리를 가집니다.
navigation.tabs 배열에 탭 구조를 정의합니다.
"navigation": {
"tabs": [
{
"tab": "가이드",
"icon": "book-open",
"groups": [
{
"group": "기본 개념",
"pages": ["guides/overview", "guides/quickstart"]
},
{
"group": "배포",
"pages": ["guides/docker", "guides/kubernetes"]
}
]
},
{
"tab": "API 레퍼런스",
"icon": "square-terminal",
"groups": [
{
"group": "엔드포인트",
"pages": ["api/v1/auth", "api/v1/payments", "api/v1/webhooks"]
}
]
},
{
"tab": "SDKs",
"icon": "code-2",
"groups": [
{
"group": "클라이언트 라이브러리",
"pages": ["sdks/node", "sdks/python", "sdks/go"]
}
]
},
{
"tab": "변경 로그",
"icon": "megaphone",
"href": "https://changelog.acme.com"
}
]
}
독자가 상단에서 "가이드", "API 레퍼런스", "SDKs" 탭을 전환하면:
- 사이드바가 해당 탭에 속한 그룹과 페이지로 즉시 교체됩니다.
- 브라우저 URL에 활성 탭의 경로가 반영됩니다.
href가 선언된 외부 링크는 헤더 디자인을 해치지 않고 외부 사이트로 자연스럽게 연결됩니다.
탭 내부 드롭다운 메뉴(menu)
단일 탭에 여러 독립 제품군이 포함되는 경우, 탭 내부에 menu 배열을 구성하여 상단 드롭다운 선택 메뉴를 제공할 수 있습니다.
{
"tab": "제품 라인업",
"icon": "layers",
"menu": [
{
"item": "결제 엔진",
"icon": "credit-card",
"description": "글로벌 결제 및 정산 연동 가이드",
"groups": [
{
"group": "연동 준비",
"pages": ["payments/intro", "payments/checkout"]
}
]
},
{
"item": "신원 인증 클라우드",
"icon": "key-round",
"description": "SSO, OAuth 2.0 및 디렉터리 동기화 규격",
"groups": [
{
"group": "인증 관리",
"pages": ["identity/overview", "identity/saml"]
}
]
}
]
}
전역 앵커(Anchors)와 탭의 차이점
- Tabs(탭): 문서의 주요 축을 나누는 도구로, 전환 시 사이드바 전체가 바뀝니다.
- Global Anchors(전역 앵커):
navigation.global.anchors로 지정하며, 사이드바 상단이나 하단에 고정되는 유틸리티 링크(예: "시스템 상태", "GitHub 저장소", "커뮤니티")로, 어떤 탭이나 페이지를 보고 있어도 항상 노출됩니다.
개념 구분: 전역 내비게이션 탭 vs 페이지 내 MDX <Tabs>
초심자가 혼동하기 쉬운 두 개념을 구분해야 합니다.
- 전역 내비게이션 탭(
docs.json): 사이트 전체의 라우팅과 사이드바 구성을 전환하는 구조적 요소입니다. - MDX 페이지 내
<Tabs>컴포넌트: 단일 문서 본문 내에서 코드 언어(예: cURL, JavaScript, Python)를 전환하기 위해 사용하는 인라인 UI 요소입니다. Mintlify는 기본적으로 한 페이지 내에서 같은 라벨명을 가진<Tabs>의 활성 상태를 동기화하며, 개별 전환이 필요한 경우sync={false}를 지정합니다.
5. 프로덕션 환경용 완전한 설정 예시
아래는 브랜드 토큰, 전역 앵커, 멀티 탭, 계층형 그룹 및 카드형 디렉터리 레이아웃이 적용된 프로덕션 수준의 docs.json 전체 설정 예시입니다.
{
"$schema": "https://mintlify.com/docs.json",
"name": "CloudScale 개발자 문서",
"theme": "maple",
"colors": {
"primary": "#059669",
"light": "#34D399",
"dark": "#047857"
},
"logo": {
"light": "/assets/brand/cloudscale-logo-light.svg",
"dark": "/assets/brand/cloudscale-logo-dark.svg",
"href": "https://cloudscale.dev"
},
"favicon": "/assets/brand/favicon.png",
"appearance": {
"default": "system",
"strict": false
},
"fonts": {
"family": "Inter"
},
"icons": {
"library": "lucide"
},
"background": {
"decoration": "gradient"
},
"navigation": {
"global": {
"anchors": [
{
"anchor": "시스템 운영 상태",
"icon": "activity",
"href": "https://status.cloudscale.dev"
},
{
"anchor": "개발자 슬랙 커뮤니티",
"icon": "messages-square",
"href": "https://cloudscale.dev/slack"
}
]
},
"tabs": [
{
"tab": "제품 가이드",
"icon": "book-open",
"groups": [
{
"group": "개요 및 초기 설정",
"root": "guides/index",
"directory": "card",
"pages": [
"guides/quickstart",
"guides/architecture",
"guides/cli-tooling"
]
},
{
"group": "인프라 구성",
"icon": "server",
"pages": [
"guides/compute-clusters",
{
"group": "네트워크 및 DNS",
"expanded": false,
"pages": [
"guides/networking/vpc-peering",
"guides/networking/tls-certificates"
]
}
]
}
]
},
{
"tab": "API 레퍼런스",
"icon": "square-terminal",
"groups": [
{
"group": "인증 및 토큰",
"pages": [
"api/auth/tokens",
"api/auth/service-accounts"
]
},
{
"group": "컴퓨트 API",
"root": "api/compute/overview",
"pages": [
"api/compute/instances",
"api/compute/snapshots"
]
}
]
}
]
}
}
6. 팀 협업 모범 사례 및 장애 방지 수칙
기술 문서가 지속적으로 확장될 때 신뢰성을 유지하기 위해 권장되는 실무 수칙은 다음과 같습니다.
- Mintlify CLI를 통한 로컬 검증: 변경 사항을 원격 저장소에 푸시하기 전, 로컬 터미널에서
npx mintlify dev를 실행하십시오. 로컬 개발 서버가 JSON 구문 오류, 오탈자로 인한 파일 경로 불일치, 누락된 링크를 사전에 즉각적으로 감지합니다. - 페이지 경로의 정확성 유지:
"pages"에 명시된 문자열은 실제 물리 파일과 정확히 일치해야 합니다. 파일 이름을guides/cli.mdx에서guides/cli-tooling.mdx로 변경한 경우, 동일한 Git 커밋 내에서docs.json도 함께 갱신해야 빌드 실패나 404 오류를 방지할 수 있습니다. - 다크 모드 시각 대비율 검수: 라이트 모드의
primary색상뿐 아니라 다크 모드용light색상의 명도 수준을 세심하게 점검해야 합니다. WCAG AA 기준을 충족하는 대비율을 확보하지 않으면 다크 모드 환경에서 링크와 활성 메뉴 텍스트를 읽기 어려워집니다. - 사이드바 중첩 깊이 제한: 사이드바 중첩 계층은 최대 2단계(메인 그룹 > 하위 그룹 > 페이지) 이내로 제한하는 것이 바람직합니다. 3단계 이상의 깊은 계층 구조는 모바일 및 좁은 화면에서 가독성을 심각하게 저해하므로, 상단 탭(Tabs)이나 드롭다운 메뉴로 분할하는 것이 유리합니다.