개요

⚡️ 도큐사우루스는 멋진 문서 사이트를 빠르게 공개할 수 있도록 도와줍니다.

💸 맞춤형 기술 스택을 직접 구축하는 것은 많은 비용이 듭니다. 대신 콘텐츠에 집중하고 Markdown 파일만 작성하세요.

💥 더 많은 기능이 필요한가요? 버전 관리, i18n, 검색, 테마 사용자 지정과 같은 고급 기능을 활용하세요.

💅 **최고의 도큐사우루스 사이트**를 살펴보며 아이디어를 얻어 보세요.

🧐 도큐사우루스는 정적 사이트 생성기입니다. 클라이언트 측에서 빠르게 페이지를 이동할 수 있는 단일 페이지 애플리케이션을 만들고, React의 기능을 최대한 활용해 사이트에 상호작용 기능을 더합니다. 문서 기능을 기본으로 제공하지만, 어떤 종류의 사이트(개인 웹사이트, 제품, 블로그, 마케팅 랜딩 페이지 등)든 만들 수 있습니다.

패스트트랙 ⏱️

직접 사용해 보며 5분 안에 도큐사우루스를 익혀 보세요!

새 도큐사우루스 사이트를 만들고 기본으로 포함된 매우 짧은 튜토리얼을 따라 해 보세요.

Node.js를 설치하고 새 도큐사우루스 사이트를 만드세요:

npx create-docusaurus@latest my-website classic

사이트를 시작합니다.

cd my-website
npx docusaurus start

http://localhost:3000에 접속하고 튜토리얼을 따라 해 보세요.

팁

**docusaurus.new**에서 브라우저로 도큐사우루스를 바로 테스트해 보세요!

또는 온라인으로 **5분 튜토리얼**을 읽어 보세요.

도큐사우루스: 문서화를 좀 더 쉽게 만들어줍니다

Algolia 커뮤니티 행사에서 진행된 이 발표에서는 Meta 오픈 소스 팀이 도큐사우루스의 사용 방법을 간단히 소개했습니다. 프로젝트를 시작하고 플러그인을 활성화하고 문서, 블로그 같은 기능을 설정하는 방법을 다루었습니다.

v1에서 마이그레이션

Docusaurus v2는 완전히 현대화된 툴체인을 활용하여 Docusaurus v1을 완전히 새롭게 만들었습니다. After v2's official release, we highly encourage you to use Docusaurus v2+ over Docusaurus v1, as Docusaurus v1 has been deprecated.

A lot of users are already using Docusaurus v2+ (trends).

Use Docusaurus v2+ if:

• ✅ 최신의 잼스택(Jamstack) 문서 사이트를 만들고자 할 때
• ✅ 클라이언트 사이드 라우팅을 적용한 단일 페이지 애플리케이션(SPA)을 만들고자 할 때
• ✅ 리액트와 MDX의 최적의 조합을 활용하고자 할 때
• ✅ IE11 사용자는 고려하지 않아도 될 때

Use Docusaurus v1 if:

• ❌ 단일 페이지 애플리케이션(SPA)을 사용하고 싶지 않을 때
• ❌ IE11 사용자에 대한 지원이 필요할 때(아마 여러분도 아시겠지만... IE has already reached end-of-life and is no longer officially supported)

For existing v1 users that are seeking to upgrade to v2+, you can follow our migration guides.

주요 기능

v2로 업그레이드하려는 기존 v1 사용자는 마이그레이션 가이드를 참고하세요.

• ⚛️ 💚와 React로 제작:
  • 리액트를 사용해 기능을 확장하거나 수정할 수 있습니다.
  • 여러분만의 리액트 컴포넌트를 통해 사이트 방문자 경험을 완전히 새롭게 구성할 수 있습니다.
• 🔌 플러그인 확장 지원:
  • 기본 템플릿으로 사이트를 시작하고 추가 기능이나 플러그인을 활용할 수 있습니다.
  • 여러분이 만든 오픈 소스 플러그인은 커뮤니티에서 공유할 수 있습니다.
• ✂️ 개발자 경험:
  • 지금 바로 문서 작성을 시작하세요.
  • 통합된 설정 시작점은 유지보수를 쉽게 만들어줍니다.
  • 변경된 부분만 증분 빌드해서 번개처럼 빠르게 반영할 수 있습니다.
  • 라우트 기반으로 코드와 데이터를 분할합니다.
  • 깃허브 페이지, 네트리파이, 베르셀이나 기타 배포 서비스에 쉽게 게시할 수 있습니다.

우리가 지향하는 목표는 여러분의 사용자가 정보를 빠르게 찾고 제품을 더 잘 이해할 수 있도록 돕는 것입니다. 여러분이 문서 사이트를 적절하게 만들 때 도움이 될만한 모범 사례를 공유할 것입니다.

• 🎯 SEO 친화적:
  • 모든 접근할 수 있는 경로에 대한 HTML 파일을 만들어줍니다.
  • 페이지별 SEO를 통해 사용자가 당면한 문제 해결에 필요한 공식 문서에 바로 도달할 수 있도록 도와줍니다.
