모든 Markdown 파일은 Vue 컴포넌트로 컴파일되며 [Vite](https://vitejs.dev/guide/assets.html)에 의해 처리됩니다. 상대 URL을 사용하여 어떠한 자산도 참조할 수 **있으며 해야 합니다**:
@ -20,7 +20,7 @@ Markdown 파일 내의 링크로 참조된 PDF 또는 기타 문서는 자동으
모든 **정적** 경로 참조, 절대 경로를 포함하여, 작업 디렉토리 구조를 기반으로 해야 합니다.
## Public 디렉토리
## Public 디렉토리 {#the-public-directory}
Markdown이나 테마 컴포넌트에서 직접 참조되지 않은 정적 자산을 제공할 필요가 있거나, 특정 파일을 원본 파일명으로 제공하고 싶은 경우가 있을 수 있습니다. 이러한 파일의 예로는 `robots.txt`, 파비콘, PWA 아이콘이 있습니다.
@ -30,7 +30,7 @@ Markdown이나 테마 컴포넌트에서 직접 참조되지 않은 정적 자
`public`에 배치된 파일을 참조할 때는 루트 절대 경로를 사용해야 한다는 점에 유의하세요 - 예를 들어, `public/icon.png`는 소스 코드에서 항상 `/icon.png`로 참조되어야 합니다.
## 기본 URL
## 기본 URL {#base-url}
사이트가 루트 URL이 아닌 곳에 배포되는 경우, `.vitepress/config.js`에서 `base` 옵션을 설정해야 합니다. 예를 들어, 사이트를 `https://foo.github.io/bar/`에 배포할 계획이라면, `base`는 `'/bar/'`(항상 슬래시로 시작하고 끝나야 함)로 설정해야 합니다.
테마 컴포넌트에서 사용할 수 있는 모든 것에 대한 [런타임 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).
@ -168,7 +168,7 @@ npm 패키지로 테마를 배포하려면 다음 단계를 따르세요:
# VitePress 사이트 배포하기 {#deploy-your-vitepress-site}
다음 가이드는 몇 가지 공유된 가정을 바탕으로 합니다:
@ -19,7 +19,7 @@ outline: deep
}
```
## 로컬에서 빌드하고 테스트하기
## 로컬에서 빌드하고 테스트하기 {#build-and-test-locally}
1. 이 명령어를 실행하여 문서를 빌드합니다:
@ -47,13 +47,13 @@ outline: deep
이제 `docs:preview` 메소드가 `http://localhost:8080`에서 서버를 시작합니다.
## public 기본 경로 설정하기
## public 기본 경로 설정하기 {#setting-a-public-base-path}
기본적으로, 사이트가 도메인의 루트 경로(`/`)에서 배포될 것으로 가정합니다. 사이트가 하위 경로, 예를 들어 `https://mywebsite.com/blog/`에서 제공되는 경우, VitePress 구성에서 [`base`](../reference/site-config#base) 옵션을 `'/blog/'`로 설정해야 합니다.
**예:** GitHub(또는 GitLab) 페이지를 사용하여 `user.github.io/repo/`로 배포하는 경우, `base`를 `/repo/`로 설정하세요.
## HTTP 캐시 헤더
## HTTP 캐시 헤더 {#http-cache-headers}
프로덕션 서버에서 HTTP 헤더를 제어할 수 있다면, 반복 방문 시 성능을 향상시키기 위해 `cache-control` 헤더를 구성할 수 있습니다.
VitePress의 기본 테마는 문서화에 최적화되어 있으며, 커스터마이징이 가능합니다. [기본 테마 구성 개요](../reference/default-theme-config)를 참조하여 가능한 옵션의 전체 목록을 확인하세요.
@ -18,7 +18,7 @@ VitePress의 기본 테마는 문서화에 최적화되어 있으며, 커스터
진행하기 전에, 사용자 지정 테마가 어떻게 작동하는지 이해하기 위해 [사용자 지정 테마 사용하기](./custom-theme)를 먼저 읽어보세요.
:::
## CSS 커스터마이징하기
## CSS 커스터마이징하기 {#customizing-css}
기본 테마의 CSS는 루트 레벨 CSS 변수를 오버라이딩하여 커스터마이즈 할 수 있습니다:
@ -40,7 +40,7 @@ export default DefaultTheme
오버라이딩할 수 있는 [기본 테마 CSS 변수](https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css)를 확인하세요.
## 다른 폰트 사용하기
## 다른 폰트 사용하기 {#using-different-fonts}
VitePress는 기본 폰트로 [Inter](https://rsms.me/inter/)를 사용하며, 빌드 출력물에 폰트를 포함합니다. 또한, 이 폰트는 프로덕션 환경에서 자동으로 프리로드됩니다. 하지만, 다른 메인 폰트를 사용하고 싶은 경우에는 바람직하지 않을 수 있습니다.
@ -92,7 +92,7 @@ export default {
}
```
## 전역 컴포넌트 등록하기
## 전역 컴포넌트 등록하기 {#registering-global-components}
```js
// .vitepress/theme/index.js
@ -125,7 +125,7 @@ export default {
Vite를 사용하기 때문에, Vite의 [글로브 임포트 기능](https://vitejs.dev/guide/features.html#glob-import)을 활용하여 컴포넌트 디렉터리를 자동으로 등록할 수도 있습니다.
## 레이아웃 슬롯
## 레이아웃 슬롯 {#layout-slots}
기본 테마의 `<Layout/>` 컴포넌트는 페이지의 특정 위치에 컨텐츠를 삽입할 수 있도록 몇 개의 슬롯을 제공합니다. 아웃라인 앞에 컴포넌트를 삽입하는 예시입니다:
@ -218,9 +218,9 @@ export default {
- `nav-screen-content-before`
- `nav-screen-content-after`
## 뷰 전환 API 사용하기
## 뷰 전환 API 사용하기 {#using-view-transitions-api}
### 외형 토글 시
### 외형 토글 시 {#on-appearance-toggle}
기본 테마를 확장하여 색상 모드가 토글될 때 사용자 정의 전환을 제공할 수 있습니다. 예시:
VitePress는 모든 Markdown 파일에서 YAML 전문(frontmatter)을 지원하며, 이를 [gray-matter](https://github.com/jonschlinkert/gray-matter)로 분석합니다. 전문은 Markdown 파일의 맨 위에 위치해야 합니다(`<script>` 태그를 포함한 모든 요소 이전에)하며, 세 개의 대시 라인 사이에 유효한 YAML 형식으로 설정되어야 합니다. 예시:
@ -15,7 +15,7 @@ editLink: true
또한 페이지상의 동적 Vue 표현식에서 사용될 수 있는 자체적인 전문 데이터를 정의할 수 있습니다.
## 전문 데이터 접근
## 전문 데이터 접근 {#accessing-frontmatter-data}
전문 데이터는 특별한 `$frontmatter` 전역 변수를 통해 접근할 수 있습니다:
@ -34,7 +34,7 @@ editLink: true
`<script setup>`에서 현재 페이지의 전문 데이터에 접근하려면 [`useData()`](../reference/runtime-api#usedata) 헬퍼를 사용할 수 있습니다.
독립 실행형 VitePress 사이트를 빌딩하는 경우, 현재 디렉토리(`./`)에 사이트를 스캐폴딩할 수 있습니다. 그러나 다른 소스 코드와 함께 기존 프로젝트에 VitePress를 설치하는 경우, 프로젝트의 나머지 부분과 별도로 (`예: `./docs`) 중첩된 디렉토리에 사이트를 스캐폴딩하는 것이 좋습니다.
@ -116,7 +117,7 @@ VitePress 프로젝트를 `./docs`에 스캐폴딩하기로 선택한 경우 생
기본적으로, VitePress는 개발 서버 캐시를 `.vitepress/cache`에, 프로덕션 빌드 출력을 `.vitepress/dist`에 저장합니다. Git을 사용하는 경우, 이들을 `.gitignore` 파일에 추가해야 합니다. 이 위치는 또한 [구성할 수 있습니다](../reference/site-config#outdir).
:::
### 설정 파일
### 설정 파일 {#the-config-file}
설정 파일(`.vitepress/config.js`)을 사용하면 사이트의 제목과 설명과 같은 VitePress 사이트의 다양한 측면을 커스터마이즈할 수 있습니다:
@ -135,7 +136,7 @@ export default {
`themeConfig` 옵션을 통해 테마의 동작을 구성할 수도 있습니다. 모든 구성 옵션에 대한 전체 세부 정보는 [구성 참조](../reference/site-config)를 참조하십시오.
### 소스 파일
### 소스 파일 {#source-files}
`.vitepress` 디렉토리 밖의 마크다운 파일들은 **소스 파일**로 간주됩니다.
@ -143,7 +144,7 @@ VitePress는 **파일 기반 라우팅**을 사용합니다: 각 `.md` 파일은
VitePress는 또한 깨끗한 URL 생성, 경로 리라이팅 및 동적 페이지 생성 기능을 제공합니다. 이러한 내용은 [라우팅 가이드](./routing)에서 다뤄질 것입니다.
## 실행 및 작동
## 실행 및 작동 {#up-and-running}
설정 프로세스 중에 허용한 경우, 도구는 `package.json`에 다음 npm 스크립트를 주입해야 합니다:
@ -207,7 +208,7 @@ $ bun vitepress dev docs
개발 서버는 `http://localhost:5173`에서 실행되어야 합니다. 브라우저에서 URL을 방문하여 새 사이트를 확인하세요!
## 다음 단계는?
## 다음 단계는? {#what-s-next}
- 생성된 HTML로 마크다운 파일이 어떻게 매핑되는지 더 잘 이해하려면, [라우팅 가이드](./routing)로 진행하세요.
**전문가 팁:** 구성 파일은 `docs/.vitepress/config/index.ts`에도 저장될 수 있습니다. 로케일별로 구성 파일을 생성한 다음 이를 `index.ts`에서 병합하여 내보내는 것으로, 내용을 구성하는데 도움이 될 수 있습니다.
## 각 로케일별 별도의 디렉토리
## 각 로케일별 별도의 디렉토리 {#separate-directory-for-each-locale}
다음은 완전히 괜찮은 구조입니다:
@ -108,6 +109,6 @@ watchEffect(() => {
</template>
```
## RTL 지원 (실험적)
## 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 플러그인을 구성해야 합니다.
@ -176,7 +176,7 @@ TOC의 렌더링은 `markdown.toc` 옵션을 사용하여 구성할 수 있습
세부 정보 블록입니다.
:::
### 사용자 정의 제목
### 사용자 정의 제목 {#custom-title}
컨테이너의 "유형" 바로 뒤에 텍스트를 추가하여 사용자 정의 제목을 설정할 수 있습니다.
@ -263,7 +263,7 @@ VitePress와 스타일 및 라우터 충돌을 방지하기 위해 사용될 수
})
```
## GitHub 스타일 경고
## 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)와 같은 방식으로 렌더링됩니다.
## 코드 블록 내 구문 강조 {#syntax-highlighting-in-code-blocks}
VitePress는 마크다운 코드 블록 내 언어 문법을 색상이 있는 텍스트로 강조하는 데 [Shiki](https://github.com/shikijs/shiki)를 사용합니다. Shiki는 다양한 프로그래밍 언어를 지원합니다. 코드 블록의 시작 백틱에 유효한 언어 별칭을 추가하기만 하면 됩니다:
@ -345,7 +345,7 @@ Shiki의 저장소에서 사용 가능한 [유효한 언어 목록](https://shik
또한 응용 프로그램 구성에서 구문 강조 테마를 사용자 지정할 수 있습니다. 자세한 내용은 [`markdown` 옵션](../reference/site-config#markdown)을 참조하세요.
## 코드 블록에서 라인 강조
## 코드 블록에서 라인 강조 {#line-highlighting-in-code-blocks}
**입력**
@ -441,7 +441,7 @@ export default {
}
```
## 코드 블록에서 포커싱
## 코드 블록에서 포커싱 {#focus-in-code-blocks}
`// [!code focus]` 주석을 라인에 추가하면 해당 라인이 포커싱되고 코드의 다른 부분은 흐릿하게 처리됩니다.
@ -473,7 +473,7 @@ export default {
}
```
## 코드 블록 내 컬러 차이점
## 코드 블록 내 컬러 차이점 {#colored-diffs-in-code-blocks}
`// [!code --]` 또는 `// [!code ++]` 주석을 라인에 추가하면 해당 라인의 차이점을 나타내며, 코드 블록의 색상을 유지합니다.
@ -505,7 +505,7 @@ export default {
}
```
## 코드 블록 내 오류 및 경고
## 코드 블록 내 오류 및 경고 {#errors-and-warnings-in-code-blocks}
`// [!code warning]` 또는 `// [!code error]` 주석을 라인에 추가하면 해당 색깔에 따라 라인이 색칠됩니다.
@ -537,7 +537,7 @@ export default {
}
```
## 라인 번호
## 라인 번호 {#line-numbers}
구성을 통해 각 코드 블록에 라인 번호를 활성화할 수 있습니다:
@ -597,7 +597,7 @@ const line3 = 'This is line 3'
const line4 = 'This is line 4'
```
## 코드 스니펫 가져오기
## 코드 스니펫 가져오기 {#import-code-snippets}
다음 문법을 통해 기존 파일에서 코드 스니펫을 가져올 수 있습니다:
@ -666,7 +666,7 @@ const line4 = 'This is line 4'
이는 파일 확장명에서 소스 언어를 유추할 수 없을 때 유용합니다.
## 코드 그룹
## 코드 그룹 {#code-groups}
다음과 같이 여러 코드 블록을 그룹화할 수 있습니다:
@ -754,7 +754,7 @@ export default config
:::
## 마크다운 파일 포함
## 마크다운 파일 포함 {#markdown-file-inclusion}
다른 마크다운 파일에 마크다운 파일을 포함시킬 수 있으며, 중첩도 가능합니다.
@ -875,7 +875,7 @@ VS Code 영역을 사용하여 코드 파일의 해당 부분만 포함할 수
파일이 없는 경우 오류를 발생시키지 않으니, 이 기능을 사용할 때는 내용이 예상대로 렌더링되고 있는지 확인해야 합니다.
:::
## 수식
## 수식 {#math-equations}
현재 선택 사항입니다. 활성화하려면 `markdown-it-mathjax3`를 설치하고 설정 파일에서 `markdown.math`를 `true`로 설정해야 합니다:
마크다운을 통해 추가된 각 이미지에 대해 지연 로딩을 활성화하려면 설정 파일에서 `lazyLoading`을 `true`로 설정하세요:
@ -935,7 +935,7 @@ export default {
}
```
## 고급 설정
## 고급 설정 {#advanced-configuration}
VitePress는 마크다운 렌더링을 위해 [markdown-it](https://github.com/markdown-it/markdown-it)을 사용합니다. 위의 확장 프로그램 대부분은 커스텀 플러그인을 통해 구현됩니다. `.vitepress/config.js`의 `markdown` 옵션을 사용하여 `markdown-it` 인스턴스를 더욱 커스터마이징할 수 있습니다:
# Migration from VitePress 0.x {#migration-from-vitepress-0-x}
If you're coming from VitePress 0.x version, there're several breaking changes due to new features and enhancement. Please follow this guide to see how to migrate your app over to the latest VitePress.
## App Config
## App Config {#app-config}
- The internationalization feature is not yet implemented.
## Theme Config
## Theme Config {#theme-config}
- `sidebar` option has changed its structure.
- `children` key is now named `items`.
@ -17,7 +17,7 @@ If you're coming from VitePress 0.x version, there're several breaking changes d
- `lastUpdated` option is now split into `config.lastUpdated` and `themeConfig.lastUpdatedText`.
- `carbonAds.carbon` is changed to `carbonAds.code`.
## Frontmatter Config
## Frontmatter Config {#frontmatter-config}
- `home: true` option has changed to `layout: home`. Also, many Homepage related settings have been modified to provide additional features. See [Home Page guide](../reference/default-theme-home-page) for details.
- `footer` option is moved to [`themeConfig.footer`](../reference/default-theme-config#footer).
# Migration from VuePress {#migration-from-vuepress}
## Config
## Config {#config}
### Sidebar
### Sidebar {#sidebar}
The sidebar is no longer automatically populated from frontmatter. You can [read the frontmatter yourself](https://github.com/vuejs/vitepress/issues/572#issuecomment-1170116225) to dynamically populate the sidebar. [Additional utilities for this](https://github.com/vuejs/vitepress/issues/96) may be provided in the future.
## Markdown
## Markdown {#markdown}
### Images
### Images {#images}
Unlike VuePress, VitePress handles [`base`](./asset-handling#base-url) of your config automatically when you use static image.
페이지 간 연결 시 절대 경로와 상대 경로를 모두 사용할 수 있습니다. `.md` 및 `.html` 확장자 모두 작동하더라도, 파일 확장자를 생략하여 VitePress가 설정에 기반한 최종 URL을 생성하도록 하는 것이 좋은 방법입니다.
@ -95,7 +95,7 @@ src/시작하기.md --> /시작하기.html
[Asset Handling](./asset-handling)에서 이미지와 같은 에셋에 연결하는 방법에 대해 자세히 알아보세요.
### VitePress 페이지가 아닌 페이지로 연결
### VitePress 페이지가 아닌 페이지로 연결 {#linking-to-non-vitepress-pages}
VitePress에서 생성하지 않은 사이트의 페이지에 연결하려면, 전체 URL을 사용해야 합니다(새 탭에서 열림) 또는 명시적으로 대상을 지정해야 합니다:
@ -121,7 +121,7 @@ VitePress에서 생성하지 않은 사이트의 페이지에 연결하려면,
:::
## 깨끗한 URL 생성
## 깨끗한 URL 생성 {#generating-clean-url}
::: warning 서버 지원 필요
VitePress로 깨끗한 URL을 제공하려면 서버 측 지원이 필요합니다.
@ -150,7 +150,7 @@ VitePress로 깨끗한 URL을 제공하려면 서버 측 지원이 필요합니
└─ index.md
```
## 라우트 재작성
## 라우트 재작성 {#route-rewrites}
소스 디렉토리 구조와 생성된 페이지 간의 매핑을 커스터마이즈할 수 있습니다. 복잡한 프로젝트 구조를 가지고 있을 때 유용합니다. 예를 들어, 여러 패키지가 있는 모노레포를 가지고 있고, 소스 파일과 함께 문서를 배치하고 싶다고 가정해 봅시다:
@ -207,11 +207,11 @@ export default {
```
:::
## 동적 라우트
## 동적 라우트 {#dynamic-routes}
단일 마크다운 파일과 동적 데이터를 사용하여 많은 페이지를 생성할 수 있습니다. 예를 들어, 프로젝트의 모든 패키지에 해당하는 페이지를 생성하는 `패키지/[pkg].md` 파일을 만들 수 있습니다. 여기서 `[pkg]` 세그먼트는 각 페이지를 다른 페이지와 구별하는 라우트 **매개변수**입니다.
### 경로 로더 파일
### 경로 로더 파일 {#paths-loader-file}
VitePress는 정적 사이트 생성기이므로, 가능한 페이지 경로는 빌드 시간에 결정되어야 합니다. 따라서 동적 라우트 페이지는 **경로 로더 파일**을 동반해야 합니다. `패키지/[pkg].md`의 경우, `패키지/[pkg].paths.js`(`.ts`도 지원)가 필요합니다:
@ -247,7 +247,7 @@ export default {
└─ bar.html
```
### 여러 매개변수
### 여러 매개변수 {#multiple-params}
동적 라우트는 여러 매개변수를 포함할 수 있습니다:
@ -284,7 +284,7 @@ export default {
└─ bar-2.0.0.html
```
### 동적으로 경로 생성
### 동적으로 경로 생성 {#dynamically-generating-paths}
경로 로더 모듈은 Node.js에서 실행되며 빌드 시간에만 실행됩니다. 로컬 또는 원격 데이터를 사용하여 경로 배열을 동적으로 생성할 수 있습니다.
@ -323,7 +323,7 @@ export default {
}
```
### 페이지에서 매개변수 접근
### 페이지에서 매개변수 접근 {#accessing-params-in-page}
각 페이지에 추가 데이터를 전달하기 위해 매개변수를 사용할 수 있습니다. 마크다운 라우트 파일은 `$params` 전역 속성을 통해 현재 페이지 매개변수에 Vue 표현식에서 접근할 수 있습니다:
@ -345,7 +345,7 @@ console.log(params.value)
</script>
```
### 원시 콘텐츠 렌더링
### 원시 콘텐츠 렌더링 {#rendering-raw-content}
페이지로 전달된 매개변수는 클라이언트 JavaScript 페이로드에 직렬화되므로, 예를 들어 원격 CMS에서 가져온 원시 마크다운이나 HTML 콘텐츠와 같이 무거운 데이터를 매개변수로 전달하지 마십시오.
VitePress는 사이트를 위한 `sitemap.xml` 파일 생성을 기본적으로 지원합니다. 이를 활성화하려면 다음을 `.vitepress/config.js`에 추가하세요:
@ -12,7 +12,7 @@ export default {
`<lastmod>` 태그를 `sitemap.xml`에 포함하려면 [`lastUpdated`](../reference/default-theme-last-updated) 옵션을 활성화할 수 있습니다.
## 옵션
## 옵션 {#options}
사이트맵 지원은 [`sitemap`](https://www.npmjs.com/package/sitemap) 모듈에 의해 제공됩니다. 설정 파일의 `sitemap` 옵션에 이 모듈이 지원하는 모든 옵션을 전달할 수 있습니다. 이 옵션들은 `SitemapStream` 생성자에 직접 전달됩니다. 자세한 내용은 [`sitemap` 문서](https://www.npmjs.com/package/sitemap#options-you-can-pass)를 참조하세요. 예제:
VitePress에서 각 Markdown 파일은 HTML로 컴파일된 다음 [Vue 단일 파일 컴포넌트](https://vuejs.org/guide/scaling-up/sfc.html)로 처리됩니다. 이는 Markdown 내에서 동적 템플릿, Vue 컴포넌트 사용 또는 `<script>` 태그를 추가하여 임의의 페이지 내 Vue 컴포넌트 로직을 사용할 수 있음을 의미합니다.
@ -8,9 +8,9 @@ VitePress가 Vue의 컴파일러를 활용하여 Markdown 콘텐츠의 순수
모든 Vue 사용은 SSR과 호환되어야 합니다. 자세한 내용과 일반적인 해결 방법은 [SSR 호환성](./ssr-compat)을 참조하십시오.
:::
## 템플릿
## 템플릿 {#templating}
### 보간(interpolation)
### 보간(interpolation) {#interpolation}
각 Markdown 파일은 먼저 HTML로 컴파일되고 나서 Vite 프로세스 파이프라인으로 Vue 컴포넌트로 전달됩니다. 이는 텍스트에서 Vue 스타일 보간을 사용할 수 있음을 의미합니다:
@ -24,7 +24,7 @@ VitePress가 Vue의 컴파일러를 활용하여 Markdown 콘텐츠의 순수
@ -38,7 +38,7 @@ VitePress가 Vue의 컴파일러를 활용하여 Markdown 콘텐츠의 순수
<divclass="language-text"><pre><code><spanv-for="i in 3">{{ i }} </span></code></pre></div>
## `<script>`와 `<style>`
## `<script>`와 `<style>` {#script-and-style}
Markdown 파일의 최상위 `<script>` 및 `<style>` 태그는 Vue SFC에서와 마찬가지로 작동합니다. `<script setup>`, `<style module>` 등을 포함합니다. 여기서 주된 차이점은 `<template>` 태그가 없다는 것입니다: 다른 모든 최상위 콘텐츠는 Markdown입니다. 또한 모든 태그는 frontmatter **이후에** 위치해야 함을 유의하십시오:
@ -96,11 +96,11 @@ const { page } = useData()
}
```
## 컴포넌트 사용하기
## 컴포넌트 사용하기 {#using-components}
Markdown 파일 내에서 Vue 컴포넌트를 직접 가져오고 사용할 수 있습니다.
### Markdown에서 가져오기
### Markdown에서 가져오기 {#importing-in-markdown}
컴포넌트가 몇 페이지에서만 사용되는 경우, 해당되는 곳에서 명시적으로 가져오는 것이 좋습니다. 이를 통해 적절하게 코드를 분할하고 관련 페이지가 표시될 때만 로드할 수 있습니다:
@ -120,7 +120,7 @@ import CustomComponent from '../components/CustomComponent.vue'
컴포넌트가 대부분의 페이지에서 사용될 것인 경우, Vue 앱 인스턴스를 사용자 지정하여 전역적으로 등록할 수 있습니다. 예제는 [기본 테마 확장](./extending-default-theme#registering-global-components) 관련 섹션을 참조하십시오.
@ -128,7 +128,7 @@ import CustomComponent from '../components/CustomComponent.vue'
커스텀 컴포넌트의 이름이 하이픈을 포함하거나 파스칼케이스(PascalCase)인지 확인하십시오. 그렇지 않으면 인라인 요소로 처리되어 `<p>` 태그 내에 포함되어 하이드레이션 불일치가 발생할 수 있습니다. `<p>`는 내부에 블록 요소를 포함할 수 없기 때문입니다.
:::
### 헤더에 컴포넌트 사용하기 <ComponentInHeader/>
### 헤더에 컴포넌트 사용하기 <ComponentInHeader/> {#using-components-in-headers}
헤더에서 Vue 컴포넌트를 사용할 수 있지만, 다음 구문 사이의 차이를 유의하십시오:
@ -144,7 +144,7 @@ import CustomComponent from '../components/CustomComponent.vue'
:::
## 이스케이프
## 이스케이프 {#escaping}
`v-pre` 지시문을 사용하여 `<span>`이나 다른 요소에 Vue 보간을 이스케이프할 수 있습니다:
@ -178,7 +178,7 @@ import CustomComponent from '../components/CustomComponent.vue'
</div>
## 코드 블록에서 이스케이프 해제하기
## 코드 블록에서 이스케이프 해제하기 {#unescape-in-code-blocks}
기본적으로 모든 fenced 코드 블록은 자동으로 `v-pre`로 둘러싸입니다. 따라서 내부에서 Vue 구문을 처리하지 않습니다. 펜스 내에서 Vue 스타일 보간을 활성화하려면, 예를 들어 `js-vue`처럼 언어에 `-vue` 접미사를 추가할 수 있습니다:
@ -198,7 +198,7 @@ import CustomComponent from '../components/CustomComponent.vue'
이는 일부 토큰이 제대로 구문 강조되지 않을 수 있음을 의미합니다.
## CSS 전처리기 사용하기
## CSS 전처리기 사용하기 {#using-css-pre-processors}
VitePress는 CSS 전처리기에 대한 [내장 지원](https://vitejs.dev/guide/features.html#css-pre-processors)을 가지고 있습니다: `.scss`, `.sass`, `.less`, `.styl` 및 `.stylus` 파일. 이것들을 위한 Vite 특정 플러그인을 설치할 필요는 없지만, 해당 전처리기 자체는 설치해야 합니다:
@ -222,7 +222,7 @@ npm install -D stylus
</style>
```
## Teleports 사용하기
## Teleports 사용하기 {#using-teleports}
현재 VitePress는 본문으로만 teleport에 대한 SSG 지원을 가지고 있습니다. 다른 대상을 위해서는, 내장된 `<ClientOnly>` 컴포넌트 내에 감싸거나 텔레포트 마크업을 최종 페이지 HTML의 올바른 위치에 주입할 수 있습니다 [`postRender` 훅](../reference/site-config#postrender)을 통해.
VitePress는 빠르고 컨텐츠 중심의 웹사이트를 구축하기 위해 설계된 [정적 사이트 생성기](https://en.wikipedia.org/wiki/Static_site_generator) (SSG)입니다. 간단히 말해, VitePress는 [Markdown](https://en.wikipedia.org/wiki/Markdown)으로 작성된 소스 컨텐츠를 가져와서 테마를 적용하고, 어디에나 쉽게 배포할 수 있는 정적 HTML 페이지를 생성합니다.
@ -8,7 +8,7 @@ VitePress는 빠르고 컨텐츠 중심의 웹사이트를 구축하기 위해
</div>
## 사용 사례
## 사용 사례 {#use-cases}
- **문서화**
@ -22,7 +22,7 @@ VitePress는 빠르고 컨텐츠 중심의 웹사이트를 구축하기 위해
공식 [Vue.js 블로그](https://blog.vuejs.org/)는 로컬 콘텐츠를 기반으로 색인 페이지를 생성하는 간단한 블로그입니다.
## 개발자 경험
## 개발자 경험 {#developer-experience}
VitePress는 Markdown 컨텐츠를 다룰 때 훌륭한 개발자 경험(DX)을 제공하고자 합니다.
@ -32,7 +32,7 @@ VitePress는 Markdown 컨텐츠를 다룰 때 훌륭한 개발자 경험(DX)을
- **[Vue를 향상된 Markdown:](./using-vue)** 각 Markdown 페이지는 HTML과 100% 문법 호환성을 가진 Vue 템플릿 덕분에 Vue [단일 파일 컴포넌트](https://vuejs.org/guide/scaling-up/sfc.html)입니다. Vue 템플릿 기능이나 가져온 Vue 컴포넌트를 사용하여 정적 콘텐츠에 상호작용성을 삽입할 수 있습니다.
## 성능
## 성능 {#performance}
전통적인 SSG들과 달리 각 탐색이 전체 페이지 새로고침을 초래하는 것이 아니라, VitePress로 생성된 웹사이트는 초기 방문 시 정적 HTML을 제공하지만, 사이트 내 이후 탐색에 대해서는 [싱글 페이지 애플리케이션](https://en.wikipedia.org/wiki/Single-page_application) (SPA)이 됩니다. 우리의 견해에 따르면, 이 모델은 성능에 있어 최적의 균형을 제공합니다:
@ -48,7 +48,7 @@ VitePress는 Markdown 컨텐츠를 다룰 때 훌륭한 개발자 경험(DX)을
정적 Markdown 내에 내장된 동적 Vue 파트를 hydrate할 수 있도록 각 Markdown 페이지는 Vue 컴포넌트로 처리되고 JavaScript로 컴파일됩니다. 이것은 비효율적으로 들릴 수 있지만, Vue 컴파일러는 정적 부분과 동적 부분을 분리하여 hydration 비용과 페이로드 크기를 최소화하는 데 충분히 똑똑합니다. 초기 페이지 로드에 대해서, 정적 부분은 JavaScript 페이로드에서 자동으로 제거되고 hydration 동안 건너뛰어집니다.
## VuePress는 어떤가요?
## VuePress는 어떤가요? {#what-about-vuepress}
VitePress는 VuePress의 영적 후계자입니다. 원래 VuePress는 Vue 2와 webpack에 기반을 두고 있었습니다. Vue 3와 Vite를 기반으로 한 VitePress는 훨씬 더 나은 DX, 더 나은 프로덕션 성능, 더 완성된 기본 테마, 그리고 더욱 유연한 커스터마이징 API를 제공합니다.
VitePress 기본 테마는 홈페이지 레이아웃을 제공하며, 이 사이트의 [홈페이지](../)에서도 사용된 것을 볼 수 있습니다. [frontmatter](./frontmatter-config)에 `layout: home`을 지정함으로써 여러분의 페이지에도 이를 사용할 수 있습니다.
@ -10,7 +10,7 @@ layout: home
하지만, 이 옵션만으로는 큰 효과를 보지 못합니다. `hero` 및 `features`와 같은 추가적인 옵션을 설정함으로써 홈페이지에 여러 가지 다른 사전 템플릿 "섹션"을 추가할 수 있습니다.
## Hero 섹션
## Hero 섹션 {#hero-section}
Hero 섹션은 홈페이지 맨 위에 옵니다. 여기에서 Hero 섹션을 구성하는 방법입니다.
@ -78,7 +78,7 @@ interface HeroAction {
}
```
### 이름 색상 사용자 정의
### 이름 색상 사용자 정의 {#customizing-the-name-color}
VitePress는 `name`에 대해 브랜드 색상 (`--vp-c-brand-1`)을 사용합니다. 하지만, `--vp-home-hero-name-color` 변수를 오버라이딩함으로써 이 색상을 사용자 정의할 수 있습니다.
@ -97,7 +97,7 @@ VitePress는 `name`에 대해 브랜드 색상 (`--vp-c-brand-1`)을 사용합
}
```
## 기능 섹션
## 기능 섹션 {#features-section}
기능 섹션에서는 Hero 섹션 바로 다음에 보여주고 싶은 기능의 수를 제한 없이 나열할 수 있습니다. 구성하려면 frontmatter에 `features` 옵션을 전달합니다.
@ -167,7 +167,7 @@ type FeatureIcon =
}
```
## 마크다운 컨텐츠
## 마크다운 컨텐츠 {#markdown-content}
`---` frontmatter 구분자 아래에 마크다운을 더함으로써 사이트의 홈페이지에 추가 컨텐츠를 추가할 수 있습니다.
페이지 [프런트매터](./frontmatter-config)에 `layout` 옵션을 설정함으로써 페이지 레이아웃을 선택할 수 있습니다. `doc`, `page`, `home`의 세 가지 레이아웃 옵션이 있습니다. 아무것도 지정하지 않으면, 해당 페이지는 `doc` 페이지로 처리됩니다.
@ -8,7 +8,7 @@ layout: doc
---
```
## Doc 레이아웃
## Doc 레이아웃 {#doc-layout}
`doc` 옵션은 기본 레이아웃이며, 전체 마크다운 내용을 "문서화"된 모양으로 스타일링합니다. 이것은 전체 내용을 `vp-doc` css 클래스로 감싸고, 그 아래 요소들에 스타일을 적용함으로써 작동합니다.
@ -21,7 +21,7 @@ layout: doc
- 개요
- [카본 광고](./default-theme-carbon-ads)
## 페이지 레이아웃
## 페이지 레이아웃 {#page-layout}
`page` 옵션은 "빈 페이지"로 처리됩니다. 마크다운은 여전히 파싱되며, 모든 [마크다운 확장](../guide/markdown) 기능은 `doc` 레이아웃과 동일하게 작동하지만, 기본 스타일은 적용받지 않습니다.
@ -29,15 +29,15 @@ layout: doc
이 레이아웃에서도 페이지가 일치하는 사이드바 구성이 있는 경우 여전히 사이드바가 표시됨을 유의하세요.
## 홈 레이아웃
## 홈 레이아웃 {#home-layout}
`home` 옵션은 템플릿화된 "홈페이지"를 생성합니다. 이 레이아웃에서는 `hero` 및 `features`와 같은 추가 옵션을 설정해 컨텐츠를 더 자세히 커스터마이즈할 수 있습니다. 자세한 내용은 [기본 테마: 홈 페이지](./default-theme-home-page)를 방문해주세요.
## 레이아웃 없음
## 레이아웃 없음 {#no-layout}
레이아웃을 원하지 않는 경우, 프런트매터를 통해 `layout: false`를 전달할 수 있습니다. 이 옵션은 완전히 맞춤화된 랜딩 페이지(기본적으로 사이드바, 내비게이션 바, 또는 푸터 없음)를 원할 때 유용합니다.
`component` 옵션을 사용하여 탐색 모음에 사용자 정의 구성 요소를 포함할 수 있습니다. `component` 키는 Vue 구성 요소 이름이어야 하며, [Theme.enhanceApp](../guide/custom-theme#theme-interface)을 사용하여 전역으로 등록해야 합니다.
VitePress는 [minisearch](https://github.com/lucaong/minisearch/)를 통해 브라우저 내 인덱스를 사용한 퍼지 전문 검색을 지원합니다. 이 기능을 활성화하려면, `.vitepress/config.ts` 파일 내에서 `themeConfig.search.provider` 옵션을 `'local'`로 설정하면 됩니다:
@ -69,7 +69,7 @@ export default defineConfig({
})
```
### miniSearch 옵션
### miniSearch 옵션 {#mini-search-options}
다음과 같이 MiniSearch를 구성할 수 있습니다:
@ -105,7 +105,7 @@ export default defineConfig({
[MiniSearch 문서](https://lucaong.github.io/minisearch/classes/MiniSearch.MiniSearch.html)에서 더 많은 정보를 얻을 수 있습니다.
### 사용자 정의 콘텐츠 렌더러
### 사용자 정의 콘텐츠 렌더러 {#custom-content-renderer}
색인 생성 전에 마크다운 콘텐츠를 렌더링하는 데 사용되는 함수를 커스터마이즈할 수 있습니다:
@ -133,7 +133,7 @@ export default defineConfig({
이 함수는 클라이언트 사이드 사이트 데이터에서 제거될 것이므로, 여기서 Node.js API를 사용할 수 있습니다.
#### 예시: 검색에서 페이지 제외
#### 예시: 검색에서 페이지 제외 {#example-excluding-pages-from-search}
페이지에서 `search: false`를 프론트매터에 추가하여 검색에서 페이지를 제외할 수 있습니다. 또는 다음과 같이 합니다:
@ -161,7 +161,7 @@ export default defineConfig({
사용자 정의 `_render` 함수를 제공하는 경우, `search: false` 프론트매터를 직접 처리해야 합니다. 또한, `md.render`가 호출되기 전에는 `env` 객체가 완전히 채워지지 않으므로, `frontmatter`와 같은 선택적 `env` 속성에 대한 검사는 그 이후에 수행해야 합니다.
:::
#### 예시: 콘텐츠 변환 - 앵커 추가
#### 예시: 콘텐츠 변환 - 앵커 추가 {#example-transforming-content-adding-anchors}
```ts
import { defineConfig } from 'vitepress'
@ -183,7 +183,7 @@ export default defineConfig({
})
```
## Algolia 검색
## Algolia 검색 {#algolia-search}
VitePress는 [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch)를 사용하여 문서 사이트 검색을 지원합니다. 시작 가이드를 참조하세요. 작동하게 하려면 `.vitepress/config.ts`에서 최소한 다음 정보를 제공해야 합니다:
@ -270,7 +270,7 @@ export default defineConfig({
[이 옵션들](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts)은 덮어쓸 수 있습니다. 공식 Algolia 문서에서 더 많은 정보를 알아보세요.
사이트 설정은 사이트의 전역 설정을 정의할 수 있는 곳입니다. 앱 설정 옵션은 사용되는 테마에 상관없이 모든 VitePress 사이트에 적용되는 설정을 정의합니다. 예를 들어, 기본 디렉토리 또는 사이트의 제목 등이 있습니다.
## 개요
## 개요 {#overview}
### 설정 해석
### 설정 해석 {#config-resolution}
설정 파일은 항상 `<root>/.vitepress/config.[ext]`에서 해석되며, 여기서 `<root>`는 여러분의 VitePress [프로젝트 루트](../guide/routing#root-and-source-directory), 그리고 `[ext]`는 지원되는 파일 확장명 중 하나입니다. TypeScript는 기본적으로 지원됩니다. 지원되는 확장명에는 `.js`, `.ts`, `.mjs`, 그리고 `.mts`가 포함됩니다.
@ -80,7 +80,7 @@ export default defineConfig({
:::
### 설정 옵션에 대한 인텔리센스
### 설정 옵션에 대한 인텔리센스 {#config-intellisense}
`defineConfig` 헬퍼를 사용하면 설정 옵션에 대해 TypeScript로 제공되는 인텔리센스를 활용할 수 있습니다. 여러분의 IDE가 지원한다면, JavaScript와 TypeScript 모두에서 작동할 것입니다.
@ -92,7 +92,7 @@ export default defineConfig({
})
```
### 타입이 지정된 테마 설정
### 타입이 지정된 테마 설정 {#typed-theme-config}
기본적으로, `defineConfig` 헬퍼는 기본 테마에서 테마 설정 유형을 예상합니다:
[Markdown-It](https://github.com/markdown-it/markdown-it) 인스턴스를 VitePress 설정에서 [markdown](#markdown) 옵션을 사용하여 구성할 수 있습니다.
## 사이트 메타데이터
## 사이트 메타데이터 {#site-metadata}
### title
@ -217,7 +217,7 @@ type HeadConfig =
| [string, Record<string,string>, string]
```
#### 예제: 파비콘 추가
#### 예제: 파비콘 추가 {#example-adding-a-favicon}
```ts
export default {
@ -229,7 +229,7 @@ export default {
*/
```
#### 예제: Google Fonts 추가
#### 예제: Google Fonts 추가 {#example-adding-google-fonts}
```ts
export default {
@ -256,7 +256,7 @@ export default {
*/
```
#### 예제: 서비스 워커 등록
#### 예제: 서비스 워커 등록 {#example-registering-a-service-worker}
```ts
export default {
@ -284,7 +284,7 @@ export default {
*/
```
#### 예제: Google Analytics 사용
#### 예제: Google Analytics 사용 {#example-using-google-analytics}
```ts
export default {
@ -343,7 +343,7 @@ export default {
}
```
## 라우팅
## 라우팅 {#routing}
### cleanUrls
@ -370,7 +370,7 @@ export default {
}
```
## 빌드
## 빌드 {#build}
### srcDir
@ -485,7 +485,7 @@ export default {
`true`로 설정하면, 프로덕션 앱이 [MPA 모드](../guide/mpa-mode)로 빌드됩니다. MPA 모드는 기본적으로 0kb의 JavaScript를 제공하지만, 클라이언트 측 탐색을 비활성화하고 상호작용에 대해 명시적인 동의가 필요합니다.
## 테마
## 테마 {#theming}
### appearance
@ -513,7 +513,7 @@ Git을 사용하여 각 페이지의 마지막 업데이트 타임스탬프를
기본 테마를 사용하는 경우, 이 옵션을 활성화하면 각 페이지의 마지막 업데이트 시간이 표시됩니다. [`themeConfig.lastUpdatedText`](./default-theme-config#lastupdatedtext) 옵션을 통해 텍스트를 사용자 정의할 수 있습니다.
## 사용자 정의
## 사용자 정의 {#customization}
### markdown
@ -557,7 +557,7 @@ export default {
}
```
## 빌드 후크
## 빌드 후크 {#build-hooks}
VitePress 빌드 후크는 웹사이트에 새로운 기능과 동작을 추가할 수 있습니다:
@ -654,7 +654,7 @@ export default {
}
```
#### 예시: 정규 URL `<link>` 추가
#### 예시: 정규 URL `<link>` 추가 {#example-adding-a-canonical-url-link}
Niceplugin
2 years ago