메인 컨텐츠로 이동

도큐사우루스 2.0이 나왔습니다

· 17분 읽기 분량
세바스티앵 로버(Sébastien Lorber)
Docusaurus maintainer, This Week In React editor
조슈아 첸(Joshua Chen)
도큐사우루스에 헌신하고 있습니다.
양순 테이(Yangshun Tay)
메타 프론트엔드 엔지니어
알렉세이 필트 신(Alexey Pyltsyn)
열정적인 오픈 소스 지지자
폴 오세네시(Paul O’Shannessy)
메타 엔지니어링 매니저
조엘 마시(Joel Marcey)
도큐사우루스 1 공동 개발자

Today we are extremely happy to finally announce Docusaurus 2.0! 🥳️

At Meta Open Source, we believe Docusaurus will help you build the best documentation websites with minimal effort, letting you focus on what really matters: writing the content.

After 4 years of work, 75 alphas and 22 betas, the next generation of Docusaurus is ready for prime time. From now on, we now plan to respect Semantic Versioning and will release major versions more frequently.

social-card image

We are on ProductHunt and Hacker News!

Now is the best time to show your love for Docusaurus!

Docusaurus 2.0 - Build optimized websites quickly, focus on your content. | Product Hunt

빨리 만나보고 싶나요? Check what's new in Docusaurus 2.0!

도큐사우루스는 정확하게 뭔가요?

Docusaurus is a static site generator that helps you ship beautiful documentation websites in no time.

Focus on your content: just write Markdown files. Docusaurus will generate an optimized website for you that's easy to host anywhere.

Docusaurus is full-featured and very flexible: we ship with well-designed docs and blog layout, as well as out-of-the-box versioning, search, and internationalization functionalities, with a call to accessibility and search engine optimizations. Its flexible theming system permits to adapt the UI to match your branding so that it integrates nicely with your main website or documentation portal. Its usage of React enables a modern client-side navigation, and the ability to build an interactive documentation.

Introducing Slash

The Docusaurus philosophy is akin to the Pareto principle: you can get 80% of the results for 20% of the effort. This enables you to compete with top-notch documentation sites with minimal effort.

Unless you're spinning up a documentation team with engineering resources, you probably want Docusaurus!

Rachel Nabors
Rachel NaborsFormer ReactJS & React-Native docs manager

Docusaurus aims to be the best documentation tool, but you can use it for other use-cases as well: a blog, a knowledge base, a developer portfolio, a second brain, or even to scaffold landing pages!

Using Docusaurus for my tech blog has been a fantastic choice. It looks tremendous out-of-the-box and the awesome DX means I write way more

Johnny Reilly
Johnny ReillyGroup Principal Engineer at Investec

Try Docusaurus now with our online playgrounds and 5 minutes tutorial ⏱️

도큐사우루스 비하인드 스토리

Docusaurus was created at Facebook Open Source in 2017 (now Meta Open Source). 우리는 문서화가 필요한 수많은 내부, 오픈 소스 프로젝트를 가지고 있었습니다. It's complicated enough to write good documentation, let alone to create the HTML, CSS, and JavaScript for a good-looking website. We wanted project leaders to be able to focus on the content, and Markdown is great for that.

At that time, our solution was to copy/paste a Jekyll template over and over again. This naturally became hard to maintain, so we created a tool to solve our own pain once for all.

Docusaurus v1 was born!

Birth of Slash

It quickly built momentum at Facebook and in the frontend ecosystem, adopted by many popular projects such as Prettier, Babel, React-Native, KaTeX, and of course Docusaurus v1 itself.


참고

위의 샘플 사이트는 다른 색상을 사용하긴 하지만 서로 비슷하게 보이는 것을 주의 깊게 살펴봐주세요.

도큐사우루스 2.0를 향해

Docusaurus v1 has been very successful, but we started to question some architectural choices:

  • React was only used as a server-side templating language, and not used on the client
  • Theming system was pretty limited, and apart from changing a few colors with CSS, it was difficult to do more advanced customizations
  • The docs versioning system was confusing, since it was based on a diff algorithm
  • The codebase was monolithic, neither well-tested nor easy to extend

