메인 컨텐츠로 이동
Version: 2.0.0-beta.5 🚧

소개

⚡️ 도큐사우루스는 좋아 보이는 문서 사이트를 눈 깜짝할 사이에 공개할 수 있게 도와줍니다.

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

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

💅 영감을 얻기 위해 도큐사우루스를 모범적으로 도입한 사이트와 추천의 글을 확인해보세요.

🧐 도큐사우루스는 정적 사이트 생성 도구입니다. 클라이언트에서 빠른 탐색 기능을 지원하고 사이트를 좀 더 인터랙티브하게 만들 수 있게 React의 기능을 최대한 끌어올린 단일 페이지 애플리케이션을 만들 수 있습니다. 문서 기능은 설치 후 바로 사용할 수 있으며 원하는 어떤 종류의 사이트(개인 웹 사이트, 제품 블로그, 마케팅 랜딩 페이지 등)든지 만들 수 있습니다.

Docusaurus Slash Introduction

패스트트랙 ⏱️#

5분 안에 도큐사우루스를 바로 실행하고 이해할 수 있습니다!

새로운 도큐사우루스 사이트를 만들고 기본으로 포함된 매우 짧은 튜토리얼을 따라가 봅니다.

Node.js를 설치하고 새로운 도큐사우루스 사이트를 만듭니다.

npx @docusaurus/init@latest init my-website classic

사이트를 시작합니다.

cd my-websitenpx docusaurus start

http://localhost:3000을 열고 튜토리얼을 따라가 봅니다.

tip

Use docusaurus.new to test Docusaurus immediately in your browser!

또는 온라인에서 5분 튜토리얼 설명을 살펴볼 수 있습니다.

유의사항#

도큐사우루스 v2는 베타이지만 이미 매우 안정적이며 다양한 곳에서 사용하고 있습니다.

도큐사우루스 v1은 조만간 사용 중단 예정이므로 도큐사우루스 v1 대신 도큐사우루스 v2를 사용할 것을 강력히 권장합니다.

많은 사용자가 도큐사우루스 v2를 이미 사용하고 있습니다(트렌드도 확인해보세요).

이럴 때는 v2를 권장합니다.

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

이럴 때는 도큐사우루스 v1을 사용해야 합니다.

  • ❌ 단일 페이지 애플리케이션(SPA)을 사용하고 싶지 않을 때
  • ❌ IE11 사용자에 대한 지원이 필요할 때

주요 기능#

도큐사우루스는 개발자와 오픈 소스 기여자 경험에 많은 관심을 기울여 만들었습니다.

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

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

  • 🎯 준비된 검색엔진 최적화
    • 모든 접근할 수 있는 경로에 대한 HTML 파일을 만들어줍니다.
    • 페이지별 SEO를 통해 사용자가 당면한 문제 해결에 필요한 공식 문서에 바로 도달할 수 있도록 도와줍니다.
  • 📝 강력한 MDX 기능 활용
    • 마크다운 문서 내에 JSX와 리액트로 동적인 컴포넌트를 작성할 수 있습니다.
    • 라이브 에디터를 사용해 사용자가 즉시 코드를 실행해볼 수 있습니다.
  • 🔍 검색 - 사이트 전체를 검색할 수 있습니다.
  • 💾 문서 버전 관리 - 프로젝트 릴리스에 따라 문서 버전을 손쉽게 관리할 수 있습니다.
  • 🌍 i18n - 여러분의 사이트를 다양한 언어로 번역하세요.

도큐사우루스는 누구나 접근할 수 있고 다른 어떤 것보다 빠르게 보이도록 만들었습니다.

  • ⚡️ 번개처럼 빠르게 - 도큐사우루스 2는 PRPL 패턴을 기반으로 콘텐츠를 엄청나게 빠르게 보여줄 수 있도록 구현했습니다.
  • 🦖 접근성 - 사이트에 누구나 접근할 수 있도록 접근성에도 주의를 기울이고 있습니다.

디자인 원칙#

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

