본문으로 건너뛰기

Docusaurus 사용 가이드

이 문서는 웰컴 모빌리티 문서 사이트의 Docusaurus 사용법을 정리한 가이드입니다.

📝 페이지 작성법​

기본 페이지 생성​

  1. docs 폴더에 새로운 Markdown 파일(.md)을 생성합니다.
  2. 파일명은 URL 경로가 됩니다 (예: my-page.md → /docs/my-page)

Front Matter 작성​

각 Markdown 파일 상단에 YAML 형식의 Front Matter를 작성합니다:

---
sidebar_position: 1
---

주요 옵션:

  • sidebar_position: 사이드바에서의 순서 (숫자가 작을수록 위에 표시)
  • title: 페이지 제목 (기본값은 파일명)
  • description: 페이지 설명 (SEO용)

Markdown 작성 예시​

---
sidebar_position: 1
---

# 페이지 제목

## 섹션 1

일반적인 Markdown 문법을 사용할 수 있습니다.


### 리스트

- 항목 1
- 항목 2
- 항목 3

📁 카테고리(폴더) 추가법​

1. 폴더 생성​

docs 폴더 하위에 새로운 폴더를 생성합니다.

예: docs/new-category/

2. 카테고리 설정 파일 생성​

해당 폴더에 _category_.json 파일을 생성합니다:

{
  "label": "카테고리 이름",
  "position": 1
}

설정 옵션:

  • label: 사이드바에 표시될 카테고리 이름
  • position: 사이드바에서의 순서 (숫자가 작을수록 위에 표시)

3. 페이지 파일 추가​

카테고리 폴더 안에 Markdown 파일들을 추가합니다.

예시 구조:

docs/
  new-category/
    _category_.json
    page1.md
    page2.md

🔧 사이드바 설정​

현재 프로젝트는 자동 생성 사이드바를 사용하고 있습니다.

자동 생성 사이드바​

sidebars.ts 파일에서 설정:

const sidebars: SidebarsConfig = {
  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
};

이 설정은 docs 폴더의 구조를 자동으로 사이드바에 반영합니다.

수동 사이드바 설정​

수동으로 사이드바를 구성하려면 sidebars.ts를 다음과 같이 수정:

const sidebars: SidebarsConfig = {
  tutorialSidebar: [
    'intro',
    {
      type: 'category',
      label: '카테고리 이름',
      items: ['category/page1', 'category/page2'],
    },
  ],
};

🎨 스타일 커스터마이징​

CSS 수정​

src/css/custom.css 파일에서 전역 스타일을 수정할 수 있습니다.

테마 설정​

docusaurus.config.ts의 themeConfig 섹션에서 테마를 설정합니다:

themeConfig: {
  colorMode: {
    disableSwitch: false,  // 다크모드 토글 표시 여부
    respectPrefersColorScheme: true,  // 시스템 설정 따르기
  },
  // ...
}

🚀 개발 서버 실행​

로컬 개발 서버 시작​

npm start

또는

yarn start

개발 서버는 http://localhost:3000에서 실행됩니다.

프로덕션 빌드​

npm run build

또는

yarn build

빌드 결과물은 build 폴더에 생성됩니다.

📋 파일 구조 예시​

docs/
  intro.md                    # 인트로 페이지
  web-front/                  # 웹 프론트엔드 카테고리
    _category_.json          # 카테고리 설정
    code-convention.md       # 페이지
  mobile-front/              # 모바일 프론트엔드 카테고리
    _category_.json
    code-convention.md
  backend/                   # 백엔드 카테고리
    _category_.json
    code-convention.md

💡 유용한 팁​

1. 페이지 순서 조정​

sidebar_position 값을 조정하여 페이지 순서를 변경합니다:

  • 작은 숫자일수록 위에 표시
  • 같은 숫자는 파일명 순서로 정렬

2. 링크 생성​

다른 페이지로 링크를 걸 때:

[링크 텍스트](./other-page)
[링크 텍스트](../parent-page)
[링크 텍스트](/docs/category/page)

3. 이미지 추가​

static/img/ 폴더에 이미지를 추가하고:

![이미지 설명](/img/image-name.png)

📚 추가 자료​

문의사항이나 문제가 있으면 개발팀에 문의해주세요.