테마 초기 설정

먼저 npm install 또는 pnpm install로 필요한 패키지를 모두 설치한 다음, npm run build 또는 pnpm build로 초기 빌드를 실행해 설정이 정상적으로 동작하는지 확인합니다.
사이트 검색에 사용하는 Pagefind 빌드 결과물을 개발 환경에서도 쓸 수 있도록 복사합니다. 방법은 운영체제에 따라 다르며, 편의를 위해 몇 가지 명령을 미리 준비해 두었습니다.
- Windows에서는 npm run winsearch를 실행합니다
- OSX 또는 Linux에서는 npm run osxsearch를 실행합니다
다음으로 사이트의 i18n 설정(단일 언어 또는 다국어)을 구성합니다. npm run docs:config-i18n 명령을 실행하고 스크립트 안내를 따르기만 하면 설정이 끝납니다.
이제 사이트를 원하는 대로 구성할 수 있습니다.

코드 둘러보기

코드베이스를 처음 익히는 데 도움이 되도록 몇 가지 코드 투어를 만들어 두었습니다. VSCode나 다른 IDE에서 보려면 Code Tour 확장이 필요합니다.

코드는 대부분의 항목이 src/docs 디렉터리 아래에 놓이도록 구성되어 있습니다. 덕분에 해당 폴더 전체를 기존 프로젝트에 그대로 옮겨 넣어 몇 분 만에 문서 기능을 추가할 수 있습니다.

사이트 전반의 구성은 src/docs/config/ 폴더에서 진행합니다. 번역을 더 쉽게 관리할 수 있도록 대부분의 설정은 언어별 폴더 안에 들어 있습니다.

src/docs/config/siteSettings.json.ts 파일에서 사이트 설정을 구성합니다. 뷰 트랜지션 사용 여부, 애니메이션 사용 여부, 문서 제목에 링크 복사 버튼을 표시할지 여부 등이 여기에 포함됩니다.

src/docs/config/[language]/siteData.json.ts 파일에서 사이트 데이터를 구성합니다. 사이트 제목, 설명, 소셜 링크, 기본 이미지 등이 여기에 포함됩니다.

상단 내비게이션 바의 내비게이션 데이터는 src/docs/config/[language]/navData.json.ts 파일에서 구성합니다.

문서 섹션의 순서는 src/docs/config/[language]/sidebarNavData.json.ts 파일에서 구성합니다.

Google 같은 크롤러가 올바른 사이트맵을 인식하도록 하려면 public/robots.txt 파일을 편집해 사용 중인 웹사이트 도메인을 지정해야 합니다.

Astro는 src/pages/ 디렉터리에서 .astro 또는 .md 파일을 찾습니다. 각 페이지는 파일 이름을 기준으로 라우트로 노출됩니다.

src/components/에 특별한 규칙이 있는 것은 아니지만, Astro/React/Vue/Svelte/Preact 컴포넌트는 이 위치에 두는 것을 권장합니다.

이미지 같은 정적 자산은 public/ 디렉터리에 배치할 수 있습니다. Astro의 이미지 최적화 기능을 사용할 때는 이미지를 src/assets에 두는 경우도 많습니다.

모든 명령은 프로젝트 루트에서 터미널로 실행합니다.

명령어	동작
`npm install`	의존성을 설치합니다
`npm run dev`	`localhost:4321`에서 로컬 개발 서버를 시작합니다
`npm run build`	프로덕션 사이트를 `./dist/`에 빌드합니다
`npm run preview`	배포 전에 빌드 결과를 로컬에서 미리 봅니다
`npm run astro ...`	`astro add`, `astro check` 같은 CLI 명령을 실행합니다
`npm run astro -- --help`	Astro CLI 사용법 도움말을 확인합니다

공식 문서를 살펴보거나 Discord 서버에 참여해 보세요.