Skip to main content
버전: 3.10.2

설치

도큐사우루스는 여러 npm 패키지로 구성되어 있습니다.

팁

**빠른 시작**을 따라 5분 ⏱ 만에 도큐사우루스를 익혀 보세요!

**docusaurus.new**에서 브라우저로 도큐사우루스를 바로 테스트해 보세요!

요구 사항​

  • Node.js version 20.0 or above (which can be checked by running node -v). nvm을 사용하면 한 컴퓨터에서 여러 Node.js 버전을 관리할 수 있습니다.
    • Node.js 설치 시 종속성과 관련된 모든 체크박스 선택을 권장합니다.

웹사이트 프로젝트를 위한 뼈대 만들기​

도큐사우루스를 가장 쉽게 설치하는 방법은 도큐사우루스 웹사이트의 기본 구조를 생성해 주는 create-docusaurus 명령줄 도구를 사용하는 것입니다. 새로 만든 저장소 또는 기존에 사용하던 저장소 어디든 실행할 수 있으며 프로젝트를 위한 기본 파일을 포함한 새로운 디렉터리를 만듭니다.

npx create-docusaurus@latest my-website classic

빠르게 시작할 수 있도록 classic 템플릿을 권장하며, 이 템플릿에는 도큐사우루스 1의 기능이 포함되어 있습니다. classic 템플릿에는 표준 문서 기능, 블로그, 사용자 지정 페이지, CSS 프레임워크(다크 모드 지원)를 포함하는 @docusaurus/preset-classic이 들어 있습니다. classic 템플릿을 바로 적용해서 시작해볼 수 있습니다. 도큐사우루스에 익숙해지면 나중에 사용자 지정 템플릿을 반영할 수도 있습니다.

--typescript 플래그를 전달하면 템플릿의 TypeScript 버전도 사용할 수 있습니다. 자세한 내용은 TypeScript 지원을 참고하세요.

npx create-docusaurus@latest my-website classic --typescript
Meta 전용

메타 오픈 소스 프로젝트를 위해 도큐사우루스 웹사이트를 설정하는 경우 내부 저장소에서 이 명령을 실행하면 몇 가지 유용한 메타 관련 기본값이 제공됩니다.

scarf static-docs-bootstrap
다른 설치 명령어

원하는 프로젝트 관리자를 사용해 새로운 프로젝트를 초기화할 수 있습니다.

npm init docusaurus

사용 가능한 모든 플래그에 대해 자세히 알아보려면 npx create-docusaurus@latest --help를 실행하거나 API 문서를 확인하세요.

프로젝트 구조​

선택한 템플릿이 classic이고 사이트 이름을 my-website로 지정했다면, 새 my-website/ 디렉터리 아래에 다음 파일이 생성된 것을 볼 수 있습니다:

my-website
├── blog
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

프로젝트 구조 요약​

  • /blog/ - 블로그 Markdown 파일이 들어 있습니다. 블로그 플러그인을 비활성화했다면 디렉터리를 삭제할 수 있으며, path 옵션을 설정한 뒤에는 디렉터리 이름을 변경할 수 있습니다. 자세한 내용은 블로그 가이드에서 확인할 수 있습니다
  • /docs/ - 문서용 Markdown 파일이 들어 있습니다. sidebars.js에서 사이드바에 표시되는 문서의 순서를 원하는 대로 지정하세요. 문서 플러그인을 비활성화했다면 디렉터리를 삭제할 수 있으며, path 옵션을 설정한 뒤에는 디렉터리 이름을 변경할 수 있습니다. 자세한 내용은 문서 가이드에서 확인할 수 있습니다
  • /src/ - 페이지나 사용자 지정 React 컴포넌트 등 문서 이외의 파일이 들어 있습니다. 문서가 아닌 파일들을 꼭 여기에 가져다 놓아야 하는 건 아닙니다. 하지만 한곳에 모아놓으면 오류를 체크하거나 추가 작업이 필요할 때 좀 더 편하게 처리할 수 있습니다.
    • /src/pages - 이 디렉터리 안의 모든 JSX/TSX/MDX 파일은 웹사이트 페이지로 변환됩니다. 자세한 내용은 페이지 가이드에서 확인할 수 있습니다
  • /static/ - 정적 파일 디렉터리입니다. 여기에 있는 모든 콘텐츠는 최종 build 디렉터리의 루트로 복사됩니다
  • /docusaurus.config.js - 사이트 설정이 담긴 설정 파일입니다. 도큐사우루스 v1의 siteConfig.js에 해당합니다
  • /package.json - 도큐사우루스 웹사이트는 React 앱입니다. You can install and use any npm packages you like in it.
  • /sidebars.js - 문서가 사이드바에 표시되는 순서를 지정하는 데 사용합니다

