Docusaurus 문서 생성 도구

Docusaurus는 Meta(구 페이스북)의 문서 생성 도구로 주로 OSS 매뉴얼이나 공지 등의 블로그를 관리하는데 사용된다.
Tags:

docusaurus

Docusaurus란?

Docusaurus는 Facebook에서 만든 오픈 소스 프로젝트로, 정적 웹사이트를 만들기 위한 도구이다. 특히 개발자들이 기술 문서를 작성하고 호스팅하는 데 사용되고 있다. Docusaurus는 React를 기반으로 한 사용자 친화적인 문서화 도구이며, Markdown을 사용하여 쉽게 문서를 작성할 수 있다.

Docusaurus의 주요 특징은 다음과 같다:

  • 사용자 친화적인 문서화
    • Markdown을 사용하여 쉽게 문서를 작성할 수 있다.
    • 또한 사용자 정의 가능한 레이아웃과 테마를 제공하여 문서의 시각적인 디자인을 개선할 수 있다.
    • Markdown 뿐만 아니라 JSX를 포함한 MDX ​​문서도 작성할 수 있다.
  • 검색 기능
    • Docusaurus는 강력한 검색 기능을 제공하여 사용자가 쉽게 원하는 정보를 찾을 수 있도록 돕습니다.
    • Algolia와 협력하여 쉽게 검색 기능을 추가할 수 있다.
  • 반응형 디자인
    • 모바일 및 데스크톱 디바이스에서도 잘 작동하도록 반응형 디자인이 구현되어 있다.
  • 다국어 지원
    • 다국어 문서 작성을 위한 지원이 내장되어 있어 글로벌 사용자들에게 다양한 언어로 문서를 제공할 수 있다.
    • 다국어 대응(현지화)도 가능하다.
  • 플러그인 시스템
    • Docusaurus는 확장성을 높이기 위한 플러그인 시스템을 제공하여 필요에 맞게 기능을 추가하고 확장할 수 있다.
  • 그밖에
    • 생성된 문서(사이트)는 React에서 작동하며 커스터마이징 할 수 있다.
    • 문서 버전 관리가 가능하며 제품 버전에 맞는 문서를 제공할 수 있다.

Docusaurus는 많은 개발자들이 자신의 프로젝트나 제품의 문서화에 사용하고 있으며, 커뮤니티에서 활발하게 유지보수되고 있다.

환경

다음과 같은 환경에서 검증하고 있다.

% sw_vers
ProductName:		macOS
ProductVersion:		14.2.1
BuildVersion:		23C71

% node -v
v21.6.2

% npx -v
10.2.4

npx 설치 하기

Docusaurus는 npx로 설치를 해야 한다. 혹시 없다면 설치를 하자.

설치 방법은 아래와 같다.

npm install npx -g

npx는 npm 레지스트리에 있는 패키지를 더 쉽게 설치하고 관리하도록 도와주는 CLI(Command-line interface) 도구이다.

  • npm: Package Manager (관리)
  • npx: Package Runner (실행)

프로젝트 만들기

Docusaurus에 대한 프로젝트 생성에는 Scaffold 명령이 제공되므로 이를 사용하기 쉽다. 명령은 다음 형식으로 실행된다.

$ npx @docusaurus/init@latest init [siteName] [template] [rootDir]

template은 classic과 facebook을 선택할 수 있다. 기본적으로 classic으로 괜찮고, facebook을 선택하면 Facebook open source project용 로고가 설정되어 있다.

그럼 실행해 보겠다.

$ cd /path/to/working
$ npx @docusaurus/init@latest init devkuma-mysite classic

설치가 완료하면 아래와 같이 표시 된다.

Successfully created "devkuma-mysite".
Inside that directory, you can run several commands:

  npm start
    Starts the development server.

  npm run build
    Bundles your website into static files for production.

  npm run serve
    Serves the built website locally.

  npm deploy
    Publishes the website to GitHub pages.

We recommend that you begin by typing:

  cd devkuma-mysite
  npm start

Happy building awesome websites!

디렉터리 구조

설치가 완료되고, 설치된 경로로 이동해서, 기본 명령어로 생성된 파일을 확인해 보자.

$ cd devkuma-mysite

생성되는 Docusaurus의 디렉터리 구조는 다음과 같다.

% tree -I node_modules -L 2
.
├── README.md
├── babel.config.js
├── blog
│   ├── 2019-05-28-first-blog-post.md
│   ├── 2019-05-29-long-blog-post.md
│   ├── 2021-08-01-mdx-blog-post.mdx
│   ├── 2021-08-26-welcome
│   └── authors.yml
├── docs
│   ├── intro.md
│   ├── tutorial-basics
│   └── tutorial-extras
├── docusaurus.config.js
├── package-lock.json
├── package.json
├── sidebars.js
├── src
│   ├── components
│   ├── css
│   └── pages
└── static
    └── img