Docusaurus v2 was rebuilt from the ground up with a new modular architecture:

  • React is now also used on the client, enabling a modern Single Page Application navigation
  • Plugins empower the community to contribute useful features as third-party packages
  • Theming is more flexible than ever
  • 문서 버전 관리는 스냅샷 사본을 기반으로 동작하며 훨씬 더 이해하기 쉬워졌습니다.
  • We kept everything good from v1: docs, blog, pages, versioning, i18n...
  • We implemented several new features

More details in the Docusaurus 2 project announcement and v1 to v2 migration guide

누가 도큐사우루스 2.0을 사용하고 있나요?

Despite being in pre-release, it didn't take long for Docusaurus v2 to outgrow Docusaurus v1 in terms of NPM downloads:

NPM downloads: v2 outgrows v1

비슷한 주요 프레임워크와 비교해서 깃허브 스타 트렌드도 매우 긍정적입니다.

GitHub stars: Docusaurus is well-positioned

도큐사우루스 v2는 출시 전부터 이미 큰 성공을 거두고 있습니다.


Please add your site to our site showcase! It only takes a few seconds: just post a comment here.

We use Docusaurus everywhere now and love it

Max Lynch
Max LynchIonic co-founder and CEO

We've been using V2 since January and it has been great

Supabase
SupabaseOpen Source Firebase alternative

Docusaurus is next level easy for literally everything you would need for documentation in your project.

Gabriel Csapo
Gabriel CsapoStaff Software Engineer at LinkedIn

Docusaurus is awesome. We use it

Matt Gregg
Matt GreggSenior Front End Developer at Shopify

2.0의 새로운 기능은 무엇인가요?

도큐사우루스 v2에서 제공하는 모든 새로운 기능을 다 설명하는 것은 무리입니다. Let's focus on the features we believe are the most impactful.

MDX

MDX allows you to interleave React components in Markdown. This enables you to build top-notch interactive documentation experiences very easily.

데모로 먼저 확인해보시죠.

docs/my-document.mdx
### Give it a try: press that button!

import ColorModeToggle from '@theme/ColorModeToggle';

<ColorModeToggle/>
http://localhost:3000

Give it a try: press that button!

정보

MDX has its own plugin system. 원하는 대로 마크다운 작성 경험을 사용자 지정하고 여러분만의 마크다운 구문을 만들 수도 있습니다.

Docusaurus + MDX is great: we were able to implement a beautiful two-pane layout and give the author fine-grained control on the placement of code and corresponding prose.

Hamel Husain
Hamel HusainHead Of Data Science at Outerbounds

파일 시스템 규칙

Our goal is to make Docusaurus very intuitive to use. 이를 파일 시스템 규칙에 반영해 마크다운 파일 하나를 만드는 것만큼 간단하게 문서 페이지를 추가할 수 있습니다.


Using the auto-generated sidebars makes it so simple to just create a page and not worry about any other configuration.

Paul Armstrong
Paul ArmstrongPrincipal Engineer at Microsoft

플러그인

Docusaurus now has a modular architecture with a plugin system — our core features like docs, blog, pages, and search are all powered by individual plugins.

More importantly, it enables our community to enhance Docusaurus with additional features.

몇 가지 사례를 살펴보죠.

redocusaurus plugin example

shiki-twoslash plugin example

The plugin API was a breeze to use, and powerful enough that I could port the code sample renderer from the TypeScript website site in a couple of hours.

Orta Therox
Orta TheroxFormer TypeScript core team at Microsoft

local search plugin example

We have a curated list of outstanding plugins in our community resources page.

The plugin system in Docusaurus v2 has made expanding 1Password's developer portal so easy and fun. 저희가 준비한 새로운 기능을 선보이게 되어 무척 기쁩니다.

Jody Heavener
Jody HeavenerSenior Developer at 1Password

