모든 Markdown 파일은 Vue 컴포넌트로 컴파일되며 [Vite](https://vitejs.dev/ko/guide/assets.html)에 의해 처리됩니다. 상대 URL을 사용하여 어떠한 자산도 참조할 수 **있으며 해야 합니다**:
모든 마크다운 파일은 Vue 컴포넌트로 컴파일되어 [Vite](https://vitejs.dev/guide/assets.html)에 의해 처리됩니다. 모든 에셋은 상대 URL을 사용하여 참조할 수 있으며, **참조해야 합니다**:
```md
```
Markdown 파일, 테마의 `*.vue` 컴포넌트, 스타일 및 일반 `.css` 파일에서 정적 자산을 참조할 수 있으며, 절대 공개 경로(프로젝트 루트를 기준으로 함) 또는 상대 경로(파일 시스템을 기준으로 함)를 사용할 수 있습니다. 후자는 Vite, Vue CLI 또는 webpack의 `file-loader`를 사용해 본 적이 있다면 익숙한 동작 방식과 유사합니다.
마크다운 파일에서 정적 에셋을 참조할 수 있으며, 테마 내의 `*.vue` 컴포넌트, 스타일 및 일반 `.css` 파일을 절대 경로(프로젝트 루트를 기준으로) 또는 상대 경로(파일 시스템을 기준으로)를 사용하여 참조할 수 있습니다. 후자는 Vite, Vue CLI 또는 webpack의 `file-loader` 동작과 유사합니다.
일반적인 이미지, 미디어, 폰트 파일 유형은 자동으로 자산으로 감지되어 포함됩니다.
일반적인 이미지, 미디어 및 글꼴 파일 형식은 자동으로 에셋으로 감지되어 포함됩니다.
::: tip 링크된 파일은 자산으로 취급되지 않음
Markdown 파일 내의 링크로 참조된 PDF 또는 기타 문서는 자동으로 자산으로 취급되지 않습니다. 링크된 파일을 접근 가능하게 만들기 위해서는 수동으로 해당 파일을 프로젝트의 [`public`](#the-public-directory) 디렉토리에 배치해야 합니다.
::: tip 링크를 통해 참조된 파일은 에셋으로 처리되지 않습니다
마크다운 파일 내에서 링크로 참조된 PDF 또는 기타 문서는 자동으로 에셋으로 처리되지 않습니다. 링크된 파일을 접근 가능하게 하려면 프로젝트의 [`public`](#the-public-directory) 디렉토리에 수동으로 배치해야 합니다.
:::
절대 경로를 포함한 모든 참조된 자산은 생산 빌드에서 해시된 파일 이름으로 출력 디렉토리에 복사됩니다. 참조되지 않은 자산은 복사되지 않습니다. 4kb보다 작은 이미지 자산은 base64 인라인으로 처리됩니다 - 이는 [`vite`](../reference/site-config#vite) 구성 옵션을 통해 설정할 수 있습니다.
절대 경로를 사용하는 에셋을 포함하여 모든 참조된 에셋은 프로덕션 빌드에서 해시된 파일 이름으로 출력 디렉토리에 복사됩니다. 참조되지 않은 에셋은 복사되지 않습니다. 4kb보다 작은 이미지 에셋은 base64로 인라인됩니다. 이는 [`vite`](../reference/site-config#vite) 구성 옵션을 통해 구성할 수 있습니다.
모든 **정적** 경로 참조, 절대 경로를 포함하여, 작업 디렉토리 구조를 기반으로 해야 합니다.
모든 **정적** 경로 참조는 절대 경로를 포함하여 작업 디렉토리 구조를 기반으로 해야 합니다.
## Public 디렉토리 {#the-public-directory}
## Public 디렉터리 {#the-public-directory}
Markdown이나 테마 컴포넌트에서 직접 참조되지 않은 정적 자산을 제공할 필요가 있거나, 특정 파일을 원본 파일명으로 제공하고 싶은 경우가 있을 수 있습니다. 이러한 파일의 예로는 `robots.txt`, 파비콘, PWA 아이콘이 있습니다.
때때로 마크다운이나 테마 컴포넌트에서 직접 참조되지 않는 정적 에셋을 제공해야 하거나 특정 파일을 원래 파일 이름으로 제공하고 싶을 때가 있습니다. 이러한 파일의 예로는 `robots.txt`, 파비콘, PWA 아이콘 등이 있습니다.
이 파일들은 [소스 디렉토리](./routing#source-directory) 아래의 `public` 디렉토리에 배치할 수 있습니다. 예를 들어, 프로젝트 루트가 `./docs`이고 기본 소스 디렉토리 위치를 사용한다면, public 디렉토리는 `./docs/public`이 됩니다.
이 파일들은 [소스 디렉토리](./routing#source-directory) 아래의 `public` 디렉토리에 놓을 수 있습니다. 예를 들어 프로젝트 루트가 `./docs`이고 기본 소스 디렉토리 위치를 사용 중인 경우, `public` 디렉토리는 `./docs/public`이 됩니다.
`public`에 배치된 자산은 그대로 출력 디렉토리의 루트로 복사됩니다.
`public`에 배치된 에셋은 출력 디렉토리의 루트로 그대로 복사됩니다.
`public`에 배치된 파일을 참조할 때는 루트 절대 경로를 사용해야 한다는 점에 유의하세요 - 예를 들어, `public/icon.png`는 소스 코드에서 항상 `/icon.png`로 참조되어야 합니다.
`public`에 배치된 파일은 루트 절대 경로를 사용하여 참조해야 한다는 점에 유의하세요. 예를 들어, `public/icon.png`는 소스 코드에서 항상 `/icon.png`로 참조되어야 합니다.
## 기본 URL {#base-url}
## Base URL {#base-url}
사이트가 루트 URL이 아닌 곳에 배포되는 경우, `.vitepress/config.js`에서 `base` 옵션을 설정해야 합니다. 예를 들어, 사이트를 `https://foo.github.io/bar/`에 배포할 계획이라면, `base`는 `'/bar/'`(항상 슬래시로 시작하고 끝나야 함)로 설정해야 합니다.
사이트가 루트 URL이 아닌 곳에 배포된 경우, `.vitepress/config.js`에서 `base` 옵션을 설정해야 합니다. 예를 들어, 사이트를 `https://foo.github.io/bar/`에 배포하려는 경우 `base`는 `'/bar/'`로 설정해야 합니다(항상 슬래시로 시작하고 끝나야 합니다).
모든 정적 자산 경로는 다양한`base` 구성 값에 맞게 자동으로 처리됩니다. 예를 들어, 마크다운에서 `public`아래에 있는 자산에 대한 절대 참조가 있는 경우:
모든 정적 에셋 경로는 다른`base` 구성 값에 맞게 자동으로 처리됩니다. 예를 들어, 마크다운에서 `public`하위의 에셋에 대한 절대 참조가 있는 경우:
```md
```
이 경우 `base` 구성 값을 변경하더라도 업데이트할 필요가 **없습니다**.
이 경우 `base` 구성 값을 변경할 때 **업데이트할 필요가 없습니다**.
그러나 자산을 동적으로 연결하는 테마 컴포넌트를 작성하는 경우, 예를 들어 테마 구성 값에 기반한 이미지의 `src`가 있는 경우:
그러나 테마 구성 값을 기반으로 `src`가 설정된 이미지와 같이 동적으로 에셋에 링크하는 테마 컴포넌트를 작성하는 경우:
```vue
<img:src="theme.logoPath"/>
```
이 경우 VitePress에 제공되는 [`withBase` 헬퍼](../reference/runtime-api#withbase)로 경로를 래핑하는 것이 권장됩니다:
이 경우 VitePress에서 제공하는 [`withBase` 헬퍼](../reference/runtime-api#withbase)로 경로를 감싸는 것이 좋습니다:
기본 내보내기는 사용자 정의 테마에 대한 유일한 계약이며, `Layout` 속성만 필수입니다. 기술적으로, VitePress 테마는 단일 Vue 컴포넌트만큼 간단할 수 있습니다.
"export default"는 커스텀 테마를 설정하는 유일한 방법이며, `Layout` 프로퍼티만 필수입니다. 따라서 기술적으로 VitePress 테마는 단일 Vue 컴포넌트처럼 간단할 수 있습니다.
레이아웃 컴포넌트 내부에서는 평소처럼 Vite + Vue 3 애플리케이션처럼 작동합니다. 테마도 [SSR-호환성이](./ssr-compat) 있어야 합니다.
레이아웃 컴포넌트 내부에서는 일반적인 Vite + Vue 3 애플리케이션처럼 동작합니다. 또한 테마가 [SSR 호환](./ssr-compat)이 되어야 합니다.
## 레이아웃 만들기 {#building-a-layout}
가장 기본적인 레이아웃 컴포넌트는 [`<Content />`](../reference/runtime-api#content) 컴포넌트를 포함해야 합니다:
가장 기본적인 레이아웃 컴포넌트는 [`<Content />`](../reference/runtime-api#content) 컴포넌트가 포함되어야 합니다:
```vue
<!-- .vitepress/theme/Layout.vue -->
<template>
<h1>사용자 정의 레이아웃!</h1>
<h1>Custom Layout!</h1>
<!-- 마크다운 내용이 여기에 렌더링됩니다 -->
<!-- 마크다운 내용은 여기에 렌더링됩니다 -->
<Content/>
</template>
```
위의 레이아웃은 각 페이지의 마크다운을 HTML로 단순히 렌더링합니다. 우리가 추가할 수 있는 첫 번째 개선 사항은 404 오류를 처리하는 것입니다:
위의 레이아웃은 각 페이지의 마크다운을 HTML로 렌더링합니다. 첫 번째로 개선 사항은 404 에러를 처리하는 것입니다:
```vue{1-4,9-12}
<scriptsetup>
@ -91,16 +91,16 @@ const { page } = useData()
</script>
<template>
<h1>사용자 정의 레이아웃!</h1>
<h1>Custom Layout!</h1>
<divv-if="page.isNotFound">
사용자 정의 404 페이지!
Custom 404 page!
</div>
<Contentv-else/>
</template>
```
[`useData()`](../reference/runtime-api#usedata) 헬퍼는 우리가 필요로 하는 모든 런타임 데이터를 제공하여, 다른 레이아웃을 조건부로 렌더링할 수 있습니다. 우리가 접근할 수 있는 또 다른 데이터는 현재 페이지의 프론트매터입니다. 이를 활용하여 사용자가 각 페이지의 레이아웃을 제어할 수 있도록 합니다. 예를 들어, 사용자는 특별한 홈페이지 레이아웃을 사용해야 한다고 지정할 수 있습니다:
[`useData()`](../reference/runtime-api#usedata) 헬퍼는 다양한 레이아웃을 조건부로 렌더링하는 데 필요한 모든 런타임 데이터를 제공합니다. 접근할 수 있는 다른 데이터 중 하나는 현재 페이지의 전문(front-matter)입니다. 이를 활용하여 각 페이지에 맞게 레이아웃을 제어할 수 있습니다. 예를 들어 특정 페이지에서 홈 페이지 레이아웃을 사용하도록 지정할 수 있습니다:
테마 컴포넌트에서 사용할 수 있는 모든 것에 대한 [런타임 API 참조](../reference/runtime-api)를 참조하세요. 또한, [빌드할 때 데이터 로딩](./data-loading)을 활용하여 데이터 기반 레이아웃을 생성할 수 있습니다 - 예를 들어, 현재 프로젝트 내 모든 블로그 포스트를 나열하는 페이지 등.
테마 컴포넌트에서 사용할 수 있는 모든 항목에 대해서는 [런타임 API 레퍼런스](../reference/runtime-api)를 참고하세요. 또한 [빌드할 때 데이터 로딩하기](./data-loading)를 활용하여 데이터 기반의 레이아웃을 생성할 수 있습니다. 예를 들어 현재 프로젝트의 모든 블로그 게시물을 나열하는 페이지를 만들 수 있습니다.
## 사용자 정의 테마 배포하기 {#distributing-a-custom-theme}
사용자 정의 테마를 배포하는 가장 쉬운 방법은 [GitHub에서 템플릿 저장소로 제공하는 것입니다](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository).
커스텀 테마를 배포하는 가장 쉬운 방법은 [GitHub 템플릿 리포지토리](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository)로 제공하는 것입니다.
npm 패키지로 테마를 배포하려면 다음 단계를 따르세요:
테마를 npm 패키지로 배포하려면 다음 단계를 따라야 합니다:
1. 패키지 엔트리에서 테마 객체를 기본 내보내기로 내보냅니다.
1. 패키지 엔트리에서 테마 객체를 "export default" 합니다.
2. 적용된다면, 테마 설정 타입 정의를 `ThemeConfig`로 내보냅니다.
2. 해당되는 경우, 테마 구성 타입 정의를 `ThemeConfig`로 "export" 합니다.
3. 테마가 VitePress 설정을 조정해야 하는 경우, 사용자가 확장할 수 있도록 패키지 하위 경로(예: `my-theme/config`)에 해당 설정을 내보냅니다.
3. 테마에서 VitePress 구성을 조정해야 하는 경우, 사용자가 확장할 수 있도록 패키지 하위 경로(예: `my-theme/config`)에 해당 구성을 "export" 합니다.
4. 설정 파일 및 프론트매터를 통한 테마 설정 옵션을 문서화합니다.
4. 테마 구성 옵션을 문서화합니다 (구성 파일과 전문 둘 다).
5. 테마를 소비하는 방법에 대한 명확한 지침을 제공합니다(아래 참조).
5. 테마를 사용하는 방법에 대한 명확한 지침을 제공합니다(아래 참조).
## 사용자 정의 테마 소비하기 {#consuming-a-custom-theme}
## 커스텀 테마 사용하기 {#consuming-a-custom-theme}
외부 테마를 소비하려면 사용자 정의 테마 엔트리에서 가져와서 다시 내보냅니다:
외부 테마를 사용하려면, 커스텀 테마 엔트리에서 테마를 "import" 후 다시 "export"합니다:
```js
// .vitepress/theme/index.js
@ -193,19 +193,19 @@ export default {
}
```
테마가 특별한 VitePress 설정을 요구하는 경우, 자신의 설정에서도 그 설정을 확장해야 합니다:
테마가 특별한 VitePress 구성을 요구하는 경우, 해당 구성을 (외부 커스텀 테마를 사용하는 자신의) 구성 파일에서도 확장해야 합니다:
```ts
// .vitepress/config.ts
import baseConfig from 'awesome-vitepress-theme/config'
VitePress는 **데이터 로더**라고 불리는 기능을 제공하여 임의의 데이터를 로드하고 페이지나 컴포넌트에서 가져올 수 있습니다. 데이터 로딩은 **빌드 시간에만 실행**됩니다: 결과적으로 생성된 데이터는 최종 자바스크립트 번들에 JSON으로 직렬화됩니다.
VitePress는 페이지나 컴포넌트에서 임의의 데이터를 로드하고 이를 가져올 수 있는 **데이터 로더** 기능을 제공합니다. 데이터 로딩은 **빌드할 때에만** 실행되며, 결과적으로 생성된 데이터는 최종 JavaScript 번들에 JSON으로 직렬화됩니다.
데이터 로더는 원격 데이터를 가져오거나 로컬 파일을 기반으로 메타데이터를 생성하는 데 사용할 수 있습니다. 예를 들어, 모든 로컬 API 페이지를 파싱하고 모든 API 항목의 색인을 자동으로 생성하기 위해 데이터 로더를 사용할 수 있습니다.
데이터 로더는 원격 데이터를 가져오거나 로컬 파일을 기반으로 메타데이터를 생성하는 데 사용할 수 있습니다. 예를 들어, 데이터 로더를 사용하여 모든 로컬 API 페이지를 파싱하고 모든 API 항목의 색인을 자동으로 생성할 수 있습니다.
## 기본 사용법 {#basic-usage}
데이터 로더 파일은 `.data.js` 또는 `.data.ts`로 끝나야 합니다. 이 파일은 `load()` 메서드를 가진 객체를 기본 내보내기해야 합니다:
데이터 로더 파일은 반드시 `.data.js` 또는 `.data.ts`로 끝나야 합니다. 이 파일은 `load()` 메서드를 가진 객체를 "export default" 해야 합니다:
```js
// example.data.js
@ -19,9 +19,9 @@ export default {
}
```
로더 모듈은 Node.js에서만 평가되므로, 필요에 따라 Node API와 npm 종속성을 가져올 수 있습니다.
로더 모듈은 Node.js에서만 평가되므로, 필요한 경우 Node API와 npm 종속성을 "import" 할 수 있습니다.
이 파일에서 데이터를 `.md` 페이지와 `.vue` 컴포넌트에서 `data`라는 이름으로 내보낼 수 있습니다:
그런 다음 `.md` 페이지와 `.vue` 컴포넌트에서 `data`라는 이름으로 "export" 한 데이터를 이 파일에서 "import" 할 수 있습니다:
```vue
<scriptsetup>
@ -39,9 +39,9 @@ import { data } from './example.data.js'
}
```
데이터 로더 자체가 `data`를 내보내지 않는 것을 알 수 있습니다. 이는 VitePress가 내부에서 `load()` 메서드를 호출하고 `data`라는 이름으로 결과를 암시적으로 노출한다는 것을 의미합니다.
데이터 로더 자체가 `data`를 "export" 하지 않는다는 점에 주목하십시오. VitePress가 백그라운드에서 `load()` 메서드를 호출하고 결과를 암묵적으로 `data`라는 이름으로 "export" 하기 때문입니다.
로더가 비동기인 경우에도 작동합니다:
이 방법은 로더가 비동기적이어도 작동합니다:
```js
export default {
@ -54,11 +54,11 @@ export default {
## 로컬 파일에서 데이터 가져오기 {#data-from-local-files}
로컬 파일을 기반으로 데이터를 생성해야 할 때는 데이터 로더에서 `watch` 옵션을 사용해야 합니다. 그래야 해당 파일에 변경 사항이 발생했을 때 핫 업데이트를 트리거할 수 있습니다.
로컬 파일을 기반으로 데이터를 생성해야 할 때는 데이터 로더에서 `watch` 옵션을 사용해야 합니다. 이 옵션을 사용하면 이러한 파일에 변경이 있을 때 핫 업데이트를 트리거할 수 있습니다.
`watch` 옵션은 또한 여러 파일을 일치시키기 위해 [글로브 패턴](https://github.com/mrmlnc/fast-glob#pattern-syntax)을 사용할 수 있어 편리합니다. 패턴은 로더 파일 자체에 상대적이며, `load()` 함수는 일치한 파일을 절대 경로로 받습니다.
`watch` 옵션은 또한 여러 파일을 매칭하는 [glob 패턴](https://github.com/mrmlnc/fast-glob#pattern-syntax)을 사용할 수 있어서 편리합니다. 패턴은 로더 파일 자체에 상대적일 수 있으며, `load()` 함수는 매칭된 파일을 절대 경로로 받게 됩니다.
다음 예제는 [csv-parse](https://github.com/adaltas/node-csv/tree/master/packages/csv-parse/)를 사용하여 CSV 파일을 불러오고 JSON으로 변환하는 방법을 보여줍니다. 이 파일은 빌드 시간에만 실행되므로, CSV 파서를 클라이언트에 전송하지 않을 것입니다!
다음 예제는 CSV 파일을 로드하고 이를 [csv-parse](https://github.com/adaltas/node-csv/tree/master/packages/csv-parse/)를 사용하여 JSON으로 변환하는 방법을 보여줍니다. 이 파일은 빌드할 때에만 실행되므로 CSV 파서를 클라이언트로 전송하지 않습니다!
```js
import fs from 'node:fs'
@ -67,9 +67,9 @@ import { parse } from 'csv-parse/sync'
export default {
watch: ['./data/*.csv'],
load(watchedFiles) {
// watchedFiles는 일치하는 파일의 절대 경로 배열이 될 것입니다.
// 블로그 포스트 메타데이터의 배열을 생성하여
// 테마 레이아웃에서 목록을 렌더링하는 데 사용할 수 있습니다
// watchedFiles는 매칭된 파일의 절대 경로 배열 입니다.
// 테마 레이아웃에서 목록을 렌더링하는 데 사용할 수 있는
// 블로그 포스트 메타데이터 배열을 생성합니다.
return watchedFiles.map((file) => {
return parse(fs.readFileSync(file, 'utf-8'), {
columns: true,
@ -82,38 +82,38 @@ export default {
## `createContentLoader`
콘텐츠 중심 사이트를 구축할 때, 우리는 종종 "아카이브" 또는 "인덱스" 페이지를 만들 필요가 있습니다: 우리 콘텐츠 컬렉션에서 사용 가능한 모든 항목을 나열하는 페이지, 예를 들어 블로그 게시물이나 API 페이지의 경우입니다. 데이터 로더 API를 직접 사용하여 이를 구현할 **수 있지만**, 이는 흔한 사용 사례이므로 VitePress는 이를 단순화하기 위해 `createContentLoader` 헬퍼를 제공합니다:
콘텐츠가 많은 사이트를 구축할 때, 종종 "아카이브" 또는 "인덱스" 페이지를 만들어야 합니다. 이 페이지는 콘텐츠 모음에 있는 모든 항목(예: 블로그 게시물, API 페이지)을 나열하는 페이지입니다. 데이터 로더 API를 직접 사용하여 이를 구현할 수 있지만, VitePress는 이러한 일반적인 사용 사례를 간소화하기 위해 `createContentLoader` 헬퍼를 제공합니다:
헬퍼는 [소스 디렉토리](./routing#source-directory)에 상대적인 글로브 패턴을 취하며, 기본 내보내기로 사용할 수 있는 `{ watch, load }` 데이터 로더 객체를 반환합니다. 이는 또한 파일 수정 타임스탬프를 기반으로 캐싱을 구현하여 개발 성능을 향상시킵니다.
이 헬퍼는 [소스 디렉터리](./routing#source-directory)를 기준으로 glob 패턴을 허용하고 데이터 로드 파일에서 "default export"로 사용할 수 있는 `{ watch, load }` 데이터 로더 객체를 반환합니다. 또한 파일 수정 타임스탬프를 기반으로 캐싱을 구현하여 개발 성능을 향상시킵니다.
# VitePress 사이트 배포하기 {#deploy-your-vitepress-site}
다음 가이드는 몇 가지 공유된 가정을 바탕으로 합니다:
다음 가이드는 몇 가지 공통된 가정을 기반으로 합니다:
- VitePress 사이트는 프로젝트의 `docs` 디렉토리 안에 있습니다.
- 기본 빌드 출력 디렉토리(`.vitepress/dist`)를 사용하고 있습니다.
- VitePress를 프로젝트의 로컬 의존성으로 설치했으며, `package.json`에 다음 스크립트를 설정했습니다:
- VitePress 사이트는 프로젝트의 `docs` 디렉토리 안에 있다.
- 기본 빌드 출력 디렉토리(`.vitepress/dist`)를 사용하고 있다.
- VitePress는 프로젝트의 로컬 종속성으로 설치되어 있으며, `package.json`에 다음 스크립트가 설정되어 있다:
```json
{
@ -33,9 +33,9 @@ outline: deep
$ npm run docs:preview
```
`preview` 명령어는 `.vitepress/dist` 출력 디렉토리를 `http://localhost:4173`에서 제공하는 로컬 정적 웹 서버를 부팅합니다. 이를 사용하여 프로덕션에 푸시하기 전에 모든 것이 잘 보이는지 확인할 수 있습니다.
`preview` 명령은 출력 디렉토리 `.vitepress/dist`를 `http://localhost:4173`에서 제공할 것입니다. 이를 사용하여 프로덕션에 푸시하기 전에 모든 것이 잘 보이는지 확인할 수 있습니다.
3. `--port` 인수를 전달하여 서버의 포트를 구성할 수 있습니다.
3. `--port` 인자를 전달하여 서버의 포트를 구성할 수 있습니다.
```json
{
@ -45,21 +45,21 @@ outline: deep
}
```
이제 `docs:preview` 메소드가 `http://localhost:8080`에서 서버를 시작합니다.
이제 `docs:preview` 메서드가 `http://localhost:8080`에서 서버를 시작합니다.
## public 기본 경로 설정하기 {#setting-a-public-base-path}
기본적으로, 사이트가 도메인의 루트 경로(`/`)에서 배포될 것으로 가정합니다. 사이트가 하위 경로, 예를 들어 `https://mywebsite.com/blog/`에서 제공되는 경우, VitePress 구성에서 [`base`](../reference/site-config#base) 옵션을 `'/blog/'`로 설정해야 합니다.
기본적으로 사이트가 도메인의 루트 경로(`/`)에 배포된다고 가정합니다. 예를 들어 사이트가 `https://mywebsite.com/blog/` 와 같은 서브 경로에서 제공될 경우, VitePress 구성에서 [`base`](../reference/site-config#base) 옵션을 `'/blog/'`로 설정해야 합니다.
**예:** GitHub(또는 GitLab) 페이지를 사용하여 `user.github.io/repo/`로 배포하는 경우, `base`를 `/repo/`로 설정하세요.
**예**: Github(또는 GitLab) Pages를 사용하여 `user.github.io/repo/`에 배포하는 경우, `base`를 `/repo/`로 설정하세요.
## HTTP 캐시 헤더 {#http-cache-headers}
프로덕션 서버에서 HTTP 헤더를 제어할 수 있다면, 반복 방문 시 성능을 향상시키기 위해 `cache-control` 헤더를 구성할 수 있습니다.
프로덕션 서버에서 HTTP 헤더를 제어할 수 있다면, 반복 방문 시 더 나은 성능을 위해 `cache-control` 헤더를 구성할 수 있습니다.
프로덕션 빌드는 정적 자산(JavaScript, CSS, `public`에 있지 않은 다른 가져온 자산)을 위해 해시된 파일 이름을 사용합니다. 브라우저 개발 도구의 네트워크 탭을 사용하여 프로덕션 미리보기를 검사하면,`app.4f283b18.js`와 같은 파일을 볼 수 있습니다.
프로덕션 빌드는 정적 자산(JavaScript, CSS, `public`가 아닌 곳에서 가져온 에셋)에 대해 해시된 파일 이름을 사용합니다. 브라우저 개발 도구의 네트워크 탭을 사용하여 프로덕션 미리보기를 검사하면 `app.4f283b18.js`와 같은 파일을 볼 수 있습니다.
이 `4f283b18` 해시는 이 파일의 내용에서 생성됩니다. 같은 해시된 URL은 항상 동일한 파일 내용을 제공하도록 보장됩니다 - 내용이 변경되면 URL도 변경됩니다. 이는 이러한 파일에 대해 가장 강력한 캐시 헤더를 안전하게 사용할 수 있음을 의미합니다. 이러한 모든 파일이 출력 디렉토리의 `assets/` 아래에 배치되므로, 그들을 위해 다음 헤더를 구성할 수 있습니다:
이 `4f283b18` 해시는 파일의 내용에서 생성됩니다. 동일한 해시된 URL은 동일한 파일 내용을 제공할 것이 보장되며, 내용이 변경되면 URL도 변경됩니다. 이는 이러한 파일에 대해 가장 강력한 캐시 헤더를 안전하게 사용할 수 있음을 의미합니다. 모든 이러한 파일은 출력 디렉토리의 `assets/` 아래에 배치되므로, 다음 헤더를 구성할 수 있습니다:
3. `main` 브랜치에 변경 사항을 푸시하고 GitHub Actions 워크플로우가 완료되기를 기다리세요. 설정에 따라 사이트가 `https://<username>.github.io/[repository]/` 또는 `https://<custom-domain>/`에 배포된 것을 볼 수 있습니다. `main` 브랜치에 푸시할 때마다 사이트가 자동으로 배포됩니다.
3. 변경 사항을 `main` 브랜치에 푸시하고 GitHub Actions 워크플로우가 완료될 때까지 기다립니다. 설정에 따라 사이트가 `https://<username>.github.io/[repository]/` 또는 `https://<custom-domain>/`에 배포된 것을 볼 수 있습니다. 사이트는 `main` 브랜치에 푸시할 때마다 자동으로 배포됩니다.
@ -282,19 +281,19 @@ HTML 코드에 대해 _Auto Minify_와 같은 옵션을 활성화하지 마세
### Edgio
[Edgio에 VitePress 앱 생성 및 배포하기](https://docs.edg.io/guides/vitepress)를 참조하세요.
[Edgio에 VitePress 앱 생성 및 배포하기](https://docs.edg.io/guides/vitepress)를 참고하세요.
### Kinsta 정적 사이트 호스팅 {#kinsta-static-site-hosting}
[Kinsta](https://kinsta.com/static-site-hosting/)에서 VitePress 웹사이트를 배포하는 방법은 [이 지침](https://kinsta.com/docs/vitepress-static-site-example/)을 따르세요.
[VitePress](https://kinsta.com/static-site-hosting/) 웹사이트를 [Kinsta](https://kinsta.com/static-site-hosting/)에 배포하려면 이 [지침](https://kinsta.com/docs/vitepress-static-site-example/)을 따르세요.
### 스톰킷
### Stormkit
VitePress 프로젝트를 [Stormkit](https://www.stormkit.io)에 배포하려면 이 [지침](https://stormkit.io/blog/how-to-deploy-vitepress)을 따르세요.
[VitePress](https://stormkit.io) 프로젝트를 [Stormkit](https://www.stormkit.io)에 배포하려면 이 [지침](https://stormkit.io/blog/how-to-deploy-vitepress)을 따르세요.
### Nginx
다음은 Nginx 서버 블록 구성의 예입니다. 이 설정에는 일반적인 텍스트 기반 자산에 대한 gzip 압축, 적절한 캐싱 헤더로 VitePress 사이트의 정적 파일을 제공하는 규칙, `cleanUrls: true`를 처리하는 규칙이 포함되어 있습니다.
다음은 Nginx 서버 블록 구성의 예입니다. 이 설정은 일반적인 텍스트 기반 에셋에 대한 gzip 압축, VitePress 사이트의 정적 파일을 적절한 캐싱 헤더와 함께 제공하는 규칙 및 `cleanUrls: true`를 처리하는 규칙을 포함합니다.
```nginx
server {
@ -306,20 +305,20 @@ server {
index index.html;
location / {
# 내용 위치
# 콘텐츠 위치
root /app;
# 정확한 일치 -> 깨끗한 URL로 처리 -> 폴더 -> 찾을 수 없음
# 정확히 일치하는 파일 -> 정제된 URL로 역방향 매핑 -> 폴더 -> 파일 없음
try_files $uri $uri.html $uri/ =404;
# 존재하지 않는 페이지
error_page 404 /404.html;
# index.html이 없는 폴더는 이 설정에서 403을 발생시킴
# index.html이 없는 폴더는 이 설정에서 403 오류를 발생시킴
error_page 403 /404.html;
# 캐싱 헤더 조정
# assets 폴더의 파일은 해시 파일 이름을 가짐
# assets 폴더의 파일들은 해시된 파일명 사용
location ~* ^/assets/ {
expires 1y;
add_header Cache-Control "public, immutable";
@ -328,10 +327,10 @@ server {
}
```
이 구성은 빌드된 VitePress 사이트가 서버상의 `/app` 디렉토리에 위치한다고 가정합니다. 사이트 파일이 다른 곳에 위치한 경우 `root` 지시문을 그에 맞게 조정하세요.
이 구성은 빌드된 VitePress 사이트가 서버의 `/app` 디렉토리에 위치한다고 가정합니다. 사이트 파일이 다른 곳에 위치한 경우 `root` 지시문을 적절하게 조정하세요.
::: warning index.html을 기본값으로 설정하지 마세요.
try_files 해결은 다른 Vue 애플리케이션처럼 index.html로 기본 설정되어서는 안 됩니다. 이것은 유효하지 않은 페이지 상태로 이어질 것입니다.
try_files는 다른 Vue 애플리케이션처럼 index.html을 기본값으로 할 수 없습니다. 이는 페이지 상태가 유효하지 않게 만듭니다.
:::
추가 정보는 [공식 nginx 문서](https://nginx.org/en/docs/), 이슈 [#2837](https://github.com/vuejs/vitepress/discussions/2837), [#3235](https://github.com/vuejs/vitepress/issues/3235) 그리고 Mehdi Merah의 [블로그 포스트](https://blog.mehdi.cc/articles/vitepress-cleanurls-on-nginx-environment#readings)에서 찾을 수 있습니다.
추가 정보는 [공식 nginx 문서](https://nginx.org/en/docs/), 이슈 [#2837](https://github.com/vuejs/vitepress/discussions/2837), [#3235](https://github.com/vuejs/vitepress/issues/3235) 및 Mehdi Merah의 [블로그 포스트](https://blog.mehdi.cc/articles/vitepress-cleanurls-on-nginx-environment#readings)에서 확인할 수 있습니다.
VitePress의 기본 테마는 문서화에 최적화되어 있으며, 커스터마이징이 가능합니다. [기본 테마 구성 개요](../reference/default-theme-config)를 참조하여 가능한 옵션의 전체 목록을 확인하세요.
VitePress의 기본 테마는 문서화에 최적화되어 있으며, 커스텀할 수 있습니다. 포괄적인 옵션 목록은 [기본 테마 구성](../reference/default-theme-config)을 참고하세요.
그러나 설정만으로는 충분하지 않은 경우가 여러 번 있을 수 있습니다. 예를 들면:
그러나 구성만으로는 충분하지 않을 수 있습니다. 예를 들어:
1. CSS 스타일링을 조정해야 할 때;
2. 전역 컴포넌트 등록과 같이 Vue 앱 인스턴스를 수정해야 할 때;
3. 레이아웃 슬롯을 통해 테마에 사용자 정의 컨텐츠를 삽입해야 할 때.
1. CSS 스타일링을 조정해야 하는 경우.
2. 전역 컴포넌트를 등록하기 위해 Vue 애플리케이션 인스턴스를 수정해야 하는 경우.
3. 레이아웃 슬롯을 통해 테마에 커스텀 컨텐츠를 삽입해야 하는 경우.
이러한 고급 커스터마이징은 기본 테마를 "확장하는" 사용자 지정 테마를 사용해야 합니다.
이러한 고급 커스터마이징은 기본 테마를 "확장"하는 커스텀 테마 사용이 필요 합니다.
::: tip
진행하기 전에, 사용자 지정 테마가 어떻게 작동하는지 이해하기 위해 [사용자 지정 테마 사용하기](./custom-theme)를 먼저 읽어보세요.
진행하기 전에, 커스텀 테마가 어떻게 작동하는지 이해하려면 먼저 [커스텀 테마 사용하기](./custom-theme)를 읽어보세요.
:::
## CSS 커스터마이징하기 {#customizing-css}
기본 테마의 CSS는 루트 레벨 CSS 변수를 오버라이딩하여 커스터마이즈 할 수 있습니다:
기본 테마의 CSS는 루트 레벨의 CSS 변수를 재정의하여 커스터마이징 할 수 있습니다:
```js
// .vitepress/theme/index.js
@ -38,13 +38,13 @@ export default DefaultTheme
}
```
오버라이딩할 수 있는 [기본 테마 CSS 변수](https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css)를 확인하세요.
재정의할 수 있는 기본 테마 CSS 변수는 [여기](https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css)를 참고하세요.
## 다른 폰트 사용하기 {#using-different-fonts}
VitePress는 기본 폰트로 [Inter](https://rsms.me/inter/)를 사용하며, 빌드 출력물에 폰트를 포함합니다. 또한, 이 폰트는 프로덕션 환경에서 자동으로 프리로드됩니다. 하지만, 다른 메인 폰트를 사용하고 싶은 경우에는 바람직하지 않을 수 있습니다.
VitePress는 기본 폰트로 [Inter](https://rsms.me/inter/)를 사용하며, 빌드 결과물에 폰트를 포함시킵니다. 폰트는 프로덕션 환경에서 자동으로 미리 로드되지만, 다른 메인 폰트를 사용하고자 할 경우 이는 바람직하지 않을 수 있습니다.
빌드 출력물에서 Inter를 포함하지 않으려면, 대신 `vitepress/theme-without-fonts`에서 테마를 임포트하세요:
[팀 페이지](../reference/default-theme-team-page)와 같은 선택적 컴포넌트를 사용하는 경우, 이들도 `vitepress/theme-without-fonts`에서 가져와야 합니다!
선택적 컴포넌트인 [팀 페이지](../reference/default-theme-team-page) 등을 사용하는 경우, 반드시 이들도 `vitepress/theme-without-fonts`에서 "import" 해야 합니다!
:::
폰트가 `@font-face`를 통해 참조된 로컬 파일이라면, 자산으로 처리되어 해시된 파일명과 함께 `.vitepress/dist/assets` 아래에 포함될 것입니다. 이 파일을 프리로드하려면, [transformHead](../reference/site-config#transformhead) 빌드 훅을 사용하세요:
폰트가 `@font-face`를 통해 참조된 로컬 파일인 경우, 에셋으로 처리되어 해시된 파일 이름으로 `.vitepress/dist/assets`에 포함됩니다. 이 파일을 미리 로드하려면 [transformHead](../reference/site-config#transformhead) 빌드 훅을 사용해야 합니다:
```js
// .vitepress/config.js
@ -102,7 +102,7 @@ import DefaultTheme from 'vitepress/theme'
export default {
extends: DefaultTheme,
enhanceApp({ app }) {
// 사용자 지정 전역 컴포넌트를 등록하세요
// 커스텀 전역 컴포넌트 등록
app.component('MyGlobalComponent' /* ... */)
}
}
@ -117,17 +117,17 @@ import DefaultTheme from 'vitepress/theme'
export default {
extends: DefaultTheme,
enhanceApp({ app }) {
// 사용자 지정 전역 컴포넌트를 등록하세요
// 커스텀 전역 컴포넌트 등록
app.component('MyGlobalComponent' /* ... */)
}
} satisfies Theme
```
Vite를 사용하기 때문에, Vite의 [글로브 임포트 기능](https://vitejs.dev/ko/guide/features.html#glob-import)을 활용하여 컴포넌트 디렉터리를 자동으로 등록할 수도 있습니다.
Vite를 사용하므로, Vite의 [glob import 기능](https://vitejs.dev/guide/features.html#glob-import)을 활용하여 컴포넌트 디렉터리를 자동으로 등록할 수 있습니다.
## 레이아웃 슬롯 {#layout-slots}
기본 테마의 `<Layout/>` 컴포넌트는 페이지의 특정 위치에 컨텐츠를 삽입할 수 있도록 몇 개의 슬롯을 제공합니다. 아웃라인 앞에 컴포넌트를 삽입하는 예시입니다:
기본 테마의 `<Layout/>` 컴포넌트는 페이지의 특정 위치에 컨텐츠를 삽입할 수 있는 몇 가지 슬롯을 가지고 있습니다. 다음은 아웃라인 앞에 컴포넌트를 삽입하는 예제입니다:
```js
// .vitepress/theme/index.js
@ -137,7 +137,7 @@ import MyLayout from './MyLayout.vue'
뷰 전환에 대한 자세한 정보는 [Chrome 문서](https://developer.chrome.com/docs/web-platform/view-transitions/)를 참고하세요.
뷰 트랜지션에 대한 자세한 정보는 [크롬 문서](https://developer.chrome.com/docs/web-platform/view-transitions/)를 참고하세요.
### 라우트 변경 시 {#on-route-change}
곧 제공될 예정입니다.
## 내부 컴포넌트 오버라이딩하기 {#overriding-internal-components}
## 내부 컴포넌트 재정의하기 {#overriding-internal-components}
Vite의 [별칭](https://vitejs.dev/config/shared-options.html#resolve-alias)을 사용하여 기본 테마 컴포넌트를 사용자 지정 컴포넌트로 대체할 수 있습니다:
Vite의 [별칭](https://vitejs.dev/config/shared-options.html#resolve-alias)을 사용하여 기본 테마 컴포넌트를 커스텀 컴포넌트로 대체할 수 있습니다:
```ts
import { fileURLToPath, URL } from 'node:url'
@ -338,4 +338,4 @@ export default defineConfig({
})
```
컴포넌트의 정확한 이름을 알고 싶다면 [저희 소스 코드](https://github.com/vuejs/vitepress/tree/main/src/client/theme-default/components)를 참조하세요. 컴포넌트가 내부적으로 사용되기 때문에, 소규모 릴리스 사이에 이름이 업데이트될 수 있습니다.
컴포넌트의 정확한 이름을 알고 싶다면 [Vitepress 소스 코드](https://github.com/vuejs/vitepress/tree/main/src/client/theme-default/components)를 참고하세요. 컴포넌트는 내부적으로 사용되기 때문에, 마이너 릴리즈 사이에 이름이 변경될 가능성이 있습니다.
VitePress는 모든 Markdown 파일에서 YAML 전문(frontmatter)을 지원하며, 이를 [gray-matter](https://github.com/jonschlinkert/gray-matter)로 분석합니다. 전문은 Markdown 파일의 맨 위에 위치해야 합니다(`<script>` 태그를 포함한 모든 요소 이전에)하며, 세 개의 대시 라인 사이에 유효한 YAML 형식으로 설정되어야 합니다. 예시:
VitePress는 모든 마크다운 파일에서 YAML 전문(frontmatter)을 지원하며, [gray-matter](https://github.com/jonschlinkert/gray-matter)로 이를 파싱합니다. 전문은 마크다운 파일의 맨 위에 있어야 하며(모든 엘리먼트 포함 `<script>` 태그 이전), 세 개의 대시 라인 사이에 유효한 YAML 형태로 작성되어야 합니다. 예:
```md
---
@ -11,15 +11,15 @@ editLink: true
---
```
많은 사이트 또는 기본 테마 구성 옵션이 전문에서 대응하는 옵션을 가지고 있습니다. 전문을 사용하여 현재 페이지에 대한 특정 동작을 재정의할 수 있습니다. 자세한 내용은 [전문 구성 참조](../reference/frontmatter-config)를 참조하십시오.
많은 사이트 또는 기본 테마 구성 옵션은 전문에 해당 옵션이 있습니다. 전문을 사용하여 현재 페이지에 대한 특정 동작을 재정의할 수 있습니다. 자세한 내용은 [전문 구성 레퍼런스](../reference/frontmatter-config)를 참고하세요.
또한 페이지상의 동적 Vue 표현식에서 사용될 수 있는 자체적인 전문 데이터를 정의할 수 있습니다.
또한 페이지에서 동적 Vue 표현식에 사용할 커스텀 전문 데이터를 정의할 수도 있습니다.
## 전문 데이터 접근 {#accessing-frontmatter-data}
## 전문 데이터에 접근하기 {#accessing-frontmatter-data}
전문 데이터는 특별한 `$frontmatter` 전역 변수를 통해 접근할 수 있습니다:
여기 Markdown 파일에서 사용하는 방법의 예시입니다:
다음은 마크다운 파일에서 이를 사용하는 예입니다:
```md
---
@ -32,11 +32,11 @@ editLink: true
가이드 내용
```
`<script setup>`에서 현재 페이지의 전문 데이터에 접근하려면 [`useData()`](../reference/runtime-api#usedata) 헬퍼를 사용할 수 있습니다.
현재 페이지의 전문 데이터는 [`useData()`](../reference/runtime-api#usedata) 헬퍼를 사용하여 `<script setup>`에서도 접근할 수 있습니다.
브라우저에서 바로 VitePress를 시도해 볼 수 있습니다 [StackBlitz](https://vitepress.new).
[StackBlitz](https://vitepress.new)에서 브라우저로 즉시 VitePress를 사용해 볼 수 있습니다.
## 설치 {#installation}
@ -11,10 +11,10 @@
- [Node.js](https://nodejs.org/) 버전 18 이상.
- VitePress를 명령줄 인터페이스(CLI)를 통해 접근하기 위한 터미널.
- [Markdown](https://en.wikipedia.org/wiki/Markdown) 문법 지원이 있는 텍스트 에디터.
- [마크다운](https://en.wikipedia.org/wiki/Markdown) 문법 지원이 있는 텍스트 에디터.
- [VSCode](https://code.visualstudio.com/)와 [공식 Vue 확장 프로그램](https://marketplace.visualstudio.com/items?itemName=Vue.volar) 사용을 권장합니다.
VitePress는 독립 실행형으로 사용하거나 기존 프로젝트에 설치할 수 있습니다. 어떤 경우든 다음과 같이 설치할 수 있습니다:
VitePress는 단독으로 사용하거나 기존 프로젝트에 설치할 수 있습니다. 두 경우 모두 다음과 같이 설치할 수 있습니다:
::: code-group
@ -40,8 +40,8 @@ $ bun add -D vitepress
:::
::: details 필요한 피어 종속성 경고가 나타나나요?
PNPM을 사용할 경우 `@docsearch/js`에 대한 누락된 피어 경고를 볼 수 있습니다. 이것은 VitePress 작동을 방해하지 않습니다. 이 경고를 억제하려면, `package.json`에 다음을 추가하세요:
::: details "missing peer deps" 경고가 표시되나요?
PNPM을 사용하는 경우 `@docsearch/js`에 대한 "missing peer deps" 경고가 표시됩니다. 이는 VitePress가 작동하는 것을 방해하지 않습니다. 이 경고를 억제하려면 `package.json`에 다음을 추가합니다:
```json
"pnpm": {
@ -58,13 +58,13 @@ PNPM을 사용할 경우 `@docsearch/js`에 대한 누락된 피어 경고를
::: tip 참고
VitePress는 ESM-only 패키지입니다. `require()`를 사용하여 가져오지 마십시오, 그리고 가장 가까운`package.json`에 `"type": "module"`이 포함되어 있는지 확인하거나, 관련 파일(예: `.vitepress/config.js`)의 확장자를 `.mjs`/`.mts`로 변경하십시오. 자세한 내용은 [Vite의 문제 해결 가이드](http://vitejs.dev/ko/guide/troubleshooting.html#this-package-is-esm-only)를 참조하십시오. 또한, 비동기 CJS 컨텍스트 내에서는 대신`await import('vitepress')`를 사용할 수 있습니다.
VitePress는 ESM 전용 패키지입니다. `require()`를 사용하여 가져오지 마시고,`package.json`에 `"type": "module"`이 포함되어 있는지 확인하거나, 관련 파일(예: `.vitepress/config.js`)의 확장자를 `.mjs`/`.mts`로 변경하세요. 자세한 내용은 [Vite 문제 해결 가이드](http://vitejs.dev/ko/guide/troubleshooting.html#this-package-is-esm-only)를 참고하세요. 또한, 비동기 CJS 컨텍스트에서는`await import('vitepress')`를 사용할 수 있습니다.
:::
### 설정 마법사 {#setup-wizard}
VitePress는 기본 프로젝트를 스캐폴딩하는 데 도움이 되는 명령줄 설정 마법사를 제공합니다. 설치 후, 마법사를 시작하려면 다음을 실행하세요:
VitePress는 기본 프로젝트를 구축하는 데 도움이 되는 명령줄 설정 마법사를 제공합니다. 설치 후, 마법사를 시작하려면 다음을 실행하세요:
커스텀을 위해 Vue 컴포넌트나 API를 사용하려는 경우, `vue`를 명시적으로 의존성으로 설치해야 합니다.
:::
## 파일 구조 {#file-structure}
독립 실행형 VitePress 사이트를 빌딩하는 경우, 현재 디렉토리(`./`)에 사이트를 스캐폴딩할 수 있습니다. 그러나 다른 소스 코드와 함께 기존 프로젝트에 VitePress를 설치하는 경우, 프로젝트의 나머지 부분과 별도로 (`예: `./docs`) 중첩된 디렉토리에 사이트를 스캐폴딩하는 것이 좋습니다.
독립형 VitePress 사이트를 구축하려는 경우, 현재 디렉터리(`./`)에 사이트를 구축할 수 있습니다. 그러나 기존 프로젝트에서 다른 소스 코드와 함께 VitePress를 설치하는 경우, 프로젝트의 나머지 부분과 분리되도록 중첩된 디렉터리(e.g. `./docs`)에 사이트를 구축하는 것이 좋습니다.
VitePress 프로젝트를 `./docs`에 스캐폴딩하기로 선택한 경우 생성된 파일 구조는 다음과 같아야 합니다:
VitePress 프로젝트를 `./docs`에 구축하기로 한 경우, 생성된 파일 구조는 다음과 같아야 합니다:
```
.
@ -111,42 +111,42 @@ VitePress 프로젝트를 `./docs`에 스캐폴딩하기로 선택한 경우 생
└─ package.json
```
`docs` 디렉토리는 VitePress 사이트의 **프로젝트 루트**로 간주됩니다. `.vitepress` 디렉토리는 VitePress의 설정 파일, 개발 서버 캐시, 빌드 출력 및 선택적 테마 사용자 정의 코드를 위한 예약된 위치입니다.
`docs` 디렉터리는 VitePress 사이트의 **프로젝트 루트**로 간주됩니다. `.vitepress` 디렉터리는 VitePress의 구성 파일, 개발 서버 캐시, 빌드 출력, 선택적 커스텀 테마 코드가 있는 위치입니다.
::: tip
기본적으로, VitePress는 개발 서버 캐시를 `.vitepress/cache`에, 프로덕션 빌드 출력을 `.vitepress/dist`에 저장합니다. Git을 사용하는 경우, 이들을 `.gitignore` 파일에 추가해야 합니다. 이 위치는 또한 [구성할 수 있습니다](../reference/site-config#outdir).
기본적으로 VitePress는 개발 서버 캐시를 `.vitepress/cache`에 저장하고, 프로덕션 빌드 출력을 `.vitepress/dist`에 저장합니다. Git을 사용하는 경우, 이러한 디렉토리를 `.gitignore` 파일에 추가해야 합니다. 또는 이러한 위치를 수동으로 [구성](../reference/site-config#outdir)할 수도 있습니다.
:::
### 설정 파일 {#the-config-file}
### 구성 파일 {#the-config-file}
설정 파일(`.vitepress/config.js`)을 사용하면 사이트의 제목과 설명과 같은 VitePress 사이트의 다양한 측면을 커스터마이즈할 수 있습니다:
구성 파일(`.vitepress/config.js`)을 사용하면 사이트의 제목과 설명과 같은 VitePress 사이트의 다양한 측면을 커스터마이즈할 수 있습니다:
```js
// .vitepress/config.js
export default {
// 사이트 수준 옵션
// 사이트 옵션
title: 'VitePress',
description: '그냥 해보는 중.',
themeConfig: {
// 테마 수준 옵션
// 테마 옵션
}
}
```
`themeConfig` 옵션을 통해 테마의 동작을 구성할 수도 있습니다. 모든 구성 옵션에 대한 전체 세부 정보는 [구성 참조](../reference/site-config)를 참조하십시오.
테마의 동작은 `themeConfig` 옵션을 통해 구성할 수도 있습니다. 모든 구성 옵션에 대한 자세한 내용은 [구성 레퍼런스](../reference/site-config)를 참고하세요.
### 소스 파일 {#source-files}
`.vitepress` 디렉토리 밖의 마크다운 파일들은 **소스 파일**로 간주됩니다.
`.vitepress` 디렉토리 외부의 마크다운 파일은 **소스 파일**로 간주됩니다.
VitePress는 **파일 기반 라우팅**을 사용합니다: 각 `.md` 파일은 동일한 경로에 해당하는 `.html` 파일로 컴파일됩니다. 예를 들어, `index.md`는 `index.html`로 컴파일되며, 결과적인 VitePress 사이트의 루트 경로 `/`에서 방문할 수 있습니다.
VitePress는 **파일 기반 라우팅**을 사용합니다: 각 `.md` 파일은 동일한 경로에 해당하는 `.html` 파일로 컴파일됩니다. 예를 들어, `index.md`는 `index.html`로 컴파일되며, 결과적으로 VitePress 사이트의 루트 경로 `/`에서 방문할 수 있습니다.
VitePress는 또한 깨끗한 URL 생성, 경로 리라이팅 및 동적 페이지 생성 기능을 제공합니다. 이러한 내용은 [라우팅 가이드](./routing)에서 다뤄질 것입니다.
또한 VitePress는 간결한 URL 생성, 경로 재작성, 동적 페이지 생성 기능을 제공합니다. 이러한 내용은 [라우팅 가이드](./routing)에서 다룹니다.
## 실행 및 작동 {#up-and-running}
설정 프로세스 중에 허용한 경우, 도구는 `package.json`에 다음 npm 스크립트를 주입해야 합니다:
설치 과정에서 허용한 경우, 도구는 다음 npm 스크립트를 `package.json`에 추가했을 것입니다:
```json
{
@ -160,7 +160,7 @@ VitePress는 또한 깨끗한 URL 생성, 경로 리라이팅 및 동적 페이
}
```
`docs:dev` 스크립트는 즉각적인 핫 업데이트를 제공하는 로컬 개발 서버를 시작합니다. 다음 명령으로 실행하세요:
`docs:dev` 스크립트는 즉각적인 핫 업데이트가 가능한 로컬 개발 서버를 시작합니다. 다음 명령어로 실행할 수 있습니다:
::: code-group
@ -182,7 +182,7 @@ $ bun run docs:dev
:::
npm 스크립트 대신, 다음과 같이 VitePress를 직접 호출할 수도 있습니다:
npm 스크립트 대신 VitePress를 직접 호출할 수도 있습니다:
::: code-group
@ -204,18 +204,18 @@ $ bun vitepress dev docs
:::
명령줄 사용법은 [CLI 참조](../reference/cli)에 문서화되어 있습니다.
더 많은 명령줄 사용법은 [CLI 레퍼런스](../reference/cli)에 문서화되어 있습니다.
개발 서버는 `http://localhost:5173`에서 실행되어야 합니다. 브라우저에서 URL을 방문하여 새 사이트를 확인하세요!
## 다음 단계는? {#what-s-next}
- 생성된 HTML로 마크다운 파일이 어떻게 매핑되는지 더 잘 이해하려면, [라우팅 가이드](./routing)로 진행하세요.
- 마크다운과 이 파일로 생성된 HTML이 어떻게 매핑되는지 더 잘 이해하려면 [라우팅 가이드](./routing)를 참고하세요.
- 페이지에서 할 수 있는 일에 대해 더 알아보려면, 마크다운 콘텐츠 작성이나 Vue 컴포넌트 사용과 같은 "작성" 섹션의 가이드를 참조하십시오. 시작하기 좋은 곳은 [마크다운 확장](./markdown)에 대해 배우는 것입니다.
- 페이지에서 할 수 있는 작업, 예를 들어 마크다운 콘텐츠 작성이나 Vue 컴포넌트 사용에 대해 더 알아보려면 가이드의 "글쓰기" 섹션을 참조하세요. 시작하기 좋은 곳은 [마크다운 확장](./markdown)에 대해 배우는 것입니다.
- 기본 문서 테마가 제공하는 기능을 탐색하려면, [기본 테마 구성 참조](../reference/default-theme-config)를 확인하세요.
- 기본 문서 테마에서 제공하는 기능을 탐색하려면 [기본 테마 구성 레퍼런스](../reference/default-theme-config)를 확인하세요.
- 사이트의 모양을 더욱 커스터마이즈하고 싶다면, [기본 테마 확장](./extending-default-theme)이나 [커스텀 테마 빌드](./custom-theme)하는 방법을 탐색해보세요.
- 사이트의 외관을 더 맞춤화하려면 [기본 테마 확장](./extending-default-theme) 또는 [커스텀 테마 빌드](./custom-theme)를 탐색하세요.
- 문서 사이트가 구성되기 시작하면, [배포 가이드](./deploy)를 반드시 읽어보세요.
기본 테마의 플레이스홀더 텍스트를 사용자 정의하는 방법은 [`DefaultTheme.Config`](https://github.com/vuejs/vitepress/blob/main/types/default-theme.d.ts) 인터페이스를 참조하세요. 로케일 레벨에서 `themeConfig.algolia` 또는 `themeConfig.carbonAds`를 덮어쓰지 마세요. 다국어 검색을 사용하는 방법에 대해서는 [Algolia 문서](../reference/default-theme-search#i18n)를 참조하세요.
기본 테마의 플레이스홀더 텍스트를 커스텀하는 방법에 대한 자세한 내용은 [`DefaultTheme.Config`](https://github.com/vuejs/vitepress/blob/main/types/default-theme.d.ts) 인터페이스를 참고하십시오. 로케일 수준에서 `themeConfig.algolia` 또는 `themeConfig.carbonAds`를 재정의하지 마십시오. 다국어 검색을 사용하려면 [Algolia docs](../reference/default-theme-search#i18n)를 참조하십시오.
**전문가 팁:** 구성 파일은 `docs/.vitepress/config/index.ts`에도 저장될 수 있습니다. 로케일별로 구성 파일을 생성한 다음 이를 `index.ts`에서 병합하여 내보내는 것으로, 내용을 구성하는데 도움이 될 수 있습니다.
**전문가 팁:** 구성 파일은 `docs/.vitepress/config/index.ts`로 저장할 수도 있습니다. 로케일마다 구성 파일을 생성한 후 `index.ts`에서 병합하고 내보내어 내용을 구성하는 데 도움이 될 수 있습니다.
## 각 로케일별 별도의 디렉토리 {#separate-directory-for-each-locale}
## 각 로케일별 디렉토리 {#separate-directory-for-each-locale}
다음은 완전히 괜찮은 구조입니다:
다음은 완벽한 구조입니다:
```
docs/
@ -68,7 +67,7 @@ docs/
├─ foo.md
```
그러나, VitePress는 기본적으로 `/`를 `/en/`로 리다이렉트하지 않습니다. 이를 위해 서버를 구성해야 합니다. 예를 들어, Netlify에서는 다음과 같이 `docs/public/_redirects` 파일을 추가할 수 있습니다:
그러나 기본적으로 VitePress는 `/`를 `/en/`로 리다이렉션하지 않습니다. 이를 위해 서버를 구성해야 합니다. 예를 들어, Netlify에서는 다음과 같이 `docs/public/_redirects` 파일을 추가할 수 있습니다:
```
/* /es/:splat 302 Language=es
@ -76,7 +75,7 @@ docs/
/* /en/:splat 302
```
**전문가 팁:** 위의 접근 방식을 사용한다면, `nf_lang` 쿠키를 사용하여 사용자의 언어 선택을 유지할 수 있습니다:
**전문가 팁:** 위의 접근 방식을 사용하는 경우 `nf_lang` 쿠키를 사용하여 유저의 언어 선택을 유지할 수 있습니다:
```ts
// docs/.vitepress/theme/index.ts
@ -111,4 +110,4 @@ watchEffect(() => {
## RTL 지원 (실험적) {#rtl-support-experimental}
RTL 지원을 위해, 설정에서`dir: 'rtl'`을 지정하고 <https://github.com/MohammadYounes/rtlcss>, <https://github.com/vkalinichev/postcss-rtl>, 또는 <https://github.com/elchininet/postcss-rtlcss>과 같은 RTLCSS PostCSS 플러그인을 사용하세요. CSS 전문성 문제를 방지하기 위해 `:where([dir="ltr"])` 및 `:where([dir="rtl"])`을 접두사로 사용하여 PostCSS 플러그인을 구성해야 합니다.
RTL 지원을 위해, 구성 파일에`dir: 'rtl'`을 지정하고 <https://github.com/MohammadYounes/rtlcss>, <https://github.com/vkalinichev/postcss-rtl> 또는 <https://github.com/elchininet/postcss-rtlcss>와 같은 RTLCSS PostCSS 플러그인을 사용하세요. PostCSS 플러그인을 구성하여 CSS 명시성 문제를 방지하기 위해 `:where([dir="ltr"])` 및 `:where([dir="rtl"])`을 접두사로 사용해야 합니다.
또한, 사이트 구성에서 다음과 같은 내용을 추가하여 전역적으로 사용자 정의 제목을 설정할 수 있습니다. 영어로 작성하지 않는 경우 유용합니다:
또는 사이트 구성에 다음을 추가하여 커스텀 제목을 전역적으로 설정할 수 있습니다. 이는 제목을 영어로 작성하지 않을 경우 유용합니다:
```ts
// config.ts
@ -227,7 +227,7 @@ export default defineConfig({
### `raw`
VitePress와 스타일 및 라우터 충돌을 방지하기 위해 사용될 수 있는 특수 컨테이너입니다. 이는 특히 컴포넌트 라이브러리를 문서화할 때 유용합니다. 더 나은 격리를 위해 [whyframe](https://whyframe.dev/docs/integrations/vitepress)을 확인해보세요.
이것은 VitePress와 스타일 및 라우터 충돌을 방지하기 위해 사용할 수 있는 특별한 컨테이너입니다. 컴포넌트 라이브러리를 문서화할 때 특히 유용합니다. 더 나은 분리를 위해 [whyframe](https://whyframe.dev/docs/integrations/vitepress)을 참고해 볼 수 있습니다.
**문법**
@ -237,15 +237,15 @@ VitePress와 스타일 및 라우터 충돌을 방지하기 위해 사용될 수
:::
```
`vp-raw` 클래스는 직접 요소에 사용될 수도 있습니다. 현재 스타일 격리는 선택 사항입니다:
`vp-raw` 클래스는 엘리먼트에 직접 사용할 수도 있습니다. 스타일 분리는 현재 선택 사항입니다:
- 원하는 패키지 관리자로`postcss`를 설치하세요:
- 선호하는 패키지 매니저를 사용하여`postcss`를 설치하세요:
```sh
$ npm add -D postcss
```
- `docs/postcss.config.mjs`라는 파일을 만들고 이것을 추가하세요:
- `docs/postcss.config.mjs`라는 파일을 만들고 다음 내용을 추가하세요:
```js
import { postcssIsolateStyles } from 'vitepress'
@ -255,7 +255,7 @@ VitePress와 스타일 및 라우터 충돌을 방지하기 위해 사용될 수
}
```
이것은 내부적으로 [`postcss-prefix-selector`](https://github.com/postcss/postcss-load-config)를 사용합니다. 이렇게 옵션을 전달할 수 있습니다:
이것은 기본적으로 [`postcss-prefix-selector`](https://github.com/postcss/postcss-load-config)를 사용합니다. 다음과 같이 옵션을 전달할 수 있습니다:
```js
postcssIsolateStyles({
@ -263,45 +263,45 @@ VitePress와 스타일 및 라우터 충돌을 방지하기 위해 사용될 수
})
```
## GitHub 스타일 경고 {#github-flavored-alerts}
## GitHub 스타일 알림 {#github-flavored-alerts}
VitePress는 [GitHub 스타일 경고](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)를 콜아웃으로 렌더링하는 것을 지원합니다. 이것은 [사용자 정의 컨테이너](#custom-containers)와 같은 방식으로 렌더링됩니다.
VitePress는 [GitHub 스타일 알림](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)을 콜아웃으로 렌더링하는 것을 지원합니다. 이것은 [커스텀 컨테이너](#custom-containers)와 같은 방식으로 렌더링됩니다.
```md
> [!NOTE]
> 사용자가 훑어보더라도 알아야 할 정보를 강조합니다.
> 문서를 빠르게 탐색할 때에도 사용자가 놓치지 말아야 할 중요한 정보.
> [!TIP]
> 사용자가 더 성공할 수 있도록 도움이 되는 선택적 정보입니다.
> 사용자가 보다 원활하게 목표를 달성하는 데 도움이 되는 정보
> [!IMPORTANT]
> 사용자가 성공하기 위해 필수적인 중요 정보입니다.
> 사용자가 목표를 달성하는 데 중요한 정보.
> [!WARNING]
> 잠재적인 위험으로 인해 즉각적인 사용자의 주의를 요하는 중요한 내용입니다.
> 위험 가능성 때문에 사용자의 즉각적인 주의가 필요한 중요한 정보.
> [!CAUTION]
> 행동의 부정적인 잠재적 결과입니다.
> 실행할 경우 잠재적으로 부정적인 결과를 생성한다는 것을 알리는 정보.
```
> [!NOTE]
> 사용자가 훑어보더라도 알아야 할 정보를 강조합니다.
> 문서를 빠르게 탐색할 때에도 사용자가 놓치지 말아야 할 중요한 정보.
> [!TIP]
> 사용자가 더 성공할 수 있도록 도움이 되는 선택적 정보입니다.
> 사용자가 보다 원활하게 목표를 달성하는 데 도움이 되는 정보
> [!IMPORTANT]
> 사용자가 성공하기 위해 필수적인 중요 정보입니다.
> 사용자가 목표를 달성하는 데 중요한 정보.
> [!WARNING]
> 잠재적인 위험으로 인해 즉각적인 사용자의 주의를 요하는 중요한 내용입니다.
> 위험 가능성 때문에 사용자의 즉각적인 주의가 필요한 중요한 정보.
> [!CAUTION]
> 행동의 부정적인 잠재적 결과입니다.
> 실행할 경우 잠재적으로 부정적인 결과를 생성한다는 것을 알리는 정보.
## 코드 블록 내 구문 강조 {#syntax-highlighting-in-code-blocks}
VitePress는 마크다운 코드 블록 내 언어 문법을 색상이 있는 텍스트로 강조하는 데 [Shiki](https://github.com/shikijs/shiki)를 사용합니다. Shiki는 다양한 프로그래밍 언어를 지원합니다. 코드 블록의 시작 백틱에 유효한 언어 별칭을 추가하기만 하면 됩니다:
VitePress는 마크다운 코드 블록 내 언어 문법을 색상이 있는 텍스트로 강조하기 위해 [Shiki](https://github.com/shikijs/shiki)를 사용합니다. Shiki는 다양한 프로그래밍 언어를 지원합니다. 코드 블록의 시작 백틱에 유효한 언어 별칭을 추가하기만 하면 됩니다:
**입력**
@ -341,9 +341,9 @@ export default {
</ul>
```
Shiki의 저장소에서 사용 가능한 [유효한 언어 목록](https://shiki.style/languages)이 제공됩니다.
Shiki의 리포지터리에서 사용 가능한 [유효한 언어 목록](https://shiki.style/languages)이 제공됩니다.
또한 응용 프로그램 구성에서 구문 강조 테마를 사용자 지정할 수 있습니다. 자세한 내용은 [`markdown` 옵션](../reference/site-config#markdown)을 참조하세요.
또한 애플리케이션 구성에서 구문 강조 테마를 커스텀 할 수 있습니다. 자세한 내용은 [`markdown` 옵션](../reference/site-config#markdown)을 참고하세요.
## 코드 블록에서 라인 강조 {#line-highlighting-in-code-blocks}
@ -373,11 +373,11 @@ export default {
}
```
단일 라인 뿐만 아니라 여러 개의 단일 라인, 범위 또는 둘 다를 지정할 수도 있습니다:
단일 라인 뿐만 아니라 여러 개의 단일 라인, 범위 또는 둘 다 지정할 수도 있습니다:
- 라인 범위: 예를 들어 `{5-8}`, `{3-10}`, `{10-17}`
- 다수의 단일 라인: 예를 들어`{4,7,9}`
- 라인 범위 및 단일 라인: 예를 들어`{4,7-13,16,23-27,40}`
- 라인 범위: `{5-8}`, `{3-10}`, `{10-17}`
- 여러 단일 라인:`{4,7,9}`
- 라인 범위와 단일 라인:`{4,7-13,16,23-27,40}`
**입력**
@ -413,7 +413,7 @@ export default { // 강조됨
}
```
또한,`// [!code highlight]` 주석을 사용하여 직접 라인에 강조를 추가할 수 있습니다.
또는`// [!code highlight]` 주석을 사용하여 직접 라인에 강조를 추가할 수 있습니다.
**입력**
@ -445,7 +445,7 @@ export default {
`// [!code focus]` 주석을 라인에 추가하면 해당 라인이 포커싱되고 코드의 다른 부분은 흐릿하게 처리됩니다.
추가로,`// [!code focus:<lines>]`를 사용하여 포커싱할 라인 수를 정의할 수 있습니다.
추가로 `// [!code focus:<lines>]`를 사용하여 포커싱할 라인 수를 정의할 수 있습니다.
**입력**
@ -473,7 +473,7 @@ export default {
}
```
## 코드 블록 내 컬러 차이점 {#colored-diffs-in-code-blocks}
## 코드 블록 내 차이점 색 강조 {#colored-diffs-in-code-blocks}
`// [!code --]` 또는 `// [!code ++]` 주석을 라인에 추가하면 해당 라인의 차이점을 나타내며, 코드 블록의 색상을 유지합니다.
@ -507,7 +507,7 @@ export default {
## 코드 블록 내 오류 및 경고 {#errors-and-warnings-in-code-blocks}
`// [!code warning]` 또는 `// [!code error]` 주석을 라인에 추가하면 해당 색깔에 따라 라인이 색칠됩니다.
`// [!code warning]` 또는 `// [!code error]` 주석을 라인에 추가하면 해당 라인이 색칠됩니다.
**입력**
@ -549,11 +549,11 @@ export default {
}
```
자세한 내용은 [`markdown` 옵션](../reference/site-config#markdown)을 참조하세요.
자세한 내용은 [`markdown` 옵션](../reference/site-config#markdown)을 참고하세요.
또한 울타리 코드 블록에 `:line-numbers` / `:no-line-numbers` 마크를 추가하여 구성에서 설정한 값을 재정의할 수 있습니다.
구성에서 지정한 값을 무시하려면 펜싱 코드 블록에 `:line-numbers` / `:no-line-numbers` 마크를 추가하면 됩니다.
또한 `:line-numbers` 뒤에 `=`를 추가하여 시작 라인 번호를 사용자 정의할 수 있습니다. 예를 들어, `:
또한 `=`를 `:line-numbers` 뒤에 추가하여 시작 라인 번호를 커스텀 할 수도 있습니다. 예를 들어 `:line-numbers=2`는 코드 블록의 라인 번호가 `2`부터 시작함을 의미합니다.
**입력**
@ -605,10 +605,10 @@ const line4 = 'This is line 4'
<<<@/파일경로
```
다음과 같이 [라인 하이라이팅](#line-highlighting-in-code-blocks)도 지원합니다:
다음과 같이 [라인 강조](#line-highlighting-in-code-blocks)도 지원합니다:
```md
<<<@/파일경로{하이라이트할 라인}
<<<@/파일경로{강조 할 라인}
```
**입력**
@ -626,7 +626,7 @@ const line4 = 'This is line 4'
<<<@/snippets/snippet.js{2}
::: tip
'@'의 값은 소스 루트에 해당합니다. 기본값은 VitePress 프로젝트 루트이지만, `srcDir`이 구성되어 있을 경우가 아니면 다릅니다. 상대 경로에서도 가져올 수 있습니다:
`@`의 값은 소스 루트에 해당합니다. 기본값은 VitePress 프로젝트 루트이지만, `srcDir`이 구성되어 있을 경우에는 다릅니다. 상대 경로에서도 가져올 수도 있습니다:
```md
<<<../snippets/snippet.js
@ -655,7 +655,7 @@ const line4 = 'This is line 4'
```md
<<<@/snippets/snippet.cs{c#}
<!-- 라인 하이라이팅과 함께: -->
<!-- 라인 강조와 함께: -->
<<<@/snippets/snippet.cs{1,2,4-6c#}
@ -756,46 +756,46 @@ export default config
## 마크다운 파일 포함 {#markdown-file-inclusion}
다른 마크다운 파일에 마크다운 파일을 포함시킬 수 있으며, 중첩도 가능합니다.
마크다운 파일을 다른 마크다운 파일에 포함시킬 수 있으며, 중첩도 가능합니다.
::: tip
마크다운 경로 앞에 '@'을 붙이면 소스 루트로 작용합니다. 기본값은 VitePress 프로젝트 루트이지만, `srcDir`이 구성되어 있을 경우가 아닙니다.
마크다운 경로 앞에 `@`를 붙일 수도 있으며, 이는 소스 루트로 작동합니다. 기본적으로 이는 VitePress 프로젝트 루트이며, `srcDir`이 구성되지 않은 경우입니다.
:::
예를 들어, 다음과 같이 상대적인 마크다운 파일을 포함할 수 있습니다:
다음과 같이 상대적인 마크다운 파일을 포함시킬 수 있습니다:
**입력**
```md
# 문서
# Docs
## 기초
## Basics
<!--@include: ./parts/basics.md-->
```
**부분 파일** (`parts/basics.md`)
**해당 파일** (`parts/basics.md`)
```md
일부 시작하는 방법입니다.
Some getting started stuff.
### 구성
### Configuration
`.foorc.json`을 사용하여 생성할 수 있습니다.
Can be created using `.foorc.json`.
```
**동일한 코드**
```md
# 문서
# Docs
## 기초
## Basics
일부 시작하는 방법입니다.
Some getting started stuff.
### 구성
### Configuration
`.foorc.json`을 사용하여 생성할 수 있습니다.
Can be created using `.foorc.json`.
```
라인 범위 선택도 지원합니다:
@ -803,38 +803,38 @@ export default config
**입력**
```md
# 문서
# Docs
## 기초
## Basics
<!--@include: ./parts/basics.md{3,}-->
```
**부분 파일** (`parts/basics.md`)
**해당 파일** (`parts/basics.md`)
```md
일부 시작하는 방법입니다.
Some getting started stuff.
### 구성
### Configuration
`.foorc.json`을 사용하여 생성할 수 있습니다.
Can be created using `.foorc.json`.
```
**동일한 코드**
```md
# 문서
# Docs
## 기초
## Basics
### 구성
### Configuration
`.foorc.json`을 사용하여 생성할 수 있습니다.
Can be created using `.foorc.json`.
```
선택된 라인 범위의 형식은:`{3,}`, `{,10}`, `{1,10}`이 될 수 있습니다.
선택된 라인 범위의 형식은 `{3,}`, `{,10}`, `{1,10}`이 될 수 있습니다.
VS Code 영역을 사용하여 코드 파일의 해당 부분만 포함할 수도 있습니다. 파일 경로 뒤에 `#`를 붙여 사용자 정의 영역 이름을 제공할 수 있습니다:
[VS Code 리전](https://code.visualstudio.com/docs/editor/codebasics#_folding)을 사용하여 코드 파일의 해당 부분만 포함할 수도 있습니다. 파일 경로 뒤에 `#`를 붙이고 커스텀 영역 이름을 제공할 수 있습니다:
**입력**
@ -847,7 +847,7 @@ VS Code 영역을 사용하여 코드 파일의 해당 부분만 포함할 수
마크다운을 통해 추가된 각 이미지에 대해 지연 로딩을 활성화하려면 설정 파일에서 `lazyLoading`을 `true`로 설정하세요:
마크다운을 통해 추가된 각 이미지에 대해 지연 로딩을 활성화하려면 구성 파일에서 `lazyLoading`을 `true`로 설정하세요:
```js
export default {
@ -937,7 +937,7 @@ export default {
## 고급 설정 {#advanced-configuration}
VitePress는 마크다운 렌더링을 위해 [markdown-it](https://github.com/markdown-it/markdown-it)을 사용합니다. 위의 확장 프로그램 대부분은 커스텀 플러그인을 통해 구현됩니다. `.vitepress/config.js`의 `markdown` 옵션을 사용하여 `markdown-it` 인스턴스를 더욱 커스터마이징할 수 있습니다:
VitePress는 마크다운 렌더러로 [markdown-it](https://github.com/markdown-it/markdown-it)을 사용합니다. 위의 많은 확장 기능은 커스텀 플러그인을 통해 구현됩니다. `.vitepress/config.js`의 `markdown` 옵션을 사용하여 `markdown-it` 인스턴스를 추가로 커스터마이즈할 수 있습니다:
```js
import { defineConfig } from 'vitepress'
@ -964,4 +964,4 @@ export default defineConfig({
})
```
[설정 참조: 앱 설정](../reference/site-config#markdown)에서 구성 가능한 속성의 전체 목록을 확인할 수 있습니다.
구성 가능한 프로퍼티의 전체 목록은 [레퍼런스: 앱 구성](../reference/site-config#markdown)에서 확인하세요.
# MPA 모드 <Badgetype="warning"text="실험적"/> {#mpa-mode}
MPA(멀티 페이지 애플리케이션) 모드는 `vitepress build --mpa` 명령어를 통해 또는 `mpa: true` 옵션을 통해 설정 파일에서 활성화할 수 있습니다.
MPA (다중 페이지 애플리케이션) 모드는 명령줄에서 `vitepress build --mpa`를 통해 활성화할 수 있으며, 구성 파일에서 `mpa: true` 옵션을 통해서도 활성화할 수 있습니다.
MPA 모드에서는 모든 페이지가 기본적으로 JavaScript 없이 렌더링됩니다. 결과적으로, 생산 사이트는 감사 도구로부터 초기 방문 성능 점수를 더 좋게 받을 가능성이 높습니다.
MPA 모드에서는 모든 페이지가 기본적으로 JavaScript 없이 렌더링됩니다. 그 결과, 프로덕션 사이트는 감사 도구로부터 초기 방문 성능 점수가 더 좋을 가능성이 있습니다.
그러나, SPA 네비게이션이 없기 때문에, 페이지 간 링크는 전체 페이지를 다시 로드하게 합니다. MPA 모드에서의 포스트-로드 탐색은 SPA 모드처럼 즉각적으로 느껴지지 않을 것입니다.
그러나 SPA 탐색이 없기 때문에 페이지 간 링크는 전체 페이지를 새로 고침합니다. MPA 모드에서의 포스트-로드 탐색은 SPA 모드만큼 즉각적으로 느껴지지 않을 것입니다.
또한, 기본적으로 JS 없음을 의미하는 것은 여러분이 본질적으로 Vue를 서버 측 템플리팅 언어로만 사용하고 있다는 것을 의미합니다. 브라우저에서는 이벤트 핸들러가 연결되지 않으므로, 상호 작용성이 없을 것입니다. 클라이언트 측 JavaScript를 로드하려면 특별한 `<script client>` 태그를 사용해야 합니다:
또한 기본적으로 JS가 없다는 것은 Vue를 순전히 서버 사이드 템플릿 언어로 사용하고 있다는 것을 의미합니다. 브라우저에서는 이벤트 핸들러가 첨부되지 않으므로 상호작용이 없습니다. 클라이언트 사이드 JavaScript를 로드하려면 특별한 `<script client>` 태그를 사용해야 합니다:
`<script client>`는 VitePress 전용 기능으로, Vue 기능이 아닙니다. `.md` 및 `.vue` 파일 모두에서 작동하지만 MPA 모드에서만 작동합니다. 모든 테마 컴포넌트의 클라이언트 스크립트는 함께 번들링되며, 특정 페이지의 클라이언트 스크립트는 해당 페이지만을 위해 분할됩니다.
`<script client>`는 VitePress 전용 기능이며, Vue 기능이 아닙니다. 이 기능은 `.md` 파일과 `.vue` 파일에서 모두 작동하지만, MPA 모드에서만 사용됩니다. 모든 테마 컴포넌트의 클라이언트 스크립트는 함께 번들링되지만, 특정 페이지에 대한 클라이언트 스크립트는 개별적으로 처리됩니다.
`<script client>`는 **Vue 컴포넌트 코드로 평가되지 않는다**는 점을 주의하세요: 이것은 일반 JavaScript 모듈로 처리됩니다. 이러한 이유로, MPA 모드는 여러분의 사이트가 절대적으로 최소한의 클라이언트 측 상호작용만을 필요로 할 때만 사용되어야 합니다.
`<script client>`는 **Vue 컴포넌트 코드로 평가되지 않음**을 유의하십시오. 이는 단순한 JavaScript 모듈로 처리됩니다. 이러한 이유로, 사이트가 최소한의 클라이언트 사이드 상호작용을 요구하는 경우에만 MPA 모드를 사용하는 것이 좋습니다.
결과적으로 생성된 HTML은 정적 파일을 제공할 수 있는 모든 웹 서버에서 호스팅할 수 있습니다.
생성된 HTML은 정적 파일을 제공할 수 있는 모든 웹 서버에서 호스팅할 수 있습니다.
## 루트와 소스 디렉토리 {#root-and-source-directory}
VitePress 프로젝트의 파일 구조에서 두 가지 중요한 개념이 있습니다: **프로젝트 루트**와 **소스 디렉토리**.
VitePress 프로젝트의 파일 구조에는 두 가지 중요한 개념이 있습니다: **프로젝트 루트**와 **소스 디렉토리**입니다.
### 프로젝트 루트 {#project-root}
프로젝트 루트는 VitePress가 `.vitepress` 특수 디렉토리를 찾으려고 시도하는 위치입니다. `.vitepress` 디렉토리는 VitePress의 설정 파일, 개발 서버 캐시, 빌드 출력, 그리고 선택적 테마 커스터마이징 코드를 위한 예약된 위치입니다.
프로젝트 루트는 VitePress가 `.vitepress` 특수 디렉토리를 찾으려고 하는 위치입니다. `.vitepress` 디렉토리는 VitePress의 구성 파일, 개발 서버 캐시, 빌드 출력물, 그리고 선택적인 커스텀 테마 코드를 위한 예약된 위치입니다.
명령줄에서 `vitepress dev`나 `vitepress build`를 실행할 때, VitePress는 현재 작업 디렉토리를 프로젝트 루트로 사용합니다. 서브 디렉토리를 루트로 지정하려면 상대 경로를 명령에 전달해야 합니다. 예를 들어, VitePress 프로젝트가 `./docs`에 위치한 경우, `vitepress dev docs`를 실행해야 합니다:
명령줄에서 `vitepress dev`나 `vitepress build`를 실행하면 VitePress는 현재 작업 디렉토리를 프로젝트 루트로 사용합니다. 서브 디렉토리를 루트로 지정하려면 명령어에 상대 경로를 전달해야 합니다. 예를 들어, VitePress 프로젝트가 `./docs`에 위치한 경우, `vitepress dev docs`를 실행해야 합니다:
```
.
├─ docs # 프로젝트 루트
│ ├─ .vitepress # 설정 디렉토리
│ ├─ 시작하기.md
│ ├─ .vitepress # 구성 폴더
│ ├─ getting-started.md
│ └─ index.md
└─ ...
```
@ -51,53 +51,53 @@ VitePress 프로젝트의 파일 구조에서 두 가지 중요한 개념이 있
vitepress dev docs
```
이것은 다음과 같은 소스-HTML 매핑을 결과로 합니다:
이렇게 하면 다음과 같은 소스에서 HTML로의 매핑이 이루어집니다:
```
docs/index.md --> /index.html (접근 가능 경로 /)
docs/시작하기.md --> /시작하기.html
docs/index.md --> /index.html (/ 로 접근 가능)
docs/getting-started.md --> /getting-started.html
```
### 소스 디렉토리 {#source-directory}
소스 디렉토리는 마크다운 소스 파일이 위치하는 곳입니다. 기본적으로, 이는 프로젝트 루트와 동일합니다. 하지만, [`srcDir`](../reference/site-config#srcdir) 설정 옵션을 통해 이를 구성할 수 있습니다.
소스 디렉터리는 마크다운 소스 파일이 저장되는 위치입니다. 기본적으로 프로젝트 루트와 동일합니다. 그러나 [`srcDir`](../reference/site-config#srcdir) 구성 옵션으로 설정할 수 있습니다.
`srcDir` 옵션은 프로젝트 루트에 상대적으로 해결됩니다. 예를 들어, `srcDir: 'src'`로 설정하면, 파일 구조는 다음과 같아질 것입니다:
`srcDir` 옵션은 프로젝트 루트를 기준으로 해석됩니다. 예를 들어, `srcDir: 'src'`로 설정하면 파일 구조는 다음과 같이 됩니다:
```
. # 프로젝트 루트
├─ .vitepress # 설정 디렉토리
└─ src # 소스 디렉토리
├─ 시작하기.md
├─ .vitepress # 구성 디렉터리
└─ src # 소스 디렉터리
├─ getting-started.md
└─ index.md
```
결과적으로 생성된 소스-HTML 매핑:
소스에서 HTML로 매핑된 결과:
```
src/index.md --> /index.html (접근 가능 경로 /)
src/시작하기.md --> /시작하기.html
src/index.md --> /index.html (/ 로 접근 가능)
src/getting-started.md --> /getting-started.html
```
## 페이지 간 연결 {#linking-between-pages}
페이지 간 연결 시 절대 경로와 상대 경로를 모두 사용할 수 있습니다. `.md` 및 `.html` 확장자 모두 작동하더라도, 파일 확장자를 생략하여 VitePress가 설정에 기반한 최종 URL을 생성하도록 하는 것이 좋은 방법입니다.
페이지 간 링크를 만들 때 절대 경로와 상대 경로 모두 사용할 수 있습니다. `.md`와 `.html` 확장자 모두 작동하지만, VitePress가 구성에 따라 최종 URL을 생성할 수 있도록 파일 확장자를 생략하는 것이 좋은 방법입니다.
```md
<!--수행-->
<!--Do-->
[시작하기](./getting-started)
[시작하기](../guide/getting-started)
<!--수행하지 말 것-->
<!--Don't-->
[시작하기](./getting-started.md)
[시작하기](./getting-started.html)
```
[Asset Handling](./asset-handling)에서 이미지와 같은 에셋에 연결하는 방법에 대해 자세히 알아보세요.
이미지와 같은 에셋에 링크하는 방법에 대해 더 알아보려면 [에셋 처리](./asset-handling)를 참고하세요.
### VitePress 페이지가 아닌 페이지로 연결 {#linking-to-non-vitepress-pages}
VitePress에서 생성하지 않은 사이트의 페이지에 연결하려면, 전체 URL을 사용해야 합니다(새 탭에서 열림) 또는 명시적으로 대상을 지정해야 합니다:
VitePress로 생성되지 않은 페이지에 연결하려면 전체 URL(새 탭에서 열림)을 사용하거나 명시적으로 target을 지정해야 합니다:
**입력**
@ -111,9 +111,9 @@ VitePress에서 생성하지 않은 사이트의 페이지에 연결하려면,
::: tip 참고
마크다운 링크에서 `base`는 자동으로 URL에 추가됩니다. 즉, base 외부의 페이지에 연결하려면 링크에 `../../pure.html`와 같은 것이 필요합니다(브라우저에 의해 현재 페이지에 상대적으로 해결됨).
마크다운 링크에서 `base`는 URL 앞에 자동으로 추가됩니다. 이는 기본 경로 외부의 페이지에 링크하려면 링크에 `../../pure.html`과 같은 내용이 필요하다는 것을 의미합니다(브라우저에서 현재 페이지를 기준으로 해석됨).
또는, 앵커 태그 구문을 직접 사용할 수 있습니다:
또는 앵커 태그 문법을 직접 사용할 수도 있습니다:
```md
<ahref="/pure.html"target="_self">Link to pure.html</a>
@ -121,42 +121,42 @@ VitePress에서 생성하지 않은 사이트의 페이지에 연결하려면,
:::
## 깨끗한 URL 생성 {#generating-clean-url}
## 간결한 URL 생성 {#generating-clean-url}
::: warning 서버 지원 필요
VitePress로 깨끗한 URL을 제공하려면 서버 측 지원이 필요합니다.
VitePress가 간결한 URL을 제공하려면 서버 측 지원이 필요합니다.
:::
기본적으로, VitePress는 `.html`로 끝나는 URL로 들어오는 링크를 해결합니다. 그러나, 일부 사용자는 `.html` 확장자 없이 "깨끗한 URL"을 선호할 수 있습니다 - 예를 들어, `example.com/path` 대신 `example.com/path.html`.
기본적으로 VitePress는 `.html`로 끝나는 URL로 들어오는 링크를 처리합니다. 하지만 일부 사용자는 `.html` 확장자가 없는 "간결한 URL"을 선호할 수 있습니다. 예를 들어, `example.com/path.html` 대신 `example.com/path`.
일부 서버나 호스팅 플랫폼(예: Netlify, Vercel, GitHub 페이지)은`/foo`와 같은 URL을 `/foo.html`로 매핑할 수 있는 기능을 제공합니다(리다이렉트 없이):
일부 서버 또는 호스팅 플랫폼(예: Netlify, Vercel, GitHub Pages)은 리다이렉션 없이`/foo`와 같은 URL을 `/foo.html`로 매핑할 수 있는 기능을 제공합니다:
`rewrites` 옵션은 동적 라우트 매개변수도 지원합니다. 위의 예제에서, 많은 패키지를 가지고 있다면 모든 경로를 나열하는 것은 장황할 것입니다. 모두 같은 파일 구조를 가지고 있다면, 설정을 다음과 같이 간단하게 할 수 있습니다:
`rewrites` 옵션은 동적 라우트 파라미터도 지원합니다. 위 예에서 많은 패키지를 가지고 있다면 모든 경로를 나열하는 것이 번거로울 것입니다. 동일한 파일 구조를 가지고 있는 경우, 구성은 다음과 같이 간단하게 만들 수 있습니다:
```ts
export default {
rewrites: {
'패키지/:pkg/src/(.*)': ':pkg/index.md'
'packages/:pkg/src/(.*)': ':pkg/index.md'
}
}
```
재작성 경로는 `path-to-regexp` 패키지를 사용하여 컴파일됩니다 - 보다 고급 구문에 대해서는 [해당 문서](https://github.com/pillarjs/path-to-regexp#parameters)를 참조하십시오.
라우트 재작성은 `path-to-regexp` 패키지를 사용하여 컴파일됩니다. 보다 고급 문법에 대해서는 [여기](https://github.com/pillarjs/path-to-regexp#parameters)를 참고하십시오.
::: warning 재작성과 상대 링크
재작성이 활성화된 경우, **상대 링크는 재작성된 경로를 기반으로 해야 합니다**. 예를 들어, `패키지/pkg-a/src/pkg-a-code.md`에서 `패키지/pkg-b/src/pkg-b-code.md`로 상대 링크를 생성하려면 다음을 사용해야 합니다:
재작성 기능이 활성화되면, **상대 링크는 재작성된 경로를 기준으로 해야 합니다**. 예를 들어, `packages/pkg-a/src/pkg-a-code.md`에서 `packages/pkg-b/src/pkg-b-code.md`로 상대 링크를 생성하려면, 다음과 같이 사용해야 합니다:
```md
[PKG B로의 링크](../pkg-b/pkg-b-code)
[Link to PKG B](../pkg-b/pkg-b-code)
```
:::
## 동적 라우트 {#dynamic-routes}
단일 마크다운 파일과 동적 데이터를 사용하여 많은 페이지를 생성할 수 있습니다. 예를 들어, 프로젝트의 모든 패키지에 해당하는 페이지를 생성하는 `패키지/[pkg].md` 파일을 만들 수 있습니다. 여기서 `[pkg]` 세그먼트는 각 페이지를 다른 페이지와 구별하는 라우트 **매개변수**입니다.
단일 마크다운 파일과 동적 데이터를 사용하여 여러 페이지를 생성할 수 있습니다. 예를 들어, 프로젝트의 모든 패키지에 해당하는 페이지를 생성하는 `packages/[pkg].md` 파일을 만들 수 있습니다. 여기서 `[pkg]` 세그먼트는 각 페이지를 구분하는 라우트 **파라미터**입니다.
### 경로 로더 파일 {#paths-loader-file}
VitePress는 정적 사이트 생성기이므로, 가능한 페이지 경로는 빌드 시간에 결정되어야 합니다. 따라서 동적 라우트 페이지는 **경로 로더 파일**을 동반해야 합니다. `패키지/[pkg].md`의 경우, `패키지/[pkg].paths.js`(`.ts`도 지원)가 필요합니다:
VitePress는 정적 사이트 생성기이므로, 가능한 페이지 경로는 빌드 시에 결정되어야 합니다. 따라서 동적 라우트 페이지는 반드시 **경로 로더 파일**과 함께 제공되어야 합니다. `packages/[pkg].md`의 경우, `packages/[pkg].paths.js` (`.ts`도 지원됩니다) 파일이 필요합니다:
```
.
└─ 패키지
├─ [pkg].md # 라우트 템플릿
└─ [pkg].paths.js # 라우트 경로 로더
└─ packages
├─ [pkg].md # route template
└─ [pkg].paths.js # route paths loader
```
경로 로더는 `params` 속성을 가진 객체의 배열을 반환하는 `paths` 메서드를 기본 export로 제공하는 객체여야 합니다. 이러한 객체 각각은 해당하는 페이지를 생성할 것입니다.
경로 로더는 `paths` 메서드를 기본 내보내기로 제공하는 객체를 포함해야 합니다. `paths` 메서드는 `params` 객체 프로퍼티를 가진 배열을 반환해야 합니다. 이 객체들 각각이 해당하는 페이지를 생성하게 됩니다.
다음 `paths` 배열이 주어진 경우:
다음과 같이`paths` 배열이 주어진 경우:
```js
// 패키지/[pkg].paths.js
// packages/[pkg].paths.js
export default {
paths() {
return [
@ -242,20 +242,20 @@ export default {
```
.
└─ 패키지
└─ packages
├─ foo.html
└─ bar.html
```
### 여러 매개변수 {#multiple-params}
### 여러 파라미터 {#multiple-params}
동적 라우트는 여러 매개변수를 포함할 수 있습니다:
동적 라우트는 여러 파라미터를 포함할 수 있습니다:
**파일 구조**
```
.
└─ 패키지
└─ packages
├─ [pkg]-[version].md
└─ [pkg]-[version].paths.js
```
@ -273,11 +273,11 @@ export default {
}
```
**출력**
**결과물**
```
.
└─ 패키지
└─ packages
├─ foo-1.0.0.html
├─ foo-2.0.0.html
├─ bar-1.0.0.html
@ -286,7 +286,7 @@ export default {
### 동적으로 경로 생성 {#dynamically-generating-paths}
경로 로더 모듈은 Node.js에서 실행되며 빌드 시간에만 실행됩니다. 로컬 또는 원격 데이터를 사용하여 경로 배열을 동적으로 생성할 수 있습니다.
경로 로더 모듈은 Node.js에서 실행되며 빌드 시에만 실행됩니다. 로컬 또는 원격 데이터를 사용하여 동적으로 경로 배열을 생성할 수 있습니다.
로컬 파일에서 경로 생성:
@ -296,7 +296,7 @@ import fs from 'fs'
export default {
paths() {
return fs
.readdirSync('패키지')
.readdirSync('packages')
.map((pkg) => {
return { params: { pkg }}
})
@ -323,16 +323,16 @@ export default {
}
```
### 페이지에서 매개변수 접근 {#accessing-params-in-page}
### 페이지에서 파라미터에 접근 {#accessing-params-in-page}
각 페이지에 추가 데이터를 전달하기 위해 매개변수를 사용할 수 있습니다. 마크다운 라우트 파일은 `$params` 전역 속성을 통해 현재 페이지 매개변수에 Vue 표현식에서 접근할 수 있습니다:
파라미터를 사용하여 각 페이지에 추가 데이터를 전달할 수 있습니다. 마크다운 라우트 파일은 `$params` 전역 프로퍼티를 통해 Vue 표현식에서 현재 페이지 파라미터에 접근할 수 있습니다:
```md
- 패키지 이름: {{ $params.pkg }}
- 버전: {{ $params.version }}
```
[`useData`](../reference/runtime-api#usedata) 런타임 API를 통해 마크다운 파일과 Vue 컴포넌트에서 현재 페이지의 매개변수에도 접근할 수 있습니다:
또는 [`useData`](../reference/runtime-api#usedata) 런타임 API를 통해 현재 페이지의 파라미터에 접근할 수 있습니다. 이는 마크다운 파일과 Vue 컴포넌트 모두에서 사용할 수 있습니다:
```vue
<scriptsetup>
@ -347,9 +347,9 @@ console.log(params.value)
### 원시 콘텐츠 렌더링 {#rendering-raw-content}
페이지로 전달된 매개변수는 클라이언트 JavaScript 페이로드에 직렬화되므로, 예를 들어 원격 CMS에서 가져온 원시 마크다운이나 HTML 콘텐츠와 같이 무거운 데이터를 매개변수로 전달하지 마십시오.
페이지에 전달되는 파라미터는 클라이언트 JavaScript 페이로드에서 직렬화되므로, 원격 CMS에서 가져온 원시 Markdown이나 HTML 콘텐츠와 같은 무거운 데이터를 파라미터로 전달하지 마십시오.
대신, 각 경로 객체의 `content`속성을 사용하여 각 페이지에 이러한 콘텐츠를 전달할 수 있습니다:
대신, 각 경로 객체의 `content`프로퍼티를 사용하여 이러한 콘텐츠를 각 페이지에 전달할 수 있습니다:
```js
export default {
@ -366,7 +366,7 @@ export default {
}
```
그런 다음 다음 특수 구문을 사용하여 마크다운 파일 자체의 일부로 콘텐츠를 렌더링하세요:
그런 다음 특수 문법을 사용하여 마크다운 파일 자체의 일부로 콘텐츠를 렌더링할 수 있습니다:
VitePress는 사이트를 위한 `sitemap.xml` 파일 생성을 기본적으로 지원합니다. 이를 활성화하려면 다음을 `.vitepress/config.js`에 추가하세요:
VitePress는 사이트의 `sitemap.xml` 파일 생성을 지원합니다. 이를 활성화하려면 `.vitepress/config.js`에 다음을 추가하십시오:
```ts
export default {
@ -14,7 +14,7 @@ export default {
## 옵션 {#options}
사이트맵 지원은 [`sitemap`](https://www.npmjs.com/package/sitemap) 모듈에 의해 제공됩니다. 설정 파일의 `sitemap` 옵션에 이 모듈이 지원하는 모든 옵션을 전달할 수 있습니다. 이 옵션들은 `SitemapStream` 생성자에 직접 전달됩니다. 자세한 내용은 [`sitemap` 문서](https://www.npmjs.com/package/sitemap#options-you-can-pass)를 참조하세요. 예제:
사이트맵 지원은 [`sitemap`](https://www.npmjs.com/package/sitemap) 모듈에 의해 제공됩니다. 구성 파일의 `sitemap` 옵션에 지원되는 모든 옵션을 전달할 수 있습니다. 이러한 옵션은 `SitemapStream` 생성자에 직접 전달됩니다. 자세한 내용은 [`sitemap` 문서](https://www.npmjs.com/package/sitemap#options-you-can-pass)를 참고하세요. 예:
```ts
export default {
@ -25,7 +25,7 @@ export default {
}
```
설정 파일에서 `base`를 사용하는 경우, `hostname` 옵션에 이를 추가해야 합니다:
구성 파일에서 `base`를 사용하는 경우, `hostname` 옵션에 이것을 추가해야 합니다:
```ts
export default {
@ -36,16 +36,16 @@ export default {
}
```
## `transformItems` Hook
## `transformItems` Hook {#transformitems-hook}
`sitemap.transformItems` 훅을 사용하여 `sitemap.xml` 파일에 작성되기 전에 사이트맵 항목을 수정할 수 있습니다. 이 훅은 사이트맵 항목 배열을 인자로 받아 배열을 반환해야 합니다. 예제:
`sitemap.transformItems` 훅을 사용하여 `sitemap.xml` 파일에 작성되기 전에 사이트맵 아이템을 수정할 수 있습니다. 이 훅은 사이트맵 아이템 배열을 인자로 받고 사이트맵 아이템 배열을 반환해야 합니다. 예제:
VitePress는 Vue의 서버 사이드 렌더링(SSR) 기능을 사용하여 프로덕션 빌드 중에 Node.js에서 앱을 사전 렌더링합니다. 이는 테마 컴포넌트의 모든 사용자 정의 코드가 SSR 호환성을 준수해야 함을 의미합니다.
VitePress는 Vue의 서버 사이드 렌더링(SSR) 기능을 사용하여 프로덕션 빌드 중에 Node.js에서 애플리케이션을 사전 렌더링합니다. 이는 테마 컴포넌트의 모든 커스텀 코드가 SSR 호환성을 준수해야 함을 의미합니다.
[공식 Vue 문서의 SSR 섹션](https://vuejs.org/guide/scaling-up/ssr.html)은 SSR이 무엇인지, SSR/SSG 간의 관계 및 SSR 친화적인 코드 작성에 대한 일반적인 참고 사항에 대한 더 많은 컨텍스트를 제공합니다. 핵심 원칙은 브라우저/DOM API에는 Vue 컴포넌트의 `beforeMount` 또는 `mounted` 후크에서만 접근해야 합니다.
공식 Vue 문서의 [SSR 섹션](https://vuejs.org/guide/scaling-up/ssr.html)은 SSR이 무엇인지, SSR / SSG 간의 관계, 그리고 SSR 친화적인 코드를 작성할 때의 일반적인 주의 사항에 대해 더 많은 정보를 제공합니다. 핵심 원칙은 Vue 컴포넌트의 `beforeMount` 또는 `mounted` 훅에서만 브라우저 / DOM API에 접근하는 것입니다.
## `<ClientOnly>`
SSR 친화적이지 않은 컴포넌트(예: 사용자 정의 지시문이 포함된 경우)를 사용하거나 시연하는 경우, 내장된 `<ClientOnly>` 컴포넌트 내부에 이를 래핑할 수 있습니다:
SSR 친화적이지 않은 컴포넌트(예: 커스텀 디렉티브를 포함한 컴포넌트)를 사용하거나 시연하는 경우, 내장된 `<ClientOnly>` 컴포넌트로 해당 컴포넌트를 래핑할 수 있습니다:
```md
<ClientOnly>
@ -18,11 +18,11 @@ SSR 친화적이지 않은 컴포넌트(예: 사용자 정의 지시문이 포
</ClientOnly>
```
## 가져오기 시 브라우저 API에 접근하는 라이브러리 {#libraries-that-access-browser-api-on-import}
## "import" 시 브라우저 API에 접근하는 라이브러리 {#libraries-that-access-browser-api-on-import}
일부 컴포넌트나 라이브러리는 **가져오기 시**에 브라우저 API에 접근합니다. 가져오기를 통해 브라우저 환경을 가정하는 코드를 사용하려면 동적으로 이를 가져와야 합니다.
일부 컴포넌트나 라이브러리는 **"import" 시** 브라우저 API에 접근합니다. "import" 시 브라우저 환경을 가정하는 코드를 사용하려면, 동적 "import"를 사용해야 합니다.
VitePress에서 각 Markdown 파일은 HTML로 컴파일된 다음 [Vue 단일 파일 컴포넌트](https://vuejs.org/guide/scaling-up/sfc.html)로 처리됩니다. 이는 Markdown 내에서 동적 템플릿, Vue 컴포넌트 사용 또는`<script>` 태그를 추가하여 임의의 페이지 내 Vue 컴포넌트 로직을 사용할 수 있음을 의미합니다.
VitePress에서는 각 마크다운 파일이 HTML로 컴파일된 후 [Vue 단일 파일 컴포넌트](https://vuejs.org/guide/scaling-up/sfc.html)로 처리됩니다. 이는 마크다운 내에서 Vue 컴포넌트를 사용하거나 동적 템플릿을 사용하거나`<script>` 태그를 추가하여 임의의 페이지 내 Vue 컴포넌트 로직을 사용할 수 있다는 것을 의미합니다.
VitePress가 Vue의 컴파일러를 활용하여 Markdown 콘텐츠의 순수 정적 부분을 자동으로 감지하고 최적화한다는 점에 주목할 가치가 있습니다. 정적 콘텐츠는 단일 자리표시자 노드로 최적화되어 초기 방문시 페이지의 JavaScript 페이로드에서 제거됩니다. 또한 클라이언트 측 하이드레이션 중에도 건너뜁니다. 간단히 말해서, 주어진 페이지에서 동적 부분에 대해서만 비용을 지불합니다.
VitePress는 Vue의 컴파일러를 활용하여 마크다운 콘텐츠의 순수 정적 부분을 자동으로 감지하고 최적화합니다. 정적 콘텐츠는 단일 플레이스홀더 노드로 최적화되어 초기 방문 시 페이지의 JavaScript 페이로드에서 제거됩니다. 또한 클라이언트 측 하이드레이션 중에도 건너뜁니다. 요약하자면 특정 페이지에서는 동적 부분에 대해서만 비용을 지불하면 됩니다.
::: tip SSR 호환성
모든 Vue 사용은 SSR과 호환되어야 합니다. 자세한 내용과 일반적인 해결 방법은 [SSR 호환성](./ssr-compat)을 참조하십시오.
모든 Vue 사용은 SSR과 호환되어야 합니다. 자세한 내용 및 일반적인 해결 방법은 [SSR 호환성](./ssr-compat)을 참고하세요.
:::
## 템플릿 {#templating}
### 보간(interpolation) {#interpolation}
### 보간 문법 {#interpolation}
각 Markdown 파일은 먼저 HTML로 컴파일되고 나서 Vite 프로세스 파이프라인으로 Vue 컴포넌트로 전달됩니다. 이는 텍스트에서 Vue 스타일 보간을 사용할 수 있음을 의미합니다:
각 마크다운 파일은 먼저 HTML로 컴파일된 다음 Vue 컴포넌트로 Vite 프로세스 파이프라인에 전달됩니다. 이는 텍스트에서 Vue 스타일 보간 문법을 사용할 수 있음을 의미합니다:
**입력**
@ -24,9 +24,9 @@ VitePress가 Vue의 컴파일러를 활용하여 Markdown 콘텐츠의 순수
@ -38,9 +38,9 @@ VitePress가 Vue의 컴파일러를 활용하여 Markdown 콘텐츠의 순수
<divclass="language-text"><pre><code><spanv-for="i in 3">{{ i }} </span></code></pre></div>
## `<script>`와`<style>` {#script-and-style}
## `<script>`&`<style>` {#script-and-style}
Markdown 파일의 최상위 `<script>` 및 `<style>` 태그는 Vue SFC에서와 마찬가지로 작동합니다. `<script setup>`, `<style module>` 등을 포함합니다. 여기서 주된 차이점은 `<template>` 태그가 없다는 것입니다: 다른 모든 최상위 콘텐츠는 Markdown입니다. 또한 모든 태그는 frontmatter **이후에** 위치해야 함을 유의하십시오:
루트 레벨의 `<script>` 및 `<style>` 태그는 마크다운 파일에서 Vue SFCs에서와 마찬가지로 작동하며, `<script setup>`, `<style module>` 등도 포함됩니다. 여기서 주요 차이점은 `<template>` 태그가 없다는 것입니다: 다른 모든 루트 레벨의 컨텐츠는 마크다운입니다. 또한 **모든 태그는 전문 이후에 배치**되어야 합니다:
```html
---
@ -53,7 +53,7 @@ import { ref } from 'vue'
const count = ref(0)
</script>
## Markdown 콘텐츠
## 마크다운 컨텐츠
현재 카운트: {{ count }}
@ -67,11 +67,11 @@ const count = ref(0)
</style>
```
::: warning Markdown에서 `<style scoped>` 사용을 피하세요
Markdown에서 `<style scoped>`를 사용할 경우, 현재 페이지의 모든 요소에 특별한 속성을 추가해야 하므로 페이지 크기가 현저하게 증가할 수 있습니다. 페이지 내에서 지역적으로 범위가 지정된 스타일링이 필요할 때는 `<style module>`이 선호됩니다.
::: warning 마크다운에서 `<style scoped>` 사용을 피하세요
마크다운에서 `<style scoped>`를 사용할 때는 현재 페이지의 모든 엘리먼트에 특수한 어트리뷰트를 추가해야 하므로 페이지 크기를 크게 부풀릴 수 있습니다. 페이지에서 로컬 범위의 스타일링이 필요한 경우 `<style module>`을 사용하는 것이 좋습니다.
:::
현재 페이지의 메타데이터에 접근할 수 있는 [`useData` 도우미](../reference/runtime-api#usedata)와 같은 VitePress의 런타임 API에도 접근할 수 있습니다:
또한 현재 페이지의 메타데이터에 접근할 수 있는 [`useData` 헬퍼](../reference/runtime-api#usedata)와 같은 VitePress의 런타임 API에도 접근할 수 있습니다:
**입력**
@ -90,7 +90,7 @@ const { page } = useData()
```json
{
"path": "/using-vue.html",
"title": "Markdown에서 Vue 사용하기",
"title": "마크다운에서 Vue 사용하기",
"frontmatter": {},
...
}
@ -98,11 +98,11 @@ const { page } = useData()
## 컴포넌트 사용하기 {#using-components}
Markdown 파일 내에서 Vue 컴포넌트를 직접 가져오고 사용할 수 있습니다.
마크다운 파일 내에서 Vue 컴포넌트를 직접 가져와서 사용할 수 있습니다.
### Markdown에서 가져오기 {#importing-in-markdown}
### 마크다운에서 컴포넌트 가져오기 {#importing-in-markdown}
컴포넌트가 몇 페이지에서만 사용되는 경우, 해당되는 곳에서 명시적으로 가져오는 것이 좋습니다. 이를 통해 적절하게 코드를 분할하고 관련 페이지가 표시될 때만 로드할 수 있습니다:
컴포넌트가 몇 페이지에서만 사용되는 경우, 사용되는 곳에서 명시적으로 가져오는 것이 좋습니다. 이렇게 하면 적절하게 코드를 분할하고 관련 페이지가 표시될 때만 로드할 수 있습니다:
```md
<scriptsetup>
@ -122,31 +122,31 @@ import CustomComponent from '../components/CustomComponent.vue'
컴포넌트가 대부분의 페이지에서 사용될 것인 경우, Vue 앱 인스턴스를 사용자 지정하여 전역적으로 등록할 수 있습니다. 예제는 [기본 테마 확장](./extending-default-theme#registering-global-components) 관련 섹션을 참조하십시오.
컴포넌트가 대부분의 페이지에서 사용될 경우, Vue 앱 인스턴스를 커스텀하여 전역적으로 등록할 수 있습니다. [기본 테마 확장](./extending-default-theme#registering-global-components)의 관련 섹션을 예제를 참고하세요.
::: warning 중요
커스텀 컴포넌트의 이름이 하이픈을 포함하거나 파스칼케이스(PascalCase)인지 확인하십시오. 그렇지 않으면 인라인 요소로 처리되어 `<p>` 태그 내에 포함되어 하이드레이션 불일치가 발생할 수 있습니다. `<p>`는 내부에 블록 요소를 포함할 수 없기 때문입니다.
커스텀 컴포넌트의 이름에 하이픈이 포함되어 있거나 파스칼케이스(PascalCase)e인지 확인하세요. 그렇지 않으면 인라인 요소로 처리되어 `<p>` 태그 안에 래핑됩니다. `<p>`는 블록 엘리먼트를 내부에 배치할 수 없기 때문에 하이드레이션 불일치가 발생합니다.
:::
### 헤더에 컴포넌트 사용하기 <ComponentInHeader/> {#using-components-in-headers}
### 헤더에 <ComponentInHeader/> 컴포넌트 사용하기 {#using-components-in-headers}
`<code>`로 둘러싸인 HTML은 그대로 표시됩니다; **아니면** `<code>`로 둘러싸이지 않은 HTML만 Vue에 의해 파싱됩니다.
`<code>`로 감싼 HTML은 있는 그대로 표시되며, **감싸지 않은** HTML만 Vue에 의해 파싱됩니다.
::: tip
출력 HTML은 [Markdown-it](https://github.com/Markdown-it/Markdown-it)에 의해 이루어지며, 파싱된 헤더는 VitePress(사이드바와 문서 제목 모두에 사용됨)에 의해 처리됩니다.
출력된 HTML은 [Markdown-it](https://github.com/Markdown-it/Markdown-it)에 의해 생성되며, 파싱된 헤더는 VitePress에 의해 처리됩니다(사이드바와 문서 제목 모두에 사용됩니다).
:::
## 이스케이프 {#escaping}
`v-pre` 지시문을 사용하여 `<span>`이나 다른 요소에 Vue 보간을 이스케이프할 수 있습니다:
Vue 보간 문법을 회피하려면, `<span>` 또는 다른 엘리먼트에 `v-pre` 디렉티브를 사용하여 감쌀 수 있습니다:
**입력**
@ -160,7 +160,7 @@ import CustomComponent from '../components/CustomComponent.vue'
<p>이것은 <spanv-pre>{{ 그대로 표시됩니다 }}</span></p>
</div>
또한, 전체 단락을 `v-pre` 커스텀 컨테이너로 둘러싸도록 선택할 수 있습니다:
또는 전체 문단을 `v-pre` 커스텀 컨테이너로 감쌀 수도 있습니다:
```md
::: v-pre
@ -180,7 +180,7 @@ import CustomComponent from '../components/CustomComponent.vue'
## 코드 블록에서 이스케이프 해제하기 {#unescape-in-code-blocks}
기본적으로 모든 fenced 코드 블록은 자동으로 `v-pre`로 둘러싸입니다. 따라서 내부에서 Vue 구문을 처리하지 않습니다. 펜스 내에서 Vue 스타일 보간을 활성화하려면, 예를 들어`js-vue`처럼 언어에 `-vue` 접미사를 추가할 수 있습니다:
기본적으로 모든 펜스 코드 블록은 자동으로 `v-pre`로 감싸져 있어, 내부에서는 Vue 문법이 처리되지 않습니다. 펜스 내부에서 Vue 스타일 보간 문법을 사용하려면,`js-vue`처럼 언어에 `-vue` 접미사를 추가할 수 있습니다:
**입력**
@ -196,11 +196,11 @@ import CustomComponent from '../components/CustomComponent.vue'
안녕하세요 {{ 1 + 1 }}
```
이는 일부 토큰이 제대로 구문 강조되지 않을 수 있음을 의미합니다.
이로 인해 특정 토큰이 올바르게 강조 표시되지 않을 수 있습니다.
## CSS 전처리기 사용하기 {#using-css-pre-processors}
VitePress는 CSS 전처리기에 대한 [내장 지원](https://vitejs.dev/ko/guide/features.html#css-pre-processors)을 가지고 있습니다: `.scss`, `.sass`, `.less`, `.styl` 및 `.stylus` 파일. 이것들을 위한 Vite 특정 플러그인을 설치할 필요는 없지만, 해당 전처리기 자체는 설치해야 합니다:
VitePress는 CSS 전처리기인 `.scss`, `.sass`, `.less`, `.styl`, `.stylus` 파일에 대해 [기본 지원](https://vitejs.dev/guide/features.html#css-pre-processors)을 제공합니다. 이를 위해 Vite 전용 플러그인을 설치할 필요는 없지만, 해당 전처리기 자체는 설치해야 합니다:
```
# .scss 및 .sass
@ -213,7 +213,7 @@ npm install -D less
npm install -D stylus
```
그런 다음 다음을 Markdown 및 테마 컴포넌트에서 사용할 수 있습니다:
그런 다음 마크다운 및 테마 컴포넌트에서 다음과 같이 사용할 수 있습니다:
```vue
<stylelang="sass">
@ -222,9 +222,9 @@ npm install -D stylus
</style>
```
## Teleports 사용하기 {#using-teleports}
## 텔레포트 사용하기 {#using-teleports}
현재 VitePress는 본문으로만 teleport에 대한 SSG 지원을 가지고 있습니다. 다른 대상을 위해서는, 내장된 `<ClientOnly>` 컴포넌트 내에 감싸거나 텔레포트 마크업을 최종 페이지 HTML의 올바른 위치에 주입할 수 있습니다 [`postRender` 훅](../reference/site-config#postrender)을 통해.
VitePress는 현재 body로 텔레포트를 사용하는 SSG만 지원합니다. 다른 대상에 대해 텔레포트를 사용하려면 내장된 `<ClientOnly>` 컴포넌트로 감싸거나 [`postRender` 훅](../reference/site-config#postrender)을 통해 최종 페이지 HTML의 올바른 위치에 텔레포트 마크업을 삽입할 수 있습니다.
VitePress는 빠르고 컨텐츠 중심의 웹사이트를 구축하기 위해 설계된 [정적 사이트 생성기](https://en.wikipedia.org/wiki/Static_site_generator) (SSG)입니다. 간단히 말해, VitePress는 [Markdown](https://en.wikipedia.org/wiki/Markdown)으로 작성된 소스 컨텐츠를 가져와서 테마를 적용하고, 어디에나 쉽게 배포할 수 있는 정적 HTML 페이지를 생성합니다.
VitePress는 빠르고 컨텐츠 중심의 웹사이트를 구축하기 위해 설계된 [정적 사이트 생성기](https://en.wikipedia.org/wiki/Static_site_generator) (SSG)입니다. 다시말해 VitePress는 [마크다운](https://en.wikipedia.org/wiki/Markdown)으로 작성된 소스 컨텐츠를 가져와서 테마를 적용하고, 어디에나 쉽게 배포할 수 있는 정적 HTML 페이지를 생성합니다.
그냥 시도해보고 싶으세요? [빠른 시작](./getting-started)으로 건너뛰세요.
그냥 한번 사용해보고 싶으신가요? [빠른 시작](./getting-started)으로 건너뛰세요.
</div>
@ -12,46 +12,46 @@ VitePress는 빠르고 컨텐츠 중심의 웹사이트를 구축하기 위해
- **문서화**
VitePress는 기술 문서를 위해 설계된 기본 테마와 함께 제공됩니다. 이 테마는 바로 지금 읽고 있는 이 페이지뿐만 아니라 [Vite](https://vitejs.dev/), [Rollup](https://rollupjs.org/), [Pinia](https://pinia.vuejs.org/), [VueUse](https://vueuse.org/), [Vitest](https://vitest.dev/), [D3](https://d3js.org/), [UnoCSS](https://unocss.dev/), [Iconify](https://iconify.design/) 그리고 [기타 많은](https://www.vuetelescope.com/explore?framework.slug=vitepress) 문서화에 힘을 실어줍니다.
VitePress는 기술 문서를 위해 설계된 기본 테마가 함께 제공됩니다. 지금 읽고 있는 이 페이지와 [Vite](https://vitejs.dev/), [Rollup](https://rollupjs.org/), [Pinia](https://pinia.vuejs.org/), [VueUse](https://vueuse.org/), [Vitest](https://vitest.dev/), [D3](https://d3js.org/), [UnoCSS](https://unocss.dev/), [Iconify](https://iconify.design/) 및 [다양한 프로젝트](https://www.vuetelescope.com/explore?framework.slug=vitepress) 문서는 모두 이 테마를 기반으로 합니다.
[공식 Vue.js 문서](https://vuejs.org/)도 VitePress 기반으로 되어 있지만, 여러 번역 간에 공유되는 커스텀 테마를 사용합니다.
[Vue.js 공식 문서](https://vuejs.org/)도 VitePress 기반으로 되어 있으며, 여러 번역본에 걸쳐 공유되는 커스텀 테마를 사용합니다.
- **블로그, 포트폴리오 및 마케팅 사이트**
VitePress는 표준 Vite + Vue 애플리케이션의 개발자 경험과 함께 [완전히 맞춤화된 테마](./custom-theme)를 지원합니다. Vite 기반이기 때문에 풍부한 생태계에서 Vite 플러그인을 직접 활용할 수 있습니다. 또한, VitePress는 [데이터 불러오기](./data-loading) (로컬 또는 원격) 및 [동적으로 경로 생성하기](./routing#dynamic-routes)를 위한 유연한 API를 제공합니다. 빌드 시점에 데이터를 결정할 수 있다면 거의 모든 것을 구축할 수 있습니다.
VitePress는 표준 Vite + Vue 애플리케이션의 개발자 경험을 가진 [커스텀 테마](./custom-theme)를 지원합니다. Vite 기반이기 때문에 Vite 생태계의 풍부한 플러그인을 직접 활용할 수 있습니다. 또한, VitePress는 [데이터 로딩](./data-loading) (로컬 또는 원격) 및 [동적 라우트 생성](./routing#dynamic-routes)을 위한 유연한 API를 제공합니다. 빌드 시점에 데이터를 결정할 수 있다면 거의 모든 것을 구축할 수 있습니다.
공식 [Vue.js 블로그](https://blog.vuejs.org/)는 로컬 콘텐츠를 기반으로 색인 페이지를 생성하는 간단한 블로그입니다.
공식 [Vue.js 블로그](https://blog.vuejs.org/)는 로컬 콘텐츠 기반의 인덱스 페이지를 생성하는 간단한 블로그입니다.
## 개발자 경험 {#developer-experience}
VitePress는 Markdown 컨텐츠를 다룰 때 훌륭한 개발자 경험(DX)을 제공하고자 합니다.
VitePress는 마크다운 컨텐츠를 다룰 때 훌륭한 개발자 경험(DX)을 제공하고자 합니다.
- **[Vite 구동:](https://vitejs.dev/)** 즉각적인 서버 시작이 가능하며, 페이지 새로고침 없이 항상 (<100ms)즉시수정사항이반영됩니다.
- **[Vite로 작동](https://vitejs.dev/)**: 즉각적인 서버 시작 가능, 페이지 새로고침 없이 즉시(<100ms)수정사항반영.
- **[내장 Markdown 확장 기능:](./markdown)** Frontmatter, 테이블, 구문 하이라이팅… 필요한 것이라면 무엇이든 있습니다. 특히, VitePress는 코드 블록과 작업할 때 많은 고급 기능을 제공하여 기술적 문서에 이상적입니다.
- **[내장된 마크다운 확장 기능](./markdown)**: 서문, 표, 구문 강조 등 무엇이든 가능. 특히 VitePress는 코드 블록 작업을 위한 고급 기능을 많이 제공하여 기술적 문서에 이상적.
- **[Vue를 향상된 Markdown:](./using-vue)** 각 Markdown 페이지는 HTML과 100% 문법 호환성을 가진 Vue 템플릿 덕분에 Vue [단일 파일 컴포넌트](https://vuejs.org/guide/scaling-up/sfc.html)입니다. Vue 템플릿 기능이나 가져온 Vue 컴포넌트를 사용하여 정적 콘텐츠에 상호작용성을 삽입할 수 있습니다.
- **[Vue로 향상된 마크다운](./using-vue)**: 각 마크다운 페이지는 HTML과 100% 문법 호환성을 가진 Vue [단일 파일 컴포넌트](https://vuejs.org/guide/scaling-up/sfc.html)입니다. Vue 템플릿 기능이나 컴포넌트를 사용하여 정적 콘텐츠에 상호작용 기능을 포함할 수 있습니다.
## 성능 {#performance}
전통적인 SSG들과 달리 각 탐색이 전체 페이지 새로고침을 초래하는 것이 아니라, VitePress로 생성된 웹사이트는 초기 방문 시 정적 HTML을 제공하지만, 사이트 내 이후 탐색에 대해서는 [싱글 페이지 애플리케이션](https://en.wikipedia.org/wiki/Single-page_application) (SPA)이 됩니다. 우리의 견해에 따르면, 이 모델은 성능에 있어 최적의 균형을 제공합니다:
전통적인 SSG들과 달리, VitePress로 생성된 웹사이트는 초기 방문 시 정적 HTML을 제공하지만, 이후 사이트 내 탐색에 대해서는 [단일 페이지 애플리케이션](https://en.wikipedia.org/wiki/Single-page_application) (SPA)이 됩니다. 이 모델은 성능에 대한 최적의 균형을 제공합니다:
- **빠른 초기 로딩**
어떤 페이지에 대한 초기 방문은 빠른 로딩 속도와 최적의 SEO를 위해 정적으로 사전 렌더링된 HTML이 제공됩니다. 그런 다음 페이지는 Vue SPA로 페이지를 변환하는 JavaScript 번들을 로드합니다("hydration"). SPA hydration이 느리다는 일반적인 가정과 달리, 이 과정은 실제로 Vue 3의 순수 성능과 컴파일러 최적화 덕분에 매우 빠릅니다. [PageSpeed Insights](https://pagespeed.web.dev/report?url=https%3A%2F%2Fvitepress.dev%2F)에서 일반적인 VitePress 사이트는 저사양 모바일 장치에서도 느린 네트워크에서 거의 완벽한 성능 점수를 달성합니다.
초기 페이지 방문은 사전 렌더링된 HTML을 제공하여 빠른 로딩 속도와 최적의 SEO를 제공합니다. 그 후 페이지를 Vue SPA로 전환하는 JavaScript 번들이 로드됩니다(이것을 "하이드레이션"이라고 함). 일반적으로 SPA 하이드레이션이 느리다고 생각할 수 있지만, Vue 3의 성능과 컴파일러 최적화 덕분에 이 과정은 매우 빠릅니다. [PageSpeed Insights](https://pagespeed.web.dev/report?url=https%3A%2F%2Fvitepress.dev%2F)에서 일반적인 VitePress 사이트는 네트워크 속도가 느린 저가형 모바일 기기에서도 거의 완벽한 성능 점수를 얻습니다.
- **빠른 후속 로드 탐색**
- **빠른 포스트 로드 탐색**
더 중요한 것은 초기 로드 **이후** 사용자 경험이 개선된다는 것입니다. 사이트 내의 이후 탐색에서는 전체 페이지 새로고침이 더 이상 발생하지 않습니다. 대신, 들어오는 페이지의 콘텐츠가 가져와져 동적으로 업데이트됩니다. VitePress는 또한 뷰포트 내 링크에 대한 페이지 청크를 자동으로 사전 로드합니다. 대부분의 경우, 이후 로드 탐색은 즉각적으로 느껴질 것입니다.
더 중요한 것은 SPA 모델이 처음 로드된 후 더 나은 UX를 제공한다는 것입니다. 이후 사이트 내에서 탐색을 해도 전체 페이지가 다시 로드되는 현상이 더 이상 발생하지 않습니다. 대신 페이지의 콘텐츠를 불러와 동적으로 업데이트 합니다. 또한 VitePress는 뷰포트 내에 있는 링크의 페이지 청크를 자동으로 미리 가져옵니다. 이렇게 하면 대부분의 경우 유저는 이미 로드된 페이지에서 탐색할 때 새 페이지가 즉시 로드됩니다.
- **패널티 없는 상호작용성**
- **페널티 없는 상호작용**
정적 Markdown 내에 내장된 동적 Vue 파트를 hydrate할 수 있도록 각 Markdown 페이지는 Vue 컴포넌트로 처리되고 JavaScript로 컴파일됩니다. 이것은 비효율적으로 들릴 수 있지만, Vue 컴파일러는 정적 부분과 동적 부분을 분리하여 hydration 비용과 페이로드 크기를 최소화하는 데 충분히 똑똑합니다. 초기 페이지 로드에 대해서, 정적 부분은 JavaScript 페이로드에서 자동으로 제거되고 hydration 동안 건너뛰어집니다.
정적 마크다운 내에 내장된 동적 Vue 부분을 하이드레이션 할 수 있도록 각 마크다운 페이지는 Vue 컴포넌트로 처리되고 JavaScript로 컴파일됩니다. 이는 비효율적으로 보일 수 있지만, Vue 컴파일러는 정적 부분과 동적 부분을 분리하여 하이드레이션 비용과 페이로드 크기를 최소화합니다. 초기 페이지 로드 시, 정적 부분은 자동으로 JavaScript 페이로드에서 제거되고 하이드레이션 중 건너뜁니다.
## VuePress는 어떤가요? {#what-about-vuepress}
VitePress는 VuePress의 영적 후계자입니다. 원래 VuePress는 Vue 2와 webpack에 기반을 두고 있었습니다. Vue 3와 Vite를 기반으로 한 VitePress는 훨씬 더 나은 DX, 더 나은 프로덕션 성능, 더 완성된 기본 테마, 그리고 더욱 유연한 커스터마이징 API를 제공합니다.
VitePress는 VuePress의 후속 버전 입니다. 원래 VuePress는 Vue 2와 webpack을 기반으로 했습니다. Vue 3와 Vite를 기반으로 한 VitePress는 훨씬 더 나은 DX, 더 나은 프로덕션 성능, 더 다듬어진 기본 테마, 더 유연한 커스터마이징 API를 제공합니다.
VitePress와 VuePress 사이의 API 차이는 주로 테마와 커스터마이징에 있습니다. 기본 테마를 사용하는 VuePress 1을 사용하는 경우, VitePress로 마이그레이션하는 것이 비교적 간단할 수 있습니다.
VitePress와 VuePress의 API 차이는 주로 테마와 커스터마이징에 있습니다. 기본 테마를 사용하는 VuePress 1을 사용 중이라면 VitePress로의 마이그레이션은 비교적 간단할 것입니다.
VuePress 2에도 투자된 노력이 있으며, 이것도 Vue 3와 Vite를 지원하고 VuePress 1과 더 호환됩니다. 그러나 동시에 두 개의 SSG를 병행하여 유지하는 것은 지속 가능하지 않으므로, Vue 팀은 장기적으로 주요 권장 SSG로 VitePress에 집중하기로 결정했습니다.
VuePress 2도 Vue 3와 Vite를 지원하며 VuePress 1과의 호환성을 높이기 위해 많은 노력이 투자되었습니다. 그러나 두 SSG를 병렬로 유지하는 것은 지속 가능하지 않으므로 Vue 팀은 장기적인 관점에서 주요 권장 SSG인 VitePress에 집중하기로 결정했습니다.
Niceplugin
2 months ago
committed by
GitHub