당신의 OpenSource를 Documentation 하는 가장 쉬운 방법, Docusaurus.

하성준
하성준
Oct 21, 2019 · 7 min read

OpenSource들의 공통적인 목표는 많은 사람들이 보고 그 OpenSource가 활성화 되는것이다. 그 첫 걸음은 Documentation에 있다. 아무리 좋아도 Document를 봤을 때 눈에 들어오지 않는다면 이목을 끌지 못 하기 때문이다.

OpenSource 문서화를 위한 Docus aurus라는 프로젝트를 소개해보겠다. Markdown으로 작성한 문서를 기반으로 React 기반 웹 앱을 빌드해준다.


1. Docusaurus install

$ npx docusaurus-init

$ npm install -g docusaurus-init

$ yarn global add docusaurus-init

위 3가지 명령어로 Docusaurus를 설치할 수 있다. create-react-app이나 serverless처럼 글로벌 패키지로 설치하여 사용한다. 설치 후 터미널에 아래 명령어를 입력하면 pwd아래에 Docusaurus 템플릿이 생성된다. (npx를 이용했다면 자동으로 생성된다.)

$ docusaurus-init

website directory에 들어가서 npm start를 하면 Dev Server가 작동되고 localhost:3000으로 접속가능한 사이트가 뜬다.(3000번이 사용중이라면 자동으로 다른포트로 매핑)

2. Docusaurus Directory Structure

docusaurus-init을 실행하면 다음과같은 directory가 생성된다.

a. docs에는 해당 프로젝트를 설명하기 위한 문서들이 들어있으며 Markdown형식으로 작성되어있다.

b. Website Directory 밑에는 다양한 directory들이 있다. blog directory는 해당 Site에서 사용하고싶은 블로그 포스트들이다 yyyy-mm-dd-name.md형식으로 작성되어야한다.

c. core/Footer.js는 사이트의 맨 밑에 렌더링 되는 컴포넌트이다. 예제 사이트에서는 아래와 같다. React 컴포넌트 형태로 되어있어서 만약 Footer를 붙이고싶지 않다면 render()에 return null을 해주면 된다.

d. pages에는 페이지 하나를 나타내는 React Component들이 들어있다. index.js가 기본 페이지로 되어있으며, 다른 페이지들을 추가하고 싶으면 추가할 수 있다.

e. siteConfig는 가장 중요한 파일중 하나이다. 자신이 만든 md 파일들을 어디로 어떻게 링크할 지, 메인 페이지의 색깔은 어떨지, 제목은 무엇인지 등을 지정할 수 있다.

위와 같이 title을 정하거나 baseUrl을 지정할 수 있으며,

위와 같이 header에 있는 링크들을 설정할 수 있다.

이 외에도 다양한 configuration을 설정할 수 있다.

3. 페이지 구성 하기

3.1 main page

Docusaurus를 구성하는 기본적인 페이지들은 React Component로부터 빌드되며, pages 디렉토리에 존재한다. 하나의 컴포넌트가 하나의 페이지로 렌더링 된다. (index.js 는 build시에 index.html로 빌드됨)

index.js가 메인 페이지다. 이곳에서서 원하는 컴포넌트를 추가하거나, 링크를 만들 수 있다. 기본적인 페이지 구성은 여기서 바꿀 수 있으며, 원한다면 이 파일을 지우고 static 디렉토리에 index.html을 추가할 수 있다.

docusaurus-init으로 생성했다면 기본으로 page/en에 파일이 3개가 있을 것이다. 각 js 파일 하나가 html파일 하나로 렌더링 되며, 만약 custom.js라는 페이지를 생성했다면, baseURL/en/custom.html, 또는 baseURL/custom.html로 접근할 수 있다.

실제 리액트 앱처럼 하나의 페이지를 여러가지 컴포넌트로 구성할 수 없다. 이 전체 프로젝트가 리액트 프로젝트가 아니라 Docusaurus가 읽어서 다시 재구성하기 때문에 기존의 리액트 프로젝트처럼 마음대로 컴포넌트를 나누어서 페이지를 제작할 수 없는것이 조금 아쉽다.

3.2. Header Links

npm start를 통해서 페이지를 렌더링해보면 상단에 head bar가 뜨는 것을 볼 수 있다. index.js에서 링크를 통해 이동할 수도 있지만(버튼을 추가하여 링크를 건다던지…?) siteConfig에 요소를 추가하는것 만으로 손쉽게 head bar에 문서 링크를 넣을 수 있다.

위가 예시 head bar 모양이다.

siteConfig파일에 보면 위와 같은 값이 있고 여기에 자신이 만든 md파일 등을 연결시킬 수 있는데, doc: ‘md 파일 안에 선언된 id’ 처럼 링크하거나, page를 통해 자신이 react component로 만든 페이지로 이동할 수 있다. 또는 특별히 제공되는 blog라는 곳으로 링크할 수 도있는데 밑에서 설명하겠다.

3.3 Footer.js

Docusaurus는 크게 head,body,Footer로 나누어져있는데, Header에 들어가는 요소들은 siteConfig에서, body는 pages, Footer는 footer.js에서 설정할 수 있다. 기본적으로는 하단에 들어가는 기본 요소들이 들어있는 React Component가 생성되며, 이를 자유자재로 바꿀 수 있다.

4. 문서 작성하기

이제 실제로 포스팅 되고 싶은 문서들을 작성하는 방법을 알아보자. 매우 쉽다 MarkDown형태로 작성하여 Docs 디렉토리에 넣기만 하면된다. 그러면 docusaurus가 ‘BaseUrl/docs/문서이름’ 으로 접근할 수 있는 html파일을 자동으로 생성해 준다. 또는 siteConfig에 headerLinks옵션에 doc : ‘MD파일 id’를 넣으면 링크를 생성해준다.

Markdown 상단에 위와 같은 값을 넣으면 Docusaurus가 알아서 페이지를 생성해준다 위에서 말한 ‘MD파일 id’가 위 이미지의 id이다.

Docusaurus는 기본적으로 BaseUrl/doc/*으로 접근하는 페이지들은 양쪽에 사이드바를 만들어준다. 원하는 문서들을 그루핑해서 사이드바를 만들 수 있는데, “그룹이름” 에 “제목” : [“파일1”, “파일2”]처럼 넣어서 만들 수 있다. 만약 [파일1, 파일2] 그룹과 [파일3,파일4]그룹을 만들고 헤더링크에서 각각 파일1과 파일3으로 가는 링크를 만들고 각각 클릭해보면 서로 다른 사이드바가 생김을 알 수 있다.

예를 들어 위처럼 만들고 헤더링크에 doc1과 doc4로 가는 링크를 만들고 각각 클릭해보면 두 종류의 사이드바가 위 문서들 사이에 생기는 것을 볼 수 있다.

5. Blog 포스팅하기.

Docusaurus는 blog기능도 제공한다. blog디렉토리 밑에 ‘yyyy-mm-dd-제목’형태의 Markdown 파일을 만들고, header Links에 {blog:true, label: “라벨이름”}을 넣으면 해당 버튼을 통해 블로그로 이동할 수 있다. 또는 index.js같은 원하는 페이지에서 링크를 만드려면 BaseURL/blog로 이동하면 된다.

6. Build

실제 배포를 하기위해 앱을 빌드하고 싶으면 npm run build 명령어를 실행하면 build 디렉토리 밑에 빌드된 파일들이 생성된다.

react-native-seoul

React Native community in Seoul

하성준

Written by

하성준

react-native-seoul

React Native community in Seoul

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade