CLI(명령 줄 인터페이스)

도큐사우루스는 여러분의 웹 사이트를 만들고 확인하고 배포할 수 있게 도움을 주는 스크립트 모음을 제공합니다.

웹 사이트를 만들면 소스 안에 패키지 관리자를 호출할 수 있는 도큐사우루스 스크립트가 포함되어 있습니다.

package.json

{
  // ...
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy",
    "clear": "docusaurus clear",
    "serve": "docusaurus serve",
    "write-translations": "docusaurus write-translations",
    "write-heading-ids": "docusaurus write-heading-ids"
  }
}

도큐사우루스 CLI 명령

도큐사우루스 CLI 명령과 사용법을 설명합니다.

docusaurus start [siteDir]

Webpack Dev Server를 사용해 로컬에서 사이트 미리보기를 빌드하고 제공합니다.

옵션

옵션명	기본값	설명
--port	3000	개발 서버에서 사용할 포트를 설정합니다.
--host	localhost	사용할 호스트를 설정합니다. 예를 들어 외부에서 서버에 접근할 수 있도록 하려면 --host 0.0.0.0을 사용할 수 있습니다.
--locale		사용할 사이트 로케일을 지정합니다.
--hot-only	false	빌드 실패 시 폴백 처리로 페이지 새로고침 없이 빠른 모듈 교체(Hot Module Replacement)를 사용할지 여부를 설정합니다. 자세한 내용은 여기를 참고하세요.
--no-open	false	브라우저에서 페이지를 자동으로 열지 않습니다.
--config	undefined	도큐사우루스 설정 파일의 경로입니다. 기본값은 [siteDir]/docusaurus.config.js입니다
--poll [optionalIntervalMs]	false	변경 상태 체크가 제대로 되지 않을 때 폴백 처리로 라이브 리로드 대신 파일 폴링을 사용하도록 설정할 수 있습니다. 자세한 내용은 여기를 참고하세요.
--no-minify	false	JS/CSS 번들 최소화 없이 웹 사이트를 빌드할지 여부를 설정합니다.

정보

일부 기능(앵커 링크 같은)은 개발 모드에서는 잘 동작하지 않을 수 있습니다. 하지만 제품 모드에서는 정상적으로 동작합니다.

Development over network

원격 서버나 VM(예: GitHub Codespaces)에서 3000번 포트를 전달할 때 개발 서버를 0.0.0.0에서 실행하면 로컬 IP에서 수신할 수 있습니다.

npm

npm run start -- --host 0.0.0.0

Yarn

yarn run start --host 0.0.0.0

pnpm

pnpm run start --host 0.0.0.0

Bun

bun run start --host 0.0.0.0

HTTPS를 사용하도록 설정하기

인증서를 받는 방법은 여러 가지가 있습니다. 여기서는 mkcert를 예로 사용하겠습니다.

1. mkcert localhost를 실행하여 localhost.pem + localhost-key.pem을 생성하세요

2. mkcert -install을 실행해 인증서를 신뢰 저장소에 설치한 후 브라우저를 다시 시작하세요

3. HTTPS 환경 변수를 설정하고 도큐사우루스 앱을 실행합니다.

HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start

4. https://localhost:3000/을 여세요

docusaurus build [siteDir]

제품 배포를 위해 사이트를 컴파일합니다.

옵션

옵션명	기본값	설명
--dev		전체 리액트 오류 메시지를 포함하여 웹사이트를 개발 모드로 빌드합니다.
--bundle-analyzer	false	Analyze your bundle with the webpack bundle analyzer.
--out-dir	build	현재 워크스페이스를 기준으로 output 디렉터리의 상대 경로를 설정합니다.
--config	undefined	도큐사우루스 설정 파일의 경로입니다. 기본값은 [siteDir]/docusaurus.config.js입니다
--locale		지정한 로케일로 사이트를 빌드합니다. 지정하지 않으면 알려진 모든 로케일을 빌드합니다.
--no-minify	false	JS/CSS 번들 최소화 없이 웹 사이트를 빌드할지 여부를 설정합니다.

정보

For advanced minification of CSS bundle, we use the advanced cssnano preset (along with additional several PostCSS plugins) and level 2 optimization of clean-css. If as a result of this advanced CSS minification you find broken CSS, build your website with the environment variable USE_SIMPLE_CSS_MINIFIER=true to minify CSS with the default cssnano preset. CSS 축소 관련 버그가 발생하면 이슈를 등록해 주세요.

SKIP_HTML_MINIFICATION=true 환경 변수로 HTML 축소를 건너뛸 수 있습니다.

docusaurus swizzle [themeName] [componentName] [siteDir]

테마 컴포넌트를 스위즐링하여 원하는 대로 변경합니다.

npm

npm run swizzle [themeName] [componentName] [siteDir]

