메인 컨텐츠로 이동
Version: 2.0.0-alpha.74

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]#

웹팩 개발 서버를 사용해 여러분의 사이트를 로컬에서 빌드하고 미리보기를 제공합니다.

옵션#

옵션명기본값설명
--port3000개발 서버에서 사용할 포트를 설정합니다.
--hostlocalhost사용할 호스트를 설정합니다. 외부에서 접근할 수 있게 --host 0.0.0.0 형태로 설정할 수도 있습니다.
--hot-onlyfalse빌드 실패 시 폴백 처리로 페이지 새로고침 없이 빠른 모듈 교체(Hot Module Replacement)를 사용할지 여부를 설정합니다. 좀 더 많은 정보는 웹팩 문서를 참고하세요.
--no-openfalse웹 브라우저에서 자동으로 페이지를 열지 여부를 설정합니다.
--configundefined도큐사우루스 설정 파일 경로를 설정합니다. 기본값은 [siteDir]/docusaurus.config.js입니다.
--poll [optionalIntervalMs]false변경 상태 체크가 제대로 되지 않을 때 폴백 처리로 라이브 리로드 대신 파일 폴링을 사용하도록 설정할 수 있습니다. 좀 더 많은 정보는 웹팩 문서를 참고하세요.
important

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

HTTPS를 사용하도록 설정하기#

인증서를 받는 방법은 여러 가지가 있습니다. 여기서는 설명을 위해 mkcert를 사용할 겁니다.

  1. localhost.pem + localhost-key.pem 파일을 만들기 위해 mkcert localhost 명령을 실행합니다.

  2. 로컬에 인증서를 설치하기 위해 mkcert -install 명령을 실행합니다. 그리고 웹 브라우저를 다시 시작합니다.

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

HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start
  1. 웹 브라우저에서 https://localhost:3000/을 실행합니다.

docusaurus build [siteDir]#

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

옵션#

옵션명기본값설명
--bundle-analyzerfalse웹팩 번들 분석 기능을 사용해 번들을 분석합니다.
--out-dirbuild현재 워크스페이스를 기준으로 output 디렉터리의 상대 경로를 설정합니다.
--configundefined도큐사우루스 설정 파일 경로를 설정합니다. 기본값은 [siteDir]/docusaurus.config.js입니다.
--no-minifyfalseJS/CSS 번들 최소화 없이 웹 사이트를 빌드할지 여부를 설정합니다.
info

CSS 번들 최소화를 위한 고급 기능으로 advanced cssnano preset(PostCSS 플러그인 추가)와 clean-css 레벨 2 최적화를 사용하고 있습니다. CSS 최소화 처리 시 CSS가 깨지는 경우에는 USE_SIMPLE_CSS_MINIFIER=true 환경 변수를 설정해 default cssnano preset을 사용해 CSS 최소화가 처리되도록 할 수 있습니다. CSS 최소화 시 문제가 발생했다면 이슈로 등록해주세요.

docusaurus swizzle [siteDir]#

caution

베타 단계에 들어가기 전에는 컴포넌트 바꾸기 기능을 사용하지 않을 것을 권장합니다. 컴포넌트 API는 빠르게 변경되고 있으며 베타 단계에 이를 때까지 변화는 계속될 겁니다. 가능한 기본 상태를 유지하는 것이 나중에 발생할 수 있는 잠재적인 문제를 최소화할 수 있습니다.

npm run swizzle을 사용해 도큐사우루스 테마 컴포넌트를 여러분이 원하는 것으로 바꿀 수 있습니다.

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

명령을 실행하면 관련 테마 파일이 여러분의 사이트 디렉터리로 복사됩니다. 여기에서 원하는 대로 수정할 수 있으며 수정된 기능은 도큐사우루스는 테마에서 제공하는 기능 대신 사용합니다.

themeName 없이 npm run swizzle 명령을 실행하면 적용할 수 있는 모든 테마 목록을 반환합니다. 마찬가지로 componentName 없이 npm run swizzle <themeName> 명령을 실행하면 적용할 수 있는 모든 컴포넌트 목록을 반환합니다.

옵션#

옵션명설명
themeName사용할 테마 이름
swizzleComponent바꿀 컴포넌트 이름
--danger안정적이지 않은 컴포넌트 바꾸기를 허용할지 설정
--typescript타입스크립트 컴포넌트 바꾸기를 허용할지 설정

--danger 옵션은 아래와 같이 적용할 수 있습니다.

npm run swizzle @docusaurus/theme-classic Logo -- --danger
caution

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

컴포넌트 바꾸기를 취소하려면 수정한 컴포넌트 파일을 삭제하기만 하면 됩니다.

docusaurus deploy [siteDir]#

여러분의 사이트를 깃허브 페이지로 배포합니다. 좀 더 자세한 내용은 배포 문서를 참고하세요.

옵션#

옵션명기본값설명
--out-dirbuild현재 워크스페이스를 기준으로 output 디렉터리의 상대 경로를 설정합니다.
--skip-buildfalse빌드 과정 없이 웹 사이트를 배포합니다. 사용자 지정 배포 스크립트를 사용하는 경우에 유용합니다.
--configundefined도큐사우루스 설정 파일 경로를 설정합니다. 기본값은 [siteDir]/docusaurus.config.js입니다.

docusaurus serve [siteDir]#

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

옵션명기본값설명
--port3000사용할 포트를 설정합니다.
--dirbuild현재 워크스페이스를 기준으로 output 디렉터리이 상대 경로를 설정합니다.
--buildfalse서비스 전에 웹 사이트를 빌드합니다.
--configundefined도큐사우루스 설정 파일 경로를 설정합니다. 기본값은 [siteDir]/docusaurus.config.js입니다.
--hostlocalhost사용할 호스트를 설정합니다. 외부에서 접근할 수 있게 --host 0.0.0.0 형태로 설정할 수도 있습니다.

docusaurus clear [siteDir]#

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

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

docusaurus write-translations [siteDir]#

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

기본적으로 website/i18n/<defaultLocale>/... 경로에 파일이 만들어집니다.

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

docusaurus write-heading-ids [siteDir]#

사이트 마크다운 문서에 id를 설정합니다.