• 📝 MDX 기반:
  • 마크다운 문서 내에 JSX와 리액트로 동적인 컴포넌트를 작성할 수 있습니다.
  • 라이브 에디터를 사용해 사용자가 즉시 코드를 실행해볼 수 있습니다.
• 🔍 검색: 사이트 전체를 검색할 수 있습니다.
• 💾 문서 버전 관리: 프로젝트 릴리스에 맞는 문서를 유지할 수 있도록 도와줍니다.
• 🌍 국제화 (i18n): 사이트를 여러 로케일로 번역하세요.

도큐사우루스 v2는 모든 사용자가 편리하게 이용할 수 있고 초고속으로 사용할 수 있도록 탄생했습니다.

• ⚡️ 번개처럼 빠른 속도. 도큐사우루스 v2+는 콘텐츠를 매우 빠르게 불러올 수 있도록 PRPL 패턴을 따릅니다.
• 🦖 접근성 지원. 접근성에 주의하여 모든 사용자가 여러분의 사이트에 차별없이 접근할 수 있게 합니다.

디자인 원칙

• 배워야 할 내용이 적습니다. 도큐사우루스의 API는 배우고 사용하기 쉽도록 작아야 합니다. 물론 사용자가 맘만 먹으면 직접 코드를 작성해서 대부분의 기능을 추가할 수 있습니다. 잘못된 추상화를 제공하는 것보다는 아예 없는 것이 낫습니다. 우리는 사용자가 잘못된 추상화에 접근하지 않기를 바랍니다. 꼭 봐야 할 발표—최소한의 API 노출 범위.
• 직관적입니다. 사용자가 도큐사우루스 프로젝트 디렉터리를 살펴보거나 새로운 기능을 추가해야 할때 당황하지 않을 겁니다. 익숙한 접근 방식을 통해 직관적으로 사용할 수 있어야 합니다.
• 계층형 아키텍처. 적절한 추상화와 모듈화를 통해 각 영역(콘텐츠/테마/스타일)의 계층 간 영향을 미치는 영역은 명확하게 구분됩니다.
• 합리적인 기본 설정. 일반적으로 많이 사용하는 성능 최적화와 설정을 제공합니다. 물론 필요한 경우 사용자가 직접 설정값을 조정할 수 있습니다.
• 특정 업체에 종속되지 않습니다. 기본 플러그인이나 CSS 사용을 권장하긴 하지만 꼭 그걸 써야 하는 건 아닙니다. React Loadable나 React Router처럼 특정 핵심 인프라는 기본 성능 최적화 처리 때문에 다른 것으로 대체할 수 없지만 상위 수준에서는 그렇지 않습니다. 마크다운 엔진, CSS 프레임워크, CSS 방법론, 기타 아키텍처를 선택하는 것은 전적으로 사용자의 몫입니다.

우리는 개발자로서 라이브러리가 어떻게 작동하는지 아는 것은 라이브러리를 더 잘 사용하는 데 도움이 된다고 믿습니다. 따라서 저희는 이 글을 읽는 사용자가 도구를 더 깊이 이해하고 더욱 능숙하게 사용할 수 있기를 바라며 도큐사우루스의 아키텍처와 다양한 구성 요소를 설명하는 데 많은 노력을 기울이고 있습니다.

다른 도구 비교

다른 정적인 사이트 생성 도구와 다르게 도큐사우루스는 문서 사이트에 포커스를 맞추고 있습니다. 기본적인 기능은 바로 사용할 준비가 되어 있습니다.

아래에 주요한 정적 사이트 생성 도구와 비교한 내용을 정리했습니다.

개츠비(Gatsby)

Gatsby는 많은 기능을 갖추고, 플러그인 생태계가 풍부하며, 도큐사우루스가 할 수 있는 모든 작업을 수행할 수 있습니다. 하지만 개츠비를 처음 사용하기 위해서는 기능을 학습하는 시간이 좀 더 필요합니다. 개츠비는 다양한 형태의 웹사이트를 만들어야 할 때 적합한 도구입니다. 반면에 도큐사우루스는 콘텐츠를 작성하고 게시하는 일에 최적화된 도구를 만드는 데 집중하고 있습니다.

그래프QL(GraphQL)은 개츠비의 핵심이기도 합니다. 물론 개츠비 사이트를 만들 때 그래프QL이 꼭 필요한 건 아닙니다. 대부분의 경우 정적인 웹사이트 구축 시에는 그래프QL이 제공하는 유연성이 필요하지 않습니다.

도큐사우루스 v2의 많은 부분은 개츠비의 여러 기능에서 영감을 얻었고 상호 보완적인 관계라고 할 수 있습니다.

Docz는 문서 사이트를 만들기 위한 Gatsby 테마입니다. 도큐사우루스의 테마와 비교하면 기능이 부족합니다.

넥스트(Next.js)

Next.js는 인기가 매우 높은 또 다른 하이브리드 React 프레임워크입니다. 좋은 문서 웹 사이트를 만들 수 있는 기능은 지원하지만, 문서화 관련 구축 사례는 찾아볼 수 없으며 도큐사우루스가 기본적으로 지원하는 기능을 구현하려면 좀 많은 작업이 필요합니다.

