메인 컨텐츠로 이동
Version: 2.0.0-beta.3

설치

Docusaurus is essentially a set of npm packages.

tip

패스트트랙에서 5분 ⏱안에 도큐사우루스를 이해할 수 있게 안내하고 있습니다!

Use docusaurus.new to test Docusaurus immediately in your browser!

요구 사항#

  • Node.js 12.13.0 이상 버전을 사용해야 합니다(node -v 명령어로 버전 정보를 확인할 수 있습니다). 여러 버전의 노드 설치가 필요하다면 nvm에서 관리할 수 있습니다.
  • Yarn 1.5 이상 버전을 사용해야 합니다(yarn --version 명령어로 버전 정보를 확인할 수 있습니다). Yarn은 npm 클라이언트를 대체할 수 있는 자바스크립트 패키지 관리자입니다. 꼭 필요한 건 아니지만 사용하는 것을 권장합니다.

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

도큐사우루스를 설치하는 가장 쉬운 방법은 웹사이트 프로젝트를 위한 뼈대를 만들어주는 명령행 도구를 사용하는 겁니다. 새로 만든 저장소 또는 기존에 사용하던 저장소 어디든 실행할 수 있으며 프로젝트를 위한 기본 파일을 포함한 새로운 디렉터리를 만듭니다.

npx @docusaurus/init@latest init [name] [template]

예를 들면 아래와 같이 설정합니다.

npx @docusaurus/init@latest init my-website classic

name이나 template 값을 설정하지 않으면 설치 중간에 물어봅니다. 도큐사우루스 1에서 사용하던 기능을 포함해 빠르게 시작하고 싶다면 classic 템플릿을 사용하는 것을 권장합니다. classic 템플릿은 기본 문서, 블로그, 커스텀 페이지, CSS 프레임워크(다크 모드 지원)을 포함한 @docusaurus/preset-classic을 제공합니다. classic 템플릿을 바로 적용해서 시작해볼 수 있습니다. 도큐사우루스에 익숙해지면 나중에 사용자 지정 템플릿을 반영할 수도 있습니다.

[FB-Only]: 페이스북 오픈소스 프로젝트를 위해 도큐사우루스 웹사이트를 설정해야 한다면 페이스북에서 설정한 기본값이 적용된 facebook 템플릿을 사용해야 합니다.

npx @docusaurus/init@latest init my-website facebook

[Experimental]: 새로운 웹사이트에 bootstrap을 적용하고 싶다면 아래와 같이 bootstrap 템플릿을 사용하세요.

npx @docusaurus/init@latest init my-website bootstrap

설치 시 의존성 체크를 건너뛰고 싶다면 --skip-install 옵션을 아래와 같이 사용하세요.

npx @docusaurus/init@latest init my-website classic --skip-install

프로젝트 구조#

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/ - 블로그에서 사용하는 마크다운 파일 디렉터리입니다. 블로그가 필요 없다면 해당 디렉터리를 삭제할 수 있습니다. 좀 더 자세한 내용은 blog 가이드에서 확인할 수 있습니다.
  • /docs/ - 문서에서 사용하는 마크다운 파일 디렉터리입니다. sidebars.js에서 사이드바에 표시되는 문서 순서를 변경할 수 있습니다. 좀 더 자세한 내용은 docs 가이드에서 확인할 수 있습니다.
  • /src/ - 페이지나 리액트 커스텀 컴포넌트처럼 문서 마크다운 파일이 아닌 파일 디렉터리입니다. 문서가 아닌 파일들을 꼭 여기에 가져다 놓아야 하는 건 아닙니다. 하지만 한곳에 모아놓으면 오류를 체크하거나 추가 작업이 필요할 때 좀 더 편하게 처리할 수 있습니다.
    • /src/pages - 웹사이트 페이지로 변환할 파일을 모아놓는 디렉터리입니다. 좀 더 자세한 내용은 pages 가이드에서 확인할 수 있습니다.
  • /static/ - 정적 파일 디렉터리입니다. 이곳에 있는 파일은 build 디렉토리의 루트 저장소로 복사됩니다.
  • /docusaurus.config.js - 사이트 설정이 저장된 설정 파일입니다. 도큐사우루스 v1에서 사용했던 siteConfig.js 파일과 같은 역할입니다.
  • /package.json - 도큐사우루스 웹사이트는 리액트 앱입니다. 앱 안에서 원하는 npm 패키지를 설치하고 사용할 수 있습니다.
  • /sidebar.js - 사이드바에 표시되는 문서의 순서를 조정할 때 사용합니다.

개발 서버 실행하기#

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

cd my-websitenpm run start

기본적으로 웹 브라우저에서 http://localhost:3000 주소를 실행합니다.

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

빌드#

도큐사우루스는 정적인 웹 사이트를 생성하는 도구입니다. 그래서 웹 사이트를 디렉터리 안에 생성하고 사용자가 접근할 수 있도록 웹 서버에 배치해주어야 합니다. 웹 사이트를 빌드하기 위해서는 아래 명령어를 사용합니다.

npm run build

콘텐츠는 /build 디렉터리 밑에 만들어지며 깃허브 페이지(GitHub pages), 베르셀(Vercel), 네트리파이(Netlify) 같은 정적 파일 호스팅 서비스에 복사할 수 있습니다. 좀 더 자세한 내용은 배포 문서를 참고하세요.

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

도큐사우루스 버전을 업데이트하는 방법은 여러가지가 있습니다. 확실한 방법은 package.json 파일 내 버전 번호를 원하는 버전으로 수정하는 겁니다. @docusaurus/ 네임스페이스 패키지는 모두 같은 버전을 사용해야 하는 것에 주의해주세요.

important

최신 도큐사우루스 2 버전은 사이트 상단에 표시되는 버전을 참고해주세요. 아래 설정은 예시일 뿐입니다.

package.json
"dependencies": {  "@docusaurus/core": "^2.0.0-beta.0",  "@docusaurus/preset-classic": "^2.0.0-beta.0",  // ...}

package.json 파일이 포함된 디렉터리에서 패키지 매니저 설치 명령을 실행합니다.

npm install

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

npx docusaurus --version

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

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

yarn upgrade @docusaurus/core@latest @docusaurus/preset-classic@latest
tip

@canary npm 배포 태그를 적용하면 공개되지 않은 새로운 도큐사우루스 기능을 사용할 수 있습니다.

설치에 문제가 있나요?#

Stack Overflow에 질문을 남기거나 우리가 운영하는 깃허브 저장소 또는 트위터에 질문을 남기셔도 괜찮습니다.