테마

Theming is one of the most important features of Docusaurus: we believe a professional documentation site should respect your company's branding and create a consistent experience.

Docusaurus theming gives a lot of flexibility on multiple levels:

  • 색상, 글꼴 등을 조정하기 위한 사용자 지정 CSS 변수
  • 나만의 CSS 스타일시트 제공
  • 바닥부터 나만의 테마 구현
  • Override any React component provided by our default theme: we call this swizzling

I love Docusaurus Swizzling feature. 고집이 세 보이지만 동시에 유연합니다. 프레임워크는 일반적으로 무언가를 희생해야 하기 때문에 이것은 매우 멋진 기능입니다.


Hung Viet Nguyen
Hung Viet NguyenCreator of JestPreview

This enables users willing to invest a bit more time on customizations to build sites that look different from others.

So far it’s working out really nicely. 우리가 원하는 스타일로 구현하는 것은 정말 간단합니다. 어떤 장벽도 없습니다.

Nader Dabit
Nader DabitWeb3 developer, Developer DAO founder

기타 기능

도큐사우루스 2에는 다음과 같이 다양하고 유용한 기능이 포함되어 있습니다.

  • Theme: dark mode, better UI and UX, flexible themeConfig options...
  • 문서 버전 관리: 워크플로우에 맞게 조정할 수 있는 유연한 플러그인 옵션
  • 문서 사이드바: 접을 수 있는 카테고리, 카테고리 인덱스 페이지...
  • 블로그: 여러 명의 저자 표시, 저자 맵, 아카이브 페이지...
  • 마크다운: 탭, 수식, 라이브 코드 블록, 링크, 유연한 프런트매터...
  • 검색: 새로운 알골리아 DocSearch 3 적용
  • 애셋: 이미지나 기타 파일을 쉽게 통합할 수 있습니다.
  • 국제화: 구성 옵션, 기본 테마 번역...
  • 접근성: aria 라벨, 색상 대비, 콘텐츠로 건너뛰기, 키보드로 탐색하기, 점진적 향상...
  • SEO: 유용한 기본 설정, 쉬운 사용자 지정, 캐노니컬 url, 소셜 카드, 검색색인차단, 사이트맵, 마이크로데이터, hreflang...
  • PWA: 오프라인에서 사이트를 설치해 사용할 수 있습니다.
  • 빠른 실패: 엄격한 설정 유효성 체크, 끊어진 링크 탐지 등을 통해 잘못된 제품이 배포되는 것을 방지합니다.
  • 구성 파일, 플로그인, 사용자 지정 페이지, 테마 작성자를 위한 타입스크립트 지원
  • Playgrounds: assess Docusaurus easily from your browser with docusaurus.new
  • 카나리(Canary) 릴리스: @canary npm 태그를 사용하면 좀 더 일찍 새로운 릴리스를 사용할 수 있습니다.
  • 테스트: 도큐사우루스는 적절하게 테스트되고 있으며 우리 사이트에 적용해 문제가 없는지 지속적으로 확인합니다.

Recently, I was shocked at how good Docusaurus is out of the box. 매우 견고하면서도 유연한 구성을 통해 저보다 좀 더 과감하게 다가선다면 원하는 스타일로 사용자 지정하는 능력도 가지고 있습니다.

Alex DeBrie
Alex DeBrieAWS Data Hero, author of The DynamoDB Book

왜 2.0이 이제야 나왔나요?

Many enthusiastic followers of ours have been curious why it took us 4 years to release Docusaurus 2.0, considering the beta is already successful and widely used in production.

The reason is that we aim to respect Semantic Versioning, which means we will be incrementing the major version number whenever we release a breaking change.

이것은 여러 이유로 중요합니다.

  • It guarantees simple minor version upgrades, as long as you only use the public API
  • 프론트엔드 생태계 규칙을 따릅니다.
  • 새로운 메이저 버전은 주요 변경 사항을 완벽하게 문서화할 수 있는 기회입니다.
  • 새로운 메이저/마이너 버전은 블로그 게시물을 통해 새로운 기능을 전달할 수 있는 기회입니다.