# Example (leaving out the siteDir to indicate this directory)
npm run swizzle @docusaurus/theme-classic Footer -- --eject

Yarn

yarn swizzle [themeName] [componentName] [siteDir]

# Example (leaving out the siteDir to indicate this directory)
yarn swizzle @docusaurus/theme-classic Footer --eject

pnpm

pnpm run swizzle [themeName] [componentName] [siteDir]

# Example (leaving out the siteDir to indicate this directory)
pnpm run swizzle @docusaurus/theme-classic Footer --eject

Bun

bun run swizzle [themeName] [componentName] [siteDir]

# Example (leaving out the siteDir to indicate this directory)
bun run swizzle @docusaurus/theme-classic Footer --eject

스위즐링 CLI는 대화형이며 스위즐링 과정 전체를 안내합니다.

옵션

옵션명	설명
themeName	스위즐할 테마 이름
componentName	스위즐할 컴포넌트 이름
--list	스위즐링에 사용할 수 있는 컴포넌트 표시
--eject	테마 컴포넌트 꺼내기
--wrap	테마 컴포넌트 래핑하기
--danger	안전하지 않은 컴포넌트의 즉각적인 스위즐링 허용
--typescript	타입스크립트 변형 컴포넌트 스위즐
--config	도큐사우루스 설정 파일의 경로입니다. 기본값은 [siteDir]/docusaurus.config.js입니다

경고

안전하지 않은 컴포넌트: 내부 리팩토링으로 인해 호환성이 손상되는 변경 위험이 높은 컴포넌트입니다.

docusaurus deploy [siteDir]

GitHub Pages로 사이트를 배포합니다. Check out the docs on deployment for more details.

옵션

옵션명	기본값	설명
--locale		지정한 로케일로 사이트를 배포합니다. 지정하지 않으면 알려진 모든 로케일을 배포합니다.
--out-dir	build	현재 워크스페이스를 기준으로 output 디렉터리의 상대 경로를 설정합니다.
--skip-build	false	빌드 과정 없이 웹 사이트를 배포합니다. 사용자 지정 배포 스크립트를 사용하는 경우에 유용합니다.
--target-dir	.	배포할 대상 디렉터리의 경로입니다.
--config	undefined	도큐사우루스 설정 파일의 경로입니다. 기본값은 [siteDir]/docusaurus.config.js입니다

docusaurus serve [siteDir]

웹 사이트를 로컬에서 서비스합니다.

옵션명	기본값	설명
--port	3000	사용할 포트를 설정합니다.
--dir	build	현재 워크스페이스를 기준으로 output 디렉터리이 상대 경로를 설정합니다.
--build	false	서비스 전에 웹 사이트를 빌드합니다.
--config	undefined	도큐사우루스 설정 파일의 경로입니다. 기본값은 [siteDir]/docusaurus.config.js입니다
--host	localhost	사용할 호스트를 설정합니다. 예를 들어 외부에서 서버에 접근할 수 있도록 하려면 --host 0.0.0.0을 사용할 수 있습니다.
--no-open	로컬에서는 false, CI에서는 true	서버 경로를 브라우저 창에서 열지 마세요.

docusaurus clear [siteDir]

도큐사우루스에서 만든 애셋, 캐시, 산출물을 삭제합니다.

버그를 발견하고 등록하기 전이나 버전 업그레이드 또는 도큐사우루스 사이트에 문제가 생겼을 때 이 명령을 실행하는 것을 권장합니다.

docusaurus write-translations [siteDir]

번역할 JSON 번역 파일을 만듭니다.

기본적으로 파일은 website/i18n/\<defaultLocale>/...에 작성됩니다.

옵션명	기본값	설명
--locale	\<defaultLocale>	JSON 파일을 번역할 로케일 디렉터리를 설정합니다.
--override	false	기존 번역 메시지를 덮어쓸지 여부를 설정합니다.
--config	undefined	도큐사우루스 설정 파일의 경로입니다. 기본값은 [siteDir]/docusaurus.config.js입니다
--messagePrefix	''	번역되지 않는 문자열을 강조하기 위해 각 번역 메시지에 접두사를 추가하도록 설정할 수 있습니다.

docusaurus write-heading-ids [siteDir] [files]

사이트의 마크다운 문서에 명시적 제목 ID를 추가합니다.

옵션명	기본값	설명
files	플러그인에서 사용하는 모든 MD 파일	제목 ID를 작성할 파일
--syntax	classic	사용할 제목 ID 구문입니다. classic({#id}) 또는 mdx-comment({/* #id */})를 지정합니다.
--migrate	false	기존 제목 ID가 다른 구문을 사용한다면 대상 --syntax로 마이그레이션합니다.
--overwrite	false	기존 제목 ID를 덮어쓰고 제목 텍스트에서 다시 생성합니다.
--maintain-case	false	제목 대소문자 유지, 그렇지 않으면 소문자로 처리.