msb-public
/
vitepress
mirror of https://github.com/vuejs/vitepress
2
1
Code Issues Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '1e4917eb30'
${ noResults }
vitepress/docs/ko/guide/getting-started.md

7.2 KiB
Raw Blame History

시작하기

온라인에서 사용해보기

StackBlitz에서 브라우저로 즉시 VitePress를 사용해 볼 수 있습니다.

설치

사전 준비 사항

VitePress는 단독으로 사용하거나 기존 프로젝트에 설치할 수 있습니다. 두 경우 모두 다음과 같이 설치할 수 있습니다:

::: code-group

$ npm add -D vitepress

$ pnpm add -D vitepress

$ yarn add -D vitepress

$ yarn add -D vitepress vue

$ bun add -D vitepress

:::

::: details "missing peer deps" 경고가 표시되나요? PNPM을 사용하는 경우 @docsearch/js에 대한 "missing peer deps" 경고가 표시됩니다. 이는 VitePress가 작동하는 것을 방해하지 않습니다. 이 경고를 억제하려면 package.json에 다음을 추가합니다:

"pnpm": {
  "peerDependencyRules": {
    "ignoreMissing": [
      "@algolia/client-search",
      "search-insights"
    ]
  }
}

:::

::: tip 참고

VitePress는 ESM 전용 패키지입니다. require()를 사용하여 가져오지 마시고, package.json에 "type": "module"이 포함되어 있는지 확인하거나, 관련 파일(예: .vitepress/config.js)의 확장자를 .mjs/.mts로 변경하세요. 자세한 내용은 Vite 문제 해결 가이드를 참고하세요. 또한, 비동기 CJS 컨텍스트에서는 await import('vitepress')를 사용할 수 있습니다.

:::

설정 마법사

VitePress는 기본 프로젝트를 구축하는 데 도움이 되는 명령줄 설정 마법사를 제공합니다. 설치 후, 마법사를 시작하려면 다음을 실행하세요:

::: code-group

$ npx vitepress init

$ pnpm vitepress init

$ yarn vitepress init

$ bun vitepress init

:::

몇 가지 간단한 질문들이 나타날 것입니다:

<<< @/snippets/init.ansi

::: tip 피어 의존성으로서의 Vue 커스텀을 위해 Vue 컴포넌트나 API를 사용하려는 경우, vue를 명시적으로 의존성으로 설치해야 합니다. :::

파일 구조

독립형 VitePress 사이트를 구축하려는 경우, 현재 디렉터리(./)에 사이트를 구축할 수 있습니다. 그러나 기존 프로젝트에서 다른 소스 코드와 함께 VitePress를 설치하는 경우, 프로젝트의 나머지 부분과 분리되도록 중첩된 디렉터리(e.g. ./docs)에 사이트를 구축하는 것이 좋습니다.

VitePress 프로젝트를 ./docs에 구축하기로 한 경우, 생성된 파일 구조는 다음과 같아야 합니다:

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

docs 디렉터리는 VitePress 사이트의 프로젝트 루트로 간주됩니다. .vitepress 디렉터리는 VitePress의 구성 파일, 개발 서버 캐시, 빌드 출력, 선택적 커스텀 테마 코드가 있는 위치입니다.

::: tip 기본적으로 VitePress는 개발 서버 캐시를 .vitepress/cache에 저장하고, 프로덕션 빌드 출력을 .vitepress/dist에 저장합니다. Git을 사용하는 경우, 이러한 디렉토리를 .gitignore 파일에 추가해야 합니다. 또는 이러한 위치를 수동으로 구성할 수도 있습니다. :::

구성 파일

구성 파일(.vitepress/config.js)을 사용하면 사이트의 제목과 설명과 같은 VitePress 사이트의 다양한 측면을 커스터마이즈할 수 있습니다:

// .vitepress/config.js
export default {
  // 사이트 옵션
  title: 'VitePress',
  description: '그냥 해보는 중.',

  themeConfig: {
    // 테마 옵션
  }
}

테마의 동작은 themeConfig 옵션을 통해 구성할 수도 있습니다. 모든 구성 옵션에 대한 자세한 내용은 구성 레퍼런스를 참고하세요.

소스 파일

.vitepress 디렉토리 외부의 마크다운 파일은 소스 파일로 간주됩니다.

VitePress는 파일 기반 라우팅을 사용합니다: 각 .md 파일은 동일한 경로에 해당하는 .html 파일로 컴파일됩니다. 예를 들어, index.md는 index.html로 컴파일되며, 결과적으로 VitePress 사이트의 루트 경로 /에서 방문할 수 있습니다.

또한 VitePress는 간결한 URL 생성, 경로 재작성, 동적 페이지 생성 기능을 제공합니다. 이러한 내용은 라우팅 가이드에서 다룹니다.

실행 및 작동

설치 과정에서 허용한 경우, 도구는 다음 npm 스크립트를 package.json에 추가했을 것입니다:

{
  ...
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
  ...
}

docs:dev 스크립트는 즉각적인 핫 업데이트가 가능한 로컬 개발 서버를 시작합니다. 다음 명령어로 실행할 수 있습니다:

::: code-group

$ npm run docs:dev

$ pnpm run docs:dev

$ yarn docs:dev

$ bun run docs:dev

:::

npm 스크립트 대신 VitePress를 직접 호출할 수도 있습니다:

::: code-group

$ npx vitepress dev docs

$ pnpm vitepress dev docs

$ yarn vitepress dev docs

$ bun vitepress dev docs

:::

더 많은 명령줄 사용법은 CLI 레퍼런스에 문서화되어 있습니다.

개발 서버는 http://localhost:5173에서 실행되어야 합니다. 브라우저에서 URL을 방문하여 새 사이트를 확인하세요!

다음 단계는?

  • 마크다운과 이 파일로 생성된 HTML이 어떻게 매핑되는지 더 잘 이해하려면 라우팅 가이드를 참고하세요.

  • 페이지에서 할 수 있는 작업, 예를 들어 마크다운 콘텐츠 작성이나 Vue 컴포넌트 사용에 대해 더 알아보려면 가이드의 "글쓰기" 섹션을 참조하세요. 시작하기 좋은 곳은 마크다운 확장에 대해 배우는 것입니다.

  • 기본 문서 테마에서 제공하는 기능을 탐색하려면 기본 테마 구성 레퍼런스를 확인하세요.

  • 사이트의 외관을 더 맞춤화하려면 기본 테마 확장 또는 커스텀 테마 빌드를 탐색하세요.

  • 문서 사이트가 형태를 갖추면 배포 가이드를 꼭 읽어보세요.