[GitHub Pages 배포기] React 컴포넌트 라이브러리 문서화하고 배포하기

"만든 라이브러리를 어떻게 문서화하고 배포해야 할까?"라이브러리를 만들고 나니, 이걸 어떻게 사용자들에게 설명해야 할지 고민이 되었다. README 파일로 설명하기엔 한계가 있고, 제대로 된 문서 사이트가 필요하다는 생각이 들었다. 그리고 이왕 만드는 거 GitHub Pages로 배포해서 누구나 쉽게 접근할 수 있게 하고 싶었다. Docusaurus가 React 문서화에 좋다고 해서 이걸로 해보자고 마음먹었다.

1. 문서화 환경 설정

먼저 Docusaurus를 설치했다.

 

npx create-docusaurus@latest react-components-docs classic
cd react-components-docs

기본 구조가 생성되었는데, 한국어로 문서를 작성하고 싶어서 설정 파일부터 수정했다.

// docusaurus.config.js
module.exports = {
  // ...
  i18n: {
    defaultLocale: 'ko',
    locales: ['ko'],
  },
  // ...
}

2. 컴포넌트 문서 작성하기

src/docs/components 폴더에 각 컴포넌트별 문서를 마크다운으로 작성했다. 아코디언 컴포넌트부터 시작했다.

import { Accordion } from 'react-common-components-library';

function AccordionExample() {
  const items = [
    { id: '1', title: '섹션 1', content: '첫 번째 섹션 내용입니다.' },
    { id: '2', title: '섹션 2', content: '두 번째 섹션 내용입니다.' },
  ];
  
  return <Accordion items={items} />;
}

3. 사이드바 설정

컴포넌트 문서가 늘어나니 사이드바 설정이 필요했다.

 

// sidebars.js
const sidebars = {
  tutorialSidebar: [
    {
      type: 'category',
      label: '시작하기',
      items: ['intro', 'installation'],
    },
    {
      type: 'category',
      label: '컴포넌트',
      items: [
        'components/accordion',
        'components/dialog',
        'components/dropdown-menu',
        // 나중에 추가한 컴포넌트들
        'components/alert-dialog',
        'components/aspect-ratio',
        'components/avatar',
        'components/button',
        'components/checkbox',
        'components/collapsible',
        'components/command',
        'components/context-menu',
      ],
    },
  ],
};

 

4. 로고와 파비콘 만들기

문서 사이트의 정체성을 위해 로고와 파비콘이 필요했다. SVG로 간단하게 만들어봤다.

 

5. GitHub Pages 배포 설정

드디어 배포 단계. GitHub Pages로 배포하려면 설정을 수정해야 했다.

 

// docusaurus.config.js
const config = {
  title: 'React Common Components Library',
  tagline: '모던하고 접근성 높은 React 컴포넌트 라이브러리',
  
  // 배포 URL 설정
  url: 'https://kyunghoonkook.github.io',
  baseUrl: '/',
  
  // GitHub pages 배포 설정
  organizationName: 'kyunghoonkook', // GitHub 사용자명
  projectName: 'kyunghoonkook.github.io', // GitHub Pages 저장소 이름
  trailingSlash: false,
  deploymentBranch: 'main', // GitHub Pages 배포 브랜치
  
  // ...
};

처음에는 baseUrl을 '/react-components-library/'로 설정했다가, 루트 도메인에 배포하려고 '/'로 바꿨다. 이 부분에서 꽤 헤맸는데, URL 경로가 맞지 않으면 배포해도 404 에러가 발생했다.

6. 빌드 및 배포

이제 빌드하고 배포할 차례였다.

 

막상 배포해보니 문제가 생겼다. 경로 문제였는데, 설정이 안 맞았다. 한참을 검색하다가 깨달은 건 GitHub Pages 배포에서는 projectName과 실제 저장소 이름이 일치해야 한다는 것이었다. 그래서 다시 설정을 수정했다.

 

// 수정한 설정
organizationName: 'kyunghoonkook',  // GitHub 사용자명 
projectName: 'kyunghoonkook.github.io',  // 저장소 이름
deploymentBranch: 'main',

 

이렇게 바꾸고 다시 배포하니 드디어 성공했다! https://kyunghoonkook.github.io/ 에서 문서가 제대로 보였다.

7. 메인 페이지 꾸미기

문서 사이트가 만들어졌으니 메인 페이지도 예쁘게 꾸미고 싶었다. src/pages/index.js를 수정했다.

 

// src/pages/index.js
function HomepageHeader() {
  const {siteConfig} = useDocusaurusContext();
  return (
    <header className={clsx('hero hero--primary', styles.heroBanner)}>
      <div className="container">
        <div className={styles.logoContainer}>
          <img src="img/logo.svg" alt="React Common Components Logo" className={styles.logo} />
        </div>
        <h1 className="hero__title">{siteConfig.title}</h1>
        <p className="hero__subtitle">{siteConfig.tagline}</p>
        <div className={styles.buttons}>
          <Link
            className="button button--secondary button--lg"
            to="/docs/intro">
            시작하기
          </Link>
        </div>
      </div>
    </header>
  );
}

CSS도 추가해서 로고가 부드럽게 나타나는 애니메이션을 넣었다.

 

 

배운 점

이번에 문서화와 배포를 하면서 많은 걸 배웠다.

문서화의 중요성: 아무리 좋은 라이브러리도 사용법을 모르면 소용없다. 문서화는 사용자 경험의 핵심이다.
Docusaurus의 편리함: 마크다운으로 쉽게 문서를 작성하고, React로 커스텀할 수 있어서 좋았다.
GitHub Pages 설정의 미묘함: URL 설정과 저장소 이름이 맞아야 한다는 점을 깨달았다.
로고와 브랜딩의 가치: 간단한 로고와 통일된 색상만으로도 전문적인 느낌이 크게 달라진다.

다음에는 검색 기능을 추가하고, 각 컴포넌트에 라이브 데모를 넣어볼 생각이다. 또한 다국어 지원도 고려해봐야겠다. 이렇게 기록하고 보니, 문서화와 배포도 개발 과정의 중요한 부분이란 걸 다시 한번 느낀다.