우리는 개발자라서 그런지 라이브러리에 대해 잘 알게 되면 더 잘 사용할 수 있다고 믿고 있습니다. 이 때문에 우리는 아키텍처와 도큐사우루스의 다양한 컴포넌트를 잘 설명하기 위해 노력하고 있습니다. 그리고 사용자들이 문서를 읽고 도구에 대해 깊이 이해하고 능숙하게 사용하기를 기대하고 있습니다.

다른 도구 비교#

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

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

개츠비(Gatsby)#

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

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

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

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

넥스트(Next.js)#

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

Nextra는 Next.js 기반으로 만든 독립적인 정적 사이트 생성 도구입니다. 도큐사우루스와 비교하면 기능이 부족합니다.

뷰프레스(VuePress)#

뷰프레스는 도큐사우루스와 비슷한 점이 많습니다. 둘 다 콘텐츠 기반의 사이트를 만들고 그에 필요한 기능을 제공하는 데 초점을 두고 있습니다. 뷰프레스는 뷰(Vue)를 기반으로 도큐사우루스는 리액트를 기반으로 만들어졌다는 차이가 있습니다. 뷰 기반의 솔루션을 원한다면 뷰프레스가 적절한 선택일 것입니다.

MkDocs#

MkDocs는 도큐사우루스와 비슷한 컨셉을 가진 인기 있는 파이썬 정적 사이트 생성 도구입니다.

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

Material for MkDocs라는 멋진 테마도 지원하고 있습니다.

Docsify#

Docsify는 문서 웹 사이트를 쉽게 만들 수 있습니다. 하지만 정적 사이트 생성 도구는 아니며 검색 엔진 최적화에 적합하지 않습니다.

깃북(GitBook)#

GitBook은 매우 깔끔한 디자인을 가지고 있으며 많은 오픈 소스 프로젝트에서 사용하고 있습니다. 하지만 오픈소스 도구보다는 상용 도구로 깃북의 관심이 옮겨지면서 오픈소스 프로젝트 문서 사이트에 필요한 요구를 더는 맞추어 주지 못하고 있습니다. 그래서 많은 프로젝트가 다른 도구로 이전하고 있습니다. 리덕스(Redux)도 도큐사우루스로 문서 도구를 이전했습니다. 문서 도구 관련 이슈에서 자세한 내용을 살펴볼 수 있습니다.

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

지킬(Jekyll)#

지킬은 가장 잘 알려진 정적인 사이트 생성 도구이며 매우 좋은 도구입니다. 사실 도큐사우루스를 내놓기 전에는 페이스북의 오픈소스 웹사이트는 대부분 지킬을 사용해 만들었습니다. 지킬은 매우 간단하게 시작할 수 있습니다. 우리는 지킬에서 정적인 사이트를 개발하는 것과 유사한 개발자 경험을 제공하고자 노력하고 있습니다.

지킬에서는 정적인 HTML 파일을 만들고 <script />를 사용해 상호 작용 기능을 추가하는데 비해 도큐사우루스는 리액트 앱으로 구현할 수 있습니다. 우리는 최신의 자바스크립트 생태계 도구를 사용하면서 사이트의 성능이나 리소스 빌드 파이프라인, 최적화, 간편한 설정에 대한 새로운 표준을 제시하고자 합니다.

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

뭔가 부족한가요?#

문서를 읽으면서 문제를 발견하거나 문서 또는 프로젝트를 개선하기 위한 의견이 있다면 이슈로 등록하거나 @docusaurus 아이디를 포함해 트윗을 남겨주세요.

새로운 기능 요청은 Canny board에 남겨주세요. 로드맵을 위한 유용한 도구이며 추천순으로 기능 요청 목록을 정렬할 수 있습니다. 깃헙 이슈에서는 어떤 요청에 대한 관심이 많은지 알 수 없지만, Canny board에서는 가장 많은 추천을 받은 요청을 개발팀에서 빠르게 인지할 수 있습니다. 새로운 기능(특히 커다란 기능)은 풀 리퀘스트를 생성하지 말아 주세요. 누군가 이미 만들고 있거나 로드맵의 일부일 수 있습니다. 새로운 기능이 필요하다면 우리에게 먼저 연락해주세요!