단일 저장소​

기존 프로젝트 문서화에 도큐사우루스를 사용하는 경우에는 단일 저장소가 해결책이 될 수 있습니다. 단일 저장소를 사용하면 비슷한 프로젝트 사이에 종속성을 공유할 수 있습니다. 예를 들어, 웹사이트는 출시 버전에 의존하지 않고 로컬 패키지를 사용하여 최신 기능을 선보일 수 있습니다. 그러면 기여자들은(contributors) 기능을 구현하면서 문서를 업데이트할 수 있습니다. 예를 들어 단일 저장소의 폴더 구조는 다음과 같습니다.

my-monorepo
├── package-a # Another package, your actual project
│   ├── src
│   └── package.json # Package A's dependencies
├── website   # Docusaurus root
│   ├── docs
│   ├── src
│   └── package.json # Docusaurus' dependencies
├── package.json # Monorepo's shared dependencies

이 경우 ./my-monorepo 폴더 안에서 npx create-docusaurus를 실행해야 합니다.

Netlify나 Vercel 같은 호스팅 제공업체를 사용한다면 사이트의 Base directory를 도큐사우루스 루트 위치로 변경해야 합니다. 이 경우에는 ./website가 됩니다. Read more about configuring ignore commands in the deployment docs.

모노레포에 관해서는 Yarn 문서에서 자세히 알아보거나 (Yarn이 모노레포를 구성하는 유일한 방법은 아니지만 흔히 쓰이는 방법입니다), 실제 사례를 보려면 도큐사우루스와 Jest를 살펴보세요.

개발 서버 실행하기​

편집한 내용을 미리보고 싶다면 로컬 개발 서버를 실행해야 합니다. 로컬 개발 서버를 통해 웹 사이트를 확인하고 마지막으로 변경된 내용을 반영해볼 수 있습니다.

cd my-website
npm run start

기본적으로 브라우저 창에서 http://localhost:3000이 열립니다.

축하합니다! 여러분은 첫 번째 도큐사우루스 사이트를 방금 만들었습니다. 실행된 사이트를 둘러보고 어떤 콘텐츠가 만들어졌는지 확인해보세요.

빌드​

도큐사우루스는 현대적인 정적 웹사이트 생성기이므로, 웹사이트를 볼 수 있도록 정적 콘텐츠가 담긴 디렉터리로 빌드한 뒤 웹 서버에 올려야 합니다. 웹 사이트를 빌드하기 위해서는 아래 명령어를 사용합니다.

npm run build

그러면 콘텐츠가 /build 디렉터리 안에 생성되며, 이를 GitHub pages, Vercel 또는 Netlify 같은 정적 파일 호스팅 서비스에 복사할 수 있습니다. Check out the docs on deployment for more details.

도큐사우루스 버전 업데이트하기​

도큐사우루스 버전을 업데이트하는 방법은 여러가지가 있습니다. 확실한 방법 하나는 package.json의 버전 번호를 원하는 버전으로 직접 변경하는 것입니다. @docusaurus/ 네임스페이스에 속한 모든 패키지는 같은 버전을 사용해야 한다는 점에 유의하세요.

package.json
{
  "dependencies": {
    "@docusaurus/core": "3.10.2",
    "@docusaurus/preset-classic": "3.10.2",
    // ...
  }
}

그런 다음, package.json이 있는 디렉터리에서 사용하는 패키지 관리자의 설치 명령을 실행하세요:

npm install
팁

npm install은 여러 취약점을 보고하고 이를 해결하기 위해 npm audit 실행을 권장할 수 있습니다. 보통 RegExp DOS와 같이 이미 보고된 취약점들은 문제가 없으므로 무시해도 됩니다. 저희의 생각을 담은 다음 글도 읽어보세요: npm audit: 설계부터 잘못됐다.

업데이트가 정상적으로 처리되었는지는 아래 명령으로 확인해볼 수 있습니다.

npx docusaurus --version

올바른 버전이 출력되어야 합니다.

Yarn을 사용하는 경우는 아래와 같이 업데이트할 수 있습니다.

yarn add @docusaurus/core @docusaurus/preset-classic
팁

@canary npm 배포 태그를 통해 아직 출시되지 않은 도큐사우루스의 새로운 기능을 사용해 보세요

설치에 문제가 있나요?​

Stack Overflow, 저희 GitHub 저장소, Discord 서버 또는 X에서 도움을 요청하세요.