The problem is that our flexible theming system inherently creates a very implicit API surface on which it is hard to know what is a breaking change in the first place. 고도로 사용자 정의된 도큐사우루스 사이트는 내부 API를 사용해 사용자 정의를 구현하기 때문에 때로는 도큐사우루스를 업그레이드하는데 어려움을 겪을 수 있습니다. We dedicated time to extensive theme refactors and clearly defining our public API, so that future code changes can be made more safely. 일반적인 사이트 사용자 정의 시에는 내부 API를 사용하지 않을 수 있게 공개된 테마 API를 계속 확장할 겁니다.

정보

From now on, Docusaurus will release new major versions more frequently. In practice, you can expect a new major version every 2 to 4 months.

Major version numbers are not sacred, but we still group breaking changes together and avoid releasing major versions too often.

Check our release process documentation for details.

다음 단계는 뭔가요?

Slash Up and Running

도큐사우루스 3.0에 대한 작업이 시작됐으며 다음 버전은 몇 개월 안에 릴리스 될 예정입니다. We will backport retro-compatible changes in Docusaurus 2.x minor versions to make them available as soon as possible to the community on a stable channel.

도큐사우루스의 향후 메이저 버전 로드맵에 포함된 기능은 아래와 같습니다.

감사합니다

We'd like to express our gratitude to all our contributors, including:

We'd like to thank in particular all our Docusaurus 2.0 early adopters for assessing its alpha, beta and canary releases, providing a ton of invaluable feedback. 좋은 경험이 되셨기를 진심으로 바라며 곧 공개될 도큐사우루스 3.0 시험판에 대한 피드백도 계속 제공해주시기 바랍니다.

At Meta Open Source, Docusaurus is one of our most successful projects. 여러분이 만들 모든 뛰어난 문서 웹 사이트를 만나보고 싶습니다! Don't forget to submit them to our site showcase!

Now, let your imagination run wild 🤪!

— 슬래시

We are on ProductHunt and Hacker News!

🙏 여러분의 커뮤니티에서 도큐사우루스의 사용 경험을 공유해주세요!

Docusaurus 2.0 - Build optimized websites quickly, focus on your content. | Product Hunt

Slash plushies

도큐사우루스 2021년 회고

· 10분 읽기 분량
조슈아 첸(Joshua Chen)
도큐사우루스에 헌신하고 있습니다.

도큐사우루스는 2021년에도 엄청난 일들을 해냈습니다! We've seen a lot of traction and just crossed 30k stars on GitHub!

We've reached full feature parity with v1 after the release of internationalization, announced our first beta, and welcomed significantly more users this year.

The official v2 release is just around the corner! Follow the roadmap issue for any latest news.

DocSearch 마이그레이션

· 5분 읽기 분량
클레망 바니카트(Clément Vannicatte)
소프트웨어 엔지니어 @ Algolia
세바스티앵 로버(Sébastien Lorber)
Docusaurus maintainer, This Week In React editor

DocSearch is migrating to a new, more powerful system, which gives users their own Algolia application and new credentials.

Docusaurus site owners should upgrade their configuration with their new credentials by February 1, 2022, existing search indexes will be frozen and become read-only after this date.

도큐사우루스 2 베타가 나왔습니다!!!

· 7분 읽기 분량
세바스티앵 로버(Sébastien Lorber)
Docusaurus maintainer, This Week In React editor
조엘 마시(Joel Marcey)
메타 디벨로퍼 애드보케이트
양순 테이(Yangshun Tay)
메타 프론트엔드 엔지니어
알렉세이 필트 신(Alexey Pyltsyn)
열정적인 오픈 소스 지지자

After a lengthy alpha stage in order to ensure feature parity and quality, we are excited to officially release the first Docusaurus 2 beta.

With the announcement of this beta, the team is even more confident that Docusaurus 2 is ready for mainstream adoption!