문서 도구 선택

결론부터

• 이 사이트는 AI가 문서를 만들고, 사람이 시각적으로 읽고 피드백하며, 웹 링크로 공유하기 위해 Starlight를 쓴다.
• Notion 같은 협업 도구, GitBook 같은 게시 서비스, 직접 만드는 문서 사이트는 표현의 자유도와 운영 부담이 다르다.
• Next.js 앱과 문서를 함께 구성하려면 Nextra·Fumadocs를, 독립 학습 사이트라면 Starlight 같은 도구를 비교한다.
• AI가 작성할 수 있는지만으로 도구가 결정되지는 않는다. 같은 학습 예제를 원하는 모습으로 만들고 유지할 수 있는지 본다.

이 장에서 처음 나오는 말2개

MDX

Markdown 본문 안에 재사용 가능한 화면 요소인 컴포넌트를 함께 넣는 문서 형식.

호스팅Hosting

완성한 웹 페이지를 인터넷에서 열 수 있도록 제공하는 서비스.

문서 도구를 고르는 기준은 어떤 문서를 만들고 어떻게 발전시킬 것인지에서 나온다. 우리에게는 직접 글을 입력하는 편의보다 AI가 만든 설명을 읽기 좋은 화면으로 다듬는 과정이 중요하다. 아래는 기능 순위가 아니라, 그 작업 방식에 비춰 본 선택 가이드다.

후보별로 무엇이 다른가

노트·팀 위키·제품 문서·학습 사이트는 요구가 다르다. 먼저 무엇을 중심으로 정리하는 도구인지 나눠 본다. 아래 분류는 주된 쓰임이며, 한 도구가 여러 방식에 걸칠 수 있다.

개인 노트와 팀 지식 정리

도구	기본 방식과 표현 수단	먼저 고려할 상황
Notion	블록·데이터베이스 기반 작업 공간. Notion Sites로 페이지를 웹에 게시	노트·업무 자료를 함께 정리하고 같은 공간에서 협업·공유하고 싶다
Confluence	공간과 페이지로 팀 문서를 관리하는 협업 도구	조직의 업무 문서·팀 위키를 모으고 함께 관리하고 싶다
Slite	팀 지식베이스와 문서 검토·AI 검색 지원	팀의 지식을 정리하고 신뢰할 문서를 찾아 활용하고 싶다
Obsidian	로컬 Markdown 노트를 중심으로 정리. Publish로 웹 게시 가능	개인 노트의 연결·탐색이 중심이고 필요한 노트를 웹에도 공유하고 싶다

Notion도 웹에 공개할 수 있으므로 “웹으로 공유한다”만으로 Starlight와 갈리지는 않는다. 우리에게 중요한 차이는 원하는 학습용 컴포넌트를 만들고 본문과 함께 고칠 수 있는가다. 서비스의 기본 블록·임베드로 충분한지, 직접 구현할 표현이 필요한지를 본다.

문서 게시와 운영을 맡기는 서비스

도구	기본 방식과 표현 수단	먼저 고려할 상황
GitBook	화면 편집과 에이전트·Git 연동을 지원하는 문서 게시 서비스	여러 편집 경로를 함께 쓰면서 문서 게시 운영을 맡기고 싶다
ReadMe	개발자 문서와 API를 직접 호출해 보는 탐색 화면 제공	API 사용자가 설명을 읽고 요청·응답을 시험하는 문서를 만들고 싶다
Mintlify	제품 가이드·API 문서와 검색 등을 제공하는 문서 플랫폼	제품 문서 사이트의 구성과 게시 운영을 서비스에 맡기고 싶다

제공하는 컴포넌트, 외부 예제 삽입, Git 연동, 요금과 공개 범위를 실제 요구와 대조한다. 서비스에 맡기는 만큼 그 서비스가 지원하는 확장 방식을 따라야 한다.

저장소에서 직접 만드는 문서 사이트

도구	기반과 표현 수단	먼저 고려할 상황
Starlight	Astro 기반. MDX·UI 컴포넌트와 문서 탐색·검색 제공	독립 학습 문서에 주제별 시각 자료와 상호작용을 붙이고 싶다
Docusaurus	React·MDX 기반. 컴포넌트 확장과 문서 버전 관리 지원	React 자산을 재사용하거나 제품 버전별 문서를 병행하려 한다
VitePress	Vite·Vue 기반. Markdown에 Vue 컴포넌트를 결합	Vue 프로젝트의 컴포넌트와 문서 구성을 함께 활용하고 싶다
MkDocs + Material for MkDocs	Python 기반 문서 생성기와 그 위에 쓰는 문서 테마. Markdown·확장 기능 활용	Markdown·테마 중심으로 문서 사이트를 구성하려 한다
Nextra	Next.js·MDX 기반 사이트 생성과 문서 테마	Next.js 앱에 문서 페이지와 탐색 화면을 함께 구성하고 싶다
Fumadocs	React 기반 문서 프레임워크. Next.js 등과 결합하는 UI·콘텐츠 구성 제공	앱의 레이아웃·컴포넌트에 맞춰 문서 화면을 조합하고 싶다
Sphinx	Python 기반 문서 생성기. 코드의 설명문을 가져오는 autodoc 확장 등 제공	라이브러리 API 레퍼런스와 설명서를 함께 관리하려 한다
mdBook	Rust로 만든 Markdown 기반 책 형식 문서 도구	읽는 순서가 있는 튜토리얼·교재를 책처럼 게시하고 싶다

