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 번들 최소화 없이 웹 사이트를 빌드할지 여부를 설정합니다.
--https	false	자체 서명 인증서를 사용하여 개발 사이트를 HTTPS로 제공합니다. --ssl-cert와 --ssl-key를 모두 지정하면 자동으로 활성화됩니다.
--ssl-cert	undefined	TLS 인증서 파일의 경로입니다(HTTPS 활성화).
--ssl-key	undefined	TLS 개인 키 파일의 경로입니다(HTTPS 활성화).

정보

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

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 CLI 옵션으로 앱을 시작하세요:

npm

npm run start -- --ssl-cert localhost.pem --ssl-key localhost-key.pem

Yarn

yarn run start --ssl-cert localhost.pem --ssl-key localhost-key.pem

pnpm

pnpm run start --ssl-cert localhost.pem --ssl-key localhost-key.pem

Bun

bun run start --ssl-cert localhost.pem --ssl-key localhost-key.pem

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

자체 서명 인증서

--https 옵션을 사용하면 자동으로 생성된 자체 서명 인증서로 개발 사이트를 HTTPS에서 제공할 수 있습니다:

npm

npm run start -- --https

Yarn

yarn run start --https

pnpm

pnpm run start --https

Bun

bun run start --https

docusaurus build [siteDir]

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

옵션

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

정보

CSS 번들은 사이트의 Browserslist 설정을 대상으로 Lightning CSS를 사용해 축소됩니다. Please fill out an issue if you experience CSS minification bugs.

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

docusaurus swizzle [themeName] [componentName] [siteDir]

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

npm

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

# 예 (현재 디렉터리로 설정한다면 siteDir 옵션은 제외할 수 있습니다)
npm run swizzle @docusaurus/theme-classic Footer -- --eject

Yarn

yarn swizzle [themeName] [componentName] [siteDir]

# 예 (현재 디렉터리로 설정한다면 siteDir 옵션은 제외할 수 있습니다)
yarn swizzle @docusaurus/theme-classic Footer --eject

pnpm

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

# 예 (현재 디렉터리로 설정한다면 siteDir 옵션은 제외할 수 있습니다)
pnpm run swizzle @docusaurus/theme-classic Footer --eject

Bun

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

# 예 (현재 디렉터리로 설정한다면 siteDir 옵션은 제외할 수 있습니다)
bun run swizzle @docusaurus/theme-classic Footer --eject

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

옵션

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

경고

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

docusaurus deploy [siteDir]

GitHub Pages로 사이트를 배포합니다. 자세한 내용은 배포 문서를 참고하세요.

옵션

옵션명	기본값	설명
--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	서버 경로를 브라우저 창에서 열지 마세요.

HTTP caching

docusaurus serve tells browsers how to cache each response with the Cache-Control header:

Responses	Cache-Control	Browser behavior
Files in /assets/	public, max-age=31536000, immutable	Reuses the file for one year, without asking the server.
Everything else: pages, other static files, redirects, errors	no-cache	Asks the server before each reuse. The server answers 304 Not Modified when the file content didn't change, using its ETag.

The bundler adds a content hash to the names of the files it emits in /assets/ (JavaScript, CSS, images, fonts…): when the content of a file changes, its URL changes too.

The other files keep their URLs from one build to the next. Revalidating them ensures you always see your latest build, and the redirects of your current baseUrl and trailingSlash config, even after serving another site on the same port.

The /assets/ folders of the other locales of an i18n site, like /fr/assets/, are revalidated like the other files.

경고

Don't put files in an assets folder of your static directories, like static/assets/. They are copied to /assets/ without a content hash, so browsers can keep using an outdated version for one year.

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	자동 추론	사용할 제목 ID 구문입니다. classic({#id}) 또는 mdx-comment({/* #id */})를 지정합니다. 기본적으로 markdown.format 설정 옵션에 따라 CommonMark로 컴파일되는 파일에는 classic을, MDX로 컴파일되는 파일에는 mdx-comment를 사용합니다.
--migrate	false	기존 제목 ID가 다른 구문을 사용한다면 대상 --syntax로 마이그레이션합니다.
--overwrite	false	기존 제목 ID를 덮어쓰고 제목 텍스트에서 다시 생성합니다.
--maintain-case	false	제목 대소문자 유지, 그렇지 않으면 소문자로 처리.