11 directories, 11 files
  • blog/
    • 블로그용 Markdown 문서가 저장되는 디렉터리이다.
  • docs/
    • 문서용 Markdown 문서가 저장되는 디렉터리이다.
    • 사이드바에 나타나는 문서의 순서는 sidebar.js 에서 설정할 수 있다.
  • src/
    • 페이지 설정이나 React 컴포넌트의 기능 및 스타일링을 커스터마이징할 수 있는 소스 디렉터리이다.
  • src/pages/
    • 웹페이지로 변환되는 콘텐츠이다.
  • static/
  • 정적인 파일이 위치되는 곳으로, 이곳에 있는 파일들은 빌드시에 build 디렉토리로 복사된다.
  • 즉, 배포 후에는 /img/some-image.jpg 등으로 static 파일에 접근할 수 있다.
  • docusaurus.config.js
    • docusaurus 사이트의 설정 파일이다. 테마 설정, preset, plugin 등등을 모두 설정할 수 있다.
  • sidebars.js
    • 문서 페이지에 나타나는 사이드 바의 순서를 명시하는 파일이다.
    • 이를 docusaurus.config.js 에서 불러와서 presets 또는 plugin 에 설정하는 방식으로 사용한다.

문서 용도라면, docs/, docusaurus.config.js, sidebar.js에 주로 수정하게 되는 파일이라고 할 수 있다.

브라우저에서 확인하면서 커스터마이징 해보기

프로젝트가 생성되면 바로 사이트를 실행하여 확인할 수 있다. 다음 명령어를 실행하면 자동으로 브라우저도 열린다. 또한, 파일을 수정하면 자동으로 브라우저를 다시 불러오기 때문에 수정한 부분을 쉽게 확인할 수 있다.

$ npm start

또는 아래 명령어 실행된다.

$ npx docusaurus start

docusaurus My Site

첫 페이지 변경하기

연습을 위해 첫 페이지에 헤더 부분을 지워보자. src/pages/index.js가 해당 파일인데, React 컴포넌트로 만들어졌기 때문에 커스터마이징을 위해서는 약간의 지식이 필요할 것 같다.

src/pages/index.js

export default function Home() {
  const {siteConfig} = useDocusaurusContext();
  return (
    <Layout
      title={`Hello from ${siteConfig.title}`}
      description="Description will go into a meta tag in <head />">
      {/* <HomepageHeader /> */}
      <main>
        <HomepageFeatures />
      </main>
    </Layout>
  );
}

<HomepageHeader /> 여기를 코멘트 처리를 하였다.

docusaurus My Site

사라졌다!

사이트 헤더에서 Blog로의 링크 변경하기

그런 다음 사이트 헤더에 설치된 블로그에 대한 링크를 지워보겠다. 헤더는 개별 페이지가 아닌 테마로 취급하는 부분다. 테마 설정이 docusaurus.config.js되어 있기 때문에 이 파일을 수정합니다.

이어서 사이트 헤더에 설치된 블로그 링크를 삭제해보겠다. 헤더는 개별 페이지가 아닌 테마에서 다루는 부분이다. 테마 설정은 docusaurus.config.js에서 이루어지므로 이 파일을 수정하겠다.

docusaurus.config.js

        items: [
          {
            type: 'doc',
            docId: 'intro',
            position: 'left',
            label: 'Tutorial',
          },
          // {to: '/blog', label: 'Blog', position: 'left'},
          {
            href: 'https://github.com/facebook/docusaurus',
            label: 'GitHub',
            position: 'right',
          },

themeConfig.navbar.items[]에서 Blog로 이동하는 네비게이션을 코멘트를 하니까 헤더 메뉴에서 사라진 것을 볼 수 있다.

docusaurus My Site

사이드 바 메뉴 확인

사이드 바 메뉴 파일을 확인 하자.

sidebar.js

module.exports = {
  // By default, Docusaurus generates a sidebar from the docs folder structure
  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],

  // But you can create a sidebar manually
  /*
  tutorialSidebar: [
    {
      type: 'category',
      label: 'Tutorial',
      items: ['hello'],
    },
  ],
   */
};

“기본적으로 다큐사우루스는 문서 폴더 구조에서 사이드바를 생성한다고 적혀 있다.” 코멘트가 적혀 있고, 그 아래에 “하지만 수동으로 사이드바를 만들 수 있다.“라고 적혀 있다. 현재 설정은 자동으로 되어 있는거 같다.

마무리

비교적 사용 방법은 어렵지 않은거 같다. 데모 페이지에서 튜토리얼 내용이 있는데, 다음에는 이 내용에 대해서 살펴보도록 하겠다.




최종 수정 : 2024-04-15