Material for MkDocs는 MkDocs와 별개로 설치하는 테마이고, mdBook은 Rust 주제만 다루는 도구가 아니다. 이 부류에서는 저장소와 사이트의 빌드·호스팅을 직접 관리한다. 자유롭게 확장할 수 있는 만큼 유지할 코드도 생긴다.

Next.js 앱에 문서를 통합한다면

Nextra와 Fumadocs가 이 목적의 후보였다. 이미 Next.js로 만든 서비스가 있고 그 안의 /docs에서 문서를 제공하려면, 앱과 문서의 레이아웃·컴포넌트·라우팅을 함께 관리하는 이점이 있다.

Nextra는 Next.js와 MDX를 바탕으로 문서 테마를 제공한다. Fumadocs는 문서 UI와 콘텐츠 구성을 조합하는 React 기반 도구이며, 현재는 Next.js 외의 React 프레임워크도 지원한다. 어느 쪽이든 AI에게 기존 앱 구조와 원하는 문서 화면을 주고, 앱의 컴포넌트를 재사용할 작은 예제를 만들어 비교할 수 있다.

이 사이트는 독립된 학습 문서 사이트이므로 앱에 통합하는 이점의 비중이 작다. Next.js 기반 도구로 옮길지는 새 기능으로 얻는 이점과 기존 그림·컴포넌트·검색·URL을 옮기는 비용을 함께 본다.

AI 작성과 시각 표현으로 비교한다

AI가 다룰 수 있는 경로는 여러 가지다. 파일을 직접 고치는 방식뿐 아니라 GitBook의 양방향 Git Sync처럼 편집기와 저장소를 잇는 방식도 있다. “AI를 쓰니 파일 기반 도구만 가능하다”는 기준으로 후보를 지우지 않는다.

대신 로그인 한 번에서 누가 무엇을 보관하는가 같은 실제 학습 질문 하나로 비교한다.

확인할 결과	비교할 질문
설명과 관계도	본문과 그림을 함께 수정하고 차이를 검토하기 쉬운가?
단계별 상태	버튼을 누를 때 전달 값·보관 상태가 함께 바뀌는 예제를 만들 수 있는가?
읽는 경험	긴 글에서도 제목·표·그림이 잘 구별되고 필요한 내용을 찾기 쉬운가?
공유	받는 사람이 앱 설치 없이 링크를 열고 같은 설명과 예제를 볼 수 있는가?
유지	AI가 수정한 뒤 오류를 검사하고 다음 변경에서도 같은 표현을 재사용할 수 있는가?

Docusaurus도 MDX 안에 React 컴포넌트를 넣을 수 있다. MkDocs도 JavaScript·테마 확장이 가능하다. 특정 도구만 상호작용을 만들 수 있다는 비교보다, 우리에게 필요한 예제를 어느 방식으로 관리할지가 판단 대상이다.

왜 이 사이트는 Starlight를 쓰는가

우리의 선택은 다음 요구를 함께 만족시키는 데서 나왔다.

• 읽는 화면을 갖춘 출발점: 사이드바·페이지 목차·테마와 Pagefind 검색을 바탕으로 문서를 쌓을 수 있다.
• 본문과 시각 자료를 함께 수정: MDX 본문에 이미지·컴포넌트를 넣고, 이 저장소의 D2 통합으로 관계도를 관리한다.
• 학습 질문에 맞는 확장: LearningFlow처럼 필요한 학습용 화면을 구현해 여러 페이지에서 재사용한다.
• AI의 수정 결과를 확인: 파일 변경을 비교하고, 같은 저장소에서 본문·그림·링크를 검사한 뒤 게시한다.

덱별 사이드바·자동 등록·D2·LearningFlow가 모두 Starlight 기본 기능인 것은 아니다. 이 사이트에서 더한 플러그인과 자체 코드가 더해진 결과다. Starlight를 새로 설치하면 현재 사이트가 그대로 만들어지지는 않는다.

Obsidian도 파일을 보관하고 웹에 게시할 수 있다. 다만 이 프로젝트에서는 원하는 문서 배치와 학습용 상호작용을 웹 컴포넌트로 계속 다듬는 방식을 택했다. 이는 이 사이트의 목적과 선호에 따른 판단이다.

선택이 달라지는 경우

먼저 자신의 요구가 어느 쪽인지 좁힌다.

우선하는 요구	비교할 후보
개인 기록과 노트 연결	Obsidian·Notion
여러 사람이 관리하는 팀 위키	Notion·Confluence·Slite
제품·API 문서의 게시 운영을 맡김	GitBook·ReadMe·Mintlify
독립된 학습 문서와 시각 자료	Starlight·Docusaurus·VitePress·MkDocs
Next.js 서비스 안의 문서	Nextra·Fumadocs
라이브러리의 API 설명 자동 생성	Sphinx, 필요한 API 추출 플러그인을 갖춘 MkDocs
읽는 순서가 있는 책 형식 문서	mdBook

이는 이 사이트의 요구에 비춰 고른 출발점이다. 후보에서 필요한 학습 예제 하나를 실제로 만들어 판단한다.

이미 Starlight로 쌓인 문서를 옮길 때는 본문 외에 컴포넌트·그림·검색·기존 URL도 함께 옮겨야 한다. 지금 읽기 어려운 것이 설명 자체라면, 먼저 그 페이지의 설명과 표현을 고쳐 보고 도구 이전을 판단한다.

AI에게 문서 작성 요청하기도구를 골랐다면, 어떤 학습 결과를 만들지 요청한다.