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

Docusaurus란

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

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

나만의 코드 저장소

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

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

Docusaurus 시작할 때

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

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

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

프로젝트 구성

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

Components

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

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

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

Storybook link

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

Prerequisite

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

Code

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

Props

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

Usage

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

References

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

나머지

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

마치며

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

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