Docusaurus로 나만의 개발 문서 만들기

2022년 06월 27일
Docusaurus

Docusaurus 소개
Docusaurus 소개

Docusaurus란

Docusaurus는 개발 문서 작성에 최적화된 React 프레임워크로, React를 만든 Facebook 팀에서 만들었습니다. 실제로 여러 개발 문서를 찾다 보면 위와 같은 포맷으로 된 문서 페이지를 많이 보았을 텐데요, 개요의 2번째 줄에서도 언급하듯이 콘텐츠에 집중하고 마크다운 파일만 작성하는데에 최적화가 되어 있어 문서 작성에 모든 포커스를 맞추고 싶을 때 매우 유용합니다.

저는 이 프레임워크를 이용해서, 지금까지 제가 개발해 온 모든 노하우를 정리해보고 싶었습니다. 직접 만든 컴포넌트도 있고, 훅스도 있고 하다 보니 여러 프로젝트에 써먹을 수도 있고 나의 경쟁력을 어필하는 데에 도움이 되지 않을까 싶어서 말이죠.

나만의 코드 저장소

오늘 소개할 프로젝트의 메인 페이지
오늘 소개할 프로젝트의 메인 페이지

Docusaurus로 만든 제 프로젝트의 이름은 Archive입니다. 개발자 kidow의 노하우가 남긴 코드들을 보관하는 저장소의 의미를 담고 싶었습니다.

홈페이지 주소는 archive.kidow.me입니다. 저는 kidow.me 도메인을 싼 값에 사서 한 도메인으로 서브도메인을 적용해서 여러 프로젝트를 돌려 쓰는 것을 좋아하는데요, 이렇게 하면 나의 사이드 프로젝트라는 것을 명시할 수도 있고 가격을 아낄 수 있는 게 좋더리구요.

Docusaurus 시작할 때

저는 호스팅 서비스로 Vercel을 사용합니다, Vercel이 개인 개발자들에게 있어 무료 플랜의 혜택이 너무나 좋기 때문이죠. 프로젝트를 무한으로 생성해도 되고, 제공해주는 템플릿으로 프로젝트를 생성하면 Vercel이 알아서 깃허브에 저장소를 만들어주고 빠르게 시작할 수 있으니까요.

Vercel로 Docusaurus 프로젝트 생성
Vercel로 Docusaurus 프로젝트 생성

하지만! 저는 Vercel로 Docusaurus를 시작하는 것을 추천하진 않습니다. 22년 6월 기준 Docusaurus 2가 베타 버전인데, 버전이 짜잘하게 수시로 올라가는데 Vercel로 만들면 최신 버전이 아니기 때문입니다.

가급적이면 Docusaurus 문서에서 직접 최신 버전을 설치 후 깃허브에 올린다음 Vercel에서 임포트하시는 것을 추천드립니다.

프로젝트 구성

리액트 개발자답게, 저는 다음과 같이 4가지 탭으로 문서를 구성했습니다.

archive.kidow.me 소개 페이지
archive.kidow.me 소개 페이지

Components

저는 CSS 프레임워크로 TailwindCSS를 주로 사용하는 편인데, TailwindCSS는 다른 건 다 좋은데 오피셜한 UI 라이브러리가 따로 없는 편이라 직접 컴포넌트를 만들어 쓰던가, MUI같은 다른 UI 프레임워크를 섞어 쓰던가 해야만 합니다. 후자의 경우는 프로젝트가 무거워지기 때문에 저는 어쩔 수 없이 전자의 경우를 택했고 지금 회사에서는 제가 직접 만든 컴포넌트를 적용해 개발을 하는 중입니다.

Button 컴포넌트
Button 컴포넌트

의외로 말이죠, 컴포넌트를 직접 만드는 것은 생각보다 재미있습니다! 😆 내가 쓰고 싶은 걸 직접 만들어 쓰면 내가 실력이 이만큼 성장했구나 싶기도 하고, 직접 만들었기 때문에 내가 필요한 대로 개조하고 다듬어서 쓸 수도 있다는 것이 보람이 생기더라구요.

컴포넌트들은 약간 실제 UI 프레임워크 문서들처럼 만들어 보려고 다음과 같이 나눠서 작성을 해보았습니다. 짧게 소개하자면,

이 프로젝트는 되도록 코드를 보여만 줄 뿐 UI를 보여주진 않아서, 스토리북 프로젝트도 따로 만들어 두고 있습니다. UI를 보고 싶은 사람들에게 소개하기 위해 링크를 따로 적어두고 있습니다.

Prerequisite

Button 컴포넌트 전제 조건
Button 컴포넌트 전제 조건

현 컴포넌트를 만들기 위해 필요한 전제조건들입니다. 제가 만든 것들이 여러 개 섞여 있는 경우 추가로 구현이 필요한 설정들을 나열하고, 필요한 라이브러리가 있다면 npm과 yarn 둘 다 복사할 수 있도록 하였습니다.

Code

말 그대로 컴포넌트에 대한 코드입니다.

Props

Modal 컴포넌트 Props
Modal 컴포넌트 Props

넘겨줄 수 있는 속성들입니다. 필수 값 여부도 구분하면 좋을 것 같아서 구분을 한 번 해봤습니다니.

Usage

Toast 컴포넌트 Usage
Toast 컴포넌트 Usage

일부 컴포넌트는 사용법도 알려줄 수 있으면 좋을 것 같아서 적어놓았습니다.

References

마지막으로 해당 문서를 작성하기 위해 참고한 사이트들에 대한 링크도 달면 좋을 것 같아서 달아두곤 합니다.

나머지

Hooks / Utils / Settings
Hooks / Utils / Settings

  • Hooks : 직접 만들어 쓰는 훅스들 모음입니다.
  • Utils : 직접 만들어 쓰는 함수 등의 모음입니다.
  • Settings : 프로젝트를 시작할 때나, 새로운 작업환경에서 코딩을 할 때 일괄적으로 개발 환경을 맞추기 위한 환경 설정 등을 저장하는 곳입니다.

마치며

Docusaurus를 개발 문서로만 접했다면, 한번쯤은 여러분 스스로의 개발 문서를 만들어 보는 것을 추천합니다. 지금까지의 경력을 통해 쌓은 내 노하우를 아낌없이 어필할 수 있는 좋은 기회가 될 수도 있으니까요.

아직 만들어 놓고 작성하지 못한 문서들도 있는데, 자유롭게 만드는 내 사이드 프로젝트인만큼 여유가 될 때마다 틈틈이 채워나갈 생각입니다!