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

개요

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

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

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

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

🧐 도큐사우루스는 정적 사이트 생성 도구입니다. It builds a single-page application with fast client-side navigation, leveraging the full power of React to make your site interactive. It provides out-of-the-box documentation features but can be used to create any kind of site (personal website, product, blog, marketing landing pages, etc).

Docusaurus Slash Introduction

패스트트랙 ⏱️

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

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

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

npx create-docusaurus@latest my-website classic

사이트를 시작합니다.

cd my-website
npx docusaurus start

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

tip

docusaurus.new에 접속하면 여러분의 웹 브라우저에서 도큐사우루스를 바로 테스트해볼 수 있습니다!

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

Docusaurus: Documentation Made Easy

In this presentation at Algolia Community Event, Meta Open Source team shared a brief walk-through of Docusaurus. They covered how to get started with the project, enable plugins, and set up functionalities like documentation and blogging.

유의사항

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

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

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

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

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

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

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

주요 기능

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

  • ⚛️ Built with 💚 and React:
    • 리액트를 사용해 기능을 확장하거나 수정할 수 있습니다.
    • 여러분만의 리액트 컴포넌트를 통해 사이트 방문자 경험을 완전히 새롭게 구성할 수 있습니다.
  • Pluggable:
    • 기본 템플릿으로 사이트를 시작하고 추가 기능이나 플러그인을 활용할 수 있습니다.
    • 여러분이 만든 오픈 소스 플러그인은 커뮤니티에서 공유할 수 있습니다.
  • ✂️ Developer experience:
    • 지금 바로 문서 작성을 시작하세요.
    • 통합된 설정 시작점은 유지보수를 쉽게 만들어줍니다.
    • Hot reloading with lightning-fast incremental build on changes
    • 라우트 기반으로 코드와 데이터를 분할합니다.
    • Publish to GitHub Pages, Netlify, Vercel, and other deployment services with ease

Our shared goal—to help your users quickly find what they need and understand your products better. We share our best practices to help you build your docs site right and well.

  • 🎯 SEO friendly:
    • HTML files are statically generated for every possible path.
    • Page-specific SEO to help your users land on your official docs directly relating their problems at hand.
  • 📝 Powered by MDX:
    • Write interactive components via JSX and React embedded in markdown.
    • Share your code in live editors to get your users to love your products on the spot.
  • 🔍 Search: Your full site is searchable.
  • 💾 Document Versioning: Helps you keep documentation in sync with project releases.
  • 🌍 Internationalization (i18n): Translate your site in multiple locales.

Docusaurus 2 is born to be compassionately accessible to all your users, and lightning-fast.

  • ⚡️ Lightning-fast. Docusaurus 2 follows the PRPL Pattern that makes sure your content loads blazing fast.
  • 🦖 Accessible. Attention to accessibility, making your site equally accessible to all users.

디자인 원칙

  • Little to learn. Docusaurus should be easy to learn and use as the API is quite small. 물론 사용자가 맘만 먹으면 직접 코드를 작성해서 대부분의 기능을 추가할 수 있습니다. 잘못된 추상화를 제공하는 것보다는 아예 없는 것이 낫습니다. 우리는 사용자가 잘못된 추상화에 접근하지 않기를 바랍니다. Mandatory talk—Minimal API Surface Area.
  • Intuitive. Users will not feel overwhelmed when looking at the project directory of a Docusaurus project or adding new features. 익숙한 접근 방식을 통해 직관적으로 사용할 수 있어야 합니다.
  • Layered architecture. The separations of concerns between each layer of our stack (content/theming/styling) should be clear—well-abstracted and modular.
  • Sensible defaults. Common and popular performance optimizations and configurations will be done for users but they are given the option to override them.
  • No vendor lock-in. Users are not required to use the default plugins or CSS, although they are highly encouraged to. Certain core infrastructures like React Loadable and React Router cannot be swapped because we do default performance optimization on them, but not higher-level ones. Choice of Markdown engines, CSS frameworks, CSS methodology, and other architectures will be entirely up to users.

We believe that, as developers, knowing how a library works helps us become better at using it. Hence we're dedicating effort to explaining the architecture and various components of Docusaurus with the hope that users reading it will gain a deeper understanding of the tool and be even more proficient in using it.

다른 도구 비교

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

We've also studied other main static site generators and would like to share our insights on the comparison, hopefully helping you navigate through the prismatic choices out there.

개츠비(Gatsby)

Gatsby is packed with a lot of features, has a rich ecosystem of plugins, and is capable of doing everything that Docusaurus does. 하지만 개츠비를 처음 사용하기 위해서는 기능을 학습하는 시간이 좀 더 필요합니다. 개츠비는 다양한 형태의 웹사이트를 만들어야 할 때 적합한 도구입니다. 반면에 도큐사우루스는 콘텐츠를 작성하고 게시하는 일에 최적화된 도구를 만드는 데 집중하고 있습니다.

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

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

Docz is a Gatsby theme to build documentation websites. 도큐사우루스의 테마와 비교하면 기능이 부족합니다.

넥스트(Next.js)

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

Nextra is an opinionated static site generator built on top of Next.js. 도큐사우루스의 테마와 비교하면 기능이 부족합니다.

뷰프레스(VuePress)

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

MkDocs

MkDocs is a popular Python static site generator with value propositions similar to Docusaurus.

It is a good option if you don't need a single-page application and don't plan to leverage React.

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

Docsify

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

깃북(GitBook)

GitBook has a very clean design and has been used by many open source projects. With its focus shifting towards a commercial product rather than an open-source tool, many of its requirements no longer fit the needs of open source projects' documentation sites. 그래서 많은 프로젝트가 다른 도구로 이전하고 있습니다. 리덕스(Redux)도 도큐사우루스로 문서 도구를 이전했습니다. 문서 도구 관련 이슈에서 자세한 내용을 살펴볼 수 있습니다.

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

지킬(Jekyll)

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

지킬에서는 정적인 HTML 파일을 만들고 <script />를 사용해 상호 작용 기능을 추가하는데 비해 도큐사우루스는 리액트 앱으로 구현할 수 있습니다. Using modern JavaScript ecosystem tooling, we hope to set new standards on doc sites' performance, asset building pipeline and optimizations, and ease to set up.

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

뭔가 부족한가요?

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

For new feature requests, you can create a post on our feature requests board (Canny), which is a handy tool for road-mapping and allows for sorting by upvotes, which gives the core team a better indicator of what features are in high demand, as compared to GitHub issues which are harder to triage. 새로운 기능(특히 커다란 기능)은 풀 리퀘스트를 생성하지 말아주세요. 누군가 이미 만들고 있거나 로드맵의 일부일 수 있습니다. 새로운 기능이 필요하다면 우리에게 먼저 연락해주세요!