설치
Docusaurus is essentially a set of npm packages.
Use the Fast Track to understand Docusaurus in 5 minutes ⏱!
Use docusaurus.new to test Docusaurus immediately in your browser!
Requirements
- Node.js version 16.14 or above (which can be checked by running
node -v
). You can use nvm for managing multiple Node versions on a single machine installed.- Node.js 설치 시 종속성과 관련된 모든 확인란을 선택하는 것을 권장합니다.
Scaffold project website
도큐사우루스를 설치하는 가장 쉬운 방법은 웹사이트 프로젝트를 위한 뼈대를 만들어주는 명령행 도구를 사용하는 겁니다. 새로 만든 저장소 또는 기존에 사용하던 저장소 어디든 실행할 수 있으며 프로젝트를 위한 기본 파일을 포함한 새로운 디렉터리를 만듭니다.
npx create-docusaurus@latest my-website classic
We recommend the classic
template so that you can get started quickly, and it contains features found in Docusaurus 1. The classic
template contains @docusaurus/preset-classic
which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support). classic 템플릿을 바로 적용해서 시작해볼 수 있습니다. 도큐사우루스에 익숙해지면 나중에 사용자 지정 템플릿을 반영할 수도 있습니다.
You can also use the template's TypeScript variant by passing the --typescript
flag. See TypeScript support for more information.
npx create-docusaurus@latest my-website classic --typescript
If you are setting up a new Docusaurus website for a Facebook open source project, use the facebook
template instead, which comes with some useful Facebook-specific defaults:
npx create-docusaurus@latest my-website facebook
Alternative installation commands
원하는 프로젝트 관리자를 사용해 새로운 프로젝트를 초기화할 수 있습니다.
- npm
- Yarn
- pnpm
npm init docusaurus
yarn create docusaurus
pnpm create docusaurus
Run npx create-docusaurus@latest --help
, or check out its API docs for more information about all available flags.
Project structure
Assuming you chose the classic template and named your site my-website
, you will see the following files generated under a new directory 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
Project structure rundown
/blog/
- Contains the blog Markdown files. You can delete the directory if you've disabled the blog plugin, or you can change its name after setting thepath
option. More details can be found in the blog guide/docs/
- Contains the Markdown files for the docs. Customize the order of the docs sidebar insidebars.js
. You can delete the directory if you've disabled the docs plugin, or you can change its name after setting thepath
option. More details can be found in the docs guide/src/
- Non-documentation files like pages or custom React components. 문서가 아닌 파일들을 꼭 여기에 가져다 놓아야 하는 건 아닙니다. 하지만 한곳에 모아놓으면 오류를 체크하거나 추가 작업이 필요할 때 좀 더 편하게 처리할 수 있습니다./src/pages
- Any JSX/TSX/MDX file within this directory will be converted into a website page. More details can be found in the pages guide
/static/
- Static directory. Any contents inside here will be copied into the root of the finalbuild
directory/docusaurus.config.js
- A config file containing the site configuration. This is the equivalent ofsiteConfig.js
in Docusaurus v1/package.json
- A Docusaurus website is a React app. 앱 안에서 원하는 npm 패키지를 설치하고 사용할 수 있습니다./sidebars.js
- Used by the documentation to specify the order of documents in the sidebar
Monorepos
기존 프로젝트 문서화에 도큐사우루스를 사용하는 경우에는 단일 저장소가 해결책이 될 수 있습니다. 단일 저장소를 사용하면 비슷한 프로젝트 사이에 종속성을 공유할 수 있습니다. 예를 들어 여러분의 웹사이트가 릴리스된 버전에 의존하는 대신 로컬 패키지를 사용해 최신 기능을 선보일 수 있습니다. 콘텐츠 작성자는 기능 구현 시 문서를 손쉽게 업데이트할 수 있습니다. 예를 들어 단일 저장소의 폴더 구조는 다음과 같습니다.
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
In this case, you should run npx create-docusaurus
within the ./my-monorepo
folder.
If you're using a hosting provider such as Netlify or Vercel, you will need to change the Base directory
of the site to where your Docusaurus root is. In this case, that would be ./website
. Read more about configuring ignore commands in the deployment docs.
Read more about monorepos in the Yarn documentation (Yarn is not the only way to set up a monorepo, but it's a common solution), or checkout Docusaurus and Jest for some real-world examples.
Running the development server
편집한 내용을 미리보고 싶다면 로컬 개발 서버를 실행해야 합니다. 로컬 개발 서버를 통해 웹 사이트를 확인하고 마지막으로 변경된 내용을 반영해볼 수 있습니다.
- npm
- Yarn
- pnpm
cd my-website
npm run start
cd my-website
yarn run start
cd my-website
pnpm run start
By default, a browser window will open at http://localhost:3000
.
축하합니다! 여러분은 첫 번째 도큐사우루스 사이트를 방금 만들었습니다. 실행된 사이트를 둘러보고 어떤 콘텐츠가 만들어졌는지 확인해보세요.
Build
도큐사우루스는 정적인 웹 사이트를 생성하는 도구입니다. 그래서 웹 사이트를 디렉터리 안에 생성하고 사용자가 접근할 수 있도록 웹 서버에 배치해주어야 합니다. 웹 사이트를 빌드하기 위해서는 아래 명령어를 사용합니다.
- npm
- Yarn
- pnpm
npm run build
yarn build
pnpm run build
and contents will be generated within the /build
directory, which can be copied to any static file hosting service like GitHub pages, Vercel or Netlify. Check out the docs on deployment for more details.
Updating your Docusaurus version
도큐사우루스 버전을 업데이트하는 방법은 여러가지가 있습니다. One guaranteed way is to manually change the version number in package.json
to the desired version. Note that all @docusaurus/
-namespaced packages should be using the same version.
오래된 버전의 문서를 탐색중입니다. 아래 스니펫은 최신 버전으로 업그레이드하는 방법을 보여줍니다.
{
"dependencies": {
"@docusaurus/core": "3.6.3",
"@docusaurus/preset-classic": "3.6.3",
// ...
}
}
Then, in the directory containing package.json
, run your package manager's install command:
- npm
- Yarn
- pnpm
npm install
yarn install
pnpm install
업데이트가 정상적으로 처리되었는지는 아래 명령으로 확인해볼 수 있습니다.
npx docusaurus --version
올바른 버전이 출력되어야 합니다.
Yarn을 사용하는 경우는 아래와 같이 업데이트할 수 있습니다.
yarn upgrade @docusaurus/core@latest @docusaurus/preset-classic@latest
Use new unreleased features of Docusaurus with the @canary
npm dist tag
설치에 문제가 있나요?
Ask for help on Stack Overflow, on our GitHub repository, our Discord server, or X.