도큐사우루스는 오픈 소스 문서 웹사이트를 쉽게 만들 수 있는 도구로 9개월 전에 공식 발표했습니다. 그 이후 깃헙에서 8,600여 개의 별을 받았고 React Native, Babel, Jest, Reason, Prettier 같은 매우 인기 있는 오픈 소스 프로젝트에서 사용하고 있습니다.
최고의 소프트웨어는 지속적으로 진화하고 최악의 소프트웨어는 그렇지 않다는 이야기가 있습니다. 눈치채고 있는 분들이 있을지 모르겠지만 우리는 새로운 버전의 도큐사우루스를 준비하고 작업을 진행하고 있습니다 🎉.
개요
이 모든 것은 2018년 6월 말 Yangshun이 올린 RFC issue에서 시작됐습니다.
[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 객체 같은 리액트의 기능을 제대로 사용하지 못했습니다. 리액트는 정적 콘텐츠를 만들기 위한 템플릿 엔진으로만 사용됐으며 스크립트 태그와 dangerouslySetInnerHTML을 사용해 대화형 페이지를 구성했습니다 😱.
또한 도큐사우루스가 콘텐츠를 로드하는 방법을 쉽게 변경할 수 없었습니다. 예를 들어 Sass나 Less같은 CSS 전처리기를 추가하는 기능을 기본 제공하지 않아 사용자가 직접 스크립트를 작성해 코드를 해킹하는 방법을 사용해야 했습니다.
도큐사우루스 2는 모듈 번들러로 webpack을 사용할 겁니다. 이를 통해 콘텐츠를 제공하는 방식이 변경됩니다. 웹팩 로더를 추가하는 것만큼 간단하게 CSS 전처리기를 추가할 수 있습니다. 정적인 HTML 파일을 바로 만들지 않고 빌드 시 서버에서 렌더링을 처리하는 버전의 앱을 만들고 필요한 HTML 파일을 만듭니다. 도큐사우루스 사이트는 본질적으로 동형/범용(isomorphic/universal) 애플리케이션이 될겁니다. 이 접근 방식은 Gatsby에서 영감을 받았습니다.
버전 관리
도큐사우루스를 사용해보았다면 도큐사우루스는 문서 콘텐츠가 다르게 변경된 경우에만 버전을 부여한 문서를 만든다는 것을 알고 있을 겁니다.
예를 들어 여러분은 docs/hello.md 문서를 가지고 있습니다:
---
id: hello
title: hello
---
Hello world !
그리고 버전 1.0.0을 만들면 도큐사우루스에서는 versioned_docs/version-1.0.0/hello.md 파일을 만듭니다.
---
id: version-1.0.0-hello
title: hello
original_id: hello
---
Hello world !
하지만 v2.0.0을 만들 때 hello.md의 변경 사항이 없다면 도 큐사우루스에서는 해당 문서에 버전을 부여한 파일을 만들지 않습니다. 즉, versioned_docs/version-2.0.0/hello.md 파일은 없다는 이야기입니다.
이런 방식은 사용자가 혼란스러울 수 있습니다. v2.0.0 문서를 편집하고 싶은 경우에는 versioned_docs/version-1.0.0/hello.md 파일을 수정하거나 아니면 versioned_docs/version-2.0.0/hello.md 파일을 직접 만들어서 수정해야 합니다. 이 과정에서 의도하지 않은 버그가 만들어질 수도 있습니다. Jest에서 실제 발생했던 사례를 확인할 수 있습니다.
또한 버전 폴백을 위한 처리가 필요해서 코드가 복잡해질 수 있습니다. 그리고 빌드 시 도큐사우루스에서 올바른 버전에 대한 링크도 처리해주어야 합니다. 이로 인해 문서 이름 변경 시 이전 버전의 링크가 깨지는 버그가 발생하기도 했습니다.
도큐사우루스 2에서는 새로운 버전이 만들어지면 모든 문서의 스냅샷을 만듭니다. 문서의 내용을 변경할 필요는 없습니다. 더 나은 개발자, 사용자 경험과 저장 공간의 복합성 사이의 절충안입니다. 서로 간의 영향을 분리하고 정확성을 보장하기 위해 좀 더 많은 저장 공간을 사용하게 됩니다.
번역
도큐사우르스에서는 크라우드인를 사용해 번역 기능을 쉽게 추가할 수 있습니다. 영어로 작성된 문 서는 커뮤니티 기반으로 사용자가 직접 번역할 수 있는 크라우드인으로 업데이트됩니다. 우리는 항상 영어가 기본 언어일 것이라 생각했지만 모든 사용자에게 해당하는 것은 아니었습니다. 많은 비영어권 오픈 소스 프로젝트에서 도큐사우루스를 사용하는 것을 확인했습니다.
도큐사우루스 2에서는 영어를 기본 언어로 설정하지 않습니다. 사용자가 국제화 기능을 활성화할때 siteConfig.js에서 기본 언어를 설정할 수 있습니다. 그렇게 하면 docs 디렉터리 아래에 있는 모든 파일은 해당 언어로 작성된 것으로 처리합니다.
또한 도큐사우루스 2 MVP 개발 이후 번역 시 크라우드인을 사용하지 않을 수도 있다는 것을 깨달았습니다. 그래서 이런 상황에 맞는 시나리오를 지원하기 위해 우리는 추가적인 워크플로우가 필요합니다. 물론 좀 더 쉬운 통합을 위해 크라우드인을 사용하는 것을 권장합니다.
사용자 맞춤
레이아웃
현재 도큐사우루스는 전체 레이아웃과 스타일이 묶여 있어서 사용자가 사이트 모양을 원하는 형태로 변경하는 것이 매우 어렵게 구성되어 있습니다.
도큐사우루스 2에서는 사용자가 레이아웃과 스타일을 직접 컨트롤할 수 있습니다. 콘텐츠 생성, 라우팅, 번역, 버전 관리를 도큐사우루스에서 제어할 수 있습니다. create-react-app과 VuePress에서 영감을 받아 도큐사우루스에서 기본 테마를 제공하고 사용자는 추가적인 레이아웃과 스타일 설정을 위해 테마를 바꿀 수 있도록 개선했습니다. 이제 사용자는 React Helmet을 사용해 HTML 메타를 변경할 수 있습니다. 커뮤니티 기반 테마를 만들어서 공개할 수도 있고요. 사용자가 레이아웃과 스타일을 변경할 수 있는 접근 방식은 대부분 정적 사이트 생성 도구에서 사용하는 방식입니다.
마크다운
현재 사용하고 있는 마크다운 구문 분석 도구는 Remarkable입니다. 하지만 사용자가 Markdown-it이나 MDX를 사용하고자 할때는 적절하게 대응할 수 없습니다. 또한 어떤 구문 강조 도구를 사용할지도 문제가 될 수 있습니다(예를 들어 Prism 또는 Highlight.js). 이러한 선택을 사용자가 할 수 있도록 허용해주어야 합니다.
도큐사우루스 2에서는 사용자가 마크다운 구문 분석 도구를 교체하거나 선택할 수 있습니다. Remark와 같은 마크다운 분석 도구를 사용하거나 자체적으로 만든 도구를 사용할 수도 있습니다. 경험상 사용자는 우리가 _마크다운 RAW 문자열_을 포함한 자식 속성을 제공할 수 있게 리액트 컴포넌트를 만들어야 합니다. 기본값으로 마크다운 구문 분석은 Remarkable, 구문 강조는 Highlight.js을 사용합니다. 기본 제공되는 구문 분석 도구는 아직 여러 가지 검토중이라 나중에 다른 마크다운 구문 분석 도구로 변경될 수는 있습니다.
검색
우리의 핵심 검색 기능은 알골리아 기반입니다. 하지만 사용자는 오프라인 검색 기능 지원을 위해 lunrjs 같은 다른 검색 기능 지원을 요청하고 있습니다.
저는 개인적으로 알골리아를 좋아하고 그들과 같이 일하는 것은 좋은 경험입니다. DocSearch는 오픈 소스이기 때문에 우리는 알골리아에 풀 리퀘스트를 편하게 요청할 수 있습니다. 그리고 그런 요청에 항상 잘 대응해주고 있습니다. 예를 들면 최근에는 this PR that enables DocSearch to scrape alternate languages in sitemap 같은 요청을 보냈습니다.
도큐사우루스 2에서는 사용자 지정 검색 상자를 사용할 수 있습니다. 기본 테마에서 기존 검색 상자 대신 검색 UI(리액트 컴포넌트로 만든)를 수정할 수 있습니다. 물론 기본 테마에서 알골리아는 계속 지원합니다.
안정성
소프트웨어가 완벽할 수는 없지만 새로운 기능을 추가하면서 도큐사우루스에 문제가 생기지 않기를 바라고 있습니다. 도큐사우루스를 처음 공개했을 때는 엄격한 자동화 테스트를 갖추지 못했습니다. 그래서 일찍 발견하지 못한 수 많은 회귀 버그가 발생했습니다. 최근에 테스트를 계속해서 추가하고 있지만 여전히 테스트 커버리지는 상대적으로 낮습니다.
도큐사우루스 2는 코드를 새로 작성할 계획이기 때문에 개발과 동시에 테스트를 추가하고 있습니다. 때문에 좀 더 안정적이며 도큐사우루스 1과 비교했을 때 문제가 생길 가능성이 줄어들겁니다.
자주 묻는 질문
변경할 것이 많은가요?
관련 글을 읽었다면 어떤 부분이 변경되는지 알 수 있을 겁니다. 가능한 변경 사항이 생기는 것은 최소화하고 이전 버전과 호환성을 유지할 겁니다. 하지만 일부 사항은 어쩔 수 없이 변경될 수 있습니다. 도큐사우루스 2 코드를 아키텍처 수준에서 다시 작성하기 때문에 생기는 변화입니다.
정확한 변경 목록은 개발이 100% 진행된 것이 아니므로 모두 확인할 수 없습니다. 하지만 한 가지 강조할 수 있는 건 siteConfig.js에 있는 수많은 옵션을 더 이상 사용하지 않으며 가능한 간결하게 유지하도록 변경할 겁니다. 예를 들어 도큐사우루스 2 사이트에서는 .html 접미사를 사용하지 않기 때문에 siteConfig에서 cleanUrl 항목도 사용하지 않게 됩니다.
우리의 목표는 대부분 사이트가 손을 많이 대지 않고 도큐사우루스 2로 업그레이드할 수 있도록 하는 겁니다. 도큐사우루스 2를 공개하게 되면 마이그레이션 가이드도 포함될 겁니다. 그때가 되면 디스코드나 트위터를 통해 질문이나 도움을 위한 요청을 자유롭게 보내주세요.
도큐사우루스 2는 언제 출시되나요?
지금으로서는 정확한 출시 일정을 가지고 있지는 않습니다. 개인적인 생각으로는 알파 버전을 한두 달 내에 출시할 것 같지만 확실하지는 않습니다.
한 가지 알려드리고 싶은 점은 도큐사우루스가 페이스북 오픈 소스 중 하나이고 대부분 팀원이 페이스북에서 일하고 있지만 유지 및 개발을 위한 작업은 정규 업무 시간 외에 진행되고 있다는 겁니다. 저 같은 경우도 난양 이공대학(NTU Singapore)의 학부 마지막 1년을 남겨놓고 있습니다. 그래서 학부수업, 졸업과제와 도큐사우루스 유지/개발 작업을 빡빡하게 진행하고 있습니다. 하지만 그렇다고 해서 우리가 도큐사우루스를 더 멋지게 만드는 것을 원하지 않는다는 건 아니니다. 사실 우리는 정말 가장 멋진 결과를 만들어내고 싶습니다.
아직은 도큐사우루스 2 작업을 개인 저장소에서 관리하고 있습니다. 조만간 공용 저장소로 이전할 계획입니다. 그때가 되면 여러분 모두 어떤 식으로든 함께 해주기를 기대하고 있습니다. 그때까지는 계속 지켜봐주세요 😉!
글을 마치며
도큐사우루스는 오픈 소스 커뮤니티에 커다란 영향력을 미치고 있습니다. 문서화를 위해 도큐사우루스를 사용하는 수 많은 인기있는 프로젝트에서 알 수 있듯이 말이죠. 앞으로 더 빨리 나아가기 위해 도큐사우루스 1이 가지고 있던 몇 가지 심각한 문제를 해결하고 모든 이들에게 더 나은 도큐사우루스를 선보일 수 있도록 노력하고 있습니다. 사실 도큐사우루스 2는 더 이상 계획 뿐인 작업이 아니라고 말할 수 있습니다. 작업은 시작됐고 가능한 빨리 선보일 수 있기를 바라고 있습니다.
도큐사우루스의 사명은 문서를 제공하는 웹 사이트를 쉽게 만들고 바로 사용할 수 있게 하는 겁니다. 도큐사우루스 2에 서도 이 사명은 변하지 않을 겁니다.
도큐사우루스 2 작업이 시작됐기 때문에 도큐사우루스 1의 새로운 기능이나 변경 요구를 받아들이기는 힘들 수 있다는 것을 양해해주시길 바랍니다.
도큐사우루스를 사용하고 있다면 여러분은 우리 커뮤니티의 일원입니다. 도큐사우루스를 좀 더 좋게 만들 수 있도록 우리에게 알려주세요. 우리 작업을 지원하고 싶다면 Docusaurus on Open Collective을 통해 도움을 줄 수도 있습니다.
Open Collective에서 기부를 해주시면 우리는 개인적으로 도큐사우루스 웹 사이트 관리나 업그레이드에 도움을 드릴 수 있습니다.
마지막으로 아직 하지 않으셨다면 깃헙에서 **별(star)**과 알림 설정(watch) 버튼을 클릭해주세요. 그리고 트위터 팔로우도 부탁드립니다.