설치
도큐사우루스는 npm 패키지로 구성되어 있습니다.
**패스트트랙**에서 5분 ⏱안에 도큐사우루스를 이해할 수 있게 안내하고 있습니다!
**docusaurus.new**에 접속하면 여러분의 웹 브라우저에서 도큐사우루스를 바로 테스트해볼 수 있습니다!
요구 사항
- Node.js 16.14 이상 버전을 사용해야 합니다(
node -v
명령어로 버전 정보를 확인할 수 있습니다). 여러 버전의 노드 설치가 필요하다면 nvm에서 관리할 수 있습니다.- Node.js 설치 시 종속성과 관련된 모든 확인란을 선택하는 것을 권장합니다.
웹사이트 프로젝트를 위한 뼈대 만들기
도큐사우루스를 설치하는 가장 쉬운 방법은 웹사이트 프로젝트를 위한 뼈대를 만들어주는 명령행 도구를 사용하는 겁니다. 새로 만든 저장소 또는 기존에 사용하던 저장소 어디든 실행할 수 있으며 프로젝트를 위한 기본 파일을 포함한 새로운 디렉터리를 만듭니다.
npx create-docusaurus@latest my-website classic
도큐사우루스 1에서 사용하던 기능을 포함해 빠르게 시작하고 싶다면 classic
템플릿을 사용하는 것을 권장합니다. classic
템플릿은 기본 문서, 블로그, 커스텀 페이지, CSS 프레임워크(다크 모드 지원)을 포함한 @docusaurus/preset-classic
을 제공합니다. classic 템플릿을 바로 적용해서 시작해볼 수 있습니다. 도큐사우루스에 익숙해지면 나중에 사용자 지정 템플릿을 반영할 수도 있습니다.
--typescript
플래그를 사용해 템플릿의 타입스크립트 변형을 사용할 수도 있습니다. 좀 더 많은 정보는 타입스크립트 지원을 참고하세요.
npx create-docusaurus@latest my-website classic --typescript
페이스북 오픈소스 프로젝트를 위해 도큐사우루스 웹사이트를 설정해야 한다면 페이스북에서 설정한 기본값이 적용된 facebook
템플릿을 사용해야 합니다.
npx create-docusaurus@latest my-website facebook
대체할 수 있는 설치 명령
원하는 프로젝트 관리자를 사용해 새로운 프로젝트를 초기화할 수 있습니다.
- npm
- yarn
- pnpm
npm init docusaurus
yarn create docusaurus
pnpm create 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/
- 블로그에서 사용하는 마크다운 파일 디렉터리입니다. 블로그 플러그인을 비활성화한 경우 디렉토리를 삭제하거나path
옵션을 설정한 후 이름을 변경할 수 있습니다. 좀 더 자세한 내용은 blog 가이드에서 확인할 수 있습니다./docs/
- 문서에서 사용하는 마크다운 파일 디렉터리입니다.sidebars.js
에서 사이드바에 표시되는 문서 순서를 변경할 수 있습니다. 문서 플러그인을 비활성화한 경우 디렉토리를 삭제하거나path
옵션을 설정한 후 이름을 변경할 수 있습니다. 좀 더 자세한 내용은 docs 가이드에서 확인할 수 있습니다./src/
- 페이지나 리액트 커스텀 컴포넌트처럼 문서 마크다운 파일이 아닌 파일 디렉터리입니다. 문서가 아닌 파일들을 꼭 여기에 가져다 놓아야 하는 건 아닙니다. 하지만 한곳에 모아놓으면 오류를 체크하거나 추가 작업이 필요할 때 좀 더 편하게 처리할 수 있습니다./src/pages
- 웹사이트 페이지로 변환할 JSX/TSX/MDX 파일을 모아놓는 디렉터리입니다. 좀 더 자세한 내용은 pages 가이드에서 확인할 수 있습니다.
/static/
- 정적 파일 디렉터리입니다. 이곳에 있는 파일은build
디렉토리의 루트 저장소로 복사됩니다./docusaurus.config.js
- 사이트 설정이 저장된 설정 파일입니다. 도큐사우루스 v1에서 사용했던siteConfig.js
파일과 같은 역할입니다./package.json
- 도큐사우루스 웹사이트는 리액트 앱입니다. 앱 안에서 원하는 npm 패키지를 설치하고 사용할 수 있습니다./sidebars.js
- 사이드바에 표시되는 문서의 순서를 조정할 때 사용합니다.
단일 저장소
기존 프로젝트 문서화에 도큐사우루스를 사용하는 경우에는 단일 저장소가 해결책이 될 수 있습니다. 단일 저장소를 사용하면 비슷한 프로젝트 사이에 종속성을 공유할 수 있습니다. 예를 들어 여러분의 웹사이트가 릴리스된 버전에 의존하는 대신 로컬 패키지를 사용해 최신 기능을 선보일 수 있습니다. 콘텐츠 작성자는 기능 구현 시 문서를 손쉽게 업데이트할 수 있습니다. 예를 들어 단일 저장소의 폴더 구조는 다음과 같습니다.
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
입니다. 문서 배포 항목에서 ignore 명령 관련 설정을 확인할 수 있습니다.
Yarn 문서(Yarn이 단일 저장소를 설정하는 유일한 방법은 아니지만 일반적인 솔루션입니다)에서 단일 저장소에 대해 좀 더 알아보세요. 또는 도큐사우루스와 Jest에서 몇 가지 사례를 살펴보세요.