도큐사우루스 2를 향해
Docusaurus was officially announced over nine months ago as a way to easily build open source documentation websites. Since then, it has amassed over 8,600 GitHub Stars, and is used by many popular open source projects such as React Native, Babel, Jest, Reason and Prettier.
최고의 소프트웨어는 지속적으로 진화하고 최악의 소프트웨어는 그렇지 않다는 이야기가 있습니다. 눈치채고 있는 분들이 있을지 모르겠지만 우리는 새로운 버전의 도큐사우루스를 준비하고 작업을 진행하고 있습니다 🎉.
개요
It all started with this RFC issue opened by Yangshun towards the end of June 2018.
[RFC] Docusaurus v2 · Issue #789 · facebook/docusaurus
These are some of the problems I'm seeing in Docusaurus now and also how we can address them in v2. A number of the ideas here were inspired by VuePress and other static site generators. In the current static site generators ecosystem, t...
제안된 개선사항 대부분은 이슈에 언급되어 있습니다. 저는 도큐사우루스 1이 가지고 있는 몇 가지 문제와 도큐사우루스 2에서 어떻게 이 문제를 해결할 것인지 설명하려 합니다.
구조
콘텐츠
도큐사우루스 1 웹 사이트는 사실 정적 HTML 페이지 묶음으로 만들어집니다. 리액트를 사용했음에도 불구하고 동적이고 인터랙티브한 페이지를 만들 수 있는 컴포넌트 state 객체 같은 리액트의 기능을 제대로 사용하지 못했습니다. React was only used as a templating engine for static content and interactivity has to be added through script tags and dangerouslySetInnerHTML
😱.
또한 도큐사우루스가 콘텐츠를 로드하는 방법을 쉽게 변경할 수 없었습니다. 예를 들어 Sass 나 Less같은 CSS 전처리기를 추가하는 기능을 기본 제공하지 않아 사용자가 직접 스크립트를 작성해 코드를 해킹하는 방법을 사용해야 했습니다.
For Docusaurus 2, we will be using webpack as a module bundler and we are changing the way we serve content. 웹팩 로더를 추가하는 것만큼 간단하게 CSS 전처리기를 추가할 수 있습니다. Instead of a pure static HTML, during build time we will create a server-rendered version of the app and render the corresponding HTML. 도큐사우루스 사이트는 본질적으로 동형/범용(isomorphic/universal) 애플리케이션이 될겁니다. This approach is heavily inspired by Gatsby.
버전 관리
If you have been using Docusaurus for a while, you might notice that Docusaurus creates versioned docs if and only if the docs content are different.
For example, if we have docs/hello.md
:
---
id: hello
title: hello
---
Hello world !
And we cut version 1.0.0, Docusaurus will create versioned_docs/version-1.0.0/hello.md
:
---
id: version-1.0.0-hello
title: hello
original_id: hello
---
Hello world !
However, if there are no changes to hello.md
when cutting v2.0.0, Docusaurus will not create any versioned docs for that document. In other words, versioned_docs/version-2.0.0/hello.md
will not exist.
This can be very confusing for users; if they want to edit the v2.0.0 docs, they have to edit versioned_docs/version-1.0.0/hello.md
or manually add versioned_docs/version-2.0.0/hello.md
. 이 과정에서 의도하지 않은 버그가 만들어질 수도 있습니다. Here is a real scenario in Jest.
또한 버전 폴백을 위한 처리가 필요해서 코드가 복잡해질 수 있습니다. 그리고 빌드 시 도큐사우루스에서 올바른 버전에 대한 링크도 처리해주어야 합니다. This is also the cause of a bug where renaming docs breaks links in old versions.
For Docusaurus 2, every time we cut a new version, we will instead take a snapshot of all the docs. 문서의 내용을 변경할 필요는 없습니다. 더 나은 개발자, 사용자 경험과 저장 공간의 복합성 사이의 절충안입니다. 서로 간의 영향을 분리하고 정확성을 보장하기 위해 좀 더 많은 저장 공간을 사용하게 됩니다.