Nextra는 Next.js를 기반으로 구축되었으며 특정 설계 원칙을 따르는 정적 사이트 생성기입니다. 도큐사우루스의 테마와 비교하면 기능이 부족합니다.

VitePress

VitePress는 도큐사우루스와 공통점이 많습니다 - 둘 다 콘텐츠 중심 웹사이트에 중점을 두며 문서화에 특화된 기능을 기본으로 제공합니다. 그러나 VitePress는 Vue를 기반으로 구동되며, Docusaurus는 React를 기반으로 구동됩니다. Vue 기반 솔루션을 원하신다면 VitePress가 괜찮은 선택이 될 것입니다.

MkDocs

MkDocs는 도큐사우루스와 비슷한 장점을 제공하는 인기 있는 Python 기반 정적 사이트 생성기입니다.

단일 페이지 애플리케이션이 필요하지 않고 리액트 기능을 활용할 계획이 없다면 나쁘지 않은 선택입니다.

Material for MkDocs는 아름다운 테마입니다.

Docsify

Docsify로 문서 웹사이트를 쉽게 만들 수 있지만, 정적 사이트 생성기는 아니며 SEO에 친화적이지 않습니다.

깃북(GitBook)

GitBook은 디자인이 매우 깔끔하며 많은 오픈 소스 프로젝트에서 사용되어 왔습니다. 하지만 오픈소스 도구보다는 상용 도구로 깃북의 관심이 옮겨지면서 오픈소스 프로젝트 문서 사이트에 필요한 요구를 더 이상 맞추어 주지 못하고 있습니다. 그래서 많은 프로젝트가 다른 도구로 이전하고 있습니다. Redux가 도큐사우루스로 전환한 이야기는 여기에서 읽을 수 있습니다.

현재 깃북은 오픈소스와 비영리 조직에만 무료로 제공됩니다. 하지만 도큐사우루스는 누구에게나 무료입니다.

지킬(Jekyll)

Jekyll은 가장 성숙한 정적 사이트 생성기 중 하나이며 훌륭한 도구로 사용되어 왔습니다 — 실제로, Facebook의 오픈 소스 웹사이트 대부분은 도큐사우루스 이전부터 Jekyll로 구축되어 있거나, 과거에 구축된 적이 있습니다! 지킬은 매우 간단하게 시작할 수 있습니다. 우리는 지킬에서 정적인 사이트를 개발하는 것과 유사한 개발자 경험을 제공하고자 노력하고 있습니다.

HTML을 정적으로 생성하고 <script /> 태그로 상호작용 기능을 추가하는 방식과 달리, 도큐사우루스 사이트는 React 앱입니다. 우리는 최신의 자바스크립트 생태계 도구를 사용하면서 사이트의 성능이나 리소스 빌드 파이프라인, 최적화, 간편한 설정에 대한 새로운 표준을 제시하고자 합니다.

Rspress

Rspress는 빠른 정적 사이트 생성기로, Rust 기반 번들러인 Rspack을 기반으로 합니다. MDX (React 컴포넌트를 포함한 Markdown)를 사용한 콘텐츠 작성, 통합 텍스트 검색, 다국어 지원 (i18n), 플러그인을 통한 확장성을 지원합니다. 깔끔한 문서와 정적 웹사이트를 만들도록 설계된 Rspress는 배포하기 쉬운 정적 HTML 파일을 생성합니다.

Rspress와 도큐사우루스는 상당히 비슷합니다. 둘 다 각각 장단점이 있습니다. Rspress는 비교적 최근에 만들어졌으며, 사이트를 더 빠르게 빌드할 수 있는 최신 인프라의 이점을 누리고 있습니다. 도큐사우루스는 성숙도, 포괄적인 기능, 유연성, 탄탄한 커뮤니티가 강점입니다. 성능 면에서 경쟁력을 유지하기 위해 정기적으로 인프라를 현대화하고 있습니다.

최신 정보는 아래에서 확인하세요

• GitHub
• X
• 블로그
• Discord

뭔가 부족한가요?

문서에서 문제를 발견했거나 문서 또는 프로젝트 전반을 개선할 제안이 있다면, 이슈를 등록하거나 X 계정 @docusaurus를 언급하는 트윗을 보내주세요.

새로운 기능을 요청하려면 기능 요청 게시판(Canny)에 글을 작성할 수 있습니다. 이 도구는 로드맵을 만드는 데 유용하고 추천 수로 정렬할 수 있어, 분류하기가 더 어려운 GitHub 이슈에 비해 핵심 팀이 어떤 기능에 대한 수요가 높은지 더 잘 파악할 수 있습니다. 새로운 기능은(특히 커다란 기능은) 풀 리퀘스트를 생성하지 말아주세요. 누군가 이미 만들고 있거나 로드맵의 일부일 수 있습니다. 새로운 기능이 필요하다면 저희에게 먼저 연락해주세요!