Layout Personalizado!
+ + +Layout Personalizado!
+ +Layout Personalizado!
+ +Layout Personalizado!
+ +{{ data }}
+```
+
+Saída:
+
+```json
+{
+ "hello": "world"
+}
+```
+
+Você notará que o próprio carregador de dados não exporta o `data`. É o VitePress chamando o método `load()` nos bastidores e expondo implicitamente o resultado por meio da exportação nomeada `data`.
+
+Isso funciona mesmo se o carregador for assíncrono:
+
+```js
+export default {
+ async load() {
+ // buscar dados remotos
+ return (await fetch('...')).json()
+ }
+}
+```
+
+## Dados de Arquivos Locais {#data-from-local-files}
+
+Quando você precisa gerar dados com base em arquivos locais, você deve usar a opção `watch` no carregador de dados para que as alterações feitas nesses arquivos possam acionar atualizações rápidas.
+
+A opção `watch` também é conveniente porque você pode usar [padrões glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) para corresponder a vários arquivos. Os padrões podem ser relativos ao próprio arquivo do carregador, e a função `load()` receberá os arquivos correspondentes como caminhos absolutos.
+
+O exemplo a seguir mostra o carregamento de arquivos CSV e a transformação deles em JSON usando [csv-parse](https://github.com/adaltas/node-csv/tree/master/packages/csv-parse/). Como este arquivo só é executado no tempo da construção, você não enviará o procesador CSV para o cliente!
+
+```js
+import fs from 'node:fs'
+import { parse } from 'csv-parse/sync'
+
+export default {
+ watch: ['./data/*.csv'],
+ load(watchedFiles) {
+ // watchedFiles será um array de caminhos absolutos dos arquivos correspondidos.
+ // gerar um array de metadados de post que pode ser usada para mostrar
+ // uma lista no layout do tema
+ return watchedFiles.map((file) => {
+ return parse(fs.readFileSync(file, 'utf-8'), {
+ columns: true,
+ skip_empty_lines: true
+ })
+ })
+ }
+}
+```
+
+## `createContentLoader`
+
+Ao construir um site focado em conteúdo, frequentemente precisamos criar uma página de "arquivo" ou "índice": uma página onde listamos todas as entradas disponíveis em nossa coleção de conteúdo, por exemplo, artigos de blog ou páginas de API. Nós **podemos** implementar isso diretamente com a API de carregador de dados, mas como este é um caso de uso tão comum, VitePress também fornece um auxiliar `createContentLoader` para simplificar isso:
+
+```js
+// posts.data.js
+import { createContentLoader } from 'vitepress'
+
+export default createContentLoader('posts/*.md', /* opções */)
+```
+
+O auxiliar aceita um padrão glob relativo ao [diretório fonte](./routing#source-directory) e retorna um objeto de carregador de dados `{ watch, load }` que pode ser usado como exportação padrão em um arquivo de carregador de dados. Ele também implementa cache com base nos selos de data do arquivo para melhorar o desempenho no desenvolvimento.
+
+Note que o carregador só funciona com arquivos Markdown - arquivos não-Markdown correspondidos serão ignorados.
+
+Os dados carregados serão um _array_ com o tipo `ContentData[]`:
+
+```ts
+interface ContentData {
+ // URL mapeada para a página. Ex: /posts/hello.html (não inclui a base)
+ // itere manualmente ou use `transform` personalizado para normalizar os caminhos
+ url: string
+ // dados frontmatter da página
+ frontmatter: RecordTodos os posts do blog
+-
+
- + {{ post.frontmatter.title }} + por {{ post.frontmatter.author }} + +
Demo
+ + + +-
+
- + {{ todo.text }} + +
-
+
- + {{ todo.text }} + +
` a `` serão exibidos.
+ *
+ * @default 2
+ */
+ level?: number | [number, number] | 'deep'
+
+ /**
+ * O título a ser exibido na outline.
+ *
+ * @default 'On this page'
+ */
+ label?: string
+}
+```
+
+## socialLinks
+
+- Tipo: `SocialLink[]`
+
+Você pode definir esta opção para mostrar os links de redes sociais com ícones na navegação.
+
+```ts
+export default {
+ themeConfig: {
+ socialLinks: [
+ { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
+ { icon: 'twitter', link: '...' },
+ // Você também pode adicionar ícones personalizados passando SVG como string:
+ {
+ icon: {
+ svg: ''
+ },
+ link: '...',
+ // Você também pode incluir um rótulo personalizado para acessibilidade (opcional mas recomendado):
+ ariaLabel: 'cool link'
+ }
+ ]
+ }
+}
+```
+
+```ts
+interface SocialLink {
+ icon: SocialLinkIcon
+ link: string
+ ariaLabel?: string
+}
+
+type SocialLinkIcon =
+ | 'discord'
+ | 'facebook'
+ | 'github'
+ | 'instagram'
+ | 'linkedin'
+ | 'mastodon'
+ | 'npm'
+ | 'slack'
+ | 'twitter'
+ | 'x'
+ | 'youtube'
+ | { svg: string }
+```
+
+## footer
+
+- Tipo: `Footer`
+- Pode ser sobreposto por página via [frontmatter](./frontmatter-config#footer)
+
+Configuração do rodapé. Você pode adicionar uma mensagem ou texto de direitos autorais no rodapé, no entanto, ela só será exibida quando a página não contiver uma barra lateral. Isso se deve a preocupações de design.
+
+```ts
+export default {
+ themeConfig: {
+ footer: {
+ message: 'Lançado sob a Licença MIT.',
+ copyright: 'Direitos autorais © 2019-presente Evan You'
+ }
+ }
+}
+```
+
+```ts
+export interface Footer {
+ message?: string
+ copyright?: string
+}
+```
+
+## editLink
+
+- Tipo: `EditLink`
+- Pode ser sobreposto por página via [frontmatter](./frontmatter-config#editlink)
+
+O _EditLink_ permite exibir um link para editar a página em serviços de gerenciamento Git, como GitHub ou GitLab. Consulte [Tema Padrão: Editar Link](./default-theme-edit-link) para mais detalhes.
+
+```ts
+export default {
+ themeConfig: {
+ editLink: {
+ pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
+ text: 'Editar esta página no GitHub'
+ }
+ }
+}
+```
+
+```ts
+export interface EditLink {
+ pattern: string
+ text?: string
+}
+```
+
+## lastUpdated
+
+- Tipo: `LastUpdatedOptions`
+
+Permite personalização para o texto de última atualização e o formato de data.
+
+```ts
+export default {
+ themeConfig: {
+ lastUpdated: {
+ text: 'Atualizado em',
+ formatOptions: {
+ dateStyle: 'full',
+ timeStyle: 'medium'
+ }
+ }
+ }
+}
+```
+
+```ts
+export interface LastUpdatedOptions {
+ /**
+ * @default 'Last updated'
+ */
+ text?: string
+
+ /**
+ * @default
+ * { dateStyle: 'short', timeStyle: 'short' }
+ */
+ formatOptions?: Intl.DateTimeFormatOptions & { forceLocale?: boolean }
+}
+```
+
+## algolia
+
+- Tipo: `AlgoliaSearch`
+
+Uma opção para dar suporte à pesquisa em seu site de documentação usando [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Saiba mais em [Tema Padrão: Pesquisa](./default-theme-search).
+
+```ts
+export interface AlgoliaSearchOptions extends DocSearchProps {
+ locales?: Record>
+}
+```
+
+Veja todas as opções [aqui](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts).
+
+## carbonAds {#carbon-ads}
+
+- Tipo: `CarbonAdsOptions`
+
+Uma opção para mostrar [Carbon Ads](https://www.carbonads.net/).
+
+```ts
+export default {
+ themeConfig: {
+ carbonAds: {
+ code: 'seu-código-carbon',
+ placement: 'sua-veiculação-carbon'
+ }
+ }
+}
+```
+
+```ts
+export interface CarbonAdsOptions {
+ code: string
+ placement: string
+}
+```
+
+Saiba mais em [Tema Padrão: Carbon Ads](./default-theme-carbon-ads).
+
+## docFooter
+
+- Tipo: `DocFooter`
+
+Pode ser usado para personalizar o texto que aparece acima dos links anterior e próximo. Útil se não estiver escrevendo documentação em inglês. Também pode ser usado para desabilitar globalmente os links anterior/próximo. Se você quiser ativar/desativar seletivamente os links anterior/próximo, pode usar [frontmatter](./default-theme-prev-next-links).
+
+```ts
+export default {
+ themeConfig: {
+ docFooter: {
+ prev: 'Página anterior',
+ next: 'Próxima página'
+ }
+ }
+}
+```
+
+```ts
+export interface DocFooter {
+ prev?: string | false
+ next?: string | false
+}
+```
+
+## darkModeSwitchLabel
+
+- Tipo: `string`
+- Padrão: `Appearance`
+
+Pode ser usado para personalizar o rótulo do botão de modo escuro. Esse rótulo é exibido apenas na visualização móvel.
+
+## lightModeSwitchTitle
+
+- Tipo: `string`
+- Padrão: `Switch to light theme`
+
+Pode ser usado para personalizar o título do botão de modo claro que aparece ao passar o mouse.
+
+## darkModeSwitchTitle
+
+- Tipo: `string`
+- Padrão: `Switch to dark theme`
+
+Pode ser usado para personalizar o título do botão de modo escuro que aparece ao passar o mouse.
+
+## sidebarMenuLabel
+
+- Tipo: `string`
+- Padrão: `Menu`
+
+Pode ser usado para personalizar o rótulo do menu da barra lateral. Esse rótulo é exibido apenas na visualização móvel.
+
+## returnToTopLabel
+
+- Tipo: `string`
+- Padrão: `Return to top`
+
+Pode ser usado para personalizar o rótulo do botão de retorno ao topo. Esse rótulo é exibido apenas na visualização móvel.
+
+## langMenuLabel
+
+- Tipo: `string`
+- Padrão: `Change language`
+
+Pode ser usado para personalizar o aria-label do botão de idioma na barra de navegação. Isso é usado apenas se você estiver usando [i18n](../guide/i18n).
+
+## externalLinkIcon
+
+- Tipo: `boolean`
+- Padrão: `false`
+
+Se deve mostrar um ícone de link externo ao lado de links externos no markdown.
diff --git a/docs/pt/reference/default-theme-edit-link.md b/docs/pt/reference/default-theme-edit-link.md
new file mode 100644
index 00000000..6b1e8793
--- /dev/null
+++ b/docs/pt/reference/default-theme-edit-link.md
@@ -0,0 +1,60 @@
+# Editar Link {#edit-link}
+
+## Configuração a nível de Site {#site-level-config}
+
+Editar Link permite que você mostre um link para editar a página com serviços de gerenciamento Git, como GitHub ou GitLab. Para habilitar, adicione a opção `themeConfig.editLink` na sua configuração.
+
+```js
+export default {
+ themeConfig: {
+ editLink: {
+ pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path'
+ }
+ }
+}
+```
+
+A opção `pattern` define a estrutura da URL para o link, e `:path` será substituído com o mesmo caminho de página.
+
+Você também pode colocar uma função pura que aceita [`PageData`](./runtime-api#usedata) como argumento e retorna uma URL em string.
+
+```js
+export default {
+ themeConfig: {
+ editLink: {
+ pattern: ({ filePath }) => {
+ if (filePath.startsWith('packages/')) {
+ return `https://github.com/acme/monorepo/edit/main/${filePath}`
+ } else {
+ return `https://github.com/acme/monorepo/edit/main/docs/${filePath}`
+ }
+ }
+ }
+ }
+}
+```
+
+Isso não deve gerar efeitos colaterais ou acessar qualquer coisa fora do seu escopo, uma vez que será serializado e executado no navegador.
+
+Por padrão, isso irá adicionar o link com texto "Edite essa página" no final da página de documentação. Você pode personalizar esse texto ao definir a opção `text`.
+
+```js
+export default {
+ themeConfig: {
+ editLink: {
+ pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
+ text: 'Edite essa página no GitHub'
+ }
+ }
+}
+```
+
+## Configuração Frontmatter {#frontmatter-config}
+
+A funcionalidade pode ser desabilitada por página usando a opção `editLink` no frontmatter:
+
+```yaml
+---
+editLink: false
+---
+```
diff --git a/docs/pt/reference/default-theme-footer.md b/docs/pt/reference/default-theme-footer.md
new file mode 100644
index 00000000..98b02b2c
--- /dev/null
+++ b/docs/pt/reference/default-theme-footer.md
@@ -0,0 +1,53 @@
+# Rodapé {#footer}
+
+VitePress irá mostrar o rodapé global na parte inferior da página quando `themeConfig.footer` está presente.
+
+```ts
+export default {
+ themeConfig: {
+ footer: {
+ message: 'Lançado sob Licença MIT.',
+ copyright: 'Direitos Reservados © 2019-present Evan You'
+ }
+ }
+}
+```
+
+```ts
+export interface Footer {
+ // A mensagem mostrada logo antes do copyright.
+ message?: string
+
+ // O próprio texto de copyright.
+ copyright?: string
+}
+```
+
+A configuração acima também suporta strings HTML. Então, por exemplo, se você quiser configurar o texto de rodapé para ter alguns links, você pode ajustar a configuração como o seguinte:
+
+```ts
+export default {
+ themeConfig: {
+ footer: {
+ message: 'Lançado sob Licença MIT.',
+ copyright: 'Direitos Reservados © 2019-present Evan You'
+ }
+ }
+}
+```
+
+::: warning
+Apenas elementos _inline_ serão usados em `message` e `copyright` conforme eles são apresentados dentro do elemento ``. Se você quiser adicionar elementos de tipo _block_, considere usar o _slot_ [`layout-bottom`](../guide/extending-default-theme#layout-slots).
+:::
+
+Note que o rodapé não será mostrado quando a [Barra Lateral](./default-theme-sidebar) estiver visível.
+
+## Configuração Frontmatter {#frontmatter-config}
+
+Isso pode ser desabilitado por página usando a opção `footer` em frontmatter:
+
+```yaml
+---
+footer: false
+---
+```
\ No newline at end of file
diff --git a/docs/pt/reference/default-theme-home-page.md b/docs/pt/reference/default-theme-home-page.md
new file mode 100644
index 00000000..460c55bf
--- /dev/null
+++ b/docs/pt/reference/default-theme-home-page.md
@@ -0,0 +1,168 @@
+# Página Inicial {#home-page}
+
+O tema padrão VitePress fornece um layout de página inicial, que você também pode ver em uso [na página inicial deste site](../). Você pode usá-lo em qualquer uma de suas páginas especificando `layout: home` em [frontmatter](./frontmatter-config).
+
+```yaml
+---
+layout: home
+---
+```
+
+No entanto, essa opção sozinha não faz muito. Você pode adicionar várias "seções" diferentes pré-modeladas à página inicial definindo opções adicionais como `hero` e `features`.
+
+## Seção Hero {#hero-section}
+
+A seção _Hero_ fica no topo da página inicial. Aqui segue como você pode configurar a seção _Hero_.
+
+```yaml
+---
+layout: home
+
+hero:
+ name: VitePress
+ text: Gerador de site estático com Vite & Vue.
+ tagline: Lorem ipsum...
+ image:
+ src: /logo.png
+ alt: VitePress
+ actions:
+ - theme: brand
+ text: Iniciar
+ link: /guide/what-is-vitepress
+ - theme: alt
+ text: Ver no GitHub
+ link: https://github.com/vuejs/vitepress
+---
+```
+
+```ts
+interface Hero {
+ // A string mostrada acima de `text`. Vem com a cor da marca
+ // e espera-se que seja curta, como o nome do produto.
+ name?: string
+
+ // O texto principal para a seção hero.
+ // Isso será definido como uma tag `h1`.
+ text: string
+
+ // Slogan exibido abaixo de `text`.
+ tagline?: string
+
+ // A imagem é exibida ao lado da área de texto e slogan.
+ image?: ThemeableImage
+
+ // Botões acionáveis para exibir na seção hero da página inicial.
+ actions?: HeroAction[]
+}
+
+type ThemeableImage =
+ | string
+ | { src: string; alt?: string }
+ | { light: string; dark: string; alt?: string }
+
+interface HeroAction {
+ // Tema de cor do botão. Padrão: `brand`.
+ theme?: 'brand' | 'alt'
+
+ // Rótulo do botão.
+ text: string
+
+ // Destino do link do botão.
+ link: string
+
+ // Atributo target do link.
+ target?: string
+
+ // Atributo rel do link.
+ rel?: string
+}
+```
+
+### Personalizando a cor do nome {#customizing-the-name-color}
+
+VitePress usa a cor da marca (`--vp-c-brand-1`) para `name`. No entanto, você pode personalizar essa cor sobrescrevendo a variável `--vp-home-hero-name-color`.
+
+```css
+:root {
+ --vp-home-hero-name-color: blue;
+}
+```
+
+Você também pode personalizá-la ainda mais combinando `--vp-home-hero-name-background` para dar ao `name` uma cor degradê.
+
+```css
+:root {
+ --vp-home-hero-name-color: transparent;
+ --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe, #41d1ff);
+}
+```
+
+## Seção de Funcionalidades {#features-section}
+
+Na seção de funcionalidades, você pode listar qualquer número de funcionalidades que deseja mostrar imediatamente após a seção _Hero_. Para configurá-la, passe a opção `features` para o frontmatter.
+
+Você pode fornecer um ícone para cada funcionalidade, que pode ser um emoji ou qualquer tipo de imagem. Quando o ícone configurado é uma imagem (svg, png, jpeg...), você deve fornecer o ícone com a largura e altura apropriadas; você também pode fornecer a descrição, seu tamanho intrínseco, bem como suas variantes para temas escuros e claros quando necessário.
+
+```yaml
+---
+layout: home
+
+features:
+ - icon: 🛠️
+ title: Simples e minimalista, sempre
+ details: Lorem ipsum...
+ - icon:
+ src: /cool-feature-icon.svg
+ title: Outro recurso legal
+ details: Lorem ipsum...
+ - icon:
+ dark: /dark-feature-icon.svg
+ light: /light-feature-icon.svg
+ title: Outro recurso legal
+ details: Lorem ipsum...
+---
+```
+
+```ts
+interface Feature {
+ // Mostra ícone em cada bloco de funcionalide.
+ icon?: FeatureIcon
+
+ // Título da funcionalidade.
+ title: string
+
+ // Detalhes da funcionalidade.
+ details: string
+
+ // Link quando clicado no componente de funcionalidade.
+ // O link pode ser interno ou externo.
+ //
+ // ex. `guide/reference/default-theme-home-page` ou `https://example.com`
+ link?: string
+
+ // Texto do link a ser exibido dentro do componente de funcionalidade.
+ // Melhor usado com a opção `link`.
+ //
+ // ex. `Saiba mais`, `Visitar página`, etc.
+ linkText?: string
+
+ // Atributo rel do link para a opção `link`.
+ //
+ // ex. `external`
+ rel?: string
+
+ // Atributo target do link para a opção `link`.
+ target?: string
+}
+
+type FeatureIcon =
+ | string
+ | { src: string; alt?: string; width?: string; height: string }
+ | {
+ light: string
+ dark: string
+ alt?: string
+ width?: string
+ height: string
+ }
+```
diff --git a/docs/pt/reference/default-theme-last-updated.md b/docs/pt/reference/default-theme-last-updated.md
new file mode 100644
index 00000000..5bc782e1
--- /dev/null
+++ b/docs/pt/reference/default-theme-last-updated.md
@@ -0,0 +1,27 @@
+# Última Atualização {#last-updated}
+
+O tempo em que o conteúdo foi atualizado pela última vez será mostrado no canto inferior direito da página. Para habilitar, adicione a opção `lastUpdated` na sua configuração.
+
+::: tip
+Você precisa fazer _commit_ no arquivo markdown para ver o tempo atualizado.
+:::
+
+## Configuração a nível de Site {#site-level-config}
+
+```js
+export default {
+ lastUpdated: true
+}
+```
+
+## Configuração Frontmatter {#frontmatter-config}
+
+Isso pode ser desabilitado por página usando a opção `lastUpdated` no frontmatter:
+
+```yaml
+---
+lastUpdated: false
+---
+```
+
+Refira-se ao [Tema Padrão: Última Atualização](./default-theme-config#lastupdated) para mais detalhes. Qualquer valor positivo a nível de tema também habilitará a funcionalidade a não ser que esteja explicitamente desabilitada a nível de página ou de site.
diff --git a/docs/pt/reference/default-theme-layout.md b/docs/pt/reference/default-theme-layout.md
new file mode 100644
index 00000000..0e4d0162
--- /dev/null
+++ b/docs/pt/reference/default-theme-layout.md
@@ -0,0 +1,62 @@
+# Layout {#layout}
+
+Você pode escolher o layout da página definindo a opção de `layout` para o [frontmatter](./frontmatter-config) da página. Há três opções de layout: `doc`, `page` e `home`. Se nada for especificado, a página será tratada como página `doc`.
+
+```yaml
+---
+layout: doc
+---
+```
+
+## Layout do documento {#doc-layout}
+
+A opção `doc` é o layout padrão e estiliza todo o conteúdo Markdown com o visual de "documentação". Ela funciona agrupando todo o conteúdo na classe CSS `vp-doc`, e aplicando os estilos aos elementos abaixo dela.
+
+Quase todos os elementos genéricos, como `p` ou `h2`, recebem um estilo especial. Portanto, lembre-se de que se você adicionar qualquer HTML personalizado dentro de um conteúdo Markdown, ele também será afetado por esses estilos.
+
+Ele também fornece recursos específicos de documentação listados abaixo. Esses recursos estão habilitados apenas neste layout.
+
+- Editar link
+- Links Anterior e Próximo
+- _Outline_
+- [Carbon Ads](./default-theme-carbon-ads)
+
+## Layout da Página {#page-layout}
+
+A opção `page` é tratada como "página em branco". O Markdown ainda será processado e todas as [Extensões Markdown](../guide/markdown) funcionarão da mesma forma que o layout `doc`, mas este não receberá nenhum estilo padrão.
+
+O layout da página permitirá que você estilize tudo sem que o tema VitePress afete a marcação. Isso é útil quando você deseja criar sua própria página personalizada.
+
+Observe que mesmo neste layout, a barra lateral ainda aparecerá se a página tiver uma configuração de barra lateral correspondente.
+
+## Layout da Home {#home-layout}
+
+A opção `home` gerará um modelo de _"Homepage"_. Nesse layout você pode definir opções extras, como `hero` e `features`, para personalizar ainda mais o conteúdo. Visite [Tema padrão: Página Inicial](./default-theme-home-page) para obter mais detalhes.
+
+## Sem Layout {#no-layout}
+
+Se você não quiser nenhum layout, pode passar `layout: false` pelo frontmatter. Esta opção é útil se você deseja uma página de destino totalmente personalizável (sem barra lateral, barra de navegação ou rodapé por padrão).
+
+## Layout Personalizado {#custom-layout}
+
+Você também pode usar um layout personalizado:
+
+```md
+---
+layout: foo
+---
+```
+
+Isto irá procurar um componente chamado `foo` registrado no contexto. Por exemplo, você pode registrar seu componente globalmente em `.vitepress/theme/index.ts`:
+
+```ts
+import DefaultTheme from 'vitepress/theme'
+import Foo from './Foo.vue'
+
+export default {
+ extends: DefaultTheme,
+ enhanceApp({ app }) {
+ app.component('foo', Foo)
+ }
+}
+```
diff --git a/docs/pt/reference/default-theme-nav.md b/docs/pt/reference/default-theme-nav.md
new file mode 100644
index 00000000..5f0d2399
--- /dev/null
+++ b/docs/pt/reference/default-theme-nav.md
@@ -0,0 +1,162 @@
+# Navegação {#nav}
+
+Referente a barra de navegação exibida no topo da página. Ela contém o título do site, links do menu global, e etc.
+
+## Título do Site e Logo {#site-title-and-logo}
+
+Por padrão, a navegação mostra o título do site referenciando o valor de [`config.title`](./site-config#title). Se desejar alterar o que é exibido na navegação, você pode definir um texto personalizado na opção `themeConfig.siteTitle`.
+
+```js
+export default {
+ themeConfig: {
+ siteTitle: 'Meu Título Personalizado'
+ }
+}
+```
+
+Se você tiver um logo para seu site, pode mostrá-lo passando o caminho para a imagem. Você deve colocar o logo diretamente dentro da pasta `public`, e definir o caminho absoluto para ele.
+
+```js
+export default {
+ themeConfig: {
+ logo: '/my-logo.svg'
+ }
+}
+```
+
+Ao adicionar um logo, ele é mostrado juntamente com o título do site. Se seu logo tem tudo o que você precisa e se você desejar ocultar o texto do título, defina `false` na opção `siteTitle`.
+
+```js
+export default {
+ themeConfig: {
+ logo: '/my-logo.svg',
+ siteTitle: false
+ }
+}
+```
+
+Você também pode passar um objeto como logo se quiser adicionar um atributo `alt` ou personalizá-lo com base no modo claro/escuro. Consulte [`themeConfig.logo`](./default-theme-config#logo) para obter detalhes.
+
+## Links de Navegação {#navigation-links}
+
+Você pode definir a opção `themeConfig.nav` para adicionar links à sua navegação.
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ { text: 'Guia', link: '/guide' },
+ { text: 'Configuração', link: '/config' },
+ { text: 'Registro de Alterações', link: 'https://github.com/...' }
+ ]
+ }
+}
+```
+
+`text` é o próprio texto mostrado na navegação, e o `link` é o link para o qual será navegado quando o texto for clicado. Para o link, defina o caminho para o próprio arquivo sem o prefixo `.md` e sempre comece com `/`.
+
+Links de navegação também podem ser menus _dropdown_. Para fazer isso, defina a chave `items` na opção do link.
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ { text: 'Guia', link: '/guide' },
+ {
+ text: 'Menu Dropdown',
+ items: [
+ { text: 'Item A', link: '/item-1' },
+ { text: 'Item B', link: '/item-2' },
+ { text: 'Item C', link: '/item-3' }
+ ]
+ }
+ ]
+ }
+}
+```
+
+Note que o título do menu _dropdown_ (`Menu Dropdown` no exemplo acima) não pode ter a propriedade `link`, pois ele se torna um botão para abrir o diálogo dropdown.
+
+Você também pode adicionar "seções" aos itens do menu _dropdown_ passando mais itens aninhados.
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ { text: 'Guia', link: '/guia' },
+ {
+ text: 'Menu Dropdown',
+ items: [
+ {
+ // Título da seção.
+ text: 'Título da Seção A',
+ items: [
+ { text: 'Item A da Seção A', link: '...' },
+ { text: 'Item B da Seção B', link: '...' }
+ ]
+ }
+ ]
+ },
+ {
+ text: 'Menu Dropdown',
+ items: [
+ {
+ // Você também pode omitir o título.
+ items: [
+ { text: 'Item A da Seção A', link: '...' },
+ { text: 'Item B da Seção B', link: '...' }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+### Personalizar o estado "ativo" do link {#customize-link-s-active-state}
+
+Os itens do menu de navegação serão destacados quando a página atual estiver no caminho correspondente. Se desejar personalizar o caminho a ser correspondido, defina a propriedade `activeMatch` e regex como um valor em string.
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ // Este link fica no estado ativo quando
+ // o usuário está no caminho `/config/`.
+ {
+ text: 'Guia',
+ link: '/guide',
+ activeMatch: '/config/'
+ }
+ ]
+ }
+}
+```
+
+::: warning
+`activeMatch` deve ser uma string regex, mas você deve defini-la como uma string. Não podemos usar um objeto RegExp real aqui porque ele não é serializável durante o momento de construção.
+:::
+
+### Personalizar os atributos "target" e "rel" de links {#customize-link-s-target-and-rel-attributes}
+
+Por padrão, VitePress determina automaticamente os atributos `target` e `rel` baseado em um link externo ou não. Mas se você quiser, também pode personalizá-los.
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ {
+ text: 'Merchandise',
+ link: 'https://www.thegithubshop.com/',
+ target: '_self',
+ rel: 'sponsored'
+ }
+ ]
+ }
+}
+```
+
+## Links Sociais {#social-links}
+
+Consulte [`socialLinks`](./default-theme-config#sociallinks).
diff --git a/docs/pt/reference/default-theme-prev-next-links.md b/docs/pt/reference/default-theme-prev-next-links.md
new file mode 100644
index 00000000..c9472a24
--- /dev/null
+++ b/docs/pt/reference/default-theme-prev-next-links.md
@@ -0,0 +1,43 @@
+# Links Anterior e Próximo {#prev-next-links}
+
+Você pode personalizar o texto e o link para os botões de Anterior e Próximo mostrados ao fim da página. Isso é útil quando você quer mostrar um texto diferente daquele que você tem na barra lateral. Além disso, você pode achar útil desabilitar o rodapé ou link para a página para ela não ser incluída na sua barra lateral.
+
+## prev
+
+- Tipo: `string | false | { text?: string; link?: string }`
+
+- Detalhes:
+
+ Especifica o texto/link para mostrar no link para a página anterior. Se você não ver isso no frontmatter, o texto/link será inferido da configuração da barra lateral.
+
+- Exemplos:
+
+ - Para personalizar apenas o texto:
+
+ ```yaml
+ ---
+ prev: 'Iniciar | Markdown'
+ ---
+ ```
+
+ - Para personalizar ambos texto e link:
+
+ ```yaml
+ ---
+ prev:
+ text: 'Markdown'
+ link: '/guide/markdown'
+ ---
+ ```
+
+ - Para esconder a página anterior:
+
+ ```yaml
+ ---
+ prev: false
+ ---
+ ```
+
+## next
+
+O mesmo que `prev` mas para a próxima página.
diff --git a/docs/pt/reference/default-theme-search.md b/docs/pt/reference/default-theme-search.md
new file mode 100644
index 00000000..35b0d812
--- /dev/null
+++ b/docs/pt/reference/default-theme-search.md
@@ -0,0 +1,379 @@
+---
+outline: deep
+---
+
+# Pesquisa {#search}
+
+## Pesquisa Local {#local-search}
+
+VitePress oferece suporte à pesquisa de texto completa usando um índice no navegador graças ao [minisearch](https://github.com/lucaong/minisearch/). Para habilitar esse recurso, basta definir a opção `themeConfig.search.provider` como `'local'` no arquivo `.vitepress/config.ts`:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local'
+ }
+ }
+})
+```
+
+Exemplo de resultado:
+
+
+
+Alternativamente, você pode usar [Algolia DocSearch](#algolia-search) ou alguns plugins da comunidade como ou .
+
+### i18n {#local-search-i18n}
+
+Você pode usar uma configuração como esta para usar a pesquisa multilínguas:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local',
+ options: {
+ locales: {
+ zh: {
+ translations: {
+ button: {
+ buttonText: '搜索文档',
+ buttonAriaLabel: '搜索文档'
+ },
+ modal: {
+ noResultsText: '无法找到相关结果',
+ resetButtonTitle: '清除查询条件',
+ footer: {
+ selectText: '选择',
+ navigateText: '切换'
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+})
+```
+
+### Opções MiniSearch {#mini-search-options}
+
+Você pode configurar o MiniSearch assim:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local',
+ options: {
+ miniSearch: {
+ /**
+ * @type {Pick}
+ */
+ options: {
+ /* ... */
+ },
+ /**
+ * @type {import('minisearch').SearchOptions}
+ * @default
+ * { fuzzy: 0.2, prefix: true, boost: { title: 4, text: 2, titles: 1 } }
+ */
+ searchOptions: {
+ /* ... */
+ }
+ }
+ }
+ }
+ }
+})
+```
+
+Saiba mais na [documentação do MiniSearch](https://lucaong.github.io/minisearch/classes/MiniSearch.MiniSearch.html).
+
+### Apresentador de Conteúdo Personalizado {#custom-content-renderer}
+
+Você pode personalizar a função usada para apresentar o conteúdo markdown antes de indexá-lo:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local',
+ options: {
+ /**
+ * @param {string} src
+ * @param {import('vitepress').MarkdownEnv} env
+ * @param {import('markdown-it')} md
+ */
+ _render(src, env, md) {
+ // retorne a string HTML
+ }
+ }
+ }
+ }
+})
+```
+
+Essa função será removida dos dados do site no lado do cliente, então você pode usar APIs do Node.js nela.
+
+#### Exemplo: Excluindo páginas da pesquisa {#example-excluding-pages-from-search}
+
+Você pode excluir páginas da pesquisa adicionando `search: false` ao frontmatter da página. Alternativamente:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local',
+ options: {
+ _render(src, env, md) {
+ const html = md.render(src, env)
+ if (env.frontmatter?.search === false) return ''
+ if (env.relativePath.startsWith('algum/caminho')) return ''
+ return html
+ }
+ }
+ }
+ }
+})
+```
+
+::: warning Nota
+No caso uma função `_render` personalizada ser fornecida, você precisa manipular o `search: false` do frontmatter por conta própria. Além disso, o objeto `env` não estará completamente populado antes que `md.render` seja chamado, então verificações em propriedades opcionais `env`, como `frontmatter`, devem ser feitas após isso.
+:::
+
+#### Exemplo: Transformando conteúdo - adicionando âncoras {#example-transforming-content-adding-anchors}
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local',
+ options: {
+ _render(src, env, md) {
+ const html = md.render(src, env)
+ if (env.frontmatter?.title)
+ return md.render(`# ${env.frontmatter.title}`) + html
+ return html
+ }
+ }
+ }
+ }
+})
+```
+
+## Pesquisa Algolia {#algolia-search}
+
+VitePress oferece suporte à pesquisa em seu site de documentação usando [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Consulte o guia de início deles. Em seu arquivo `.vitepress/config.ts`, você precisará fornecer pelo menos o seguinte para que funcione:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'algolia',
+ options: {
+ appId: '...',
+ apiKey: '...',
+ indexName: '...'
+ }
+ }
+ }
+})
+```
+
+### i18n {#algolia-search-i18n} {#algolia-search-i18n}
+
+Você pode usar uma configuração como esta para usar a pesquisa multilínguas:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'algolia',
+ options: {
+ appId: '...',
+ apiKey: '...',
+ indexName: '...',
+ locales: {
+ zh: {
+ placeholder: '搜索文档',
+ translations: {
+ button: {
+ buttonText: '搜索文档',
+ buttonAriaLabel: '搜索文档'
+ },
+ modal: {
+ searchBox: {
+ resetButtonTitle: '清除查询条件',
+ resetButtonAriaLabel: '清除查询条件',
+ cancelButtonText: '取消',
+ cancelButtonAriaLabel: '取消'
+ },
+ startScreen: {
+ recentSearchesTitle: '搜索历史',
+ noRecentSearchesText: '没有搜索历史',
+ saveRecentSearchButtonTitle: '保存至搜索历史',
+ removeRecentSearchButtonTitle: '从搜索历史中移除',
+ favoriteSearchesTitle: '收藏',
+ removeFavoriteSearchButtonTitle: '从收藏中移除'
+ },
+ errorScreen: {
+ titleText: '无法获取结果',
+ helpText: '你可能需要检查你的网络连接'
+ },
+ footer: {
+ selectText: '选择',
+ navigateText: '切换',
+ closeText: '关闭',
+ searchByText: '搜索提供者'
+ },
+ noResultsScreen: {
+ noResultsText: '无法找到相关结果',
+ suggestedQueryText: '你可以尝试查询',
+ reportMissingResultsText: '你认为该查询应该有结果？',
+ reportMissingResultsLinkText: '点击反馈'
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+})
+```
+
+[Essas opções](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts) podem ser sobrepostas. Consulte a documentação oficial Algolia para obter mais informações sobre elas.
+
+### Configuração _Crawler_ {#crawler-config}
+
+Aqui está um exemplo de configuração baseado na qual este site usa:
+
+```ts
+new Crawler({
+ appId: '...',
+ apiKey: '...',
+ rateLimit: 8,
+ startUrls: ['https://vitepress.dev/'],
+ renderJavaScript: false,
+ sitemaps: [],
+ exclusionPatterns: [],
+ ignoreCanonicalTo: false,
+ discoveryPatterns: ['https://vitepress.dev/**'],
+ schedule: 'at 05:10 on Saturday',
+ actions: [
+ {
+ indexName: 'vitepress',
+ pathsToMatch: ['https://vitepress.dev/**'],
+ recordExtractor: ({ $, helpers }) => {
+ return helpers.docsearch({
+ recordProps: {
+ lvl1: '.content h1',
+ content: '.content p, .content li',
+ lvl0: {
+ selectors: '',
+ defaultValue: 'Documentation'
+ },
+ lvl2: '.content h2',
+ lvl3: '.content h3',
+ lvl4: '.content h4',
+ lvl5: '.content h5'
+ },
+ indexHeadings: true
+ })
+ }
+ }
+ ],
+ initialIndexSettings: {
+ vitepress: {
+ attributesForFaceting: ['type', 'lang'],
+ attributesToRetrieve: ['hierarchy', 'content', 'anchor', 'url'],
+ attributesToHighlight: ['hierarchy', 'hierarchy_camel', 'content'],
+ attributesToSnippet: ['content:10'],
+ camelCaseAttributes: ['hierarchy', 'hierarchy_radio', 'content'],
+ searchableAttributes: [
+ 'unordered(hierarchy_radio_camel.lvl0)',
+ 'unordered(hierarchy_radio.lvl0)',
+ 'unordered(hierarchy_radio_camel.lvl1)',
+ 'unordered(hierarchy_radio.lvl1)',
+ 'unordered(hierarchy_radio_camel.lvl2)',
+ 'unordered(hierarchy_radio.lvl2)',
+ 'unordered(hierarchy_radio_camel.lvl3)',
+ 'unordered(hierarchy_radio.lvl3)',
+ 'unordered(hierarchy_radio_camel.lvl4)',
+ 'unordered(hierarchy_radio.lvl4)',
+ 'unordered(hierarchy_radio_camel.lvl5)',
+ 'unordered(hierarchy_radio.lvl5)',
+ 'unordered(hierarchy_radio_camel.lvl6)',
+ 'unordered(hierarchy_radio.lvl6)',
+ 'unordered(hierarchy_camel.lvl0)',
+ 'unordered(hierarchy.lvl0)',
+ 'unordered(hierarchy_camel.lvl1)',
+ 'unordered(hierarchy.lvl1)',
+ 'unordered(hierarchy_camel.lvl2)',
+ 'unordered(hierarchy.lvl2)',
+ 'unordered(hierarchy_camel.lvl3)',
+ 'unordered(hierarchy.lvl3)',
+ 'unordered(hierarchy_camel.lvl4)',
+ 'unordered(hierarchy.lvl4)',
+ 'unordered(hierarchy_camel.lvl5)',
+ 'unordered(hierarchy.lvl5)',
+ 'unordered(hierarchy_camel.lvl6)',
+ 'unordered(hierarchy.lvl6)',
+ 'content'
+ ],
+ distinct: true,
+ attributeForDistinct: 'url',
+ customRanking: [
+ 'desc(weight.pageRank)',
+ 'desc(weight.level)',
+ 'asc(weight.position)'
+ ],
+ ranking: [
+ 'words',
+ 'filters',
+ 'typo',
+ 'attribute',
+ 'proximity',
+ 'exact',
+ 'custom'
+ ],
+ highlightPreTag: '',
+ highlightPostTag: '',
+ minWordSizefor1Typo: 3,
+ minWordSizefor2Typos: 7,
+ allowTyposOnNumericTokens: false,
+ minProximity: 1,
+ ignorePlurals: true,
+ advancedSyntax: true,
+ attributeCriteriaComputedByMinProximity: true,
+ removeWordsIfNoResults: 'allOptional'
+ }
+ }
+})
+```
+
+
diff --git a/docs/pt/reference/default-theme-sidebar.md b/docs/pt/reference/default-theme-sidebar.md
new file mode 100644
index 00000000..62c3b3b1
--- /dev/null
+++ b/docs/pt/reference/default-theme-sidebar.md
@@ -0,0 +1,215 @@
+# Barra Lateral {#sidebar}
+
+A barra lateral é o bloco principal de navegação da sua documentação. Você pode configurar o menu da barra lateral em [`themeConfig.sidebar`](./default-theme-config#sidebar).
+
+```js
+export default {
+ themeConfig: {
+ sidebar: [
+ {
+ text: 'Guia',
+ items: [
+ { text: 'Introdução', link: '/introduction' },
+ { text: 'Iniciando', link: '/getting-started' },
+ ...
+ ]
+ }
+ ]
+ }
+}
+```
+
+## O Básico {#the-basics}
+
+A forma mais simples do menu da barra lateral é passar um único _array_ de links. O item do primeiro nível define a "seção" da barra lateral. Ele deve conter `text`, que é o título da seção, e `items` que são os próprios links de navegação.
+
+```js
+export default {
+ themeConfig: {
+ sidebar: [
+ {
+ text: 'Título da Seção A',
+ items: [
+ { text: 'Item A', link: '/item-a' },
+ { text: 'Item B', link: '/item-b' },
+ ...
+ ]
+ },
+ {
+ text: 'Título da Seção B',
+ items: [
+ { text: 'Item C', link: '/item-c' },
+ { text: 'Item D', link: '/item-d' },
+ ...
+ ]
+ }
+ ]
+ }
+}
+```
+
+Cada `link` deve especificar o caminho para o próprio arquivo começando com `/`. Se você adicionar uma barra no final do link, será mostrado o `index.md` do diretório correspondente.
+
+```js
+export default {
+ themeConfig: {
+ sidebar: [
+ {
+ text: 'Guia',
+ items: [
+ // Isso mostra a página `/guide/index.md`.
+ { text: 'Introdução', link: '/guide/' }
+ ]
+ }
+ ]
+ }
+}
+```
+
+Você pode aninhar ainda mais os itens da barra lateral até 6 níveis de profundidade contando a partir do nível raiz. Note que níveis mais profundos que 6 serão ignorados e não serão exibidos na barra lateral.
+
+```js
+export default {
+ themeConfig: {
+ sidebar: [
+ {
+ text: 'Nível 1',
+ items: [
+ {
+ text: 'Nível 2',
+ items: [
+ {
+ text: 'Nível 3',
+ items: [
+ ...
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+## Múltiplas Barras Laterais {#multiple-sidebars}
+
+Você pode mostrar uma barra lateral diferente dependendo do caminho da página. Por exemplo, como mostrado neste site, você pode querer criar seções separadas de conteúdo em sua documentação, como a página "Guia" e a página "Configuração".
+
+Para fazer isso, primeiro organize suas páginas em diretórios para cada seção desejada:
+
+```
+.
+├─ guide/
+│ ├─ index.md
+│ ├─ one.md
+│ └─ two.md
+└─ config/
+ ├─ index.md
+ ├─ three.md
+ └─ four.md
+```
+
+Em seguida, atualize sua configuração para definir sua barra lateral para cada seção. Desta vez, você deve passar um objeto em vez de um array.
+
+```js
+export default {
+ themeConfig: {
+ sidebar: {
+ // Esta barra lateral é exibida quando um usuário
+ // está no diretório `guide`.
+ '/guide/': [
+ {
+ text: 'Guia',
+ items: [
+ { text: 'Índice', link: '/guide/' },
+ { text: 'Um', link: '/guide/one' },
+ { text: 'Dois', link: '/guide/two' }
+ ]
+ }
+ ],
+
+ // Esta barra lateral é exibida quando um usuário
+ // está no diretório `config`.
+ '/config/': [
+ {
+ text: 'Configuração',
+ items: [
+ { text: 'Índice', link: '/config/' },
+ { text: 'Três', link: '/config/three' },
+ { text: 'Quatro', link: '/config/four' }
+ ]
+ }
+ ]
+ }
+ }
+}
+```
+
+## Grupos Retráteis na Barra Lateral {#collapsible-sidebar-groups}
+
+Adicionando a opção `collapsed` ao grupo da barra lateral, ela mostra um botão para ocultar/mostrar cada seção.
+
+```js
+export default {
+ themeConfig: {
+ sidebar: [
+ {
+ text: 'Título da Seção A',
+ collapsed: false,
+ items: [...]
+ }
+ ]
+ }
+}
+```
+
+Todas as seções são "abertas" por padrão. Se você deseja que elas estejam "fechadas" na carga inicial da página, defina a opção `collapsed` como `true`.
+
+```js
+export default {
+ themeConfig: {
+ sidebar: [
+ {
+ text: 'Título da Seção A',
+ collapsed: true,
+ items: [...]
+ }
+ ]
+ }
+}
+```
+
+## `useSidebar`
+ sidebar: ComputedRef
+ sidebarGroups: ComputedRef
+ hasSidebar: ComputedRef
+ hasAside: ComputedRef
+ leftAside: ComputedRef
+ isSidebarEnabled: ComputedRef
+ open: () => void
+ close: () => void
+ toggle: () => void
+}
+```
+
+**Exemplo:**
+
+```vue
+
+
+
+ Visível apenas quando a barra lateral existe
+
+```
diff --git a/docs/pt/reference/default-theme-team-page.md b/docs/pt/reference/default-theme-team-page.md
new file mode 100644
index 00000000..9021b959
--- /dev/null
+++ b/docs/pt/reference/default-theme-team-page.md
@@ -0,0 +1,258 @@
+
+
+# Página da Equipe {#team-page}
+
+Se você quiser apresentar sua equipe, você pode usar componentes de equipe para construir a Página da Equipe. Existem duas maneiras de usar esses componentes. Uma é incorporá-lo na página de documento, e outra é criar uma Página de Equipe completa.
+
+## Mostrar membros da equipe em uma página {#show-team-members-in-a-page}
+
+Você pode usar o componente `` exposto em `vitepress/theme` para exibir uma lista de membros da equipe em qualquer página.
+
+```html
+
+
+# Nosso time
+
+Diga olá à nossa equipe incrível.
+
+` vem em 2 tamanhos diferentes, pequeno `small` e médio `medium`. Enquanto é uma questão de preferência, geralmente o tamanho `small` deve encaixar melhor quando usado na página de documento. Além disso, você pode adicionar mais propriedades a cada membro, como adicionar o botão "descrição" ou "patrocinador". Saiba mais sobre em [``](#vpteammembers).
+
+Incorporar membros da equipe na página de documento é bom para equipes de pequeno porte, onde ter uma página de equipe inteira dedicada pode ser demais, ou introduzir membros parciais como uma referência ao contexto da documentação.
+
+Se você tiver um grande número de membros, ou simplesmente quiser ter mais espaço para mostrar os membros da equipe, considere [criar uma página de equipe completa.](#create-a-full-team-page)
+
+## Criando uma página de equipe completa {#create-a-full-team-page}
+
+Em vez de adicionar membros da equipe à página de documento, você também pode criar uma Página de Equipe completa, da mesma forma que pode criar uma [Página Inicial](./default-theme-home-page) personalizada.
+
+Para criar uma página de equipe, primeiro crie um novo arquivo md. O nome do arquivo não importa, mas aqui vamos chamá-lo de `team.md`. Neste arquivo, defina a opção `layout: page` do frontmatter, e então você poderá compor a estrutura da sua página usando componentes `TeamPage`.
+
+```html
+---
+layout: page
+---
+
+
+
+
+
+ Nosso time
+
+
+ O desenvolvimento do VitePress é orientado por uma equipe internacional,
+ alguns dos membros escolheram ser apresentados abaixo.
+
+
+
+```
+
+Ao criar uma página de equipe completa, lembre-se de agrupar todos os componentes com o componente ``. Este componente garantirá que todos os componentes aninhados relacionados à equipe obtenham a estrutura de layout adequada, como espaçamentos.
+
+O componente `` adiciona a seção de título da página. O título é ``. Use os _slots_ `#title` e `#lead`para documentar sobre sua equipe.
+
+`` funciona da mesma forma que quando usado em uma página de documento. Ele exibirá a lista de membros.
+
+### Adicione seções para dividir os membros da equipe {#add-sections-to-divide-team-members}
+
+Você pode adicionar "seções" à página da equipe. Por exemplo, você pode ter diferentes tipos de membros da equipe, como membros da Equipe Principal e Parceiros da Comunidade. Você pode dividir esses membros em seções para explicar melhor os papéis de cada grupo.
+
+Para fazer isso, adicione o componente `` ao arquivo `team.md` que criamos anteriormente.
+
+```html
+---
+layout: page
+---
+
+
+
+
+ Nosso time
+ ...
+
+
+ Parceiros
+ ...
+
+
+
+```
+
+O componente `` pode ter os _slots_ `#title` e `#lead` similar ao componente `VPTeamPageTitle`, e também o _slot_ `#members` para exibir os membros da equipe.
+
+Lembre-se de colocar o componente `` dentro do _slot_ `#members`.
+
+## ``
+
+O componente `` exibe uma determinada lista de membros.
+
+```html
+`
+
+O componente raiz ao criar uma página de equipe completa. Ele aceita apenas um único _slot_. Ele estilizará todos os componentes relacionados à equipe passados.
+
+## ``
+
+Adiciona a seção "título" da página. Melhor usar logo no início sob ``. Aceita os _slots_ `#title` e `#lead`.
+
+```html
+
+
+
+ Nosso time
+
+
+ O desenvolvimento do VitePress é orientado por uma equipe internacional,
+ alguns dos membros escolheram ser apresentados abaixo.
+
+
+
+```
+
+## ``
+
+Cria uma "seção" na página da equipe. Aceita os _slots_ `#title`, `#lead` e `#members`. Você pode adicionar quantas seções quiser dentro de ``.
+
+```html
+
+ ...
+
+ Parceiros
+ Lorem ipsum...
+
+
+
+```
diff --git a/docs/pt/reference/frontmatter-config.md b/docs/pt/reference/frontmatter-config.md
new file mode 100644
index 00000000..41ccad66
--- /dev/null
+++ b/docs/pt/reference/frontmatter-config.md
@@ -0,0 +1,221 @@
+---
+outline: deep
+---
+
+# Configuração Frontmatter {#frontmatter-config}
+
+Frontmatter permite a configuração baseada em páginas. Em cada arquivo markdown, você pode usar a configuração frontmatter para sobrepor opções de configuração a nível de site ou de tema. Além disso, existem opções de configuração que só podem ser definidas em frontmatter.
+
+Exemplo de uso:
+
+```md
+---
+title: Documentação com VitePress
+editLink: true
+---
+```
+
+Você pode acessar os dados do frontmatter através da variável global `$frontmatter` em expressões Vue:
+
+```md
+{{ $frontmatter.title }}
+```
+
+## title
+
+- Tipo: `string`
+
+Título para a página. É o mesmo que [config.title](./site-config#title), e sobrepõe a configuração a nível de site.
+
+```yaml
+---
+title: VitePress
+---
+```
+
+## titleTemplate
+
+- Tipo: `string | boolean`
+
+O sufixo para o título. É o mesmo que [config.titleTemplate](./site-config#titletemplate), e sobrepõe a configuração a nível de site.
+
+```yaml
+---
+title: VitePress
+titleTemplate: Gerador de site estático com Vite & Vue
+---
+```
+
+## description
+
+- Tipo: `string`
+
+Descrição para a página. É o mesmo que [config.description](./site-config#description), e sobrepõe a configuração a nível de site.
+
+```yaml
+---
+description: VitePress
+---
+```
+
+## head
+
+- Tipo: `HeadConfig[]`
+
+Especifica tags head adicionais a serem injetadas na página atual. Elas serão acrescentadas após as tags head injetadas pela configuração a nível de site.
+
+```yaml
+---
+head:
+ - - meta
+ - name: description
+ content: hello
+ - - meta
+ - name: keywords
+ content: super duper SEO
+---
+```
+
+```ts
+type HeadConfig =
+ | [string, Record]
+ | [string, Record, string]
+```
+
+## Somente no Tema Padrão {#default-theme-only}
+
+As seguintes opções frontmatter são aplicáveis apenas ao usar o tema padrão.
+
+### layout
+
+- Tipo: `doc | home | page`
+- Padrão: `doc`
+
+Determina o layout da página.
+
+- `doc` - Aplica estilos de documentação padrão ao conteúdo markdown.
+- `home` - Layout especial para a "Página Inicial". Você pode adicionar opções extras como `hero` e `features` para criar rapidamente uma bela página inicial.
+- `page` - Comporta-se de maneira semelhante a `doc`, mas não aplica estilos ao conteúdo. Útil quando você deseja criar uma página totalmente personalizada.
+
+```yaml
+---
+layout: doc
+---
+```
+
+### hero {{ theme.footer.copyright }}
+
+```
+
+## `useRoute`
+ /**
+ * Chamado antes da mudança de rota. Retorne `false` para cancelar a navegação.
+ */
+ onBeforeRouteChange?: (to: string) => Awaitable
+ /**
+ * Chamado antes do carregamento do componente da página (depois que o estado do histórico é
+ * atualizado). Retorne `false` para cancelar a navegação.
+ */
+ onBeforePageLoad?: (to: string) => Awaitable
+ /**
+ * Chamado após a mudança de rota.
+ */
+ onAfterRouteChanged?: (to: string) => Awaitable
+}
+```
+
+## `withBase` Layout Personalizado!
+
+
+```
+
+- Relacionado: [Compatibilidade SSR](../guide/ssr-compat)
+
+## `$frontmatter` /.vitepress/config.[ext]`, onde `` é a [raiz do projeto](../guide/routing#root-and-source-directory) VitePress e `[ext]` é uma das extensões de arquivo suportadas. O TypeScript é suportado de fábrica. As extensões suportadas incluem `.js`, `.ts`, `.mjs` e `.mts`.
+
+Recomenda-se usar a sintaxe de módulos ES nos arquivos de configuração. O arquivo de configuração deve exportar por padrão um objeto:
+
+```ts
+export default {
+ // opções de configuração de nível da aplicação
+ lang: 'pt-BR',
+ title: 'VitePress',
+ description: 'Gerador de site estático Vite & Vue.',
+ ...
+}
+```
+
+:::details Configuração Dinâmica (Assíncrona)
+
+Se você precisar gerar dinamicamente a configuração, também pode exportar por padrão uma função. Por exemplo:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default async () => {
+ const posts = await (await fetch('https://my-cms.com/blog-posts')).json()
+
+ return defineConfig({
+ // opções de configuração de nível da aplicação
+ lang: 'pt-BR',
+ title: 'VitePress',
+ description: 'Gerador de site estático Vite & Vue.',
+
+ // opções de configuração de nível do tema
+ themeConfig: {
+ sidebar: [
+ ...posts.map((post) => ({
+ text: post.name,
+ link: `/posts/${post.name}`
+ }))
+ ]
+ }
+ })
+}
+```
+
+Você também pode usar o `await` no nível superior. Como:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+const posts = await (await fetch('https://my-cms.com/blog-posts')).json()
+
+export default defineConfig({
+ // opções de configuração de nível da aplicação
+ lang: 'pt-BR',
+ title: 'VitePress',
+ description: 'Gerador de site estático Vite & Vue.',
+
+ // opções de configuração de nível do tema
+ themeConfig: {
+ sidebar: [
+ ...posts.map((post) => ({
+ text: post.name,
+ link: `/posts/${post.name}`
+ }))
+ ]
+ }
+})
+```
+
+:::
+
+### Configuração Intellisense {#config-intellisense}
+
+Usar o auxiliar `defineConfig` fornecerá Intellisense alimentado por TypeScript para as opções de configuração. Supondo que seu IDE o suporte, isso deve funcionar tanto em JavaScript quanto em TypeScript.
+
+```js
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ // ...
+})
+```
+
+### Configuração de Tema Tipada {#typed-theme-config}
+
+Por padrão, o auxiliar `defineConfig` espera o tipo de configuração de tema do tema padrão:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ // O tipo é `DefaultTheme.Config`
+ }
+})
+```
+
+Se você estiver usando um tema personalizado e desejar verificações de tipo para a configuração do tema, será necessário usar `defineConfigWithTheme` em vez disso, e passar o tipo de configuração para o seu tema personalizado por meio de um argumento genérico:
+
+```ts
+import { defineConfigWithTheme } from 'vitepress'
+import type { ThemeConfig } from 'your-theme'
+
+export default defineConfigWithTheme({
+ themeConfig: {
+ // O tipo é `ThemeConfig`
+ }
+})
+```
+
+### Configuração Vite, Vue & Markdown
+
+- **Vite**
+
+ Você pode configurar a instância subjacente do Vite usando a opção [vite](#vite) em sua configuração VitePress. Não é necessário criar um arquivo de configuração Vite separado.
+
+- **Vue**
+
+ VitePress já inclui o plugin Vue oficial para Vite ([@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue)). Você pode configurar suas opções usando a opção [vue](#vue) em sua configuração VitePress.
+
+- **Markdown**
+
+ Você pode configurar a instância subjacente de [Markdown-It](https://github.com/markdown-it/markdown-it) usando a opção [markdown](#markdown) em sua configuração VitePress.
+
+## Metadados do Site {#site-metadata}
+
+### title
+
+- Tipo: `string`
+- Padrão: `VitePress`
+- Pode ser substituído por página via [frontmatter](./frontmatter-config#title)
+
+Título do site. Ao usar o tema padrão, isso será exibido na barra de navegação.
+
+Ele também será usado como o sufixo padrão para todos os títulos individuais das páginas, a menos que [`titleTemplate`](#titletemplate) seja definido. O título final de uma página individual será o conteúdo textual do seu primeiro cabeçalho ``, combinado com o título global como sufixo. Por exemplo, com a seguinte configuração e conteúdo da página:
+
+```ts
+export default {
+ title: 'Meu Site Incrível'
+}
+```
+
+```md
+# Olá
+```
+
+O título da página será `Olá | Meu Site Incrível`.
+
+### titleTemplate
+
+- Tipo: `string | boolean`
+- Pode ser substituído por página via [frontmatter](./frontmatter-config#titletemplate)
+
+Permite personalizar o sufixo do título de cada página ou o título inteiro. Por exemplo:
+
+```ts
+export default {
+ title: 'Meu Site Incrível',
+ titleTemplate: 'Sufixo Personalizado'
+}
+```
+
+```md
+# Olá
+```
+
+O título da página será `Olá | Sufixo Personalizado`.
+
+Para personalizar completamente como o título deve ser renderizado, você pode usar o símbolo `:title` em `titleTemplate`:
+
+```ts
+export default {
+ titleTemplate: ':title - Sufixo Personalizado'
+}
+```
+
+Aqui, `:title` será substituído pelo texto inferido do primeiro cabeçalho `` da página. O título do exemplo anterior da página será `Olá - Sufixo Personalizado`.
+
+A opção pode ser definida como `false` para desativar sufixos de título.
+
+### description
+
+- Tipo: `string`
+- Padrão: `Um site VitePress`
+- Pode ser substituído por página via [frontmatter](./frontmatter-config#descrição)
+
+Descrição para o site. Isso será apresentado como uma tag `` na página HTML.
+
+```ts
+export default {
+ descrição: 'Um site VitePress'
+}
+```
+
+### head
+
+- Tipo: `HeadConfig[]`
+- Padrão: `[]`
+- Pode ser acrescentado por página via [frontmatter](./frontmatter-config#head)
+
+Elementos adicionais para adicionar na tag `` da página HTML. As tags adicionadas pelo usuário são mostradas antes da tag `head` de fechamento, após as tags VitePress.
+
+```ts
+type HeadConfig =
+ | [string, Record]
+ | [string, Record, string]
+```
+
+#### Exemplo: Adicionando um favicon {#example-adding-a-favicon}
+
+```ts
+export default {
+ cabeça: [['link', { rel: 'icon', href: '/favicon.ico' }]]
+} // coloque o favicon.ico no diretório public, se a base estiver definida, use /base/favicon.ico
+
+/* Mostraria:
+
+*/
+```
+
+#### Exemplo: Adicionando Fontes do Google {#example-adding-google-fonts}
+
+```ts
+export default {
+ head: [
+ [
+ 'link',
+ { rel: 'preconnect', href: 'https://fonts.googleapis.com' }
+ ],
+ [
+ 'link',
+ { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }
+ ],
+ [
+ 'link',
+ { href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap', rel: 'stylesheet' }
+ ]
+ ]
+}
+
+/* Mostraria:
+
+
+
+*/
+```
+
+#### Exemplo: Registrando um _service worker_ {#example-registering-a-service-worker}
+
+```ts
+export default {
+ head: [
+ [
+ 'script',
+ { id: 'register-sw' },
+ `;(() => {
+ if ('serviceWorker' in navigator) {
+ navigator.serviceWorker.register('/sw.js')
+ }
+ })()`
+ ]
+ ]
+}
+
+/* Mostraria:
+
+*/
+```
+
+#### Exemplo: Usando o Google Analytics {#example-using-google-analytics}
+
+```ts
+export default {
+ head: [
+ [
+ 'script',
+ { async: '', src: 'https://www.googletagmanager.com/gtag/js?id=TAG_ID' }
+ ],
+ [
+ 'script',
+ {},
+ `window.dataLayer = window.dataLayer || [];
+ function gtag(){dataLayer.push(arguments);}
+ gtag('js', new Date());
+ gtag('config', 'TAG_ID');`
+ ]
+ ]
+}
+
+/* Mostraria:
+
+
+*/
+```
+
+### lang
+
+- Tipo: `string`
+- Padrão: `en-US`
+
+O atributo de idioma para o site. Isso será mostrado como uma tag `` na página HTML.
+
+```ts
+export default {
+ lang: 'en-US'
+}
+```
+
+### base
+
+- Tipo: `string`
+- Padrão: `/`
+
+A URL base em que o site será implantado. Você precisará definir isso se planeja implantar seu site em um subdiretório, por exemplo, no GitHub pages. Se você planeja implantar seu site em `https://foo.github.io/bar/` então você deve definir a base como `'/bar/'`. Deve sempre começar e terminar com uma barra.
+
+A base é automaticamente adicionada a todos as URLs que começam com / em outras opções, então você só precisa especificá-la uma vez.
+
+```ts
+export default {
+ base: '/base/'
+}
+```
+
+## Roteamento {#routing}
+
+### cleanUrls
+
+- Tipo: `boolean`
+- Padrão: `false`
+
+Quando definido como `true`, VitePress removerá o `.html` no final dos URLs. Veja também [Gerando URL Limpa](../guide/routing#generating-clean-url).
+
+::: alerta Suporte do Servidor Necessário
+Ativar isso pode exigir configurações adicionais em sua plataforma de hospedagem. Para funcionar, seu servidor deve ser capaz de servir `/foo.html` ao visitar `/foo` **sem redirecionamento**.
+:::
+
+### rewrites
+
+- Tipo: `Record`
+
+Define mapeamentos personalizados de diretório <-> URL. Veja [Roteamento: Reescrever Rotas](../guide/routing#route-rewrites) para mais detalhes.
+
+```ts
+export default {
+ rewrites: {
+ 'source/:page': 'destination/:page'
+ }
+}
+```
+
+## Construção {#build}
+
+### srcDir
+
+- Tipo: `string`
+- Padrão: `.`
+
+O diretório onde suas páginas de markdown são armazenadas, relativo à raiz do projeto. Veja também [Diretório Raiz e Fonte](../guide/routing#root-and-source-directory).
+
+```ts
+export default {
+ srcDir: './src'
+}
+```
+
+### srcExclude
+
+- Tipo: `string`
+- Padrão: `undefined`
+
+Um [padrão glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) para corresponder a arquivos markdown que devem ser excluídos como conteúdo fonte.
+
+```ts
+export default {
+ srcExclude: ['**/README.md', '**/TODO.md']
+}
+```
+
+### outDir
+
+- Tipo: `string`
+- Padrão: `./.vitepress/dist`
+
+A localização da saída da compilação para o site, relativa à [raiz do projeto](../guide/routing#root-and-source-directory).
+
+```ts
+export default {
+ outDir: '../public'
+}
+```
+
+### assetsDir
+
+- Tipo: `string`
+- Padrão: `assets`
+
+Especifica o diretório para aninhar ativos gerados. O caminho deve estar dentro de [`outDir`](#outdir) e é resolvido em relação a ele.
+
+```ts
+export default {
+ assetsDir: 'static'
+}
+```
+
+### cacheDir
+
+- Tipo: `string`
+- Padrão: `./.vitepress/cache`
+
+O diretório para arquivos de cache, relativo à [raiz do projeto](../guide/routing#root-and-source-directory). Veja também: [cacheDir](https://vitejs.dev/config/shared-options.html#cachedir).
+
+```ts
+export default {
+ cacheDir: './.vitepress/.vite'
+}
+```
+
+### ignoreDeadLinks
+
+- Tipo: `boolean | 'localhostLinks' | (string | RegExp | ((link: string) => boolean))[]`
+- Padrão: `false`
+
+Quando definido como `true`, VitePress não falhará na compilação devido a links quebrados.
+
+Quando definido como `'localhostLinks'`, a compilação falhará em links quebrados, mas não verificará links `localhost`.
+
+```ts
+export default {
+ ignoreDeadLinks: true
+}
+```
+
+Também pode ser um _array_ de uma exata URL em string, padrões regex, ou funções de filtro personalizadas.
+
+```ts
+export default {
+ ignoreDeadLinks: [
+ // ignora URL exata "/playground"
+ '/playground',
+ // ignora todos os links localhost
+ /^https?:\/\/localhost/,
+ // ignora todos os links incluindo "/repl/""
+ /\/repl\//,
+ // função personalizada, ignora todos os links incluindo "ignore"
+ (url) => {
+ return url.toLowerCase().includes('ignore')
+ }
+ ]
+}
+```
+
+### mpa `
+`buildEnd` é um gancho de compilação CLI (Interface de Linha de Comando), ele será executado após a conclusão da compilação (SSG), mas antes que o processo VitePress CLI termine.
+
+```ts
+export default {
+ async buildEnd(siteConfig) {
+ // ...
+ }
+}
+```
+
+## postRender
+- Tipo: `(context: SSGContext) => Awaitable`
+- `postRender` é um gancho de compilação, chamado quando a interpretação SSG é concluída. Ele permitirá que você manipule o conteúdo de _teleports_ durante a geração de site estático.
+
+ ```ts
+ export default {
+ async postRender(context) {
+ // ...
+ }
+ }
+ ```
+
+ ```ts
+ interface SSGContext {
+ content: string
+ teleports?: Record
+ [key: string]: any
+ }
+ ```
+
+## transformHead
+- Tipo: `(context: TransformContext) => Awaitable`
+
+`transformHead` é um gancho de compilação para transformar o cabeçalho antes de gerar cada página. Isso permite adicionar entradas no cabeçalho que não podem ser adicionadas estaticamente à configuração VitePress. Você só precisa retornar entradas extras, que serão mescladas automaticamente com as existentes.
+
+:::warning
+Não faça mutações em qualquer item dentro de `context`.
+:::
+
+```ts
+export default {
+ async transformHead(context) {
+ // ...
+ }
+}
+```
+
+```ts
+interface TransformContext {
+ page: string // e.g. index.md (relativo a srcDir)
+ assets: string[] // todos os ativos não-js/css com URL pública completamente resolvida
+ siteConfig: SiteConfig
+ siteData: SiteData
+ pageData: PageData
+ title: string
+ description: string
+ head: HeadConfig[]
+ content: string
+}
+```
+
+Note que este gancho só é chamado ao gerar o site estaticamente. Não é chamado durante o desenvolvimento. Se você precisar adicionar entradas de cabeçalho dinâmicas durante o desenvolvimento, pode usar o gancho [`transformPageData`](#transformpagedata) em seu lugar.
+
+ ```ts
+ export default {
+ transformPageData(pageData) {
+ pageData.frontmatter.head ??= []
+ pageData.frontmatter.head.push([
+ 'meta',
+ {
+ name: 'og:title',
+ content:
+ pageData.frontmatter.layout === 'home'
+ ? `VitePress`
+ : `${pageData.title} | VitePress`
+ }
+ ])
+ }
+ }
+ ```
+
+#### Exemplo: Adicionar URL canônica `` {#example-adding-a-canonical-url-link}
+
+```ts
+export default {
+ transformPageData(pageData) {
+ const canonicalUrl = `https://example.com/${pageData.relativePath}`
+ .replace(/index\.md$/, '')
+ .replace(/\.md$/, '.html')
+
+ pageData.frontmatter.head ??= []
+ pageData.frontmatter.head.push([
+ 'link',
+ { rel: 'canonical', href: canonicalUrl }
+ ])
+ }
+}
+```
+
+### transformHtml
+- Tipo: `(code: string, id: string, context: TransformContext) => Awaitable`
+`transformHtml` é um gancho de compilação para transformar o conteúdo de cada página antes de salvá-lo no disco.
+
+:::warning
+Não faça mutações em qualquer item dentro de `context`. Além disso, modificar o conteúdo HTML pode causar problemas de hidratação em tempo de execução.
+:::
+
+```ts
+export default {
+ async transformHtml(code, id, context) {
+ // ...
+ }
+}
+```
+
+### transformPageData
+- Tipo: `(pageData: PageData, context: TransformPageContext) => Awaitable | { [key: string]: any } | void>`
+
+`transformPageData` é um gancho para transformar os dados de cada página. Você pode fazer mutações diretamente em `pageData` ou retornar valores alterados que serão mesclados nos dados da página.
+
+:::warning
+Não faça mutações em qualquer item dentro de `context` e tenha cuidado pois isso pode impactar no desempenho do servidor de desenvolvimento, especialmente se você tiver algumas solicitações de rede ou computações pesadas (como gerar imagens) no gancho. Você pode verificar `process.env.NODE_ENV === 'production'` para lógica condicional.
+:::
+
+```ts
+export default {
+ async transformPageData(pageData, { siteConfig }) {
+ pageData.contributors = await getPageContributors(pageData.relativePath)
+ }
+
+ // ou retorne dados a serem mesclados
+ async transformPageData(pageData, { siteConfig }) {
+ return {
+ contributors: await getPageContributors(pageData.relativePath)
+ }
+ }
+}
+```
+
+```ts
+interface TransformPageContext {
+ siteConfig: SiteConfig
+}
+```
diff --git a/docs/public/_headers b/docs/public/_headers
index f7fa3afc..5d2850dd 100644
--- a/docs/public/_headers
+++ b/docs/public/_headers
@@ -1,3 +1,6 @@
/assets/*
cache-control: max-age=31536000
- cache-control: immutable
\ No newline at end of file
+ cache-control: immutable
+
+/_translations/*
+ x-robots-tag: noindex
diff --git a/docs/reference/default-theme-config.md b/docs/reference/default-theme-config.md
index 8402dc08..4a431538 100644
--- a/docs/reference/default-theme-config.md
+++ b/docs/reference/default-theme-config.md
@@ -93,6 +93,7 @@ interface NavItemWithLink {
activeMatch?: string
target?: string
rel?: string
+ noIcon?: boolean
}
interface NavItemChildren {
@@ -134,7 +135,7 @@ export default {
export type Sidebar = SidebarItem[] | SidebarMulti
export interface SidebarMulti {
- [path: string]: SidebarItem[]
+ [path: string]: SidebarItem[] | { items: SidebarItem[]; base: string }
}
export type SidebarItem = {
@@ -161,6 +162,19 @@ export type SidebarItem = {
* If `false`, group is collapsible but expanded by default
*/
collapsed?: boolean
+
+ /**
+ * Base path for the children items.
+ */
+ base?: string
+
+ /**
+ * Customize text that appears on the footer of previous/next page.
+ */
+ docFooterText?: string
+
+ rel?: string
+ target?: string
}
```
@@ -244,8 +258,10 @@ type SocialLinkIcon =
| 'instagram'
| 'linkedin'
| 'mastodon'
+ | 'npm'
| 'slack'
| 'twitter'
+ | 'x'
| 'youtube'
| { svg: string }
```
@@ -406,6 +422,20 @@ export interface DocFooter {
Can be used to customize the dark mode switch label. This label is only displayed in the mobile view.
+## lightModeSwitchTitle
+
+- Type: `string`
+- Default: `Switch to light theme`
+
+Can be used to customize the light mode switch title that appears on hovering.
+
+## darkModeSwitchTitle
+
+- Type: `string`
+- Default: `Switch to dark theme`
+
+Can be used to customize the dark mode switch title that appears on hovering.
+
## sidebarMenuLabel
- Type: `string`
diff --git a/docs/reference/default-theme-home-page.md b/docs/reference/default-theme-home-page.md
index bbded876..f7baecca 100644
--- a/docs/reference/default-theme-home-page.md
+++ b/docs/reference/default-theme-home-page.md
@@ -69,6 +69,12 @@ interface HeroAction {
// Destination link of the button.
link: string
+
+ // Link target attribute.
+ target?: string
+
+ // Link rel attribute.
+ rel?: string
}
```
@@ -131,7 +137,7 @@ interface Feature {
// Link when clicked on feature component. The link can
// be both internal or external.
//
- // e.g. `guid/reference/default-theme-home-page` or `htttps://example.com`
+ // e.g. `guide/reference/default-theme-home-page` or `https://example.com`
link?: string
// Link text to be shown inside feature component. Best
@@ -144,6 +150,9 @@ interface Feature {
//
// e.g. `external`
rel?: string
+
+ // Link target attribute for the `link` option.
+ target?: string
}
type FeatureIcon =
@@ -157,3 +166,30 @@ type FeatureIcon =
height: string
}
```
+
+## Markdown Content
+
+You can add additional content to your site's homepage just by adding Markdown below the `---` frontmatter divider.
+
+````md
+---
+layout: home
+
+hero:
+ name: VitePress
+ text: Vite & Vue powered static site generator.
+---
+
+## Getting Started
+
+You can get started using VitePress right away using `npx`!
+
+```sh
+npm init
+npx vitepress init
+```
+````
+
+::: info
+VitePress didn't always auto-style the extra content of the `layout: home` page. To revert to older behavior, you can add `markdownStyles: false` to the frontmatter.
+:::
diff --git a/docs/reference/default-theme-team-page.md b/docs/reference/default-theme-team-page.md
index 5a6e2a9e..29b071ff 100644
--- a/docs/reference/default-theme-team-page.md
+++ b/docs/reference/default-theme-team-page.md
@@ -212,6 +212,9 @@ interface TeamMember {
// URL for the sponsor page for the member.
sponsor?: string
+
+ // Text for the sponsor link. Defaults to 'Sponsor'.
+ actionText?: string
}
```
diff --git a/docs/reference/runtime-api.md b/docs/reference/runtime-api.md
index 03bb6160..b65c2661 100644
--- a/docs/reference/runtime-api.md
+++ b/docs/reference/runtime-api.md
@@ -38,6 +38,10 @@ interface VitePressData {
isDark: Ref
dir: Ref
localeIndex: Ref
+ /**
+ * Current location hash
+ */
+ hash: Ref
}
interface PageData {
diff --git a/docs/reference/site-config.md b/docs/reference/site-config.md
index b5e124d2..e11f42b9 100644
--- a/docs/reference/site-config.md
+++ b/docs/reference/site-config.md
@@ -24,6 +24,62 @@ export default {
}
```
+:::details Dynamic (Async) Config
+
+If you need to dynamically generate the config, you can also default export a function. For example:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default async () => {
+ const posts = await (await fetch('https://my-cms.com/blog-posts')).json()
+
+ return defineConfig({
+ // app level config options
+ lang: 'en-US',
+ title: 'VitePress',
+ description: 'Vite & Vue powered static site generator.',
+
+ // theme level config options
+ themeConfig: {
+ sidebar: [
+ ...posts.map((post) => ({
+ text: post.name,
+ link: `/posts/${post.name}`
+ }))
+ ]
+ }
+ })
+}
+```
+
+You can also use top-level `await`. For example:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+const posts = await (await fetch('https://my-cms.com/blog-posts')).json()
+
+export default defineConfig({
+ // app level config options
+ lang: 'en-US',
+ title: 'VitePress',
+ description: 'Vite & Vue powered static site generator.',
+
+ // theme level config options
+ themeConfig: {
+ sidebar: [
+ ...posts.map((post) => ({
+ text: post.name,
+ link: `/posts/${post.name}`
+ }))
+ ]
+ }
+})
+```
+
+:::
+
### Config Intellisense
Using the `defineConfig` helper will provide TypeScript-powered intellisense for config options. Assuming your IDE supports it, this should work in both JavaScript and TypeScript.
@@ -415,6 +471,13 @@ export default {
}
```
+### metaChunk `
diff --git a/docs/ru/components/ModalDemo.vue b/docs/ru/components/ModalDemo.vue
new file mode 100644
index 00000000..85c9dec1
--- /dev/null
+++ b/docs/ru/components/ModalDemo.vue
@@ -0,0 +1,80 @@
+
+
+
+
+
+
+
+
+
+ Привет из модального окна!
+
+
+
+
+
+
+
+
diff --git a/docs/ru/guide/asset-handling.md b/docs/ru/guide/asset-handling.md
new file mode 100644
index 00000000..c24bfa73
--- /dev/null
+++ b/docs/ru/guide/asset-handling.md
@@ -0,0 +1,63 @@
+# Обработка ресурсов {#asset-handling}
+
+## Ссылки на статические ресурсы {#referencing-static-assets}
+
+Все файлы Markdown компилируются в компоненты Vue и обрабатываются [Vite](https://vitejs.dev/guide/assets.html). Вы можете, **и должны**, ссылаться на любые ресурсы, используя относительные URL:
+
+```md
+
+```
+
+Вы можете ссылаться на статические ресурсы в ваших файлах разметки, компоненты `*.vue` в теме, стили и обычные файлы `.css`, используя абсолютные пути (основанные на корне проекта) или относительные пути (основанные на вашей файловой системе). Последнее похоже на поведение, к которому вы привыкли, если использовали Vite, Vue CLI или `file-loader` в webpack.
+
+Распространенные типы файлов изображений, мультимедиа и шрифтов определяются и включаются в качестве ресурсов автоматически.
+
+::: tip Связанные файлы не рассматриваются как ресурсы
+PDF-файлы или другие документы, на которые есть ссылки в файлах с разметкой, не рассматриваются автоматически как ресурсы. Чтобы сделать связанные файлы доступными, вы должны вручную поместить их в каталог [`public`](#the-public-directory) вашего проекта.
+:::
+
+Все ссылающиеся ресурсы, включая те, которые используют абсолютные пути, будут скопированы в выходной каталог с хэшированным именем файла в производственной сборке. Ресурсы, на которые никогда не ссылались, не будут скопированы. Изображения размером менее 4 КБ будут вставляться в формате base64 — это можно настроить с помощью опции конфигурации [`vite`](../reference/site-config#vite).
+
+Все **статические** ссылки на пути, включая абсолютные пути, должны быть основаны на структуре ваших рабочих каталогов.
+
+## Директория `public` {#the-public-directory}
+
+Иногда вам может понадобиться предоставить статические ресурсы, на которые нет прямых ссылок ни в одном из компонентов Markdown или темы, или вы можете захотеть предоставить определённые файлы с оригинальным именем. Примерами таких файлов являются `robots.txt`, `favicon.ico` и иконки PWA.
+
+Вы можете поместить эти файлы в директорию `public` в [директории с исходными файлами](./routing#source-directory). Например, если корень вашего проекта — `./docs`, и вы используете стандартное расположение исходного каталога, то ваш публичный каталог будет `./docs/public`.
+
+Ресурсы, размещённые в `public`, будут скопированы в корень выходного каталога как есть.
+
+Обратите внимание, что вы должны ссылаться на файлы, размещённые в `public`, используя корневой абсолютный путь — например, `public/icon.png` всегда должен упоминаться в исходном коде как `/icon.png`.
+
+## Базовый URL {#base-url}
+
+Если ваш сайт развёрнут на URL-адресе, не являющемся корневым, вам нужно установить параметр `base` в файле `.vitepress/config.js`. Например, если вы планируете развернуть свой сайт на `https://foo.github.io/bar/`, то параметр `base` следует установить на `'/bar/'` (он всегда должен начинаться и заканчиваться слэшем).
+
+Все пути к статическим ресурсам автоматически обрабатываются с учётом различных значений конфигурации `base`. Например, если в вашей разметке есть абсолютная ссылка на ресурс в директории `public`:
+
+```md
+
+```
+
+В этом случае вам **не** нужно обновлять его при изменении значения конфигурации `base`.
+
+Однако если вы создаете компонент темы, который динамически ссылается на активы, например, изображение, атрибут `src` которого основан на значении конфигурации темы:
+
+```vue
+![]()
+```
+
+В этом случае рекомендуется обернуть путь с помощью [хелпера `withBase`](../reference/runtime-api#withbase), предоставляемого VitePress:
+
+```vue
+
+
+
+ ![]()
+
+```
diff --git a/docs/ru/guide/cms.md b/docs/ru/guide/cms.md
new file mode 100644
index 00000000..81542d2b
--- /dev/null
+++ b/docs/ru/guide/cms.md
@@ -0,0 +1,58 @@
+---
+outline: deep
+---
+
+# Подключение к CMS {#connecting-to-a-cms}
+
+## Общий рабочий процесс {#general-workflow}
+
+Подключение VitePress к CMS в значительной степени зависит от [динамических маршрутов](./routing#dynamic-routes). Прежде чем приступить к работе, убедитесь, что вы понимаете, как это работает.
+
+Поскольку каждая CMS работает по-своему, здесь мы можем предоставить лишь общую схему работы, которую вам нужно будет адаптировать под свой конкретный сценарий.
+
+1. Если ваша CMS требует аутентификации, создайте файл `.env` для хранения токенов API и загрузите его таким образом:
+
+ ```js
+ // posts/[id].paths.js
+ import { loadEnv } from 'vitepress'
+
+ const env = loadEnv('', process.cwd())
+ ```
+
+2. Получите необходимые данные из CMS и преобразуйте их в соответствующие пути:
+
+ ```js
+ export default {
+ async paths() {
+ // при необходимости используйте соответствующую клиентскую библиотеку CMS
+ const data = await (
+ await fetch('https://my-cms-api', {
+ headers: {
+ // токен, если необходимо
+ }
+ })
+ ).json()
+
+ return data.map((entry) => {
+ return {
+ params: { id: entry.id /* заголовок, автор, дата и т. д. */ },
+ content: entry.content
+ }
+ })
+ }
+ }
+ ```
+
+3. Отрисуйте содержимое страницы:
+
+ ```md
+ # {{ $params.title }}
+
+ - Автор: {{ $params.author }}, {{ $params.date }}
+
+
+ ```
+
+## Руководства по интеграции {#integration-guides}
+
+Если вы написали руководство по интеграции VitePress с конкретной CMS, воспользуйтесь ссылкой «Редактировать эту страницу», чтобы добавить его сюда!
diff --git a/docs/ru/guide/custom-theme.md b/docs/ru/guide/custom-theme.md
new file mode 100644
index 00000000..05ca3b23
--- /dev/null
+++ b/docs/ru/guide/custom-theme.md
@@ -0,0 +1,222 @@
+# Пользовательская тема {#using-a-custom-theme}
+
+## Разрешение темы {#theme-resolving}
+
+Вы можете включить пользовательскую тему, создав файл `.vitepress/theme/index.js` или `.vitepress/theme/index.ts` («файл входа темы»):
+
+```
+.
+├─ docs # корень проекта
+│ ├─ .vitepress
+│ │ ├─ theme
+│ │ │ └─ index.js # файл входа темы
+│ │ └─ config.js # файл конфигурации
+│ └─ index.md
+└─ package.json
+```
+
+VitePress всегда будет использовать пользовательскую тему вместо темы по умолчанию, если обнаружит наличие входного файла темы. Однако вы можете [расширить тему по умолчанию](./extending-default-theme), чтобы выполнить расширенные настройки поверх нее.
+
+## Интерфейс темы {#theme-interface}
+
+Пользовательская тема VitePress определяется как объект со следующим интерфейсом:
+
+```ts
+interface Theme {
+ /**
+ * Корневой компонент макета для каждой страницы
+ * @required
+ */
+ Layout: Component
+ /**
+ * Улучшение экземпляра приложения Vue
+ * @optional
+ */
+ enhanceApp?: (ctx: EnhanceAppContext) => Awaitable
+ /**
+ * Расширяем другую тему, вызывая её `enhanceApp` перед нашей
+ * @optional
+ */
+ extends?: Theme
+}
+
+interface EnhanceAppContext {
+ app: App // Экземпляр приложения Vue
+ router: Router // Экземпляр маршрутизатора VitePress
+ siteData: Ref // Метаданные на уровне сайта
+}
+```
+
+Файл входа темы должен экспортировать тему по умолчанию:
+
+```js
+// .vitepress/theme/index.js
+
+// Вы можете напрямую импортировать файлы Vue в файле входа темы.
+// VitePress предварительно настроен с помощью @vitejs/plugin-vue.
+import Layout from './Layout.vue'
+
+export default {
+ Layout,
+ enhanceApp({ app, router, siteData }) {
+ // ...
+ }
+}
+```
+
+Экспорт по умолчанию является единственным контрактом для пользовательской темы, и только свойство `Layout` является обязательным. Таким образом, технически тема VitePress может быть простой, как один компонент Vue.
+
+Внутри компонент макета работает так же, как и обычное приложение Vite + Vue 3. Обратите внимание, что тема также должна быть [SSR-совместимой](./ssr-compat).
+
+## Создание макета {#building-a-layout}
+
+Самый базовый компонент макета должен содержать компонент [`Пользовательский макет!
+
+
+ Пользовательский макет!
+
+
+ Пользовательская страница 404!
+
+ Пользовательский макет!
+
+
+ Пользовательская страница 404!
+
+
+ Пользовательская домашняя страница!
+
+ Пользовательский макет!
+
+ ({
+ extends: baseConfig,
+ themeConfig: {
+ // Тип `ThemeConfig`
+ }
+})
+```
diff --git a/docs/ru/guide/data-loading.md b/docs/ru/guide/data-loading.md
new file mode 100644
index 00000000..a611dc88
--- /dev/null
+++ b/docs/ru/guide/data-loading.md
@@ -0,0 +1,258 @@
+# Загрузка данных в режиме реального времени {#build-time-data-loading}
+
+VitePress предоставляет функцию **загрузчиков данных**, которая позволяет загружать произвольные данные и импортировать их со страниц или компонентов. Загрузка данных выполняется **только во время сборки**: Полученные данные будут сериализованы в виде JSON в финальной сборке JavaScript.
+
+Загрузчики данных могут использоваться для получения удалённых данных или генерирования метаданных на основе локальных файлов. Например, вы можете использовать загрузчики данных для анализа всех локальных страниц API и автоматического создания индекса всех записей API.
+
+## Пример использования {#basic-usage}
+
+Файл загрузчика данных должен заканчиваться либо `.data.js`, либо `.data.ts`. Файл должен предоставлять экспорт объекта по умолчанию с помощью метода `load()`:
+
+```js
+// example.data.js
+export default {
+ load() {
+ return {
+ hello: 'мир'
+ }
+ }
+}
+```
+
+Модуль загрузчика выполняется только в Node.js, поэтому вы можете импортировать любые API Node и зависимости npm по мере необходимости.
+
+Затем вы можете импортировать данные из этого файла в страницы `.md` и компоненты `.vue` с помощью экспорта с именем `data`:
+
+```vue
+
+
+{{ data }}
+```
+
+Результат:
+
+```json
+{
+ "hello": "мир"
+}
+```
+
+Вы заметите, что сам загрузчик данных не экспортирует `data`. Это VitePress вызывает метод `load()` за кулисами и неявно раскрывает результат через именованный экспорт `data`.
+
+Это работает, даже если загрузчик асинхронный:
+
+```js
+export default {
+ async load() {
+ // получение удалённых данных
+ return (await fetch('...')).json()
+ }
+}
+```
+
+## Данные из локальных файлов {#data-from-local-files}
+
+Если вам нужно генерировать данные на основе локальных файлов, используйте опцию `watch` в загрузчике данных, чтобы изменения, внесённые в эти файлы, вызывали горячие обновления.
+
+Опция `watch` удобна ещё и тем, что вы можете использовать [шаблоны glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) для соответствия нескольким файлам. Шаблоны могут быть относительными к самому файлу загрузчика, а функция `load()` будет получать совпадающие файлы в виде абсолютных путей.
+
+В следующем примере показана загрузка CSV-файлов и их преобразование в JSON с помощью [csv-parse](https://github.com/adaltas/node-csv/tree/master/packages/csv-parse/). Поскольку этот файл выполняется только во время сборки, вы не будете передавать CSV-парсер клиенту!
+
+```js
+import fs from 'node:fs'
+import { parse } from 'csv-parse/sync'
+
+export default {
+ watch: ['./data/*.csv'],
+ load(watchedFiles) {
+ // watchedFiles будет представлять собой массив абсолютных путей к найденным файлам.
+ // Формируем массив метаданных записи блога, которые можно использовать для визуализации списка в макете темы
+ return watchedFiles.map((file) => {
+ return parse(fs.readFileSync(file, 'utf-8'), {
+ columns: true,
+ skip_empty_lines: true
+ })
+ })
+ }
+}
+```
+
+## `createContentLoader` {#createcontentloader}
+
+При создании сайта, ориентированного на контент, нам часто приходится создавать страницы типа «архив», или «индекс», на которых мы перечисляем все доступные записи в нашей коллекции контента. Например, записи в блоге или страницы API. Мы **можем** реализовать это напрямую с помощью API загрузчика данных, но поскольку это очень распространённый случай использования, VitePress также предоставляет функцию `createContentLoader`, чтобы упростить эту задачу:
+
+```js
+// posts.data.js
+import { createContentLoader } from 'vitepress'
+
+export default createContentLoader('posts/*.md' /* параметры */)
+```
+
+Эта функция принимает шаблон glob относительно [исходного каталога](./routing#source-directory) и возвращает объект `{ watch, load }` загрузчика данных, который может быть использован в качестве экспорта по умолчанию в файле загрузчика данных. В нем также реализовано кэширование на основе временных меток изменения файлов для повышения производительности dev.
+
+Обратите внимание, что загрузчик работает только с файлами Markdown — совпадающие файлы, не относящиеся к Markdown, будут пропущены.
+
+Загруженные данные будут представлять собой массив с типом `ContentData[]`:
+
+```ts
+interface ContentData {
+ // отображаемый URL-адрес страницы, например: /posts/hello.html (не включает `base`)
+ // выполните итерацию вручную или используйте пользовательскую `трансформацию` для нормализации путей
+ url: string
+ // метаданные страницы
+ frontmatter: Record
+
+ // следующие параметры присутствуют только в том случае, если соответствующие опции включены
+ // мы рассмотрим их ниже
+ src: string | undefined
+ html: string | undefined
+ excerpt: string | undefined
+}
+```
+
+По умолчанию указываются только `url` и `frontmatter`. Это связано с тем, что загруженные данные будут вложены в клиентский пакет в виде JSON, поэтому нам нужно быть осторожными с их размером. Вот пример использования этих данных для создания минимальной индексной страницы блога:
+
+```vue
+
+
+
+ Все записи блога
+
+ -
+ {{ post.frontmatter.title }}
+ by {{ post.frontmatter.author }}
+
+
+
+```
+
+### Параметры {#options}
+
+Данные по умолчанию могут не соответствовать всем требованиям — вы можете изменить данные с помощью параметров:
+
+```js
+// posts.data.js
+import { createContentLoader } from 'vitepress'
+
+export default createContentLoader('posts/*.md', {
+ includeSrc: true, // включить исходный текст в формате Markdown?
+ render: true, // включать в себя полный HTML страницы?
+ excerpt: true, // включить отрывок?
+ transform(rawData) {
+ // составляйте карты, сортируйте или фильтруйте исходные данные по своему усмотрению.
+ // конечный результат — это то, что будет отправлено клиенту.
+ return rawData
+ .sort((a, b) => {
+ return +new Date(b.frontmatter.date) - +new Date(a.frontmatter.date)
+ })
+ .map((page) => {
+ page.src // исходный текст в формате Markdown
+ page.html // отображение полной страницы HTML
+ page.excerpt // отображаемый отрывок HTML (содержимое выше первого `---`)
+ return {
+ /* ... */
+ }
+ })
+ }
+})
+```
+
+Посмотрите, как он используется в [блоге Vue.js](https://github.com/vuejs/blog/blob/main/.vitepress/theme/posts.data.ts).
+
+API `createContentLoader` также можно использовать внутри [хуков сборки](../reference/site-config#build-hooks):
+
+```js
+// .vitepress/config.js
+export default {
+ async buildEnd() {
+ const posts = await createContentLoader('posts/*.md').load()
+ // генерируем файлы на основе метаданных сообщений, например, RSS-канал
+ }
+}
+```
+
+**Types**
+
+```ts
+interface ContentOptions {
+ /**
+ * Включаем src?
+ * @default false
+ */
+ includeSrc?: boolean
+
+ /**
+ * Преобразовываем src в HTML и включаем в данные?
+ * @default false
+ */
+ render?: boolean
+
+ /**
+ * Если `boolean`, то следует ли разбирать и включать отрывок? (отображается как HTML)
+ *
+ * Если `function`, то управляйте тем, как отрывок извлекается из содержимого.
+ *
+ * Если `string`, определите пользовательский разделитель, который будет использоваться для извлечения
+ * отрывка. Разделителем по умолчанию является `---`, если `excerpt` имеет значение `true`.
+ *
+ * @see https://github.com/jonschlinkert/gray-matter#optionsexcerpt
+ * @see https://github.com/jonschlinkert/gray-matter#optionsexcerpt_separator
+ *
+ * @default false
+ */
+ excerpt?:
+ | boolean
+ | ((
+ file: {
+ data: { [key: string]: any }
+ content: string
+ excerpt?: string
+ },
+ options?: any
+ ) => void)
+ | string
+
+ /**
+ * Преобразуйте данные. Обратите внимание, что при импорте из компонентов или файлов
+ * с разметкой данные будут вложены в клиентский пакет в виде JSON.
+ */
+ transform?: (data: ContentData[]) => T | Promise
+}
+```
+
+## Загрузчики типизированных данных {#typed-data-loaders}
+
+При использовании TypeScript вы можете ввести свой загрузчик и экспортировать `data` следующим образом:
+
+```ts
+import { defineLoader } from 'vitepress'
+
+export interface Data {
+ // тип данных
+}
+
+declare const data: Data
+export { data }
+
+export default defineLoader({
+ // тип проверенных опций загрузчика
+ watch: ['...'],
+ async load(): Promise {
+ // ...
+ }
+})
+```
+
+## Конфигурация {#configuration}
+
+Чтобы получить информацию о конфигурации внутри загрузчика, вы можете использовать код, подобный этому:
+
+```ts
+import type { SiteConfig } from 'vitepress'
+
+const config: SiteConfig = (globalThis as any).VITEPRESS_CONFIG
+```
diff --git a/docs/ru/guide/deploy.md b/docs/ru/guide/deploy.md
new file mode 100644
index 00000000..c54c1dc9
--- /dev/null
+++ b/docs/ru/guide/deploy.md
@@ -0,0 +1,337 @@
+---
+outline: deep
+---
+
+# Развёртывание вашего сайта VitePress {#deploy-your-vitepress-site}
+
+Следующие руководства основаны на некоторых общих предположениях:
+
+- Сайт VitePress находится в директории `docs` вашего проекта.
+- Вы используете выходной каталог сборки по умолчанию (`.vitepress/dist`).
+- VitePress установлен как локальная зависимость в вашем проекте, и вы установили следующие скрипты в вашем `package.json`:
+
+ ```json
+ {
+ "scripts": {
+ "docs:build": "vitepress build docs",
+ "docs:preview": "vitepress preview docs"
+ }
+ }
+ ```
+
+## Создание и локальное тестирование {#build-and-test-locally}
+
+1. Выполните эту команду, чтобы собрать документацию:
+
+ ```sh
+ $ npm run docs:build
+ ```
+
+2. После сборки просмотрите её локально, запустив команду:
+
+ ```sh
+ $ npm run docs:preview
+ ```
+
+ Команда `preview` загрузит локальный статический веб-сервер, который будет обслуживать выходной каталог `.vitepress/dist` по адресу `http://localhost:4173`. Вы можете использовать это, чтобы убедиться, что всё выглядит хорошо, прежде чем отправлять в производство.
+
+3. Вы можете настроить порт сервера, передав `--port` в качестве аргумента.
+
+ ```json
+ {
+ "scripts": {
+ "docs:preview": "vitepress preview docs --port 8080"
+ }
+ }
+ ```
+
+ Теперь метод `docs:preview` запустит сервер по адресу `http://localhost:8080`.
+
+## Установка публичного базового пути {#setting-a-public-base-path}
+
+По умолчанию предполагается, что сайт будет развёрнут по корневому пути домена (`/`). Если ваш сайт будет обслуживаться по подпути, например, `https://mywebsite.com/blog/`, то в конфигурации VitePress необходимо установить для опции [`base`](../reference/site-config#base) значение `'/blog/'`.
+
+**Пример:** Если вы используете Github (или GitLab) Pages и развёртываете на `user.github.io/repo/`, то установите `base` на `/repo/`.
+
+## Заголовки кэша HTTP {#http-cache-headers}
+
+Если вы контролируете HTTP-заголовки на своем рабочем сервере, вы можете настроить заголовки `cache-control` для достижения лучшей производительности при повторных посещениях.
+
+В производственной сборке используются хэшированные имена файлов для статических ресурсов (JavaScript, CSS и другие импортированные ресурсы, не находящиеся в `public`). Если вы просмотрите предварительную версию с помощью сетевой вкладки devtools вашего браузера, вы увидите файлы типа `app.4f283b18.js`.
+
+Этот хэш `4f283b18` генерируется из содержимого этого файла. Один и тот же хэшированный URL гарантированно обслуживает одно и то же содержимое файла — если содержимое меняется, то и URL тоже. Это означает, что вы можете смело использовать самые сильные заголовки кэша для этих файлов. Все такие файлы будут помещены в каталог `assets/` в выходном каталоге, поэтому вы можете настроить для них следующий заголовок:
+
+```
+Cache-Control: max-age=31536000,immutable
+```
+
+::: details Пример файла Netlify `_headers`
+
+```
+/assets/*
+ cache-control: max-age=31536000
+ cache-control: immutable
+```
+
+Примечание: файл `_headers` должен быть помещён в [директорию `public`](./asset-handling#the-public-directory) — в нашем случае `docs/public/_headers` — так, чтобы он был скопирован в выходной каталог.
+
+[Netlify custom headers documentation](https://docs.netlify.com/routing/headers/)
+
+:::
+
+::: details Пример конфигурации Vercel в файле `vercel.json`
+
+```json
+{
+ "headers": [
+ {
+ "source": "/assets/(.*)",
+ "headers": [
+ {
+ "key": "Cache-Control",
+ "value": "max-age=31536000, immutable"
+ }
+ ]
+ }
+ ]
+}
+```
+
+Примечание: Файл `vercel.json` должен быть помещен в корень вашего **репозитория**.
+
+[Документация Vercel по конфигурации заголовков](https://vercel.com/docs/concepts/projects/project-configuration#headers)
+
+:::
+
+## Руководства по платформам {#platform-guides}
+
+### Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render {#netlify-vercel-cloudflare-pages-aws-amplify-render}
+
+Создайте новый проект и измените эти настройки с помощью панели управления:
+
+- **Build Command:** `npm run docs:build`
+- **Output Directory:** `docs/.vitepress/dist`
+- **Node Version:** `18` (или выше)
+
+::: warning ПРЕДУПРЕЖДЕНИЕ
+Не включайте такие опции, как _Auto Minify_ для HTML-кода. Он удалит из вывода комментарии, которые имеют значение для Vue. При их удалении могут возникать ошибки несоответствия гидратации.
+:::
+
+### GitHub Pages {#github-pages}
+
+1. Создайте файл с именем `deploy.yml` в директории `.github/workflows` вашего проекта с примерно таким содержанием:
+
+ ```yaml
+ # Пример рабочего процесса для создания и развёртывания сайта VitePress на GitHub Pages
+ #
+ name: Deploy VitePress site to Pages
+
+ on:
+ # Выполняется при пушах, направленных в ветку `main`. Измените это значение на `master`, если вы
+ # используете ветку `master` в качестве ветки по умолчанию.
+ push:
+ branches: [main]
+
+ # Позволяет запустить этот рабочий процесс вручную на вкладке «Actions».
+ workflow_dispatch:
+
+ # Устанавливает разрешения GITHUB_TOKEN, чтобы разрешить развёртывание на страницах GitHub.
+ permissions:
+ contents: read
+ pages: write
+ id-token: write
+
+ # Разрешите только одно одновременное развёртывание, пропуская запуски, стоящие в очереди.
+ # Однако НЕ отменяйте текущие запуски, поскольку мы хотим дать возможность завершить производственные развёртывания.
+ concurrency:
+ group: pages
+ cancel-in-progress: false
+
+ jobs:
+ # Сборка
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+ with:
+ fetch-depth: 0 # Не требуется, если функция lastUpdated не включена
+ # - uses: pnpm/action-setup@v3 # Раскомментируйте, если вы используете pnpm
+ # - uses: oven-sh/setup-bun@v1 # Раскомментируйте, если вы используете Bun
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version: 20
+ cache: npm # или pnpm / yarn
+ - name: Setup Pages
+ uses: actions/configure-pages@v4
+ - name: Install dependencies
+ run: npm ci # или pnpm install / yarn install / bun install
+ - name: Build with VitePress
+ run: npm run docs:build # или pnpm docs:build / yarn docs:build / bun run docs:build
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v3
+ with:
+ path: docs/.vitepress/dist
+
+ # Развёртывание
+ deploy:
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ needs: build
+ runs-on: ubuntu-latest
+ name: Deploy
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4
+ ```
+
+ ::: warning ПРЕДУПРЕЖДЕНИЕ
+ Убедитесь, что опция `base` в вашем VitePress настроена правильно. Дополнительные сведения см. в секции [Установка публичного базового пути](#setting-a-public-base-path).
+ :::
+
+2. В настройках вашего репозитория в разделе «Pages» выберите пункт меню «GitHub Actions» в секции «Build and deployment > Source».
+
+3. Внесите свои изменения в ветку `main` и дождитесь завершения процесса GitHub Actions. Вы должны увидеть, что ваш сайт развёрнут по адресу `https://.github.io/[repository]/` или `https:///` в зависимости от ваших настроек. Ваш сайт будет автоматически разворачиваться при каждом внесении изменений в ветке `main`.
+
+### GitLab Pages {#gitlab-pages}
+
+1. Установите `outDir` в конфигурации VitePress на `../public`. Настройте опцию `base` на `'/<репозиторий>/'`, если вы хотите развернуть ваш проект по адресу на `https://<имя пользователя>.gitlab.io/<репозиторий>/`.
+
+2. Создайте файл с именем `.gitlab-ci.yml` в корне вашего проекта с приведённым ниже содержимым. Это позволит создавать и развёртывать ваш сайт каждый раз, когда вы вносите изменения в его содержимое:
+
+ ```yaml
+ image: node:18
+ pages:
+ cache:
+ paths:
+ - node_modules/
+ script:
+ # - apk add git # Отметьте это, если вы используете небольшие докер-образы, такие как alpine, и у вас включен lastUpdated
+ - npm install
+ - npm run docs:build
+ artifacts:
+ paths:
+ - public
+ only:
+ - main
+ ```
+
+### Статические веб-приложения Azure {#azure-static-web-apps}
+
+1. Следуйте [официальной документации](https://docs.microsoft.com/ru-ru/azure/static-web-apps/build-configuration).
+
+2. Установите эти значения в вашем конфигурационном файле (и удалите те, которые вам не нужны, например, `api_location`):
+
+ - **`app_location`**: `/`
+ - **`output_location`**: `docs/.vitepress/dist`
+ - **`app_build_command`**: `npm run docs:build`
+
+### Firebase {#firebase}
+
+1. Создайте `firebase.json` и `.firebaserc` в корне вашего проекта:
+
+ `firebase.json`:
+
+ ```json
+ {
+ "hosting": {
+ "public": "docs/.vitepress/dist",
+ "ignore": []
+ }
+ }
+ ```
+
+ `.firebaserc`:
+
+ ```json
+ {
+ "projects": {
+ "default": ""
+ }
+ }
+ ```
+
+2. После запуска `npm run docs:build` выполните эту команду для развёртывания:
+
+ ```sh
+ firebase deploy
+ ```
+
+### Surge {#surge}
+
+1. После запуска `npm run docs:build` выполните эту команду для развёртывания:
+
+ ```sh
+ npx surge docs/.vitepress/dist
+ ```
+
+### Heroku {#heroku}
+
+1. Следуйте документации и руководству, приведённому в [`heroku-buildpack-static`](https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-static).
+
+2. Создайте файл `static.json` в корне вашего проекта со следующим содержимым:
+
+ ```json
+ {
+ "root": "docs/.vitepress/dist"
+ }
+ ```
+
+### Edgio {#edgio}
+
+См. [Создание и развёртывание приложения VitePress в Edgio](https://docs.edg.io/applications/v6/sites_frameworks/getting_started/vitepress).
+
+### Хостинг статических файлов Kinsta {#kinsta-static-site-hosting}
+
+Вы можете развернуть свой сайт Vitepress на [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).
+
+### Nginx
+
+Вот пример конфигурации блока сервера Nginx. Эта настройка включает сжатие gzip для общих текстовых ресурсов, правила обслуживания статических файлов вашего сайта VitePress с правильными заголовками кэширования и обработку параметра `cleanUrls: true`.
+
+```nginx
+server {
+ gzip on;
+ gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
+
+ listen 80;
+ server_name _;
+ index index.html;
+
+ location / {
+ # расположение контента
+ root /app;
+
+ # точные совпадения -> обратные чистые URL-адреса -> папки -> не найдены
+ try_files $uri $uri.html $uri/ =404;
+
+ # несуществующие страницы
+ error_page 404 /404.html;
+
+ # папка без index.html вызывает ошибку 403 в этой настройке
+ error_page 403 /404.html;
+
+ # настройка заголовков кэширования
+ # файлы в папке с ресурсами имеют хэши имён файлов
+ location ~* ^/assets/ {
+ expires 1y;
+ add_header Cache-Control "public, immutable";
+ }
+ }
+}
+```
+
+Эта конфигурация предполагает, что ваш собранный сайт VitePress находится в директории `/app`. При необходимости измените директиву `root`, если файлы вашего сайта расположены в другом месте.
+
+::: warning Не используйте index.html по умолчанию
+Разрешение try_files не должно использовать index.html, как это делается в других приложениях Vue. Это может привести к недопустимому состоянию страницы.
+:::
+
+Дополнительную информацию можно найти в официальной документации [Nginx](https://nginx.org/ru/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).
diff --git a/docs/ru/guide/extending-default-theme.md b/docs/ru/guide/extending-default-theme.md
new file mode 100644
index 00000000..818f4399
--- /dev/null
+++ b/docs/ru/guide/extending-default-theme.md
@@ -0,0 +1,342 @@
+---
+outline: deep
+---
+
+# Расширение темы по умолчанию {#extending-the-default-theme}
+
+Тема VitePress по умолчанию оптимизирована для документации и может быть настроена по своему усмотрению. Полный список опций можно найти в главе [Настройки темы по умолчанию](../reference/default-theme-config).
+
+Однако есть ряд случаев, когда одной лишь конфигурации будет недостаточно. Например:
+
+1. Вам нужно изменить стили CSS;
+2. Вам нужно изменить экземпляр приложения Vue, например, чтобы зарегистрировать глобальные компоненты;
+3. Вам нужно внедрить пользовательский контент в тему через слоты макета.
+
+Эти расширенные настройки потребуют использования пользовательской темы, которая «расширяет» тема по умолчанию.
+
+::: tip СОВЕТ
+Прежде чем приступить к работе, обязательно прочитайте главу [Пользовательская тема](./custom-theme), чтобы понять, как работают пользовательские темы.
+:::
+
+## Настройка CSS {#customizing-css}
+
+CSS темы по умолчанию можно настроить, переопределив переменные CSS корневого уровня:
+
+```js
+// .vitepress/theme/index.js
+import DefaultTheme from 'vitepress/theme'
+import './custom.css'
+
+export default DefaultTheme
+```
+
+```css
+/* .vitepress/theme/custom.css */
+:root {
+ --vp-c-brand-1: #646cff;
+ --vp-c-brand-2: #747bff;
+}
+```
+
+См. [переменные CSS темы по умолчанию](https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css), которые можно переопределить.
+
+## Использование различных шрифтов {#using-different-fonts}
+
+VitePress использует [Inter](https://rsms.me/inter/) в качестве шрифта по умолчанию, и будет включать шрифты в вывод сборки. Шрифт также автоматически загружается в производство. Однако это может быть нежелательно, если вы хотите использовать другой основной шрифт.
+
+Чтобы не включать Inter в вывод сборки, импортируйте тему из `vitepress/theme-without-fonts`:
+
+```js
+// .vitepress/theme/index.js
+import DefaultTheme from 'vitepress/theme-without-fonts'
+import './my-fonts.css'
+
+export default DefaultTheme
+```
+
+```css
+/* .vitepress/theme/custom.css */
+:root {
+ --vp-font-family-base: /* normal text font */ --vp-font-family-mono:
+ /* code font */;
+}
+```
+
+::: warning ПРЕДУПРЕЖДЕНИЕ
+Если вы используете дополнительные компоненты, такие как [Страница команды](../reference/default-theme-team-page), убедитесь, что они также импортированы из `vitepress/theme-without-fonts`!
+:::
+
+Если ваш шрифт — это локальный файл, на который ссылаются через `@font-face`, он будет обработан как ресурс и включён в каталог `.vitepress/dist/assets` с хэшированным именем файла. Чтобы предварительно загрузить этот файл, используйте хук сборки [transformHead](../reference/site-config#transformhead):
+
+```js
+// .vitepress/config.js
+export default {
+ transformHead({ assets }) {
+ // настраиваем regex соответствующим образом, чтобы он соответствовал вашему шрифту
+ const myFontFile = assets.find((file) => /font-name\.\w+\.woff2/)
+ if (myFontFile) {
+ return [
+ [
+ 'link',
+ {
+ rel: 'preload',
+ href: myFontFile,
+ as: 'font',
+ type: 'font/woff2',
+ crossorigin: ''
+ }
+ ]
+ ]
+ }
+ }
+}
+```
+
+## Регистрация глобальных компонентов {#registering-global-components}
+
+```js
+// .vitepress/theme/index.js
+import DefaultTheme from 'vitepress/theme'
+
+/** @type {import('vitepress').Theme} */
+export default {
+ extends: DefaultTheme,
+ enhanceApp({ app }) {
+ // регистрируем пользовательские глобальные компоненты
+ app.component('MyGlobalComponent' /* ... */)
+ }
+}
+```
+
+Если вы используете TypeScript:
+
+```ts
+// .vitepress/theme/index.ts
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+
+export default {
+ extends: DefaultTheme,
+ enhanceApp({ app }) {
+ // регистрируем пользовательские глобальные компоненты
+ app.component('MyGlobalComponent' /* ... */)
+ }
+} satisfies Theme
+```
+
+Поскольку мы используем Vite, вы также можете использовать [глобальную функцию импорта](https://vitejs.dev/guide/features.html#glob-import) Vite для автоматической регистрации каталога компонентов.
+
+## Слоты макета {#layout-slots}
+
+Компонент `
+
+ Верхнее содержимое моей пользовательской боковой панели
+
+
+
+```
+
+Также можно использовать функцию рендеринга.
+
+```js
+// .vitepress/theme/index.js
+import { h } from 'vue'
+import DefaultTheme from 'vitepress/theme'
+import MyComponent from './MyComponent.vue'
+
+export default {
+ extends: DefaultTheme,
+ Layout() {
+ return h(DefaultTheme.Layout, null, {
+ 'aside-outline-before': () => h(MyComponent)
+ })
+ }
+}
+```
+
+Полный список слотов, доступных в макете темы по умолчанию:
+
+- Когда `layout: 'doc'` (по умолчанию) включен через метаданные:
+ - `doc-top`
+ - `doc-bottom`
+ - `doc-footer-before`
+ - `doc-before`
+ - `doc-after`
+ - `sidebar-nav-before`
+ - `sidebar-nav-after`
+ - `aside-top`
+ - `aside-bottom`
+ - `aside-outline-before`
+ - `aside-outline-after`
+ - `aside-ads-before`
+ - `aside-ads-after`
+- Когда `layout: 'home'` включен через метаданные:
+ - `home-hero-before`
+ - `home-hero-info-before`
+ - `home-hero-info`
+ - `home-hero-info-after`
+ - `home-hero-actions-after`
+ - `home-hero-image`
+ - `home-hero-after`
+ - `home-features-before`
+ - `home-features-after`
+- Когда `layout: 'page'` включен через метаданные:
+ - `page-top`
+ - `page-bottom`
+- На странице «Не найдено (404)»:
+ - `not-found`
+- Всегда:
+ - `layout-top`
+ - `layout-bottom`
+ - `nav-bar-title-before`
+ - `nav-bar-title-after`
+ - `nav-bar-content-before`
+ - `nav-bar-content-after`
+ - `nav-screen-content-before`
+ - `nav-screen-content-after`
+
+## Использование View Transitions API {#using-view-transitions-api}
+
+### Переключение внешнего вида {#on-appearance-toggle}
+
+Вы можете расширить стандартную тему, чтобы обеспечить пользовательский переход при переключении цветового режима. Пример:
+
+```vue
+
+
+
+
+
+ Демонстрация
+
+
+
+
+
+Более подробно о переходах между представлениями читайте в [документации Chrome](https://developer.chrome.com/docs/web-platform/view-transitions/).
+
+### Изменение маршрута {#on-route-change}
+
+Скоро будет.
+
+## Переопределение внутренних компонентов {#overriding-internal-components}
+
+Вы можете использовать [псевдонимы](https://vitejs.dev/config/shared-options.html#resolve-alias) Vite, чтобы заменить стандартные компоненты темы на свои собственные:
+
+```ts
+import { fileURLToPath, URL } from 'node:url'
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ vite: {
+ resolve: {
+ alias: [
+ {
+ find: /^.*\/VPNavBar\.vue$/,
+ replacement: fileURLToPath(
+ new URL('./components/CustomNavBar.vue', import.meta.url)
+ )
+ }
+ ]
+ }
+ }
+})
+```
+
+Чтобы узнать точное название компонента, обратитесь к [нашему исходному коду](https://github.com/vuejs/vitepress/tree/main/src/client/theme-default/components). Поскольку компоненты являются внутренними, есть небольшая вероятность того, что их название будет обновлено между минорными выпусками.
diff --git a/docs/ru/guide/frontmatter.md b/docs/ru/guide/frontmatter.md
new file mode 100644
index 00000000..967338f8
--- /dev/null
+++ b/docs/ru/guide/frontmatter.md
@@ -0,0 +1,48 @@
+# Метаданные {#frontmatter}
+
+## Использование {#usage}
+
+VitePress поддерживает метаданные YAML во всех Markdown-файлах, разбирая их с помощью [gray-matter](https://github.com/jonschlinkert/gray-matter). Метаданные должны находиться в верхней части Markdown-файла (перед любыми элементами, включая теги `
+
+
+ , или . Вам нужно настроить плагин PostCSS на использование `:where([dir="ltr"])` и `:where([dir="rtl"])` в качестве префиксов, чтобы избежать проблем со спецификой CSS.
diff --git a/docs/ru/guide/markdown.md b/docs/ru/guide/markdown.md
new file mode 100644
index 00000000..05eb4ad3
--- /dev/null
+++ b/docs/ru/guide/markdown.md
@@ -0,0 +1,933 @@
+# Расширения Markdown {#markdown-extensions}
+
+VitePress поставляется со встроенными расширениями Markdown.
+
+## Якоря заголовков {#header-anchors}
+
+К заголовкам автоматически применяются якорные ссылки. Отрисовку якорей можно настроить с помощью опции `markdown.anchor`.
+
+### Пользовательские якоря {#custom-anchors}
+
+Чтобы указать пользовательский тег якоря для заголовка, а не использовать автоматически сгенерированный, добавьте суффикс к заголовку:
+
+```
+# Использование пользовательских якорей {#мой-якорь}
+```
+
+Это позволит вам ссылаться на заголовок как `#мой-якорь` вместо стандартного `#использование-пользовательских-якорей`.
+
+## Ссылки {#links}
+
+Особое внимание уделяется как внутренним, так и внешним ссылкам.
+
+### Внутренние ссылки {#internal-links}
+
+Внутренние ссылки преобразуются в ссылки маршрутизатора для навигации SPA. Кроме того, каждый `index.md`, содержащийся в каждом подкаталоге, будет автоматически преобразован в `index.html`, с соответствующим URL `/`.
+
+Например, при следующей структуре каталогов:
+
+```
+.
+├─ index.md
+├─ foo
+│ ├─ index.md
+│ ├─ one.md
+│ └─ two.md
+└─ bar
+ ├─ index.md
+ ├─ three.md
+ └─ four.md
+```
+
+И при условии, что вы находитесь в `foo/one.md`:
+
+```md
+[Home](/)
+[foo](/foo/)
+[foo heading](./#heading)
+[bar - three](../bar/three)
+[bar - three](../bar/three.md)
+[bar - four](../bar/four.html)
+```
+
+### Суффикс страницы {#page-suffix}
+
+Страницы и внутренние ссылки по умолчанию генерируются с суффиксом `.html`.
+
+### Внешние ссылки {#external-links}
+
+Исходящие ссылки автоматически получают значение `target="_blank" rel="noreferrer"`:
+
+- [vuejs.org](https://vuejs.org)
+- [VitePress on GitHub](https://github.com/vuejs/vitepress)
+
+## Метаданные {#frontmatter}
+
+[Метаданные YAML](https://jekyllrb.com/docs/front-matter/) поддерживаются из коробки:
+
+```yaml
+---
+title: Веду блог как хакер
+lang: ru-RU
+---
+```
+
+Эти данные будут доступны остальной части страницы, а также всем пользовательским и тематическим компонентам.
+
+Более подробную информацию можно найти в главе [Метаданные](../reference/frontmatter-config).
+
+## Таблицы в стиле GitHub {#github-style-tables}
+
+**Разметка**
+
+```md
+| Таблицы | это | круто |
+| ---------------- | :----------------------: | ----: |
+| столбец 3 | выровнен по правому краю | $1600 |
+| столбец 2 | отцентрован | $12 |
+| полосатые строки | как полоски у зебры | $1 |
+```
+
+**Результат**
+
+| Таблицы | это | круто |
+| ---------------- | :----------------------: | -----: |
+| столбец 3 | выровнен по правому краю | \$1600 |
+| столбец 2 | отцентрован | \$12 |
+| полосатые строки | как полоски у зебры | \$1 |
+
+## Эмодзи :tada: {#emoji}
+
+**Разметка**
+
+```
+:tada: :100:
+```
+
+**Результат**
+
+:tada: :100:
+
+[Список всех эмодзи](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/full.mjs).
+
+## Оглавление {#table-of-contents}
+
+**Разметка**
+
+```
+[[toc]]
+```
+
+**Результат**
+
+[[toc]]
+
+Отрисовка TOC может быть настроена с помощью опции `markdown.toc`.
+
+## Пользовательские контейнеры {#custom-containers}
+
+Пользовательские контейнеры можно определить по их типам, заголовкам и содержимому.
+
+### Заголовок по умолчанию {#default-title}
+
+**Разметка**
+
+```md
+::: info
+Это информация.
+:::
+
+::: tip
+Это совет.
+:::
+
+::: warning
+Это предупреждение.
+:::
+
+::: danger
+Это сигнал об опасности.
+:::
+
+::: details
+Это блок-спойлер.
+:::
+```
+
+**Результат**
+
+::: info
+Это информация.
+:::
+
+::: tip
+Это совет.
+:::
+
+::: warning
+Это предупреждение.
+:::
+
+::: danger
+Это сигнал об опасности.
+:::
+
+::: details
+Это блок-спойлер.
+:::
+
+### Пользовательский заголовок {#custom-title}
+
+Вы можете задать собственный заголовок, добавив текст сразу после «типа» контейнера.
+
+**Разметка**
+
+````md
+::: danger СТОП
+Опасная зона, остановитесь
+:::
+
+::: details Нажмите на меня, чтобы просмотреть код
+
+```js
+console.log('Привет, VitePress!')
+```
+
+:::
+````
+
+**Результат**
+
+::: danger СТОП
+Опасная зона, остановитесь
+:::
+
+::: details Нажмите на меня, чтобы просмотреть код
+
+```js
+console.log('Привет, VitePress!')
+```
+
+:::
+
+Кроме того, вы можете установить пользовательские заголовки глобально, добавив следующее содержимое в конфигурацию сайта, полезное, если вы пишете не на английском языке:
+
+```ts
+// config.ts
+export default defineConfig({
+ // ...
+ markdown: {
+ container: {
+ tipLabel: 'СОВЕТ',
+ warningLabel: 'ПРЕДУПРЕЖДЕНИЕ',
+ dangerLabel: 'ОПАСНОСТЬ',
+ infoLabel: 'ИНФОРМАЦИЯ',
+ detailsLabel: 'Подробная информация'
+ }
+ }
+ // ...
+})
+```
+
+### `raw` {#raw}
+
+Это специальный контейнер, который можно использовать для предотвращения конфликтов стилей и маршрутизаторов с VitePress. Это особенно полезно при документировании библиотек компонентов. Вы также можете посмотреть [whyframe](https://whyframe.dev/docs/integrations/vitepress) для лучшей изоляции.
+
+**Syntax**
+
+```md
+::: raw
+Заворачивается в
+:::
+```
+
+Класс `vp-raw` можно использовать и непосредственно на элементах. Изоляция стиля в настоящее время осуществляется по желанию:
+
+- Установите `postcss` с помощью предпочитаемого менеджера пакетов:
+
+ ```sh
+ $ npm add -D postcss
+ ```
+
+- Создайте файл с именем `docs/postcss.config.mjs` и добавьте в него следующее:
+
+ ```js
+ import { postcssIsolateStyles } from 'vitepress'
+
+ export default {
+ plugins: [postcssIsolateStyles()]
+ }
+ ```
+
+ Он использует [`postcss-prefix-selector`](https://github.com/postcss/postcss-load-config) под капотом. Вы можете передать ему параметры следующим образом:
+
+ ```js
+ postcssIsolateStyles({
+ includeFiles: [/vp-doc\.css/] // по умолчанию /base\.css/
+ })
+ ```
+
+## Оповещения в стиле 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).
+
+```md
+> [!NOTE]
+> Выделяет информацию, на которую пользователи должны обратить внимание, даже при беглом просмотре.
+
+> [!TIP]
+> Дополнительная информация, которая поможет пользователю добиться большего успеха.
+
+> [!IMPORTANT]
+> Важнейшая информация, необходимая пользователям для достижения успеха.
+
+> [!WARNING]
+> Критический контент, требующий немедленного внимания пользователей из-за потенциальных рисков.
+
+> [!CAUTION]
+> Негативные потенциальные последствия того или иного действия.
+```
+
+> [!NOTE]
+> Выделяет информацию, на которую пользователи должны обратить внимание, даже при беглом просмотре.
+
+> [!TIP]
+> Дополнительная информация, которая поможет пользователю добиться большего успеха.
+
+> [!IMPORTANT]
+> Важнейшая информация, необходимая пользователям для достижения успеха.
+
+> [!WARNING]
+> Критический контент, требующий немедленного внимания пользователей из-за потенциальных рисков.
+
+> [!CAUTION]
+> Негативные потенциальные последствия того или иного действия.
+
+## Подсветка синтаксиса в блоках кода {#syntax-highlighting-in-code-blocks}
+
+VitePress использует [Shiki](https://github.com/shikijs/shiki) для выделения синтаксиса языка в блоках кода Markdown с помощью цветного текста. Shiki поддерживает широкий спектр языков программирования. Всё, что вам нужно сделать, это добавить правильный псевдоним языка к начальным значкам блока кода:
+
+**Разметка**
+
+````
+```js
+export default {
+ name: 'MyComponent',
+ // ...
+}
+```
+````
+
+````
+```html
+
+ -
+ {{ todo.text }}
+
+
+```
+````
+
+**Результат**
+
+```js
+export default {
+ name: 'MyComponent'
+ // ...
+}
+```
+
+```html
+
+ - {{ todo.text }}
+
+```
+
+[Список всех поддерживаемых языков](https://shiki.style/languages).
+
+Вы также можете настроить тему подсветки синтаксиса в конфигурации приложения. Более подробную информацию см. в секции [`markdown`](../reference/site-config#markdown).
+
+## Выделение строк в блоках кода {#line-highlighting-in-code-blocks}
+
+**Разметка**
+
+````
+```js{4}
+export default {
+ data () {
+ return {
+ msg: 'Подсвечено!'
+ }
+ }
+}
+```
+````
+
+**Результат**
+
+```js{4}
+export default {
+ data () {
+ return {
+ msg: 'Подсвечено!'
+ }
+ }
+}
+```
+
+Помимо одной строки, вы можете указать несколько отдельных строк, диапазонов или и то, и другое:
+
+– Диапазоны строк, например: `{5-8}`, `{3-10}`, `{10-17}`
+
+- Несколько одиночных строк, например: `{4,7,9}`
+- Диапазоны строк и отдельные строки, например: `{4,7-13,16,23-27,40}`
+
+**Разметка**
+
+````
+```js{1,4,6-8}
+export default { // Подсвечено
+ data () {
+ return {
+ msg: `Подсвечено!
+ Эта строка не выделена,
+ но эта и две следующих - да.`,
+ motd: 'VitePress - это потрясающе',
+ lorem: 'ipsum'
+ }
+ }
+}
+```
+````
+
+**Результат**
+
+```js{1,4,6-8}
+export default { // Подсвечено
+ data () {
+ return {
+ msg: `Подсвечено!
+ Эта строка не выделена,
+ но эта и две следующих - да.`,
+ motd: 'VitePress - это потрясающе',
+ lorem: 'ipsum',
+ }
+ }
+}
+```
+
+Кроме того, можно выделять непосредственно в строке, используя комментарий `// [!code highlight]`.
+
+**Разметка**
+
+````
+```js
+export default {
+ data () {
+ return {
+ msg: 'Подсвечено!' // [!!code highlight]
+ }
+ }
+}
+```
+````
+
+**Результат**
+
+```js
+export default {
+ data() {
+ return {
+ msg: 'Подсвечено!' // [!code highlight]
+ }
+ }
+}
+```
+
+## Фокус в блоках кода {#focus-in-code-blocks}
+
+Добавление комментария `// [!code focus]` к строке сфокусирует её и размоет остальные части кода.
+
+Кроме того, вы можете задать количество строк для фокусировки с помощью `// [!code focus:]`.
+
+**Разметка**
+
+````
+```js
+export default {
+ data () {
+ return {
+ msg: 'Фокус!' // [!!code focus]
+ }
+ }
+}
+```
+````
+
+**Результат**
+
+```js
+export default {
+ data() {
+ return {
+ msg: 'Фокус!' // [!code focus]
+ }
+ }
+}
+```
+
+## Подсветка различий в блоках кода {#colored-diffs-in-code-blocks}
+
+Добавление в строку комментариев `// [!code --]` или `// [!code ++]` создаст diff этой строки, сохраняя цвета блока кода.
+
+**Разметка**
+
+````
+```js
+export default {
+ data () {
+ return {
+ msg: 'Удалено' // [!!code --]
+ msg: 'Добавлено' // [!!code ++]
+ }
+ }
+}
+```
+````
+
+**Результат**
+
+```js
+export default {
+ data () {
+ return {
+ msg: 'Удалено' // [!code --]
+ msg: 'Добавлено' // [!code ++]
+ }
+ }
+}
+```
+
+## Ошибки и предупреждения в блоках кода {#errors-and-warnings-in-code-blocks}
+
+Добавление в строку комментариев `// [!code warning]` или `// [!code error]` окрасит её соответствующим образом.
+
+**Разметка**
+
+````
+```js
+export default {
+ data () {
+ return {
+ msg: 'Ошибка', // [!!code error]
+ msg: 'Предупреждение' // [!!code warning]
+ }
+ }
+}
+```
+````
+
+**Результат**
+
+```js
+export default {
+ data() {
+ return {
+ msg: 'Ошибка', // [!code error]
+ msg: 'Предупреждение' // [!code warning]
+ }
+ }
+}
+```
+
+## Номера строк {#line-numbers}
+
+Вы можете включить нумерацию строк для каждого блока кода в конфигурации:
+
+```js
+export default {
+ markdown: {
+ lineNumbers: true
+ }
+}
+```
+
+Более подробную информацию см. в секции [`markdown`](../reference/site-config#markdown).
+
+Вы можете добавить метки `:line-numbers` / `:no-line-numbers` в ваши ограждённые блоки кода, чтобы переопределить значение, установленное в конфиге.
+
+Вы также можете настроить номер начальной строки, добавив `=` после `:line-numbers`. Например, `:line-numbers=2` означает, что номера строк в блоках кода будут начинаться с `2`.
+
+**Разметка**
+
+````md
+```ts {1}
+// опция line-numbers по умолчанию отключена
+const line2 = 'Строка 2'
+const line3 = 'Строка 3'
+```
+
+```ts:line-numbers {1}
+// опция line-numbers включена
+const line2 = 'Строка 2'
+const line3 = 'Строка 3'
+```
+
+```ts:line-numbers=2 {1}
+// опция line-numbers включена, нумерация начинается с 2
+const line3 = 'Строка 3'
+const line4 = 'Строка 4'
+```
+````
+
+**Результат**
+
+```ts {1}
+// опция line-numbers по умолчанию отключена
+const line2 = 'Строка 2'
+const line3 = 'Строка 3'
+```
+
+```ts:line-numbers {1}
+// опция line-numbers включена
+const line2 = 'Строка 2'
+const line3 = 'Строка 3'
+```
+
+```ts:line-numbers=2 {1}
+// опция line-numbers включена, нумерация начинается с 2
+const line3 = 'Строка 3'
+const line4 = 'Строка 4'
+```
+
+## Импорт фрагментов кода {#import-code-snippets}
+
+Вы можете импортировать фрагменты кода из существующих файлов, используя следующий синтаксис:
+
+```md
+<<< @/filepath
+```
+
+[Выделение строк](#line-highlighting-in-code-blocks) тоже поддерживается:
+
+```md
+<<< @/filepath{highlightLines}
+```
+
+**Разметка**
+
+```md
+<<< @/snippets/snippet.js{2}
+```
+
+**Файл с кодом**
+
+<<< @/snippets/snippet.js
+
+**Результат**
+
+<<< @/snippets/snippet.js{2}
+
+::: tip СОВЕТ
+Значение `@` соответствует корню источника. По умолчанию это корень проекта VitePress, если не настроен `srcDir`. Альтернативно вы также можете импортировать из относительных путей:
+
+```md
+<<< ../snippets/snippet.js
+```
+
+:::
+
+Вы также можете использовать [регион VS Code](https://code.visualstudio.com/docs/editor/codebasics#_folding), чтобы включить только соответствующую часть файла кода. Имя пользовательского региона начинается с `#` после пути к файлу:
+
+**Разметка**
+
+```md
+<<< @/snippets/snippet-with-region.js#snippet{1}
+```
+
+**Файл с кодом**
+
+<<< @/snippets/snippet-with-region.js
+
+**Результат**
+
+<<< @/snippets/snippet-with-region.js#snippet{1}
+
+Вы также можете указать язык внутри фигурных скобок (`{}`) следующим образом:
+
+```md
+<<< @/snippets/snippet.cs{c#}
+
+
+
+<<< @/snippets/snippet.cs{1,2,4-6 c#}
+
+
+
+<<< @/snippets/snippet.cs{1,2,4-6 c#:line-numbers}
+```
+
+Это полезно, если исходный язык нельзя определить по расширению вашего файла.
+
+## Группы кодов {#code-groups}
+
+Вы можете сгруппировать несколько блоков кода следующим образом:
+
+**Разметка**
+
+````md
+::: code-group
+
+```js [config.js]
+/**
+ * @type {import('vitepress').UserConfig}
+ */
+const config = {
+ // ...
+}
+
+export default config
+```
+
+```ts [config.ts]
+import type { UserConfig } from 'vitepress'
+
+const config: UserConfig = {
+ // ...
+}
+
+export default config
+```
+
+:::
+````
+
+**Результат**
+
+::: code-group
+
+```js [config.js]
+/**
+ * @type {import('vitepress').UserConfig}
+ */
+const config = {
+ // ...
+}
+
+export default config
+```
+
+```ts [config.ts]
+import type { UserConfig } from 'vitepress'
+
+const config: UserConfig = {
+ // ...
+}
+
+export default config
+```
+
+:::
+
+Вы также можете [импортировать фрагменты](#import-code-snippets) в группы кода:
+
+**Разметка**
+
+```md
+::: code-group
+
+
+
+<<< @/snippets/snippet.js
+
+
+
+<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [фрагмент с регионом]
+
+:::
+```
+
+**Результат**
+
+::: code-group
+
+<<< @/snippets/snippet.js
+
+<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [фрагмент с регионом]
+
+:::
+
+## Включение файла Markdown {#markdown-file-inclusion}
+
+Вы можете включить файл Markdown в другой файл Markdown, даже вложенный.
+
+::: tip СОВЕТ
+Вы также можете добавить в префикс пути к Markdown символ `@`, он будет выступать в качестве корня источника. По умолчанию это корень проекта VitePress, если не настроена опция `srcDir`.
+:::
+
+Например, вы можете включить относительный файл Markdown следующим образом:
+
+**Разметка**
+
+```md
+# Документация
+
+## Основы
+
+
+```
+
+**Файл части** (`parts/basics.md`)
+
+```md
+Некоторые вещи для начала.
+
+### Конфигурация
+
+Может быть создана с помощью `.foorc.json`.
+```
+
+**Эквивалентный код**
+
+```md
+# Документация
+
+## Основы
+
+Некоторые вещи для начала.
+
+### Конфигурация
+
+Может быть создана с помощью `.foorc.json`.
+```
+
+Он также поддерживает выбор диапазона строк:
+
+**Разметка**
+
+```md
+# Документация
+
+## Основы
+
+
+```
+
+**Файл части** (`parts/basics.md`)
+
+```md
+Некоторые вещи для начала.
+
+### Конфигурация
+
+Может быть создана с помощью `.foorc.json`.
+```
+
+**Эквивалентный код**
+
+```md
+# Документация
+
+## Основы
+
+### Конфигурация
+
+Может быть создана с помощью `.foorc.json`.
+```
+
+Формат выбранного диапазона строк может быть следующим: `{3,}`, `{,10}`, `{1,10}`
+
+::: warning ПРЕДУПРЕЖДЕНИЕ
+Обратите внимание, что это не приводит к ошибкам, если ваш файл отсутствует. Поэтому при использовании этой функции убедитесь, что содержимое отображается так, как ожидается.
+:::
+
+## Математические уравнения {#math-equations}
+
+В настоящее время эта фича предоставляется по желанию. Чтобы включить её, вам нужно установить `markdown-it-mathjax3` и установить значение `true` для опции `markdown.math` в вашем файле конфигурации:
+
+```sh
+npm add -D markdown-it-mathjax3
+```
+
+```ts
+// .vitepress/config.ts
+export default {
+ markdown: {
+ math: true
+ }
+}
+```
+
+**Разметка**
+
+```md
+Когда $a \ne 0$, существует два решения $(ax^2 + bx + c = 0)$:
+$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
+
+**Уравнения Максвелла:**
+
+| уравнение | описание |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| $\nabla \cdot \vec{\mathbf{B}} = 0$ | дивергенция $\vec{\mathbf{B}}$ равна нулю |
+| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}$ | искривление $\vec{\mathbf{E}}$ пропорционально скорости изменения $\vec{\mathbf{B}}$ |
+| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _что?_ |
+```
+
+**Результат**
+
+Когда $a \ne 0$, существует два решения $(ax^2 + bx + c = 0)$:
+$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
+
+**Уравнения Максвелла:**
+
+| уравнение | описание |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| $\nabla \cdot \vec{\mathbf{B}} = 0$ | дивергенция $\vec{\mathbf{B}}$ равна нулю |
+| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}$ | искривление $\vec{\mathbf{E}}$ пропорционально скорости изменения $\vec{\mathbf{B}}$ |
+| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _что?_ |
+
+## Ленивая загрузка изображений {#image-lazy-loading}
+
+Вы можете включить ленивую загрузку для каждого изображения, добавленного через markdown, установив значение `true` для опции `lazyLoading` в вашем файле конфигурации:
+
+```js
+export default {
+ markdown: {
+ image: {
+ // ленивая загрузка изображений отключена по умолчанию
+ lazyLoading: true
+ }
+ }
+}
+```
+
+## Расширенная конфигурация {#advanced-configuration}
+
+VitePress использует [markdown-it](https://github.com/markdown-it/markdown-it) для отрисовки Markdown. Многие из вышеперечисленных расширений реализованы с помощью пользовательских плагинов. Вы можете дополнительно настроить экземпляр `markdown-it` с помощью опции `markdown` в файле `.vitepress/config.js`:
+
+```js
+import { defineConfig } from 'vitepress'
+import markdownItAnchor from 'markdown-it-anchor'
+import markdownItFoo from 'markdown-it-foo'
+
+export default defineConfig({
+ markdown: {
+ // опции для markdown-it-anchor
+ // https://github.com/valeriangalliat/markdown-it-anchor#usage
+ anchor: {
+ permalink: markdownItAnchor.permalink.headerLink()
+ },
+
+ // опции для @mdit-vue/plugin-toc
+ // https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
+ toc: { level: [1, 2] },
+
+ config: (md) => {
+ // используйте любые плагины для markdown-it!
+ md.use(markdownItFoo)
+ }
+ }
+})
+```
+
+Полный список настраиваемых свойств см. в секции [`markdown`](../reference/site-config#markdown).
diff --git a/docs/ru/guide/migration-from-vitepress-0.md b/docs/ru/guide/migration-from-vitepress-0.md
new file mode 100644
index 00000000..4d5c7426
--- /dev/null
+++ b/docs/ru/guide/migration-from-vitepress-0.md
@@ -0,0 +1,23 @@
+# Переход с VitePress 0.x
+
+Если вы переходите с версии VitePress 0.x, то в ней есть несколько изменений, связанных с новыми функциями и улучшениями. Следуйте этому руководству, чтобы узнать, как перенести ваше приложение на последнюю версию VitePress.
+
+## Конфигурация приложения
+
+- Функция интернационализации ещё не реализована.
+
+## Конфигурация темы
+
+- Опция `sidebar` изменила свою структуру.
+ - Ключ `children` теперь называется `items`.
+ - Элемент верхнего уровня может не содержать `link` в данный момент. Мы планируем вернуть его обратно.
+- `repo`, `repoLabel`, `docsDir`, `docsBranch`, `editLinks`, `editLinkText` удалены в пользу более гибкого api.
+ - Для добавления ссылки GitHub с иконкой в навигацию используйте функцию [Социальные ссылки](../reference/default-theme-nav#navigation-links).
+ - Для добавления ссылки «Редактировать эту страницу» используйте функцию [Ссылка для редактирования](../reference/default-theme-edit-link).
+- Опция `lastUpdated` теперь разделена на `config.lastUpdated` и `themeConfig.lastUpdatedText`.
+- Опция `carbonAds.carbon` заменена на `carbonAds.code`.
+
+## Конфигурация метаданных
+
+- Опция `home: true` заменена на `layout: home`. Кроме того, многие настройки, связанные с главной страницей, были изменены для обеспечения дополнительных возможностей. Подробности см. в разделе [Главная страница](../reference/default-theme-home-page).
+- Опция `footer` перенесена в [`themeConfig.footer`](../reference/default-theme-config#footer).
diff --git a/docs/ru/guide/migration-from-vuepress.md b/docs/ru/guide/migration-from-vuepress.md
new file mode 100644
index 00000000..afacc630
--- /dev/null
+++ b/docs/ru/guide/migration-from-vuepress.md
@@ -0,0 +1,30 @@
+# Переход с VuePress
+
+## Конфигурация
+
+### Сайдбар
+
+Боковая панель больше не заполняется автоматически из метаданных. Вы можете [самостоятельно прочитать вступление](https://github.com/vuejs/vitepress/issues/572#issuecomment-1170116225), чтобы научиться динамически заполнять боковую панель. [Дополнительные утилиты для этого](https://github.com/vuejs/vitepress/issues/96) могут быть предоставлены в будущем.
+
+## Markdown
+
+### Изображения
+
+В отличие от VuePress, VitePress автоматически обрабатывает опцию [`base`](./asset-handling#base-url) вашего конфига, когда вы используете статическое изображение.
+
+Таким образом, теперь вы можете выводить изображения без тега `img`.
+
+```diff
+- ![foo]()
++ 
+```
+
+::: warning ПРЕДУПРЕЖДЕНИЕ
+Для динамических изображений вам всё ещё нужно использовать `withBase`, как показано в [Руководстве по базовому URL](./asset-handling#base-url).
+:::
+
+Используйте регулярное выражение `` для поиска всех изображений с синтаксисом `` и замены на ``.
+
+---
+
+продолжение следует...
diff --git a/docs/ru/guide/mpa-mode.md b/docs/ru/guide/mpa-mode.md
new file mode 100644
index 00000000..81843708
--- /dev/null
+++ b/docs/ru/guide/mpa-mode.md
@@ -0,0 +1,23 @@
+# Режим MPA ` присутствовали в вашем файле `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). Пример:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ sitemap: {
+ hostname: 'https://example.com',
+ lastmodDateOnly: false
+ }
+})
+```
+
+## Хук `transformItems` {#transformitems-hook}
+
+Вы можете использовать хук `sitemap.transformItems` для изменения элементов карты сайта перед их записью в файл `sitemap.xml`. Этот хук вызывается с массивом элементов sitemap и ожидает возвращения массива элементов sitemap. Пример:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ sitemap: {
+ hostname: 'https://example.com',
+ transformItems: (items) => {
+ // добавляем новые элементы или изменяем/фильтруем существующие
+ items.push({
+ url: '/extra-page',
+ changefreq: 'monthly',
+ priority: 0.8
+ })
+ return items
+ }
+ }
+})
+```
diff --git a/docs/ru/guide/ssr-compat.md b/docs/ru/guide/ssr-compat.md
new file mode 100644
index 00000000..fd8c6ae8
--- /dev/null
+++ b/docs/ru/guide/ssr-compat.md
@@ -0,0 +1,137 @@
+---
+outline: deep
+---
+
+# Совместимость с SSR {#ssr-compatibility}
+
+VitePress предварительно рендерит приложение в Node.js во время производственной сборки, используя возможности Vue по рендерингу на стороне сервера (SSR). Это означает, что весь пользовательский код в компонентах темы подлежит проверке на совместимость с SSR.
+
+Глава [Рендеринг на стороне сервера](https://ru.vuejs.org/guide/scaling-up/ssr.html) в документации Vue содержит более подробную информацию о том, что такое SSR, взаимосвязь между SSR и SSG, а также общие указания по написанию кода, дружественного к SSR. Правило заключается в том, чтобы обращаться к API браузера / DOM только в хуках `beforeMount` или `mounted` компонентов Vue.
+
+## `` {#clientonly}
+
+Если вы используете или демонстрируете компоненты, которые не являются SSR-дружественными (например, содержат пользовательские директивы), вы можете обернуть их внутри встроенного компонента ``:
+
+```md
+
+
+```
+
+## Библиотеки, обращающиеся к API браузера при импорте {#libraries-that-access-browser-api-on-import}
+
+Некоторые компоненты или библиотеки получают доступ к API браузера **при импорте**. Чтобы использовать код, предполагающий наличие среды браузера при импорте, необходимо динамически импортировать их.
+
+### Импорт в хуке `onMounted` {#importing-in-mounted-hook}
+
+```vue
+
+```
+
+### Условный импорт {#conditional-import}
+
+Вы также можете условно импортировать зависимость с помощью флага `import.meta.env.SSR` (часть [env-переменных Vite](https://vitejs.dev/guide/env-and-mode.html#env-variables)):
+
+```js
+if (!import.meta.env.SSR) {
+ import('./lib-that-access-window-on-import').then((module) => {
+ // используем код
+ })
+}
+```
+
+Поскольку [`Theme.enhanceApp`](./custom-theme#theme-interface) может быть асинхронным, вы можете условно импортировать и регистрировать плагины Vue, которые получают доступ к API браузера при импорте:
+
+```js
+// .vitepress/theme/index.js
+/** @type {import('vitepress').Theme} */
+export default {
+ // ...
+ async enhanceApp({ app }) {
+ if (!import.meta.env.SSR) {
+ const plugin = await import('plugin-that-access-window-on-import')
+ app.use(plugin.default)
+ }
+ }
+}
+```
+
+Если вы используете TypeScript:
+
+```ts
+// .vitepress/theme/index.ts
+import type { Theme } from 'vitepress'
+
+export default {
+ // ...
+ async enhanceApp({ app }) {
+ if (!import.meta.env.SSR) {
+ const plugin = await import('plugin-that-access-window-on-import')
+ app.use(plugin.default)
+ }
+ }
+} satisfies Theme
+```
+
+### `defineClientComponent` {#defineclientcomponent}
+
+VitePress предоставляет удобный помощник для импорта компонентов Vue, которые получают доступ к API браузера при импорте.
+
+```vue
+
+
+
+ ` или внедрить разметку телепортации в нужное место HTML конечной страницы через [хук `postRender`](../reference/site-config#postrender).
+
+
+
+
+ // ...
+
+
+
+```
+
+
+
+
diff --git a/docs/ru/guide/what-is-vitepress.md b/docs/ru/guide/what-is-vitepress.md
new file mode 100644
index 00000000..1bcc3e18
--- /dev/null
+++ b/docs/ru/guide/what-is-vitepress.md
@@ -0,0 +1,57 @@
+# Что такое VitePress? {#what-is-vitepress}
+
+VitePress — это [Генератор статических сайтов](https://en.wikipedia.org/wiki/Static_site_generator) (ГСС), предназначенный для быстрого создания сайтов, ориентированных на контент. В двух словах, VitePress берёт ваш исходный контент, написанный в [Markdown](https://ru.wikipedia.org/wiki/Markdown), применяет к нему тему и генерирует статические HTML-страницы, которые можно легко развернуть в любом месте.
+
+
+
+Хотите попробовать прямо сейчас? Перейдите к главе [Первые шаги](./getting-started).
+
+
+
+## Примеры использования {#use-cases}
+
+- **Документация**
+
+ 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, но использует пользовательскую тему, разделяемую между несколькими переводами.
+
+- **Блоги, портфолио и маркетинговые сайты**
+
+ VitePress поддерживает [полностью кастомизированные темы](./custom-theme), при этом разработчики могут использовать стандартное приложение Vite + Vue. То, что он построен на базе Vite, также означает, что вы можете напрямую использовать плагины Vite из его богатой экосистемы. Кроме того, VitePress предоставляет гибкие API для [загрузки данных](./data-loading) (локальной или удаленной) и [динамической генерации маршрутов](./routing#dynamic-routes). С его помощью можно построить практически всё, что угодно, если данные могут быть определены во время сборки.
+
+ Официальный [блог Vue.js](https://blog.vuejs.org/) — это простой блог, который генерирует свою индексную страницу на основе локального контента.
+
+## Опыт разработчика {#developer-experience}
+
+VitePress стремится обеспечить отличные возможности для разработчиков при работе с содержимым в формате Markdown.
+
+- **[На базе Vite:](https://vitejs.dev/)** мгновенный запуск сервера, правки всегда отражаются мгновенно (<100 мс) без перезагрузки страницы.
+
+- **[Встроенные расширения Markdown:](./markdown)** Frontmatter, таблицы, подсветка синтаксиса... называйте как хотите. В частности, VitePress предоставляет множество расширенных возможностей для работы с блоками кода, что делает его идеальным для создания технической документации.
+
+- **[Markdown с возможностями Vue:](./using-vue)** каждая Markdown-страница также является [однофайловым компонентом](https://ru.vuejs.org/guide/scaling-up/sfc.html) Vue, благодаря 100% синтаксической совместимости шаблона Vue с HTML. Вы можете внедрить интерактивность в статический контент, используя шаблонизаторы Vue или импортированные компоненты Vue.
+
+## Производительность {#performance}
+
+В отличие от многих традиционных ГСС, где каждая навигация приводит к полной перезагрузке страницы, сайт, созданный VitePress, обслуживает статический HTML при первом посещении, но становится [Одностраничным приложением](https://ru.wikipedia.org/wiki/%D0%9E%D0%B4%D0%BD%D0%BE%D1%81%D1%82%D1%80%D0%B0%D0%BD%D0%B8%D1%87%D0%BD%D0%BE%D0%B5_%D0%BF%D1%80%D0%B8%D0%BB%D0%BE%D0%B6%D0%B5%D0%BD%D0%B8%D0%B5) (SPA) для последующей навигации по сайту. Эта модель, на наш взгляд, обеспечивает оптимальный баланс производительности:
+
+- **Быстрая начальная загрузка**
+
+ При первом посещении любой страницы будет использоваться статичный, предварительно отрендеренный HTML для быстрой загрузки и оптимального SEO. Затем на страницу загружается пакет JavaScript, который превращает страницу в Vue SPA («гидратация»). Вопреки распространённому мнению о медленной гидратации SPA, этот процесс на самом деле чрезвычайно быстр благодаря высокой производительности Vue 3 и оптимизациям компилятора. По данным [PageSpeed Insights](https://pagespeed.web.dev/report?url=https%3A%2F%2Fvitepress.dev%2F), типичные сайты VitePress достигают почти идеальных показателей производительности даже на мобильных устройствах с низкой скоростью передачи данных.
+
+- **Быстрая навигация после загрузки**
+
+ Что ещё более важно, модель SPA приводит к улучшению пользовательского опыта **после** первоначальной загрузки. Последующая навигация по сайту больше не будет приводить к полной перезагрузке страницы. Вместо этого содержимое входящей страницы будет получено и динамически обновлено. VitePress также автоматически выполняет предварительную выборку фрагментов страницы для ссылок, которые находятся в пределах области просмотра. В большинстве случаев навигация после загрузки будет ощущаться мгновенно.
+
+- **Интерактивность без штрафов**
+
+ Для того чтобы динамические части Vue, встроенные в статический Markdown, могли работать в режиме гидратации, каждая страница Markdown обрабатывается как компонент Vue и компилируется в JavaScript. Это может показаться неэффективным, но компилятор Vue достаточно умён, чтобы разделить статическую и динамическую части, минимизируя как стоимость гидратации, так и размер полезной нагрузки. При первоначальной загрузке страницы статические части автоматически исключаются из полезной нагрузки JavaScript и пропускаются во время гидратации.
+
+## Что насчёт VuePress? {#what-about-vuepress}
+
+VitePress — это духовный наследник VuePress. Оригинальный VuePress был основан на Vue 2 и webpack. Благодаря Vue 3 и Vite под капотом, VitePress обеспечивает значительно лучший опыт разработки, лучшую производительность, более отточенную тему по умолчанию и более гибкий API для настройки.
+
+Разница в API между VitePress и VuePress заключается в основном в тематическом оформлении и настройке. Если вы используете VuePress 1 с темой по умолчанию, то переход на VitePress будет относительно простым.
+
+Также были приложены усилия для создания VuePress 2, который также поддерживает Vue 3 и Vite с большей совместимостью с VuePress 1. Однако поддерживать два генератора параллельно не представляется возможным, поэтому команда Vue решила сосредоточиться на VitePress как основном рекомендуемом генераторе статических сайтов в долгосрочной перспективе.
diff --git a/docs/ru/index.md b/docs/ru/index.md
new file mode 100644
index 00000000..5d2e52e5
--- /dev/null
+++ b/docs/ru/index.md
@@ -0,0 +1,60 @@
+---
+layout: home
+
+title: VitePress
+titleTemplate: Генератор статических сайтов на основе Vite и Vue
+
+hero:
+ name: VitePress
+ text: Генератор статических сайтов на основе Vite и Vue
+ tagline: Из Markdown в красивую документацию за считанные минуты
+ actions:
+ - theme: brand
+ text: Что такое VitePress?
+ link: /ru/guide/what-is-vitepress
+ - theme: alt
+ text: Первые шаги
+ link: /ru/guide/getting-started
+ - theme: alt
+ text: GitHub
+ link: https://github.com/vuejs/vitepress
+ image:
+ src: /vitepress-logo-large.webp
+ alt: VitePress
+
+features:
+ - icon: 📝
+ title: Сосредоточьтесь на своем контенте
+ details: Легко создавайте красивые сайты с документацией, используя только Markdown.
+ - icon:
+ title: Наслаждайтесь опытом разработчиков Vite
+ details: Мгновенный запуск сервера, молниеносные горячие обновления и использование плагинов экосистемы Vite.
+ - icon:
+ title: Настройка с помощью Vue
+ details: Используйте синтаксис Vue и компоненты прямо в Markdown или создавайте собственные темы с помощью Vue.
+ - icon: 🚀
+ title: Быстрый запуск веб-сайтов
+ details: Быстрая начальная загрузка с помощью статического HTML, быстрая навигация после загрузки с помощью маршрутизации на стороне клиента.
+---
+
+
diff --git a/docs/ru/reference/cli.md b/docs/ru/reference/cli.md
new file mode 100644
index 00000000..93954da2
--- /dev/null
+++ b/docs/ru/reference/cli.md
@@ -0,0 +1,74 @@
+# Интерфейс командной строки {#command-line-interface}
+
+## `vitepress dev` {#vitepress-dev}
+
+Запуск сервера разработки VitePress, с использованием указанного каталога в качестве корневого. По умолчанию используется текущий каталог. Команду `dev` также можно опустить при работе в текущем каталоге.
+
+### Использование {#usage}
+
+```sh
+# запуск в текущем каталоге, опускаем `dev`
+vitepress
+
+# запуск в подкаталоге
+vitepress dev [root]
+```
+
+### Параметры {#options}
+
+| Параметр | Описание |
+| --------------- | ------------------------------------------------------------------------------ |
+| `--open [path]` | Открытие браузера при запуске (`boolean \| string`) |
+| `--port ` | Номер порта (`number`) |
+| `--base ` | Публичный базовый путь (по умолчанию: `/`) (`string`) |
+| `--cors` | Включить CORS |
+| `--strictPort` | Выйти, если указанный порт уже используется (`boolean`) |
+| `--force` | Заставить оптимизатор игнорировать кэш и повторно объединять файлы (`boolean`) |
+
+## `vitepress build` {#vitepress-build}
+
+Создание производственной сборки текущего сайта VitePress.
+
+### Использование {#usage-1}
+
+```sh
+vitepress build [root]
+```
+
+### Параметры {#options-1}
+
+| Параметр | Описание |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `--mpa` (экспериментально) | Сборка в режиме [MPA](../guide/mpa-mode) без гидратации на стороне клиента (`boolean`) |
+| `--base ` | Публичный базовый путь (по умолчанию: `/`) (`string`) |
+| `--target ` | Транспилировать цель (по умолчанию: `"modules"`) (`string`) |
+| `--outDir ` | Выходной каталог относительно **cwd** (по умолчанию: `/.vitepress/dist`) (`string`) |
+| `--minify [minifier]` | Включить/выключить минификацию или задать используемый минификатор (по умолчанию: `"esbuild"`) (`boolean \| "terser" \| "esbuild"`) |
+| `--assetsInlineLimit ` | Статический встроенный порог ресурса base64 в байтах (по умолчанию: `4096`) (`number`) |
+
+## `vitepress preview` {#vitepress-preview}
+
+Локальный предварительный просмотр производственной сборки.
+
+### Использование {#usage-2}
+
+```sh
+vitepress preview [root]
+```
+
+### Параметры {#options-2}
+
+| Параметр | Описание |
+| --------------- | ----------------------------------------------------- |
+| `--base ` | Публичный базовый путь (по умолчанию: `/`) (`string`) |
+| `--port ` | Номер порта (`number`) |
+
+## `vitepress init` {#vitepress-init}
+
+Запуск [Мастера настройки](../guide/getting-started#setup-wizard) в текущем каталоге.
+
+### Использование {#usage-3}
+
+```sh
+vitepress init
+```
diff --git a/docs/ru/reference/default-theme-badge.md b/docs/ru/reference/default-theme-badge.md
new file mode 100644
index 00000000..fc546436
--- /dev/null
+++ b/docs/ru/reference/default-theme-badge.md
@@ -0,0 +1,72 @@
+# Значки {#badge}
+
+С помощью значков удобно добавлять статус к заголовкам. Например, может быть полезно указать тип раздела или поддерживаемую версию.
+
+## Использование {#usage}
+
+Вы можете использовать компонент `Badge`, который доступен глобально.
+
+```html
+### Заголовок ` принимает параметр `children`, который будет отображаться внутри значка.
+
+```html
+### Заголовок вложенный элемент
+```
+
+### Заголовок вложенный элемент
+
+## Настройка стиля значков {#customize-type-color}
+
+Вы можете настроить стиль значков, переопределив переменные CSS. Ниже приведены значения по умолчанию:
+
+```css
+:root {
+ --vp-badge-info-border: transparent;
+ --vp-badge-info-text: var(--vp-c-text-2);
+ --vp-badge-info-bg: var(--vp-c-default-soft);
+
+ --vp-badge-tip-border: transparent;
+ --vp-badge-tip-text: var(--vp-c-brand-1);
+ --vp-badge-tip-bg: var(--vp-c-brand-soft);
+
+ --vp-badge-warning-border: transparent;
+ --vp-badge-warning-text: var(--vp-c-warning-1);
+ --vp-badge-warning-bg: var(--vp-c-warning-soft);
+
+ --vp-badge-danger-border: transparent;
+ --vp-badge-danger-text: var(--vp-c-danger-1);
+ --vp-badge-danger-bg: var(--vp-c-danger-soft);
+}
+```
+
+## `` {#badge-1}
+
+Компонент `` принимает следующие параметры:
+
+```ts
+interface Props {
+ // Когда передается ``, это значение игнорируется.
+ text?: string
+
+ // По умолчанию: `tip`.
+ type?: 'info' | 'tip' | 'warning' | 'danger'
+}
+```
diff --git a/docs/ru/reference/default-theme-carbon-ads.md b/docs/ru/reference/default-theme-carbon-ads.md
new file mode 100644
index 00000000..457b92b1
--- /dev/null
+++ b/docs/ru/reference/default-theme-carbon-ads.md
@@ -0,0 +1,22 @@
+# Carbon Ads {#carbon-ads}
+
+В VitePress встроена встроенная поддержка [Carbon Ads](https://www.carbonads.net/). Определив в конфиге учётные данные Carbon Ads, VitePress будет отображать рекламу на странице.
+
+```js
+export default {
+ themeConfig: {
+ carbonAds: {
+ code: 'код-рекламы',
+ placement: 'место-размещения-рекламы'
+ }
+ }
+}
+```
+
+Эти значения используются для вызова сценария carbon CDN, как показано ниже:
+
+```js
+;`//cdn.carbonads.com/carbon.js?serve=${code}&placement=${placement}`
+```
+
+Чтобы узнать больше о конфигурации Carbon Ads, посетите [веб-сайт Carbon Ads](https://www.carbonads.net/).
diff --git a/docs/ru/reference/default-theme-config.md b/docs/ru/reference/default-theme-config.md
new file mode 100644
index 00000000..265d17f1
--- /dev/null
+++ b/docs/ru/reference/default-theme-config.md
@@ -0,0 +1,452 @@
+# Настройка темы по умолчанию {#default-theme-config}
+
+Конфигурация темы позволяет настроить её под себя. Вы можете настроить тему с помощью опции `themeConfig` в файле конфигурации:
+
+```ts
+export default {
+ lang: 'ru-RU',
+ title: 'VitePress',
+ description: 'Генератор статического сайта на базе Vite и Vue.',
+
+ // Конфигурации, связанные с темой.
+ themeConfig: {
+ logo: '/logo.svg',
+ nav: [...],
+ sidebar: { ... }
+ }
+}
+```
+
+**Параметры, описанные на этой странице, применимы только к теме по умолчанию.** Разные темы предполагают разные конфигурации темы. При использовании пользовательской темы объект конфигурации темы будет передан теме, чтобы она могла определить условное поведение на его основе.
+
+## i18nRouting {#i18nrouting}
+
+- Тип: `boolean`
+
+При смене локали на `ru` URL изменится с `/foo` (или `/en/foo/`) на `/ru/foo`. Вы можете отключить это поведение, установив для параметра `themeConfig.i18nRouting` значение `false`.
+
+## logo {#logo}
+
+- Тип: `ThemeableImage`
+
+Файл логотипа для отображения в навигационной панели, прямо перед заголовком сайта. Принимает строку пути или объект, чтобы установить другой логотип для светлого/тёмного режима.
+
+```ts
+export default {
+ themeConfig: {
+ logo: '/logo.svg'
+ }
+}
+```
+
+```ts
+type ThemeableImage =
+ | string
+ | { src: string; alt?: string }
+ | { light: string; dark: string; alt?: string }
+```
+
+## siteTitle {#sitetitle}
+
+- Тип: `string | false`
+
+Вы можете настроить этот элемент для замены стандартного заголовка сайта (`title` в конфигурации приложения) в nav. При установке значения `false` заголовок в панели навигации будет отключен. Пригодится, если у вас есть `logo`, который уже содержит текст названия сайта.
+
+```ts
+export default {
+ themeConfig: {
+ siteTitle: 'Привет, мир'
+ }
+}
+```
+
+## nav {#nav}
+
+- Тип: `NavItem`
+
+Конфигурация для пункта навигационного меню. Подробнее в главе [Тема по умолчанию: Навигация](./default-theme-nav#navigation-links).
+
+```ts
+export default {
+ themeConfig: {
+ nav: [
+ { text: 'Руководство', link: '/guide' },
+ {
+ text: 'Выпадающее меню',
+ items: [
+ { text: 'Пункт A', link: '/item-1' },
+ { text: 'Пункт B', link: '/item-2' },
+ { text: 'Пункт C', link: '/item-3' }
+ ]
+ }
+ ]
+ }
+}
+```
+
+```ts
+type NavItem = NavItemWithLink | NavItemWithChildren
+
+interface NavItemWithLink {
+ text: string
+ link: string
+ activeMatch?: string
+ target?: string
+ rel?: string
+ noIcon?: boolean
+}
+
+interface NavItemChildren {
+ text?: string
+ items: NavItemWithLink[]
+}
+
+interface NavItemWithChildren {
+ text?: string
+ items: (NavItemChildren | NavItemWithLink)[]
+ activeMatch?: string
+}
+```
+
+## sidebar {#sidebar}
+
+- Тип: `Sidebar`
+
+Конфигурация для пунктов меню боковой панели. Подробнее в главе [Тема по умолчанию: Сайдбар](./default-theme-sidebar).
+
+```ts
+export default {
+ themeConfig: {
+ sidebar: [
+ {
+ text: 'Руководство',
+ items: [
+ { text: 'Введение', link: '/introduction' },
+ { text: 'Первые шаги', link: '/getting-started' },
+ ...
+ ]
+ }
+ ]
+ }
+}
+```
+
+```ts
+export type Sidebar = SidebarItem[] | SidebarMulti
+
+export interface SidebarMulti {
+ [path: string]: SidebarItem[]
+}
+
+export type SidebarItem = {
+ /**
+ * Текстовая метка элемента
+ */
+ text?: string
+
+ /**
+ * Ссылка на элемент
+ */
+ link?: string
+
+ /**
+ * Потомки элемента
+ */
+ items?: SidebarItem[]
+
+ /**
+ * Если не указано, группа не будет сворачиваться
+ *
+ * Если `true`, то группа будет сворачиваться и разворачиваться по умолчанию
+ *
+ * Если `false`, группа сворачивается, но по умолчанию разворачивается
+ */
+ collapsed?: boolean
+}
+```
+
+## aside {#aside}
+
+- Тип: `boolean | 'left'`
+- По умолчанию: `true`
+- Можно переопределить для каждой страницы с помощью [метаданных](./frontmatter-config#aside)
+
+Установка этого значения в `false` предотвращает отрисовку контейнера сайдбара.\
+Установка этого значения в `true` приведёт к отображению сайдбара справа.\
+Установка этого значения в `left` приведёт к отображению сайдбара слева.
+
+Если вы хотите отключить его для всех режимов просмотра, используйте `aside: false`.
+
+## outline {#outline}
+
+- Тип: `Outline | Outline['level'] | false`
+- Уровень можно переопределить для каждой страницы с помощью [метаданных](./frontmatter-config#outline)
+
+Установка этого значения в `false` предотвращает отрисовку оглавления. Для получения более подробной информации обратитесь к этому интерфейсу:
+
+```ts
+interface Outline {
+ /**
+ * Уровни заголовков, которые будут отображаться в оглавлении.
+ * Одиночное число означает, что будут отображаться только заголовки этого уровня.
+ * Если передается кортеж, то первое число — это минимальный уровень, а второе — максимальный.
+ * `'deep'` то же самое, что `[2, 6]`, что означает, что будут отображены все заголовки от `` до ``.
+ *
+ * @default 2
+ */
+ level?: number | [number, number] | 'deep'
+
+ /**
+ * Заголовок, который будет отображаться в оглавлении.
+ *
+ * @default 'На этой странице'
+ */
+ label?: string
+}
+```
+
+## socialLinks {#sociallinks}
+
+- Тип: `SocialLink[]`
+
+Вы можете задать эту опцию, чтобы показывать ссылки на ваши социальные аккаунты с помощью иконок в панели навигации.
+
+```ts
+export default {
+ themeConfig: {
+ socialLinks: [
+ { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
+ { icon: 'twitter', link: '...' },
+ // Вы также можете добавить пользовательские иконки, передав SVG в виде строки:
+ {
+ icon: {
+ svg: ''
+ },
+ link: '...',
+ // Вы также можете включить пользовательский ярлык для доступности (необязательно, но рекомендуется):
+ ariaLabel: 'классная ссылка'
+ }
+ ]
+ }
+}
+```
+
+```ts
+interface SocialLink {
+ icon: SocialLinkIcon
+ link: string
+ ariaLabel?: string
+}
+
+type SocialLinkIcon =
+ | 'discord'
+ | 'facebook'
+ | 'github'
+ | 'instagram'
+ | 'linkedin'
+ | 'mastodon'
+ | 'npm'
+ | 'slack'
+ | 'twitter'
+ | 'x'
+ | 'youtube'
+ | { svg: string }
+```
+
+## footer {#footer}
+
+- Тип: `Footer`
+- Можно переопределить для каждой страницы с помощью [метаданных](./frontmatter-config#footer)
+
+Настройка подвала. Вы можете разместить в подвале сообщение или текст об авторских правах, однако он будет отображаться только в том случае, если страница не содержит боковой панели. Это объясняется соображениями дизайна.
+
+```ts
+export default {
+ themeConfig: {
+ footer: {
+ message: 'Опубликовано под лицензией MIT.',
+ copyright: '© 2019 – настоящее время, Эван Ю'
+ }
+ }
+}
+```
+
+```ts
+export interface Footer {
+ message?: string
+ copyright?: string
+}
+```
+
+## editLink {#editlink}
+
+- Тип: `EditLink`
+- Можно переопределить для каждой страницы с помощью [метаданных](./frontmatter-config#editlink)
+
+Ссылка для редактирования позволяет отобразить ссылку для редактирования страницы на сервисах управления Git, таких как GitHub или GitLab. См. секцию [Тема по умолчанию: Ссылка для редактирования](./default-theme-edit-link) для получения более подробной информации.
+
+```ts
+export default {
+ themeConfig: {
+ editLink: {
+ pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
+ text: 'Редактировать эту страницу на GitHub'
+ }
+ }
+}
+```
+
+```ts
+export interface EditLink {
+ pattern: string
+ text?: string
+}
+```
+
+## lastUpdated {#lastupdated}
+
+- Тип: `LastUpdatedOptions`
+
+Позволяет настраивать текст и формат даты последнего обновления.
+
+```ts
+export default {
+ themeConfig: {
+ lastUpdated: {
+ text: 'Обновлено',
+ formatOptions: {
+ dateStyle: 'full',
+ timeStyle: 'medium'
+ }
+ }
+ }
+}
+```
+
+```ts
+export interface LastUpdatedOptions {
+ /**
+ * @default 'Last updated'
+ */
+ text?: string
+
+ /**
+ * @default
+ * { dateStyle: 'short', timeStyle: 'short' }
+ */
+ formatOptions?: Intl.DateTimeFormatOptions & { forceLocale?: boolean }
+}
+```
+
+## algolia {#algolia}
+
+- Тип: `AlgoliaSearch`
+
+Опция для поддержки поиска на вашем сайте документации с помощью [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Подробнее в главе [Тема по умолчанию: Поиск](./default-theme-search)
+
+```ts
+export interface AlgoliaSearchOptions extends DocSearchProps {
+ locales?: Record>
+}
+```
+
+Посмотреть все доступные опции можно [здесь](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts).
+
+## carbonAds {#carbon-ads}
+
+- Тип: `CarbonAdsOptions`
+
+Возможность отображения [Carbon Ads](https://www.carbonads.net/).
+
+```ts
+export default {
+ themeConfig: {
+ carbonAds: {
+ code: 'код-рекламы',
+ placement: 'место-размещения-рекламы'
+ }
+ }
+}
+```
+
+```ts
+export interface CarbonAdsOptions {
+ code: string
+ placement: string
+}
+```
+
+Подробнее в главе [Тема по умолчанию: Carbon Ads](./default-theme-carbon-ads)
+
+## docFooter {#docfooter}
+
+- Тип: `DocFooter`
+
+Можно использовать для настройки текста, отображаемого над ссылками на предыдущую и следующую страницы. Полезно, если вы не пишете документы только на английском языке. Также можно использовать для глобального отключения подобных ссылок. Если вы хотите выборочно включить/выключить эти ссылки на отдельной странице, воспользуйтесь [метаданными](./default-theme-prev-next-links).
+
+```ts
+export default {
+ themeConfig: {
+ docFooter: {
+ prev: 'Предыдущая страница',
+ next: 'Следующая страница'
+ }
+ }
+}
+```
+
+```ts
+export interface DocFooter {
+ prev?: string | false
+ next?: string | false
+}
+```
+
+## darkModeSwitchLabel {#darkmodeswitchlabel}
+
+- Тип: `string`
+- По умолчанию: `Appearance`
+
+Можно использовать для настройки надписи переключателя тёмного режима. Этот ярлык отображается только в мобильном представлении.
+
+## lightModeSwitchTitle {#lightmodeswitchtitle}
+
+- Тип: `string`
+- По умолчанию: `Switch to light theme`
+
+Может использоваться для настройки заголовка переключателя светлого режима, который появляется при наведении курсора.
+
+## darkModeSwitchTitle {#darkmodeswitchtitle}
+
+- Тип: `string`
+- По умолчанию: `Switch to dark theme`
+
+Можно использовать для настройки заголовка переключателя тёмного режима, который появляется при наведении курсора.
+
+## sidebarMenuLabel {#sidebarmenulabel}
+
+- Тип: `string`
+- По умолчанию: `Menu`
+
+Может использоваться для настройки метки бокового меню. Эта метка отображается только в мобильном представлении.
+
+## returnToTopLabel {#returntotoplabel}
+
+- Тип: `string`
+- По умолчанию: `Return to top`
+
+Может использоваться для настройки метки кнопки возврата наверх. Эта метка отображается только в мобильном представлении.
+
+## langMenuLabel {#langmenulabel}
+
+- Тип: `string`
+- По умолчанию: `Change language`
+
+Можно использовать для настройки aria-метки кнопки переключения языка в панели навигации. Это используется только в том случае, если вы используете [i18n](../guide/i18n).
+
+## externalLinkIcon {#externallinkicon}
+
+- Тип: `boolean`
+- По умолчанию: `false`
+
+Отображать ли значок внешней ссылки рядом с внешними ссылками в Markdown.
diff --git a/docs/ru/reference/default-theme-edit-link.md b/docs/ru/reference/default-theme-edit-link.md
new file mode 100644
index 00000000..a2cd6b00
--- /dev/null
+++ b/docs/ru/reference/default-theme-edit-link.md
@@ -0,0 +1,60 @@
+# Ссылка для редактирования {#edit-link}
+
+## Настройка в файле конфигурации {#site-level-config}
+
+Ссылка на редактирование позволяет отобразить ссылку для редактирования страницы на сервисах управления Git, таких как GitHub или GitLab. Чтобы включить её, добавьте опции `themeConfig.editLink` в свой конфиг:
+
+```js
+export default {
+ themeConfig: {
+ editLink: {
+ pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path'
+ }
+ }
+}
+```
+
+Параметр `pattern` задает структуру URL для ссылки, а `:path` будет заменён на путь к странице.
+
+Вы также можете поместить чистую функцию, которая принимает [`PageData`](./runtime-api#usedata) в качестве аргумента и возвращает строку URL.
+
+```js
+export default {
+ themeConfig: {
+ editLink: {
+ pattern: ({ filePath }) => {
+ if (filePath.startsWith('packages/')) {
+ return `https://github.com/acme/monorepo/edit/main/${filePath}`
+ } else {
+ return `https://github.com/acme/monorepo/edit/main/docs/${filePath}`
+ }
+ }
+ }
+ }
+}
+```
+
+Она не должна иметь побочных эффектов или доступа к чему-либо за пределами своей области, поскольку будет сериализована и выполнена в браузере.
+
+По умолчанию это добавит текст ссылки «Редактировать страницу» в нижней части документа. Вы можете настроить этот текст, определив опцию `text`.
+
+```js
+export default {
+ themeConfig: {
+ editLink: {
+ pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
+ text: 'Редактировать эту страницу на GitHub'
+ }
+ }
+}
+```
+
+## Настройка в метаданных {#frontmatter-config}
+
+Эту ссылку можно отключить на конкретной странице с помощью опции `editLink` в метаданных:
+
+```yaml
+---
+editLink: false
+---
+```
diff --git a/docs/ru/reference/default-theme-footer.md b/docs/ru/reference/default-theme-footer.md
new file mode 100644
index 00000000..2222f436
--- /dev/null
+++ b/docs/ru/reference/default-theme-footer.md
@@ -0,0 +1,55 @@
+# Подвал {#footer}
+
+VitePress будет отображать блок подвала внизу страницы, если присутствует объект `themeConfig.footer`.
+
+```ts
+export default {
+ themeConfig: {
+ footer: {
+ message: 'Опубликовано под лицензией MIT.',
+ copyright: '© 2019 – настоящее время, Эван Ю'
+ }
+ }
+}
+```
+
+```ts
+export interface Footer {
+ // Сообщение, отображаемое прямо перед копирайтом.
+ message?: string
+
+ // Уведомление об авторских правах.
+ copyright?: string
+}
+```
+
+Приведённая выше конфигурация также поддерживает строки HTML. Так, например, если вы хотите разместить в подвале несколько ссылок, можно настроить конфигурацию следующим образом:
+
+```ts
+export default {
+ themeConfig: {
+ footer: {
+ message:
+ 'Опубликовано под лицензией MIT.',
+ copyright:
+ '© 2019 – настоящее время, Эван Ю'
+ }
+ }
+}
+```
+
+::: warning ПРЕДУПРЕЖДЕНИЕ
+В `message` и `copyright` можно использовать только встроенные элементы, поскольку они отображаются внутри элемента ``. Если вы хотите добавить блочные элементы, рассмотрите возможность использования слота [`layout-bottom`](../guide/extending-default-theme#layout-slots).
+:::
+
+Обратите внимание, что подвал не будет отображаться, если виден [Сайдбар](./default-theme-sidebar).
+
+## Настройка в метаданных {#frontmatter-config}
+
+Отображение подвала можно отключить на конкретной странице с помощью опции `footer` в метаданных:
+
+```yaml
+---
+footer: false
+---
+```
diff --git a/docs/ru/reference/default-theme-home-page.md b/docs/ru/reference/default-theme-home-page.md
new file mode 100644
index 00000000..fedf2b53
--- /dev/null
+++ b/docs/ru/reference/default-theme-home-page.md
@@ -0,0 +1,196 @@
+# Главная страница {#home-page}
+
+Тема VitePress по умолчанию предоставляет макет главной страницы, который вы также можете увидеть на [главной странице этого сайта](../). Вы можете использовать его на любой из своих страниц, указав `layout: home` в [метаданных](./frontmatter-config) страницы.
+
+```yaml
+---
+layout: home
+---
+```
+
+Однако сам по себе этот вариант мало что даст. Вы можете добавить несколько различных готовых «секций» на главную страницу, установив дополнительные опции, такие как `hero` и `features`.
+
+## Секция `hero` {#hero-section}
+
+Секция `hero` находится в верхней части главной страницы. Вот как можно её настроить:
+
+```yaml
+---
+layout: home
+
+hero:
+ name: VitePress
+ text: Генератор статических сайтов на основе Vite и Vue.
+ tagline: Lorem ipsum...
+ image:
+ src: /logo.png
+ alt: VitePress
+ actions:
+ - theme: brand
+ text: Начать
+ link: /guide/what-is-vitepress
+ - theme: alt
+ text: Посмотреть на GitHub
+ link: https://github.com/vuejs/vitepress
+---
+```
+
+```ts
+interface Hero {
+ // Строка, отображаемая поверх `text`. Поставляется в фирменном цвете и,
+ // как ожидается, будет короткой — например, название продукта
+ name?: string
+
+ // Основной текст секции. Будет использоваться внутри тега `h1`
+ text: string
+
+ // Заголовок, отображаемый под `text`
+ tagline?: string
+
+ // Изображение отображается рядом с `text` и `tagline`
+ image?: ThemeableImage
+
+ // Кнопки действий для отображения в секции
+ actions?: HeroAction[]
+}
+
+type ThemeableImage =
+ | string
+ | { src: string; alt?: string }
+ | { light: string; dark: string; alt?: string }
+
+interface HeroAction {
+ // Цветовая тема кнопки. По умолчанию принимает значение `brand`.
+ theme?: 'brand' | 'alt'
+
+ // Метка кнопки.
+ text: string
+
+ // Ссылка назначения кнопки.
+ link: string
+
+ // Атрибут цели ссылки.
+ target?: string
+
+ // Атрибут rel ссылки.
+ rel?: string
+}
+```
+
+### Настройка цвета заголовка секции {#customizing-the-name-color}
+
+VitePress использует фирменный цвет (`--vp-c-brand-1`) для атрибута `name` в секции `hero`. Однако вы можете настроить этот цвет, переопределив переменную `--vp-home-hero-name-color`.
+
+```css
+:root {
+ --vp-home-hero-name-color: blue;
+}
+```
+
+Также вы можете настроить его ещё больше, комбинируя `--vp-home-hero-name-background`, чтобы придать `name` градиентный цвет.
+
+```css
+:root {
+ --vp-home-hero-name-color: transparent;
+ --vp-home-hero-name-background: -webkit-linear-gradient(
+ 120deg,
+ #bd34fe,
+ #41d1ff
+ );
+}
+```
+
+## Секция `features` {#features-section}
+
+В секции `features` можно перечислить любое количество функций, которые вы хотели бы показать сразу после секции `hero`. Чтобы настроить её, передайте опцию `features` в метаданных страницы.
+
+Для каждой функции можно указать иконку, который может быть эмодзи или любым другим изображением. Если настраиваемая иконка представляет собой изображение (svg, png, jpeg...), вы должны предоставить ей соответствующую ширину и высоту. При необходимости можно указать описание, собственный размер, а также варианты для тёмной и светлой темы.
+
+```yaml
+---
+layout: home
+
+features:
+ - icon: 🛠️
+ title: Просто и минималистично, всегда
+ details: Lorem ipsum...
+ - icon:
+ src: /cool-feature-icon.svg
+ title: Ещё одна интересная функция
+ details: Lorem ipsum...
+ - icon:
+ dark: /dark-feature-icon.svg
+ light: /light-feature-icon.svg
+ title: Ещё одна интересная функция
+ details: Lorem ipsum...
+---
+```
+
+```ts
+interface Feature {
+ // Иконка
+ icon?: FeatureIcon
+
+ // Заголовок фичи
+ title: string
+
+ // Описание фичи
+ details: string
+
+ // Ссылка при нажатии на компонент функции. Ссылка может быть как внутренней, так и внешней.
+ //
+ // например, `guide/reference/default-theme-home-page` или `https://example.com`
+ link?: string
+
+ // Текст ссылки, который будет отображаться внутри компонента функции. Лучше всего использовать с опцией `link`.
+ //
+ // например, `Узнать подробнее`, `Посетить страницу` и т. д.
+ linkText?: string
+
+ // Атрибут rel для опции `link`
+ //
+ // например, `external`
+ rel?: string
+
+ // Атрибут target для опции `link`
+ target?: string
+}
+
+type FeatureIcon =
+ | string
+ | { src: string; alt?: string; width?: string; height: string }
+ | {
+ light: string
+ dark: string
+ alt?: string
+ width?: string
+ height: string
+ }
+```
+
+## Содержимое Markdown {#markdown-content}
+
+Вы можете добавить дополнительный контент на главную страницу вашего сайта, просто добавив Markdown под разделителем `---`.
+
+````md
+---
+layout: home
+
+hero:
+ name: VitePress
+ text: Генератор статических сайтов на основе Vite и Vue.
+---
+
+## Начало работы
+
+Вы можете начать использовать VitePress прямо сейчас, используя `npx`!
+
+```sh
+npm init
+npx vitepress init
+```
+````
+
+::: info ПРИМЕЧАНИЕ
+VitePress не всегда автоматически стилизовал дополнительный контент страницы с макетом `layout: home`. Чтобы вернуться к старому поведению, добавьте `markdownStyles: false` в метаданных.
+:::
diff --git a/docs/ru/reference/default-theme-last-updated.md b/docs/ru/reference/default-theme-last-updated.md
new file mode 100644
index 00000000..7d926dc5
--- /dev/null
+++ b/docs/ru/reference/default-theme-last-updated.md
@@ -0,0 +1,27 @@
+# Последнее обновление {#last-updated}
+
+Время последнего обновления содержимого будет отображаться в правом нижнем углу страницы. Чтобы включить его, добавьте опцию `lastUpdated` в свой конфиг.
+
+::: tip Совет
+Чтобы увидеть обновленное время, необходимо зафиксировать файл Markdown.
+:::
+
+## Настройка в файле конфигурации {#site-level-config}
+
+```js
+export default {
+ lastUpdated: true
+}
+```
+
+## Настройка в метаданных {#frontmatter-config}
+
+Эту информацию можно отключить на конкретной странице с помощью опции `lastUpdated` в метаданных:
+
+```yaml
+---
+lastUpdated: false
+---
+```
+
+Также смотрите [Тема по умолчанию: `lastUpdated`](./default-theme-config#lastupdated) для получения более подробной информации. Любое истинное значение на уровне темы также включит функцию, если только она не будет явно отключена на уровне сайта или страницы.
diff --git a/docs/ru/reference/default-theme-layout.md b/docs/ru/reference/default-theme-layout.md
new file mode 100644
index 00000000..f02af7d5
--- /dev/null
+++ b/docs/ru/reference/default-theme-layout.md
@@ -0,0 +1,62 @@
+# Макет {#layout}
+
+Вы можете выбрать макет страницы, установив опцию `layout` в [метаданных](./frontmatter-config). Изначально есть 3 макета: `doc`, `page` и `home`. Если ничего не указано, то страница будет использовать макет `doc`.
+
+```yaml
+---
+layout: doc
+---
+```
+
+## Макет `doc` {#doc-layout}
+
+Вариант `doc` — это макет по умолчанию, который стилизует всё содержимое Markdown в виде «документации». Он работает, оборачивая весь контент в CSS-класс `vp-doc` и применяя стили к вложенным элементам.
+
+Почти все общие элементы, такие как `p` или `h2`, получают специальную стилизацию. Поэтому имейте в виду, что если вы добавите какой-либо пользовательский HTML внутри Markdown-контента, то он также будет подвержен влиянию этих стилей.
+
+Кроме того, в нём предусмотрены специальные функции, перечисленные ниже. Эти функции включены только в данном макете.
+
+- Ссылка «Редактировать»
+- Ссылки предыдущая/следующая
+- Оглавление
+- Реклама [Carbon Ads](./default-theme-carbon-ads)
+
+## Макет `page` {#page-layout}
+
+Вариант `page` сгенерирует «пустую страницу». Markdown всё равно будет разобран, и все [расширения Markdown](../guide/markdown) будут работать так же, как и с макетом `doc`, но никаких стилей по умолчанию применено не будет.
+
+Макет `page` позволит вам оформить всё самостоятельно, без влияния темы VitePress на разметку. Это удобно, когда вы хотите создать свою собственную страницу.
+
+Обратите внимание, что даже при таком раскладе сайдбар всё равно будет отображаться, если у страницы есть соответствующая конфигурация сайдбара.
+
+## Макет `home` {#home-layout}
+
+Вариант `home` сгенерирует шаблонную «домашнюю страницу». В этом макете вы можете установить дополнительные параметры, такие как `hero` и `features`, для дальнейшей настройки контента. Посетите секцию [Тема по умолчанию: Домашняя страница](./default-theme-home-page) для получения более подробной информации.
+
+## Без макета {#no-layout}
+
+Если вам не нужен макет, вы можете указать `layout: false` в метаданных. Этот параметр полезен, если вам нужна полностью настраиваемая целевая страница (по умолчанию без сайдбара, панели навигации или подвала).
+
+## Свой макет {#custom-layout}
+
+Вы также можете использовать собственный макет:
+
+```md
+---
+layout: foo
+---
+```
+
+Будет выполнен поиск компонента с именем `foo`, зарегистрированного в контексте. Например, вы можете зарегистрировать свой компонент глобально в `.vitepress/theme/index.ts`:
+
+```ts
+import DefaultTheme from 'vitepress/theme'
+import Foo from './Foo.vue'
+
+export default {
+ extends: DefaultTheme,
+ enhanceApp({ app }) {
+ app.component('foo', Foo)
+ }
+}
+```
diff --git a/docs/ru/reference/default-theme-nav.md b/docs/ru/reference/default-theme-nav.md
new file mode 100644
index 00000000..9ff77659
--- /dev/null
+++ b/docs/ru/reference/default-theme-nav.md
@@ -0,0 +1,162 @@
+# Навигация {#nav}
+
+Ключ `nav` в конфигурации — это панель навигации, отображаемая в верхней части страницы. Она содержит заголовок сайта, ссылки глобального меню и т. д.
+
+## Название и логотип сайта {#site-title-and-logo}
+
+По умолчанию навигация отображает название сайта, ссылаясь на значение [`config.title`](./site-config#title). Если вы хотите изменить то, что отображается в панели навигации, задайте пользовательский текст в опции `themeConfig.siteTitle`.
+
+```js
+export default {
+ themeConfig: {
+ siteTitle: 'Мой заголовок'
+ }
+}
+```
+
+Если у вас есть логотип для вашего сайта, вы можете отобразить его, передав путь к изображению. Вы должны поместить логотип непосредственно в директорию `public` и указать абсолютный путь к нему.
+
+```js
+export default {
+ themeConfig: {
+ logo: '/my-logo.svg'
+ }
+}
+```
+
+При добавлении логотипа он отображается вместе с названием сайта. Если вам нужен только логотип и вы хотите скрыть текст заголовка сайта, установите `false` для параметра `SiteTitle`.
+
+```js
+export default {
+ themeConfig: {
+ logo: '/my-logo.svg',
+ siteTitle: false
+ }
+}
+```
+
+Вы также можете передать объект в качестве логотипа, если хотите добавить атрибут `alt` или настроить его в зависимости от тёмного/светлого режима. Подробности смотрите в [`themeConfig.logo`](./default-theme-config#logo).
+
+## Навигационные ссылки {#navigation-links}
+
+Вы можете определить опцию `themeConfig.nav`, чтобы добавить ссылки в панель навигации:
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ { text: 'Руководство', link: '/guide' },
+ { text: 'Настройка', link: '/config' },
+ { text: 'Изменения', link: 'https://github.com/...' }
+ ]
+ }
+}
+```
+
+`text` — это текст, отображаемый в навигации, а `link` — это ссылка, на которую будет осуществлён переход при нажатии на текст. Для ссылки задайте путь к фактическому файлу без префикса `.md` и всегда начинайте с `/`.
+
+Навигационные ссылки также могут быть выпадающими меню. Для этого установите ключ `items` вместо ключа `link`:
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ { text: 'Руководство', link: '/guide' },
+ {
+ text: 'Выпадающее меню',
+ items: [
+ { text: 'Пункт A', link: '/item-1' },
+ { text: 'Пункт B', link: '/item-2' },
+ { text: 'Пункт C', link: '/item-3' }
+ ]
+ }
+ ]
+ }
+}
+```
+
+Обратите внимание, что заголовок выпадающего меню (`Выпадающее меню` в примере выше) не может иметь свойство `link`, так как он становится кнопкой для открытия выпадающего диалога.
+
+Вы можете добавить «секции» в пункты выпадающего меню, передавая больше вложенных элементов:
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ { text: 'Руководство', link: '/guide' },
+ {
+ text: 'Выпадающее меню',
+ items: [
+ {
+ // Заголовок секции
+ text: 'Секция A',
+ items: [
+ { text: 'Пункт A в секции A', link: '...' },
+ { text: 'Пункт B в секции A', link: '...' }
+ ]
+ }
+ ]
+ },
+ {
+ text: 'Выпадающее меню',
+ items: [
+ {
+ // Заголовок можно опустить
+ items: [
+ { text: 'Пункт A в секции A', link: '...' },
+ { text: 'Пункт B в секции A', link: '...' }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+### Настройка «активного» состояния ссылки {#customize-link-s-active-state}
+
+Пункты меню навигации будут выделены, если текущая страница находится под соответствующим путём. Если вы хотите настроить сопоставление путей, определите свойство `activeMatch` и регулярное выражение в качестве строкового значения.
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ // Эта ссылка получает активное состояние, когда пользователь
+ // переходит по пути `/config/`.
+ {
+ text: 'Руководство',
+ link: '/guide',
+ activeMatch: '/config/'
+ }
+ ]
+ }
+}
+```
+
+::: warning ПРЕДУПРЕЖДЕНИЕ
+Ожидается, что `activeMatch` будет регулярным выражением, но вы должны определить его как строку. Мы не можем использовать здесь реальный объект RegExp, потому что он не сериализуется во время сборки.
+:::
+
+### Настройка атрибутов «target» и «rel» {#customize-link-s-target-and-rel-attributes}
+
+По умолчанию VitePress автоматически определяет атрибуты `target` и `rel` в зависимости от того, является ли ссылка внешней. Но при желании их можно настроить и вручную.
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ {
+ text: 'Товары',
+ link: 'https://www.thegithubshop.com/',
+ target: '_self',
+ rel: 'sponsored'
+ }
+ ]
+ }
+}
+```
+
+## Социальные ссылки {#social-links}
+
+См. [`socialLinks`](./default-theme-config#sociallinks).
diff --git a/docs/ru/reference/default-theme-prev-next-links.md b/docs/ru/reference/default-theme-prev-next-links.md
new file mode 100644
index 00000000..e2da9501
--- /dev/null
+++ b/docs/ru/reference/default-theme-prev-next-links.md
@@ -0,0 +1,43 @@
+# Предыдущая и следующая страницы {#prev-next-links}
+
+Вы можете настроить текст и ссылку для предыдущей и следующей страниц (отображаются в нижней части страницы). Это полезно, если вы хотите, чтобы текст отличался от того, что находится в сайдбаре. Кроме того, вы можете счесть полезным отключить подвал или ссылку на страницу, которая не включена в сайдбар.
+
+## prev {#prev}
+
+- Тип: `string | false | { text?: string; link?: string }`
+
+- Подробности:
+
+ Указывает текст/ссылку, который должен отображаться при переходе на предыдущую страницу. Если вы не зададите это в метаданных, текст/ссылка будет определяться из конфигурации сайдбара.
+
+- Примеры:
+
+ - Для настройки только текста:
+
+ ```yaml
+ ---
+ prev: 'Начать | Markdown'
+ ---
+ ```
+
+ - Для настройки текста и ссылки:
+
+ ```yaml
+ ---
+ prev:
+ text: 'Markdown'
+ link: '/guide/markdown'
+ ---
+ ```
+
+ - Для скрытия предыдущей страницы:
+
+ ```yaml
+ ---
+ prev: false
+ ---
+ ```
+
+## next {#next}
+
+Аналогично параметру `prev`, но для следующей страницы.
diff --git a/docs/ru/reference/default-theme-search.md b/docs/ru/reference/default-theme-search.md
new file mode 100644
index 00000000..dae85f47
--- /dev/null
+++ b/docs/ru/reference/default-theme-search.md
@@ -0,0 +1,382 @@
+---
+outline: deep
+---
+
+# Поиск {#search}
+
+## Локальный поиск {#local-search}
+
+VitePress поддерживает нечёткий полнотекстовый поиск с использованием внутрибраузерного индекса благодаря [MiniSearch](https://github.com/lucaong/minisearch/). Чтобы включить эту функцию, просто установите значение `'local'` для опции `themeConfig.search.provider` в файле `.vitepress/config.ts`:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local'
+ }
+ }
+})
+```
+
+Пример результата:
+
+
+
+В качестве альтернативы можно использовать [Algolia DocSearch](#algolia-search) или некоторые плагины сообщества, например или .
+
+### i18n {#local-search-i18n}
+
+Вы можете использовать подобную конфигурацию для использования многоязычного поиска:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local',
+ options: {
+ locales: {
+ ru: {
+ translations: {
+ button: {
+ buttonText: 'Поиск',
+ buttonAriaLabel: 'Поиск'
+ },
+ modal: {
+ noResultsText: 'Нет результатов для',
+ resetButtonTitle: 'Сбросить поиск',
+ footer: {
+ selectText: 'выбрать',
+ navigateText: 'перейти'
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+})
+```
+
+### Параметры MiniSearch {#minisearch-options}
+
+Вы можете настроить MiniSearch следующим образом:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local',
+ options: {
+ miniSearch: {
+ /**
+ * @type {Pick}
+ */
+ options: {
+ /* ... */
+ },
+ /**
+ * @type {import('minisearch').SearchOptions}
+ * @default
+ * { fuzzy: 0.2, prefix: true, boost: { title: 4, text: 2, titles: 1 } }
+ */
+ searchOptions: {
+ /* ... */
+ }
+ }
+ }
+ }
+ }
+})
+```
+
+Подробнее в [документации MiniSearch](https://lucaong.github.io/minisearch/classes/MiniSearch.MiniSearch.html).
+
+### Пользовательский рендерер содержимого {#custom-content-renderer}
+
+Вы можете настроить функцию, используемую для отображения содержимого в формате Markdown перед его индексацией:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local',
+ options: {
+ /**
+ * @param {string} src
+ * @param {import('vitepress').MarkdownEnv} env
+ * @param {import('markdown-it')} md
+ */
+ _render(src, env, md) {
+ // возвращаем html
+ }
+ }
+ }
+ }
+})
+```
+
+Эта функция будет очищена от данных сайта на стороне клиента, поэтому вы можете использовать в ней API Node.js.
+
+#### Пример: Исключение страниц из поиска {#example-excluding-pages-from-search}
+
+Вы можете исключить страницы из поиска, добавив `search: false` в блок метаданных страницы. Альтернативный вариант:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local',
+ options: {
+ _render(src, env, md) {
+ const html = md.render(src, env)
+ if (env.frontmatter?.search === false) return ''
+ if (env.relativePath.startsWith('some/path')) return ''
+ return html
+ }
+ }
+ }
+ }
+})
+```
+
+::: warning ПРИМЕЧАНИЕ
+В случае, если предоставляется пользовательская функция `_render`, вам нужно самостоятельно обработать заголовок `search: false`. Кроме того, объект `env` не будет полностью заполнен до вызова `md.render`, поэтому любые проверки необязательных свойств `env`, таких как `frontmatter`, должны быть выполнены после этого.
+:::
+
+#### Пример: Преобразование содержимого - добавление якорей {#example-transforming-content-adding-anchors}
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local',
+ options: {
+ _render(src, env, md) {
+ const html = md.render(src, env)
+ if (env.frontmatter?.title)
+ return md.render(`# ${env.frontmatter.title}`) + html
+ return html
+ }
+ }
+ }
+ }
+})
+```
+
+## Поиск Algolia {#algolia-search}
+
+VitePress поддерживает поиск в вашей документации с помощью [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Обратитесь к руководству по началу работы. В файле `.vitepress/config.ts` вам нужно будет указать, по крайней мере, следующее, чтобы всё работало:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'algolia',
+ options: {
+ appId: '...',
+ apiKey: '...',
+ indexName: '...'
+ }
+ }
+ }
+})
+```
+
+### i18n {#algolia-search-i18n}
+
+Вы можете использовать подобную конфигурацию для использования многоязычного поиска:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'algolia',
+ options: {
+ appId: '...',
+ apiKey: '...',
+ indexName: '...',
+ locales: {
+ ru: {
+ placeholder: 'Поиск в документации',
+ translations: {
+ button: {
+ buttonText: 'Поиск',
+ buttonAriaLabel: 'Поиск'
+ },
+ modal: {
+ searchBox: {
+ resetButtonTitle: 'Сбросить поиск',
+ resetButtonAriaLabel: 'Сбросить поиск',
+ cancelButtonText: 'Отменить поиск',
+ cancelButtonAriaLabel: 'Отменить поиск'
+ },
+ startScreen: {
+ recentSearchesTitle: 'История поиска',
+ noRecentSearchesText: 'Нет истории поиска',
+ saveRecentSearchButtonTitle: 'Сохранить в истории поиска',
+ removeRecentSearchButtonTitle: 'Удалить из истории поиска',
+ favoriteSearchesTitle: 'Избранное',
+ removeFavoriteSearchButtonTitle: 'Удалить из избранного'
+ },
+ errorScreen: {
+ titleText: 'Невозможно получить результаты',
+ helpText:
+ 'Вам может потребоваться проверить подключение к Интернету'
+ },
+ footer: {
+ selectText: 'выбрать',
+ navigateText: 'перейти',
+ closeText: 'закрыть',
+ searchByText: 'поставщик поиска'
+ },
+ noResultsScreen: {
+ noResultsText: 'Нет результатов для',
+ suggestedQueryText: 'Вы можете попытаться узнать',
+ reportMissingResultsText:
+ 'Считаете, что поиск даёт ложные результаты？',
+ reportMissingResultsLinkText:
+ 'Нажмите на кнопку «Обратная связь»'
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+})
+```
+
+[Эти параметры](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts) можно переопределить. Чтобы узнать о них больше, обратитесь к официальной документации Algolia.
+
+### Конфигурация поискового робота {#crawler-config}
+
+Вот пример конфигурации, основанной на той, что используется на этом сайте:
+
+```ts
+new Crawler({
+ appId: '...',
+ apiKey: '...',
+ rateLimit: 8,
+ startUrls: ['https://vitepress.dev/'],
+ renderJavaScript: false,
+ sitemaps: [],
+ exclusionPatterns: [],
+ ignoreCanonicalTo: false,
+ discoveryPatterns: ['https://vitepress.dev/**'],
+ schedule: 'at 05:10 on Saturday',
+ actions: [
+ {
+ indexName: 'vitepress',
+ pathsToMatch: ['https://vitepress.dev/**'],
+ recordExtractor: ({ $, helpers }) => {
+ return helpers.docsearch({
+ recordProps: {
+ lvl1: '.content h1',
+ content: '.content p, .content li',
+ lvl0: {
+ selectors: '',
+ defaultValue: 'Documentation'
+ },
+ lvl2: '.content h2',
+ lvl3: '.content h3',
+ lvl4: '.content h4',
+ lvl5: '.content h5'
+ },
+ indexHeadings: true
+ })
+ }
+ }
+ ],
+ initialIndexSettings: {
+ vitepress: {
+ attributesForFaceting: ['type', 'lang'],
+ attributesToRetrieve: ['hierarchy', 'content', 'anchor', 'url'],
+ attributesToHighlight: ['hierarchy', 'hierarchy_camel', 'content'],
+ attributesToSnippet: ['content:10'],
+ camelCaseAttributes: ['hierarchy', 'hierarchy_radio', 'content'],
+ searchableAttributes: [
+ 'unordered(hierarchy_radio_camel.lvl0)',
+ 'unordered(hierarchy_radio.lvl0)',
+ 'unordered(hierarchy_radio_camel.lvl1)',
+ 'unordered(hierarchy_radio.lvl1)',
+ 'unordered(hierarchy_radio_camel.lvl2)',
+ 'unordered(hierarchy_radio.lvl2)',
+ 'unordered(hierarchy_radio_camel.lvl3)',
+ 'unordered(hierarchy_radio.lvl3)',
+ 'unordered(hierarchy_radio_camel.lvl4)',
+ 'unordered(hierarchy_radio.lvl4)',
+ 'unordered(hierarchy_radio_camel.lvl5)',
+ 'unordered(hierarchy_radio.lvl5)',
+ 'unordered(hierarchy_radio_camel.lvl6)',
+ 'unordered(hierarchy_radio.lvl6)',
+ 'unordered(hierarchy_camel.lvl0)',
+ 'unordered(hierarchy.lvl0)',
+ 'unordered(hierarchy_camel.lvl1)',
+ 'unordered(hierarchy.lvl1)',
+ 'unordered(hierarchy_camel.lvl2)',
+ 'unordered(hierarchy.lvl2)',
+ 'unordered(hierarchy_camel.lvl3)',
+ 'unordered(hierarchy.lvl3)',
+ 'unordered(hierarchy_camel.lvl4)',
+ 'unordered(hierarchy.lvl4)',
+ 'unordered(hierarchy_camel.lvl5)',
+ 'unordered(hierarchy.lvl5)',
+ 'unordered(hierarchy_camel.lvl6)',
+ 'unordered(hierarchy.lvl6)',
+ 'content'
+ ],
+ distinct: true,
+ attributeForDistinct: 'url',
+ customRanking: [
+ 'desc(weight.pageRank)',
+ 'desc(weight.level)',
+ 'asc(weight.position)'
+ ],
+ ranking: [
+ 'words',
+ 'filters',
+ 'typo',
+ 'attribute',
+ 'proximity',
+ 'exact',
+ 'custom'
+ ],
+ highlightPreTag: '',
+ highlightPostTag: '',
+ minWordSizefor1Typo: 3,
+ minWordSizefor2Typos: 7,
+ allowTyposOnNumericTokens: false,
+ minProximity: 1,
+ ignorePlurals: true,
+ advancedSyntax: true,
+ attributeCriteriaComputedByMinProximity: true,
+ removeWordsIfNoResults: 'allOptional'
+ }
+ }
+})
+```
+
+
diff --git a/docs/ru/reference/default-theme-sidebar.md b/docs/ru/reference/default-theme-sidebar.md
new file mode 100644
index 00000000..92fd89c1
--- /dev/null
+++ b/docs/ru/reference/default-theme-sidebar.md
@@ -0,0 +1,213 @@
+# Сайдбар {#sidebar}
+
+Сайдбар (боковая панель) — основной навигационный блок вашей документации. Меню боковой панели можно настроить в секции [`themeConfig.sidebar`](./default-theme-config#sidebar).
+
+```js
+export default {
+ themeConfig: {
+ sidebar: [
+ {
+ text: 'Руководство',
+ items: [
+ { text: 'Введение', link: '/ru/introduction' },
+ { text: 'Первые шаги', link: '/ru/getting-started' },
+ ...
+ ]
+ }
+ ]
+ }
+}
+```
+
+## Основы {#the-basics}
+
+Простейшая форма сайдбара — это передача массива ссылок. Элемент первого уровня определяет «секцию» сайдбара. Он должен содержать `text`, который является заголовком секции, и `items`, которые являются фактическими навигационными ссылками.
+
+```js
+export default {
+ themeConfig: {
+ sidebar: [
+ {
+ text: 'Заголовок секции A',
+ items: [
+ { text: 'Пункт A', link: '/item-a' },
+ { text: 'Пункт B', link: '/item-b' },
+ ...
+ ]
+ },
+ {
+ text: 'Заголовок секции B',
+ items: [
+ { text: 'Пункт C', link: '/item-c' },
+ { text: 'Пункт D', link: '/item-d' },
+ ...
+ ]
+ }
+ ]
+ }
+}
+```
+
+Каждый элемент `link` должен указывать путь к фактическому файлу, начинающийся с `/`. Если добавить в конец ссылки косую черту, то будет показан `index.md` соответствующего каталога.
+
+```js
+export default {
+ themeConfig: {
+ sidebar: [
+ {
+ text: 'Руководство',
+ items: [
+ // Ссылка на страницу `/ru/guide/index.md`
+ { text: 'Введение', link: '/ru/guide/' }
+ ]
+ }
+ ]
+ }
+}
+```
+
+Вы можете вложить элементы боковой панели на 6 уровней вглубь, считая от корневого уровня. Обратите внимание, что более 6 уровней вложенных элементов будут игнорироваться и не отображаться на боковой панели.
+
+```js
+export default {
+ themeConfig: {
+ sidebar: [
+ {
+ text: 'Уровень 1',
+ items: [
+ {
+ text: 'Уровень 2',
+ items: [
+ {
+ text: 'Уровень 3',
+ items: [
+ ...
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+## Несколько сайдбаров {#multiple-sidebars}
+
+Вы можете показывать разные боковые панели в зависимости от текущего маршрута. Например, как показано на этом сайте, вы можете создать в документации отдельные разделы, например, «Руководство» и «Настройка».
+
+Для этого сначала организуйте страницы в каталоги для каждого нужного раздела:
+
+```
+.
+├─ guide/
+│ ├─ index.md
+│ ├─ one.md
+│ └─ two.md
+└─ config/
+ ├─ index.md
+ ├─ three.md
+ └─ four.md
+```
+
+Затем обновите конфигурацию, чтобы определить боковую панель для каждого раздела. На этот раз вместо массива нужно передать объект.
+
+```js
+export default {
+ themeConfig: {
+ sidebar: {
+ // Эта боковая панель отображается, когда пользователь находится в директории `guide`
+ '/guide/': [
+ {
+ text: 'Руководство',
+ items: [
+ { text: 'Index', link: '/guide/' },
+ { text: 'One', link: '/guide/one' },
+ { text: 'Two', link: '/guide/two' }
+ ]
+ }
+ ],
+
+ // Эта боковая панель отображается, когда пользователь находится в директории `config`
+ '/config/': [
+ {
+ text: 'Настройка',
+ items: [
+ { text: 'Index', link: '/config/' },
+ { text: 'Three', link: '/config/three' },
+ { text: 'Four', link: '/config/four' }
+ ]
+ }
+ ]
+ }
+ }
+}
+```
+
+## Сворачиваемые группы {#collapsible-sidebar-groups}
+
+Добавив опцию `collapsed` внутри группы `sidebar`, вы увидите кнопку переключения для скрытия/показа каждой секции.
+
+```js
+export default {
+ themeConfig: {
+ sidebar: [
+ {
+ text: 'Заголовок секции A',
+ collapsed: false,
+ items: [...]
+ }
+ ]
+ }
+}
+```
+
+Все секции «развёрнуты» по умолчанию. Если вы хотите, чтобы они были «свёрнуты» при первоначальной загрузке страницы, установите для опции `collapsed` значение `true`.
+
+```js
+export default {
+ themeConfig: {
+ sidebar: [
+ {
+ text: 'Заголовок секции A',
+ collapsed: true,
+ items: [...]
+ }
+ ]
+ }
+}
+```
+
+## `useSidebar`
+ sidebar: ComputedRef
+ sidebarGroups: ComputedRef
+ hasSidebar: ComputedRef
+ hasAside: ComputedRef
+ leftAside: ComputedRef
+ isSidebarEnabled: ComputedRef
+ open: () => void
+ close: () => void
+ toggle: () => void
+}
+```
+
+**Пример:**
+
+```vue
+
+
+
+ Показывать только при наличии сайдбара
+
+```
diff --git a/docs/ru/reference/default-theme-team-page.md b/docs/ru/reference/default-theme-team-page.md
new file mode 100644
index 00000000..0eebaa24
--- /dev/null
+++ b/docs/ru/reference/default-theme-team-page.md
@@ -0,0 +1,252 @@
+
+
+# Страница команды {#team-page}
+
+Если вы хотите представить свою команду, вы можете использовать компоненты Team для создания страницы команды. Есть два варианта использования этих компонентов. Один из вариантов — встроить их в страницу с макетом `doc`, а другой — создать полноценную страницу команды.
+
+## Отображение членов команды на странице {#show-team-members-in-a-page}
+
+Вы можете использовать компонент ``, доступный из `vitepress/theme`, для отображения списка членов команды на любой странице.
+
+```html
+
+
+# Поприветствуйте нашу замечательную команду
+
+` поставляется в двух различных размерах, `small` и `medium`. Хотя это зависит от ваших предпочтений, обычно размер `small` лучше подходит для использования на странице с макетом `doc`. Кроме того, вы можете добавить дополнительные свойства для карточки члена команды, например, добавить «описание» или кнопку «спонсировать». Подробнее об этом в секции [``](#vpteammembers).
+
+Встраивание членов команды в страницу документа хорошо подходит для небольших команд, где наличие полной страницы команды может быть слишком большим, или для представления частичных членов команды в качестве ссылки на контекст документации.
+
+Если у вас большое количество участников или вы просто хотите иметь больше места для отображения членов команды, подумайте о [создании отдельной страницы команды](#create-a-full-team-page).
+
+## Создание отдельной страницы команды {#create-a-full-team-page}
+
+Вместо того чтобы добавлять членов команды на страницу с макетом `doc`, вы можете создать полноценную страницу команды, подобно созданию пользовательской [главной страницы](./default-theme-home-page).
+
+Чтобы создать страницу команды, сначала создайте новый md-файл. Имя файла не имеет значения, но здесь мы назовем его `team.md`. В этом файле установите в блоке метаданных параметр `layout: page`, а затем вы можете организовать структуру страницы, используя компоненты `TeamPage`.
+
+```html
+---
+layout: page
+---
+
+
+
+
+
+ Наша команда
+
+ Разработкой VitePress руководит международная команда, некоторые члены
+ которой представлены ниже.
+
+
+
+```
+
+При создании полной страницы команды не забудьте обернуть все компоненты компонентом ``. Этот компонент обеспечит всем вложенным компонентам, связанным с командой, правильную структуру макета, например, расстояние между ними.
+
+Компонент `` добавляет блок заголовка страницы. Заголовок — это тег ``. Используйте слоты `#title` и `#lead`, чтобы рассказать о своей команде.
+
+`` работает так же, как и при использовании в doc-странице. Отобразится список участников.
+
+### Добавление секций для разделения членов команды {#add-sections-to-divide-team-members}
+
+Вы можете добавить «секции» на страницу команды. Например, у вас могут быть разные типы членов команды, такие как члены основной команды и партнёры сообщества. Вы можете разделить этих членов на секции, чтобы лучше объяснить роли каждой группы.
+
+Для этого добавьте компонент `` в файл `team.md`, который мы создали ранее.
+
+```html
+---
+layout: page
+---
+
+
+
+
+
+ Наша команда
+ ...
+
+
+ Партнёры
+ ...
+
+
+
+```
+
+Компонент `` может иметь слоты `#title` и `#lead`, аналогичные компоненту `VPTeamPageTitle`, а также слот `#members` для отображения членов команды.
+
+Не забудьте поместить компонент `` в слот `#members`.
+
+## `` {#vpteammembers}
+
+Компонент `` отображает заданный список членов команды.
+
+```html
+` {#vpteampage}
+
+Корневой компонент при создании отдельной страницы команды. Принимает только один слот. Он будет стилизовать все передаваемые компоненты, связанные с командой.
+
+## `` {#vpteampagetitle}
+
+Добавляет блок «заголовка» страницы. Лучше всего использовать в самом начале внутри ``. Принимает слоты `#title` и `#lead`.
+
+```html
+
+
+ Наша команда
+
+ Разработкой VitePress руководит международная команда, некоторые члены
+ которой представлены ниже.
+
+
+
+```
+
+## `` {#vpteampagesection}
+
+Создает «секцию» на странице команды. Принимает слоты `#title`, `#lead` и `#members`. Внутри `` вы можете добавить столько секций, сколько захотите.
+
+```html
+
+ ...
+
+ Партнёры
+ Lorem ipsum...
+
+
+
+```
diff --git a/docs/ru/reference/frontmatter-config.md b/docs/ru/reference/frontmatter-config.md
new file mode 100644
index 00000000..5c4b3a93
--- /dev/null
+++ b/docs/ru/reference/frontmatter-config.md
@@ -0,0 +1,221 @@
+---
+outline: deep
+---
+
+# Конфигурация метаданных {#frontmatter-config}
+
+Метаданные обеспечивают настройку отдельных страниц. В каждом файле Markdown можно использовать метаданные, чтобы переопределить параметры конфигурации сайта или темы. Кроме того, есть параметры конфигурации, которые можно задать только через метаданные.
+
+Пример использования:
+
+```md
+---
+title: Документация с VitePress
+editLink: true
+---
+```
+
+Вы можете получить доступ к метаданным через глобальный объект `$frontmatter` в выражениях Vue:
+
+```md
+{{ $frontmatter.title }}
+```
+
+## title {#title}
+
+- Тип: `string`
+
+Заголовок страницы. Это то же самое, что [config.title](./site-config#title), и оно переопределяет конфигурацию сайта.
+
+```yaml
+---
+title: VitePress
+---
+```
+
+## titleTemplate {#titletemplate}
+
+- Тип: `string | boolean`
+
+Суффикс для названия. Это то же самое, что и [config.titleTemplate](./site-config#titletemplate), и оно переопределяет конфигурацию сайта.
+
+```yaml
+---
+title: VitePress
+titleTemplate: Генератор статических сайтов на основе Vite и Vue
+---
+```
+
+## description {#description}
+
+- Тип: `string`
+
+Описание для страницы. Это то же самое, что и [config.description](./site-config#description), и оно переопределяет конфигурацию сайта.
+
+```yaml
+---
+description: VitePress
+---
+```
+
+## head {#head}
+
+- Тип: `HeadConfig[]`
+
+Укажите дополнительные теги, которые будут выводиться для текущей страницы. Они будут добавляться после других тегов внутри блока head, введённых в конфигурации сайта.
+
+```yaml
+---
+head:
+ - - meta
+ - name: description
+ content: привет
+ - - meta
+ - name: keywords
+ content: супер-пупер SEO
+---
+```
+
+```ts
+type HeadConfig =
+ | [string, Record]
+ | [string, Record, string]
+```
+
+## Только для темы по умолчанию {#default-theme-only}
+
+Следующие параметры метаданных применимы только при использовании темы по умолчанию.
+
+### layout {#layout}
+
+- Тип: `doc | home | page`
+- По умолчанию: `doc`
+
+Определяет макет страницы.
+
+- `doc` - Применяет стили документации по умолчанию к содержимому Markdown.
+- `home` - Вы можете добавить дополнительные параметры, такие как `hero` и `features`, чтобы быстро создать красивую целевую страницу.
+- `page` - Ведет себя аналогично `doc`, но не применяет стили к содержимому. Полезно, если вы хотите создать полностью настраиваемую страницу.
+
+```yaml
+---
+layout: doc
+---
+```
+
+### hero {{ theme.footer.copyright }}
+
+```
+
+## `useRoute`
+ /**
+ * Вызывается перед изменением маршрута. Верните `false`, чтобы отменить навигацию.
+ */
+ onBeforeRouteChange?: (to: string) => Awaitable
+ /**
+ * Вызывается перед загрузкой компонента страницы (после того, как состояние истории
+ * обновлено). Верните `false`, чтобы отменить навигацию.
+ */
+ onBeforePageLoad?: (to: string) => Awaitable
+ /**
+ * Вызывается после изменения маршрута.
+ */
+ onAfterRouteChanged?: (to: string) => Awaitable
+}
+```
+
+## `withBase` Пользовательский макет!
+
+
+```
+
+- См. также: [Совместимость с SSR](../guide/ssr-compat)
+
+## `$frontmatter` /.vitepress/config.[ext]`, где `` — это корень вашего [проекта](../guide/routing#root-and-source-directory) VitePress, а `[ext]` — одно из поддерживаемых расширений файла. TypeScript поддерживается из коробки. Поддерживаемые расширения включают `.js`, `.ts`, `.mjs` и `.mts`.
+
+В файлах конфигурации рекомендуется использовать синтаксис ES-модулей. Файл конфигурации должен по умолчанию экспортировать объект:
+
+```ts
+export default {
+ // параметры конфигурации на уровне приложения
+ lang: 'ru-RU',
+ title: 'VitePress',
+ description: 'Генератор статических сайтов на основе Vite и Vue.',
+ ...
+}
+```
+
+:::details Динамическая (асинхронная) конфигурация
+
+Если вам нужно генерировать конфигурацию динамически, вы также можете экспортировать функцию по умолчанию. Например:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default async () => {
+ const posts = await (await fetch('https://my-cms.com/blog-posts')).json()
+
+ return defineConfig({
+ // параметры конфигурации на уровне приложения
+ lang: 'ru-RU',
+ title: 'VitePress',
+ description: 'Генератор статических сайтов на основе Vite и Vue.',
+
+ // параметры конфигурации на уровне темы
+ themeConfig: {
+ sidebar: [
+ ...posts.map((post) => ({
+ text: post.name,
+ link: `/posts/${post.name}`
+ }))
+ ]
+ }
+ })
+}
+```
+
+Вы также можете использовать `await` верхнего уровня. Например:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+const posts = await (await fetch('https://my-cms.com/blog-posts')).json()
+
+export default defineConfig({
+ // параметры конфигурации на уровне приложения
+ lang: 'ru-RU',
+ title: 'VitePress',
+ description: 'Генератор статических сайтов на основе Vite и Vue.',
+
+ // параметры конфигурации на уровне темы
+ themeConfig: {
+ sidebar: [
+ ...posts.map((post) => ({
+ text: post.name,
+ link: `/posts/${post.name}`
+ }))
+ ]
+ }
+})
+```
+
+:::
+
+### Интеллектуальная настройка {#config-intellisense}
+
+Использование помощника `defineConfig` обеспечит интеллектуальный анализ опций конфигурации на основе TypeScript. Если ваша IDE поддерживает эту функцию, она должна работать как в JavaScript, так и в TypeScript.
+
+```js
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ // ...
+})
+```
+
+### Типизированная конфигурация темы {#typed-theme-config}
+
+По умолчанию помощник `defineConfig` ожидает тип конфигурации темы из темы по умолчанию:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ // Тип `DefaultTheme.Config`
+ }
+})
+```
+
+Если вы используете пользовательскую тему и хотите проверять типы для конфигурации темы, вам нужно использовать `defineConfigWithTheme`, и передавать тип конфигурации для вашей пользовательской темы через общий аргумент:
+
+```ts
+import { defineConfigWithTheme } from 'vitepress'
+import type { ThemeConfig } from 'your-theme'
+
+export default defineConfigWithTheme({
+ themeConfig: {
+ // Tип `ThemeConfig`
+ }
+})
+```
+
+### Настройка Vite, Vue и Markdown {#vite-vue-markdown-config}
+
+- **Vite**
+
+ Вы можете настроить базовый экземпляр Vite с помощью опции [vite](#vite) в конфигурации VitePress. Нет необходимости создавать отдельный файл конфигурации Vite.
+
+- **Vue**
+
+ VitePress уже включает в себя официальный плагин Vue для Vite ([@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue)). Вы можете настроить его параметры с помощью опции [vue](#vue) в конфигурации VitePress.
+
+- **Markdown**
+
+ Вы можете настроить базовый экземпляр [Markdown-It](https://github.com/markdown-it/markdown-it) с помощью опции [markdown](#markdown) в конфигурации VitePress.
+
+## Метаданные сайта {#site-metadata}
+
+### title {#title}
+
+- Тип: `string`
+- По умолчанию: `VitePress`
+- Можно переопределить для каждой страницы с помощью [метаданных](./frontmatter-config#title)
+
+Название для сайта. При использовании темы по умолчанию оно будет отображаться в панели навигации.
+
+Оно также будет использоваться в качестве суффикса по умолчанию для всех заголовков отдельных страниц, если не определен [`titleTemplate`](#titletemplate). Окончательный заголовок отдельной страницы будет представлять собой текстовое содержимое её первого заголовка ``, объединённое с глобальным `title` в качестве суффикса. Например, со следующей конфигурацией и содержимым страницы:
+
+```ts
+export default {
+ title: 'Мой замечательный сайт'
+}
+```
+
+```md
+# Привет
+```
+
+Заголовок страницы будет таким: `Привет | Мой замечательный сайт`.
+
+### titleTemplate {##titletemplate}
+
+- Тип: `string | boolean`
+- Можно переопределить для каждой страницы с помощью [метаданных](./frontmatter-config#titletemplate)
+
+Позволяет настраивать суффикс заголовка каждой страницы или весь заголовок. Например:
+
+```ts
+export default {
+ title: 'Мой замечательный сайт',
+ titleTemplate: 'Пользовательский суффикс'
+}
+```
+
+```md
+# Привет
+```
+
+Заголовок страницы будет таким: `Привет | Пользовательский суффикс`.
+
+Чтобы полностью настроить отображение заголовка, вы можете использовать символ `:title` в `titleTemplate`:
+
+```ts
+export default {
+ titleTemplate: ':title - Пользовательский суффикс'
+}
+```
+
+Здесь `:title` будет заменён текстом, выведенным из первого заголовка страницы ``. Заголовок страницы предыдущего примера будет `Привет - Пользовательский суффикс`.
+
+Опция может быть установлена в значение `false`, чтобы отключить суффиксы заголовков.
+
+### description {#description}
+
+- Тип: `string`
+- По умолчанию: `A VitePress site`
+- Можно переопределить для каждой страницы с помощью [метаданных](./frontmatter-config#description)
+
+Описание для сайта. Это будет отображаться как тег `` в HTML-странице.
+
+```ts
+export default {
+ description: 'A VitePress site'
+}
+```
+
+### head {#head}
+
+- Тип: `HeadConfig[]`
+- По умолчанию: `[]`
+- Можно добавлять на страницу через [метаданные](./frontmatter-config#head)
+
+Дополнительные элементы для отображения в теге `` в HTML-странице. Добавленные пользователем теги выводятся перед закрывающим тегом `head`, после тегов VitePress.
+
+```ts
+type HeadConfig =
+ | [string, Record]
+ | [string, Record, string]
+```
+
+#### Пример: Добавление значка сайта {#example-adding-a-favicon}
+
+```ts
+export default {
+ head: [['link', { rel: 'icon', href: '/favicon.ico' }]]
+} // поместите favicon.ico в публичную директорию; если установлен параметр base, используйте /base/favicon.ico
+
+/* Отрисуется так:
+
+*/
+```
+
+#### Пример: Добавление шрифтов Google {#example-adding-google-fonts}
+
+```ts
+export default {
+ head: [
+ ['link', { rel: 'preconnect', href: 'https://fonts.googleapis.com' }],
+ [
+ 'link',
+ { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }
+ ],
+ [
+ 'link',
+ {
+ href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap',
+ rel: 'stylesheet'
+ }
+ ]
+ ]
+}
+
+/* Отрисуется так:
+
+
+
+*/
+```
+
+#### Пример: Регистрация сервис-воркера {#example-registering-a-service-worker}
+
+```ts
+export default {
+ head: [
+ [
+ 'script',
+ { id: 'register-sw' },
+ `;(() => {
+ if ('serviceWorker' in navigator) {
+ navigator.serviceWorker.register('/sw.js')
+ }
+ })()`
+ ]
+ ]
+}
+
+/* Отрисуется так:
+
+*/
+```
+
+#### Пример: Использование Google Analytics {#example-using-google-analytics}
+
+```ts
+export default {
+ head: [
+ [
+ 'script',
+ { async: '', src: 'https://www.googletagmanager.com/gtag/js?id=TAG_ID' }
+ ],
+ [
+ 'script',
+ {},
+ `window.dataLayer = window.dataLayer || [];
+ function gtag(){dataLayer.push(arguments);}
+ gtag('js', new Date());
+ gtag('config', 'TAG_ID');`
+ ]
+ ]
+}
+
+/* Отрисуется так:
+
+
+*/
+```
+
+### lang {#lang}
+
+- Тип: `string`
+- По умолчанию: `en-US`
+
+Атрибут lang для сайта. Будет выглядеть как тег `` в HTML-странице.
+
+```ts
+export default {
+ lang: 'en-US'
+}
+```
+
+### base {#base}
+
+- Тип: `string`
+- По умолчанию: `/`
+
+Базовый URL-адрес, по которому будет развёрнут сайт. Этот параметр необходимо задать, если вы планируете развернуть свой сайт по подпути, например, для страниц GitHub. Если вы планируете развернуть свой сайт на `https://foo.github.io/bar/`, то вам следует установить base на `'/bar/'`. Он всегда должен начинаться и заканчиваться косой чертой.
+
+Параметр `base` автоматически добавляется ко всем URL, которые начинаются с `/` в других опциях, поэтому вам нужно указать его только один раз.
+
+```ts
+export default {
+ base: '/base/'
+}
+```
+
+## Маршрутизация {#routing}
+
+### cleanUrls {#cleanurls}
+
+- Тип: `boolean`
+- По умолчанию: `false`
+
+Если установить значение `true`, VitePress будет удалять из URL-адресов завершающий `.html`. Также смотрите [Создание чистого URL-адреса](../guide/routing#generating-clean-url).
+
+::: warning Требуется поддержка сервера
+Для включения этой функции может потребоваться дополнительная настройка на вашей хостинговой платформе. Чтобы это сработало, ваш сервер должен быть способен обслуживать `/foo.html` при посещении `/foo` **без редиректа**.
+:::
+
+### rewrites {#rewrites}
+
+- Тип: `Record`
+
+Определяет сопоставление пользовательских каталогов с URL-адресами. Дополнительную информацию см. в секции [Маршрутизация: перезапись маршрутов](../guide/routing#route-rewrites).
+
+```ts
+export default {
+ rewrites: {
+ 'source/:page': 'destination/:page'
+ }
+}
+```
+
+## Сборка {#build}
+
+### srcDir {#srcdir}
+
+- Тип: `string`
+- По умолчанию: `.`
+
+Каталог, в котором хранятся ваши страницы в формате Markdown, относительно корня проекта. Также смотрите [Корневая директория и директория с исходными файлами](../guide/routing#root-and-source-directory).
+
+```ts
+export default {
+ srcDir: './src'
+}
+```
+
+### srcExclude {#srcexclude}
+
+- Тип: `string`
+- По умолчанию: `undefined`
+
+[Шаблон](https://github.com/mrmlnc/fast-glob#pattern-syntax) для поиска файлов, которые должны быть исключены из исходного содержимого.
+
+```ts
+export default {
+ srcExclude: ['**/README.md', '**/TODO.md']
+}
+```
+
+### outDir {#outdir}
+
+- Тип: `string`
+- По умолчанию: `./.vitepress/dist`
+
+Расположение вывода сборки для сайта, относительно [корня проекта](../guide/routing#root-and-source-directory).
+
+```ts
+export default {
+ outDir: '../public'
+}
+```
+
+### assetsDir {#assetsdir}
+
+- Тип: `string`
+- По умолчанию: `assets`
+
+Укажите каталог, в котором будут храниться сгенерированные ресурсы. Путь должен находиться внутри [`outDir`](#outdir) и разрешается относительно него.
+
+```ts
+export default {
+ assetsDir: 'static'
+}
+```
+
+### cacheDir {#cachedir}
+
+- Тип: `string`
+- По умолчанию: `./.vitepress/cache`
+
+Каталог для файлов кэша, относительно [корня проекта](../guide/routing#root-and-source-directory). См. также: [cacheDir](https://vitejs.dev/config/shared-options.html#cachedir).
+
+```ts
+export default {
+ cacheDir: './.vitepress/.vite'
+}
+```
+
+### ignoreDeadLinks {#ignoredeadlinks}
+
+- Тип: `boolean | 'localhostLinks' | (string | RegExp | ((link: string) => boolean))[]`
+- По умолчанию: `false`
+
+Если установлено значение `true`, VitePress не будет завершать сборку из-за неработающих ссылок.
+
+Если установить значение `'localhostLinks'`, сборка будет завершаться при наличии неработающих ссылок, но не будет проверять ссылки `localhost`.
+
+```ts
+export default {
+ ignoreDeadLinks: true
+}
+```
+
+Это также может быть массив точных строк url, шаблонов regex или пользовательских функций фильтрации.
+
+```ts
+export default {
+ ignoreDeadLinks: [
+ // игнорировать url "/playground"
+ '/playground',
+ // игнорировать все ссылки на localhost
+ /^https?:\/\/localhost/,
+ // игнорировать все ссылки, включающие "/repl/""
+ /\/repl\//,
+ // пользовательская функция, игнорирует все ссылки, включающие "ignore"
+ (url) => {
+ return url.toLowerCase().includes('ignore')
+ }
+ ]
+}
+```
+
+### metaChunk `
+
+`buildEnd` — это хук CLI сборки, который будет запущен после завершения сборки (SSG), но до выхода из процесса VitePress CLI.
+
+```ts
+export default {
+ async buildEnd(siteConfig) {
+ // ...
+ }
+}
+```
+
+### postRender {#postrender}
+
+- Тип: `(context: SSGContext) => Awaitable`
+
+`postRender` — это хук сборки, вызываемый после завершения рендеринга SSG. Это позволит вам обрабатывать содержимое телепортов во время SSG.
+
+```ts
+export default {
+ async postRender(context) {
+ // ...
+ }
+}
+```
+
+```ts
+interface SSGContext {
+ content: string
+ teleports?: Record
+ [key: string]: any
+}
+```
+
+### transformHead {#transformhead}
+
+- Тип: `(context: TransformContext) => Awaitable`
+
+`transformHead` — это хук сборки для преобразования заголовка перед генерацией каждой страницы. Это позволит вам добавить в конфигурацию VitePress записи, которые не могут быть добавлены статически. Вам нужно только вернуть дополнительные записи, они будут автоматически объединены с существующими.
+
+::: warning ПРЕДУПРЕЖДЕНИЕ
+Не мутируйте ничего внутри `context`.
+:::
+
+```ts
+export default {
+ async transformHead(context) {
+ // ...
+ }
+}
+```
+
+```ts
+interface TransformContext {
+ page: string // например, index.md (относительно srcDir)
+ assets: string[] // все ресурсы, не относящиеся к js/css, в виде полностью разрешённых публичных URL-адресов
+ siteConfig: SiteConfig
+ siteData: SiteData
+ pageData: PageData
+ title: string
+ description: string
+ head: HeadConfig[]
+ content: string
+}
+```
+
+Обратите внимание, что этот хук вызывается только при статической генерации сайта. Он не вызывается во время разработки. Если вам нужно добавить динамические записи в голову во время разработки, вместо этого вы можете использовать хук [`transformPageData`](#transformpagedata):
+
+```ts
+export default {
+ transformPageData(pageData) {
+ pageData.frontmatter.head ??= []
+ pageData.frontmatter.head.push([
+ 'meta',
+ {
+ name: 'og:title',
+ content:
+ pageData.frontmatter.layout === 'home'
+ ? `VitePress`
+ : `${pageData.title} | VitePress`
+ }
+ ])
+ }
+}
+```
+
+#### Пример: Добавление канонического URL-адреса `` {#example-adding-a-canonical-url-link}
+
+```ts
+export default {
+ transformPageData(pageData) {
+ const canonicalUrl = `https://example.com/${pageData.relativePath}`
+ .replace(/index\.md$/, '')
+ .replace(/\.md$/, '.html')
+
+ pageData.frontmatter.head ??= []
+ pageData.frontmatter.head.push([
+ 'link',
+ { rel: 'canonical', href: canonicalUrl }
+ ])
+ }
+}
+```
+
+### transformHtml {#transformhtml}
+
+- Тип: `(code: string, id: string, context: TransformContext) => Awaitable`
+
+`transformHtml` — это хук сборки для преобразования содержимого каждой страницы перед сохранением на диск.
+
+::: warning ПРЕДУПРЕЖДЕНИЕ
+Не мутируйте ничего внутри `контекста`. Кроме того, изменение html-содержимого может вызвать проблемы с гидратацией во время выполнения.
+:::
+
+```ts
+export default {
+ async transformHtml(code, id, context) {
+ // ...
+ }
+}
+```
+
+### transformPageData {#transformpagedata}
+
+- Тип: `(pageData: PageData, context: TransformPageContext) => Awaitable | { [key: string]: any } | void>`
+
+`transformPageData` — это хук для преобразования `pageData` каждой страницы. Вы можете напрямую изменять `pageData` или возвращать изменённые значения, которые будут объединены с данными страницы.
+
+::: warning ПРЕДУПРЕЖДЕНИЕ
+Не мутируйте ничего внутри `context` и будьте осторожны, это может повлиять на производительность dev-сервера, особенно если у вас есть некоторые сетевые запросы или тяжёлые вычисления (например, генерация изображений) в хуке. Вы можете проверить `process.env.NODE_ENV === 'production'` для условной логики.
+:::
+
+```ts
+export default {
+ async transformPageData(pageData, { siteConfig }) {
+ pageData.contributors = await getPageContributors(pageData.relativePath)
+ }
+
+ // или возвращаем данные для объединения
+ async transformPageData(pageData, { siteConfig }) {
+ return {
+ contributors: await getPageContributors(pageData.relativePath)
+ }
+ }
+}
+```
+
+```ts
+interface TransformPageContext {
+ siteConfig: SiteConfig
+}
+```
diff --git a/docs/zh/guide/asset-handling.md b/docs/zh/guide/asset-handling.md
new file mode 100644
index 00000000..69259a6a
--- /dev/null
+++ b/docs/zh/guide/asset-handling.md
@@ -0,0 +1,63 @@
+# 资源处理 {#asset-handling}
+
+## 引用静态资源 {#referencing-static-assets}
+
+所有的 Markdown 文件都会被编译成 Vue 组件，并由 [Vite](https://cn.vitejs.dev/guide/assets.html) 处理。可以**并且应该**使用相对路径来引用资源：
+
+```md
+
+```
+
+可以在 Markdown 文件、主题中的 `*.vue` 组件、样式和普通的 `.css` 文件中引用静态资源，可以使用绝对路径 (基于项目根目录) 或者相对路径 (基于文件系统)。后者类似于 Vite、Vue CLI 或者 webpack 的 `file-loader` 的行为。
+
+常见的图像，媒体和字体文件会被自动检测并视作资源。
+
+::: tip 通过链接引用的文件不会视作资源
+在 Markdown 内，通过链接引用的 PDF 或者其他文档不会被自动视作资源。要使这些文件可用，你必须手动将其放在项目的 [`public`](#the-public-directory) 目录内。
+:::
+
+所有引用的资源，包括那些使用绝对路径的，都会在生产构建过程中被复制到输出目录，并使用哈希文件名。从未使用过的资源将不会被复制。小于 4kb 的图像资源将会采用 base64 内联——这可以通过 [`vite`](../reference/site-config#vite) 配置选项进行配置。
+
+所有**静态**路径引用，包括绝对路径，都应基于你的工作目录的结构。
+
+## public 目录 {#the-public-directory}
+
+有时可能需要一些静态资源，但这些资源没有直接被 Markdown 或主题组件直接引用，或者你可能想以原始文件名提供某些文件，像 `robots.txt`，favicons 和 PWA 图标这样的文件。
+
+可以将这些文件放置在[源目录](./routing#source-directory)的 `public` 目录中。例如，如果项目根目录是 `./docs`，并且使用默认源目录位置，那么 public 目录将是 `./docs/public`。
+
+放置在 `public` 中的资源将按原样复制到输出目录的根目录中。
+
+请注意，应使用根绝对路径来引用放置在 `public` 中的文件——例如，`public/icon.png` 应始终在源代码中使用 `/icon.png` 引用。
+
+## 根 URL {#base-url}
+
+如果站点没有部署在根 URL 上，则需要在 `.vitepress/config.js` 中设置 `base` 选项。例如，如果计划将站点部署到 `https://foo.github.io/bar/`，则 `base` 应设置为 `'/bar/'`(它应始终以斜杠开头和结尾)。
+
+所有静态资源路径都会被自动处理，来适应不同的 `base` 配置值。例如，如果 markdown 中有一个对 `public` 中的资源的绝对引用：
+
+```md
+
+```
+
+在这种情况下，更改 `base` 配置值时，**无需**更新该引用。
+
+但是如果你正在编写一个主题组件，它动态地链接到资源，例如一个图片，它的 `src` 基于主题配置：
+
+```vue
+![]()
+```
+
+在这种情况下，建议使用 VitePress 提供的 [`withBase` helper](../reference/runtime-api#withbase) 来包括路径：
+
+```vue
+
+
+
+ ![]()
+
+```
diff --git a/docs/zh/guide/cms.md b/docs/zh/guide/cms.md
new file mode 100644
index 00000000..916ba050
--- /dev/null
+++ b/docs/zh/guide/cms.md
@@ -0,0 +1,56 @@
+---
+outline: deep
+---
+
+# 连接到 CMS {#connecting-to-a-cms}
+
+## 一般的工作流 {#general-workflow}
+
+将 VitePress 连接到 CMS 主要围绕[动态路由](./routing#dynamic-routes)展开。在继续阅读之前，请确保了解它的工作原理。
+
+由于每个 CMS 的工作方式都不同，因此我们只能提供一个通用的工作流，你需要根据具体情况进行调整。
+
+1. 如果你的 CMS 需要身份验证，请创建一个 `.env` 文件来存储你的 API token：
+
+ ```js
+ // posts/[id].paths.js
+ import { loadEnv } from 'vitepress'
+
+ const env = loadEnv('', process.cwd())
+ ```
+
+2. 从 CMS 获取必要的数据并将其格式调整为合适的路径数据：
+
+ ```js
+ export default {
+ async paths() {
+ // 如有需要，使用相应的 CMS 客户端库
+ const data = await (await fetch('https://my-cms-api', {
+ headers: {
+ // 如有必要，可使用 token
+ }
+ })).json()
+
+ return data.map(entry => {
+ return {
+ params: { id: entry.id, /* title, authors, date 等 */ },
+ content: entry.content
+ }
+ })
+ }
+ }
+ ```
+
+3. 在页面中渲染内容：
+
+ ```md
+ # {{ $params.title }}
+
+ - by {{ $params.author }} on {{ $params.date }}
+
+
+ ```
+
+## 整合指南 {#integration-guides}
+
+如果你已经写了一篇关于如何将 VitePress 与特定的 CMS 集成的指南，请点击下面的“在 GitHub 上编辑此页面”链接将它提交到这里！
diff --git a/docs/zh/guide/custom-theme.md b/docs/zh/guide/custom-theme.md
new file mode 100644
index 00000000..e5eb760b
--- /dev/null
+++ b/docs/zh/guide/custom-theme.md
@@ -0,0 +1,222 @@
+# 自定义主题 {#using-a-custom-theme}
+
+## 解析主题 {#theme-resolving}
+
+可以通过创建一个 `.vitepress/theme/index.js` 或 `.vitepress/theme/index.ts` 文件 (即“主题入口文件”) 来启用自定义主题：
+
+```
+.
+├─ docs # 项目根目录
+│ ├─ .vitepress
+│ │ ├─ theme
+│ │ │ └─ index.js # 主题入口
+│ │ └─ config.js # 配置文件
+│ └─ index.md
+└─ package.json
+```
+
+当检测到存在主题入口文件时，VitePress 总会使用自定义主题而不是默认主题。但你可以[扩展默认主题](./extending-default-theme)来在其基础上实现更高级的自定义。
+
+## 主题接口 {#theme-interface}
+
+VitePress 自定义主题是一个对象，该对象具有如下接口：
+
+```ts
+interface Theme {
+ /**
+ * 每个页面的根布局组件
+ * @required
+ */
+ Layout: Component
+ /**
+ * 增强 Vue 应用实例
+ * @optional
+ */
+ enhanceApp?: (ctx: EnhanceAppContext) => Awaitable
+ /**
+ * 扩展另一个主题，在我们的主题之前调用它的 `enhanceApp`
+ * @optional
+ */
+ extends?: Theme
+}
+
+interface EnhanceAppContext {
+ app: App // Vue 应用实例
+ router: Router // VitePress 路由实例
+ siteData: Ref // 站点级元数据
+}
+```
+
+主题入口文件需要将主题作为默认导出来导出：
+
+```js
+// .vitepress/theme/index.js
+
+// 可以直接在主题入口导入 Vue 文件
+// VitePress 已预先配置 @vitejs/plugin-vue
+import Layout from './Layout.vue'
+
+export default {
+ Layout,
+ enhanceApp({ app, router, siteData }) {
+ // ...
+ }
+}
+```
+
+默认导出是自定义主题的唯一方式，并且只有 `Layout` 属性是必须的。所以从技术上讲，一个 VitePress 主题可以是一个单独的 Vue 组件。
+
+在组件内部，它的工作方式就像是一个普通的 Vite + Vue 3 应用。请注意，主题还需要保证 [SSR 兼容](./ssr-compat)。
+
+## 构建布局 {#building-a-layout}
+
+最基本的布局组件需要包含一个 [`Custom Layout!
+
+
+ Custom Layout!
+
+
+ Custom 404 page!
+
+ Custom Layout!
+
+
+ Custom 404 page!
+
+
+ Custom home page!
+
+ Custom Layout!
+
+ ({
+ extends: baseConfig,
+ themeConfig: {
+ // 类型为 `ThemeConfig`
+ }
+})
+```
diff --git a/docs/zh/guide/data-loading.md b/docs/zh/guide/data-loading.md
new file mode 100644
index 00000000..ae23b0d1
--- /dev/null
+++ b/docs/zh/guide/data-loading.md
@@ -0,0 +1,247 @@
+# 构建时数据加载 {#build-time-data-loading}
+
+VitePress 提供了**数据加载**的功能，它允许加载任意数据并从页面或组件中导入它。数据加载**只在构建时**执行：最终的数据将被序列化为 JavaScript 包中的 JSON。
+
+数据加载可以被用于获取远程数据，也可以基于本地文件生成元数据。例如，可以使用数据加载来解析所有本地 API 页面并自动生成所有 API 入口的索引。
+
+## 基本用法 {#basic-usage}
+
+一个用于数据加载的文件必须以 `.data.js` 或 `.data.ts` 结尾。该文件应该提供一个默认导出的对象，该对象具有 `load()` 方法：
+
+```js
+// example.data.js
+export default {
+ load() {
+ return {
+ hello: 'world'
+ }
+ }
+}
+```
+
+数据加载模块只在 Node.js 中执行，因此可以按需导入 Node API 和 npm 依赖。
+
+然后，可以在 `.md` 页面和 `.vue` 组件中使用 `data` 具名导出从该文件中导入数据：
+
+```vue
+
+
+{{ data }}
+```
+
+输出：
+
+```json
+{
+ "hello": "world"
+}
+```
+
+你会注意到 data loader 本身并没有导出 `data`。这是因为 VitePress 在后台调用了 `load()` 方法，并通过名为 `data` 的具名导出隐式地暴露了结果。
+
+即使它是异步的，这也是有效的：
+
+```js
+export default {
+ async load() {
+ // 获取远程数据
+ return (await fetch('...')).json()
+ }
+}
+```
+
+## 使用本地文件生成数据 {#data-from-local-files}
+
+当需要基于本地文件生成数据时，需要在 data loader 中使用 `watch` 选项，以便这些文件改动时可以触发热更新。
+
+`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 解析器发送到客户端。
+
+```js
+import fs from 'node:fs'
+import { parse } from 'csv-parse/sync'
+
+export default {
+ watch: ['./data/*.csv'],
+ load(watchedFiles) {
+ // watchFiles 是一个所匹配文件的绝对路径的数组。
+ // 生成一个博客文章元数据数组
+ // 可用于在主题布局中呈现列表。
+ return watchedFiles.map((file) => {
+ return parse(fs.readFileSync(file, 'utf-8'), {
+ columns: true,
+ skip_empty_lines: true
+ })
+ })
+ }
+}
+```
+
+## `createContentLoader`
+
+当构建一个内容为主的站点时，我们经常需要创建一个“归档”或“索引”页面：一个我们可以列出内容中的所有可用条目的页面，例如博客文章或 API 页面。我们**可以**直接使用数据加载 API 实现这一点，但由于这会经常使用，VitePress 还提供了一个 `createContentLoader` 辅助函数来简化这个过程：
+
+```js
+// posts.data.js
+import { createContentLoader } from 'vitepress'
+
+export default createContentLoader('posts/*.md', /* options */)
+```
+
+该辅助函数接受一个相对于[源目录](./routing#source-directory)的 glob 模式，并返回一个 `{ watch, load }` 数据加载对象，该对象可以用作数据加载文件中的默认导出。它还基于文件修改时间戳实现了缓存以提高开发性能。
+
+请注意，数据加载仅适用于 Markdown 文件——匹配的非 Markdown 文件将被跳过。
+
+加载的数据将是一个类型为 `ContentData[]` 的数组：
+
+```ts
+interface ContentData {
+ // 页面的映射 URL，如 /posts/hello.html（不包括 base）
+ // 手动迭代或使用自定义 `transform` 来标准化路径
+ url: string
+ // 页面的 frontmatter 数据
+ frontmatter: Record
+
+ // 只有启用了相关选项，才会出现以下内容
+ // 我们将在下面讨论它们
+ src: string | undefined
+ html: string | undefined
+ excerpt: string | undefined
+}
+```
+
+默认情况下只提供 `url` 和 `frontmatter`。这是因为加载的数据将作为 JSON 内联在客户端 bundle 中，我们需要谨慎考虑其大小。下面的例子展示了如何使用数据构建最小的博客索引页面：
+
+```vue
+
+
+
+ All Blog Posts
+
+ -
+ {{ post.frontmatter.title }}
+ by {{ post.frontmatter.author }}
+
+
+
+```
+
+### 选项 {#options}
+
+默认数据可能不适合所有需求——可以选择使用选项转换数据：
+
+```js
+// posts.data.js
+import { createContentLoader } from 'vitepress'
+
+export default createContentLoader('posts/*.md', {
+ includeSrc: true, // 包含原始 markdown 源?
+ render: true, // 包含渲染的整页 HTML?
+ excerpt: true, // 包含摘录?
+ transform(rawData) {
+ // 根据需要对原始数据进行 map、sort 或 filter
+ // 最终的结果是将发送给客户端的内容
+ return rawData.sort((a, b) => {
+ return +new Date(b.frontmatter.date) - +new Date(a.frontmatter.date)
+ }).map((page) => {
+ page.src // 原始 markdown 源
+ page.html // 渲染的整页 HTML
+ page.excerpt // 渲染的摘录 HTML（第一个 `---` 上面的内容）
+ return {/* ... */}
+ })
+ }
+})
+```
+
+查看它在 [Vue.js 博客](https://github.com/vuejs/blog/blob/main/.vitepress/theme/posts.data.ts)中是如何使用的。
+
+`createContentLoader` API 也可以在[构建钩子](/reference/site-config#build-hooks)中使用：
+
+```js
+// .vitepress/config.js
+export default {
+ async buildEnd() {
+ const posts = await createContentLoader('posts/*.md').load()
+ // 根据 posts 元数据生成文件，如 RSS 订阅源
+ }
+}
+```
+
+**类型**
+
+```ts
+interface ContentOptions {
+ /**
+ * 包含 src?
+ * @default false
+ */
+ includeSrc?: boolean
+
+ /**
+ * 将 src 渲染为 HTML 并包含在数据中?
+ * @default false
+ */
+ render?: boolean
+
+ /**
+ * 如果为 `boolean`，是否解析并包含摘录? (呈现为 HTML)
+ *
+ * 如果为 `function`，则控制如何从内容中提取摘录
+ *
+ * 如果为 `string`，则定义用于提取摘录的自定义分隔符
+ * 如果 `excerpt` 为 `true`，则默认分隔符为 `---`
+ *
+ * @see https://github.com/jonschlinkert/gray-matter#optionsexcerpt
+ * @see https://github.com/jonschlinkert/gray-matter#optionsexcerpt_separator
+ *
+ * @default false
+ */
+ excerpt?:
+ | boolean
+ | ((file: { data: { [key: string]: any }; content: string; excerpt?: string }, options?: any) => void)
+ | string
+
+ /**
+ * 转换数据。请注意，如果从组件或 Markdown 文件导入，数据将以 JSON 形式内联到客户端包中
+ */
+ transform?: (data: ContentData[]) => T | Promise
+}
+```
+
+## 为 data loader 导出类型 {#typed-data-loaders}
+
+当使用 TypeScript 时，可以像这样为 loader 和 `data` 导出类型：
+
+```ts
+import { defineLoader } from 'vitepress'
+
+export interface Data {
+ // data 类型
+}
+
+declare const data: Data
+export { data }
+
+export default defineLoader({
+ // 类型检查加载器选项
+ watch: ['...'],
+ async load(): Promise {
+ // ...
+ }
+})
+```
+
+## 配置 {#configuration}
+
+要获取 data loader 中的配置信息，可以使用如下代码：
+
+```ts
+import type { SiteConfig } from 'vitepress'
+
+const config: SiteConfig = (globalThis as any).VITEPRESS_CONFIG
+```
diff --git a/docs/zh/guide/deploy.md b/docs/zh/guide/deploy.md
new file mode 100644
index 00000000..cb479305
--- /dev/null
+++ b/docs/zh/guide/deploy.md
@@ -0,0 +1,289 @@
+---
+outline: deep
+---
+
+# 部署 VitePress 站点 {#deploy-your-vitepress-site}
+
+以下指南基于一些前提：
+
+- VitePress 站点位于项目的 `docs` 目录中。
+- 你使用的是默认的生成输出目录 （`.vitepress/dist`）。
+- VitePress 作为本地依赖项安装在项目中，并且你已在 `package.json` 中设置以下脚本：
+
+ ```json
+ {
+ "scripts": {
+ "docs:build": "vitepress build docs",
+ "docs:preview": "vitepress preview docs"
+ }
+ }
+ ```
+
+## 本地构建与测试 {#build-and-test-locally}
+
+1. 可以运行以下命令来构建文档：
+
+ ```sh
+ $ npm run docs:build
+ ```
+
+2. 构建文档后，通过运行以下命令可以在本地预览它：
+
+ ```sh
+ $ npm run docs:preview
+ ```
+
+ `preview` 命令将启动一个本地静态 Web 服务 `http://localhost:4173`，该服务以 `.vitepress/dist` 作为源文件。这是检查生产版本在本地环境中是否正常的一种简单方法。
+
+3. 可以通过传递 `--port` 作为参数来配置服务器的端口。
+
+ ```json
+ {
+ "scripts": {
+ "docs:preview": "vitepress preview docs --port 8080"
+ }
+ }
+ ```
+
+ 现在 `docs:preview` 方法将会在 `http://localhost:8080` 启动服务。
+
+## 设定 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-cache-headers}
+
+如果可以控制生产服务器上的 HTTP 标头，则可以配置 `cache-control` 标头以在重复访问时获得更好的性能。
+
+生产版本对静态资源 (JavaScript、CSS 和其他非 `public` 目录中的导入资源) 使用哈希文件名。如果你使用浏览器开发工具的网络选项卡查看生产预览，你将看到类似 `app.4f283b18.js` 的文件。
+
+此哈希 `4f283b18` 是从此文件的内容生成的。相同的哈希 URL 保证提供相同的文件内容——如果内容更改，URL 也会更改。这意味着你可以安全地为这些文件使用最强的缓存标头。所有此类文件都将放置在输出目录的 `assets/` 中，因此你可以为它们配置以下标头：
+
+```
+Cache-Control: max-age=31536000,immutable
+```
+
+::: details Netlify 示例 `_headers` 文件
+
+```
+/assets/*
+ cache-control: max-age=31536000
+ cache-control: immutable
+```
+
+注意：该 `_headers` 文件应放置在 [public 目录](/guide/asset-handling#the-public-directory)中 (在我们的例子中是 `docs/public/_headers`)，以便将其逐字复制到输出目录。
+
+[Netlify 自定义标头文档](https://docs.netlify.com/routing/headers/)
+
+:::
+
+::: details Vercel 配置示例 `vercel.json`
+
+```json
+{
+ "headers": [
+ {
+ "source": "/assets/(.*)",
+ "headers": [
+ {
+ "key": "Cache-Control",
+ "value": "max-age=31536000, immutable"
+ }
+ ]
+ }
+ ]
+}
+```
+
+注意：`vercel.json` 文件应放在存储库的根目录中。
+
+[Vercel 关于标头配置的文档](https://vercel.com/docs/concepts/projects/project-configuration#headers)
+
+:::
+
+## 各平台部署指南 {#platform-guides}
+
+### Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render
+
+使用仪表板创建新项目并更改这些设置：
+
+- **构建命令：** `npm run docs:build`
+- **输出目录：** `docs/.vitepress/dist`
+- **node 版本：** `18` (或更高版本)
+
+::: warning
+不要为 HTML 代码启用 _Auto Minify_ 等选项。它将从输出中删除对 Vue 有意义的注释。如果被删除，你可能会看到激活不匹配错误。
+:::
+
+### GitHub Pages
+
+1. 在项目的 `.github/workflows` 目录中创建一个名为 `deploy.yml` 的文件，其中包含这样的内容：
+
+ ```yaml
+ # 构建 VitePress 站点并将其部署到 GitHub Pages 的示例工作流程
+ #
+ name: Deploy VitePress site to Pages
+
+ on:
+ # 在针对 `main` 分支的推送上运行。如果你
+ # 使用 `master` 分支作为默认分支，请将其更改为 `master`
+ push:
+ branches: [main]
+
+ # 允许你从 Actions 选项卡手动运行此工作流程
+ workflow_dispatch:
+
+ # 设置 GITHUB_TOKEN 的权限，以允许部署到 GitHub Pages
+ permissions:
+ contents: read
+ pages: write
+ id-token: write
+
+ # 只允许同时进行一次部署，跳过正在运行和最新队列之间的运行队列
+ # 但是，不要取消正在进行的运行，因为我们希望允许这些生产部署完成
+ concurrency:
+ group: pages
+ cancel-in-progress: false
+
+ jobs:
+ # 构建工作
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+ with:
+ fetch-depth: 0 # 如果未启用 lastUpdated，则不需要
+ # - uses: pnpm/action-setup@v3 # 如果使用 pnpm，请取消注释
+ # - uses: oven-sh/setup-bun@v1 # 如果使用 Bun，请取消注释
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version: 20
+ cache: npm # 或 pnpm / yarn
+ - name: Setup Pages
+ uses: actions/configure-pages@v4
+ - name: Install dependencies
+ run: npm ci # 或 pnpm install / yarn install / bun install
+ - name: Build with VitePress
+ run: npm run docs:build # 或 pnpm docs:build / yarn docs:build / bun run docs:build
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v3
+ with:
+ path: docs/.vitepress/dist
+
+ # 部署工作
+ deploy:
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ needs: build
+ runs-on: ubuntu-latest
+ name: Deploy
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4
+ ```
+
+ ::: warning
+ 确保 VitePress 中的 `base` 选项配置正确。有关更多详细信息，请参阅[设置根路径](#setting-a-public-base-path)。
+ :::
+
+2. 在存储库设置中的“Pages”菜单项下，选择“Build and deployment > Source > GitHub Actions”。
+
+3. 将更改推送到 `main` 分支并等待 GitHub Action 工作流完成。你应该看到站点部署到 `https://.github.io/[repository]/` 或 `https:///`，这取决于你的设置。你的站点将在每次推送到 `main` 分支时自动部署。
+
+### GitLab Pages
+
+1. 如果你想部署到 `https:// .gitlab.io/ /`，将 VitePress 配置中的 `outDir` 设置为 `../public`。将 `base` 选项配置为 `'//'`。
+
+2. 在项目的根目录中创建一个名为 `.gitlab-ci.yml` 的文件，其中包含以下内容。每当你更改内容时，这都会构建和部署你的站点：
+
+ ```yaml
+ image: node:18
+ pages:
+ cache:
+ paths:
+ - node_modules/
+ script:
+ # - apk add git # 如果你使用的是像 alpine 这样的小型 docker 镜像，并且启用了 lastUpdated，请取消注释
+ - npm install
+ - npm run docs:build
+ artifacts:
+ paths:
+ - public
+ only:
+ - main
+ ```
+
+### Azure 静态 web 应用 {#azure-static-web-apps}
+
+1. 参考[官方文档](https://docs.microsoft.com/en-us/azure/static-web-apps/build-configuration)。
+
+2. 在配置文件中设置这些值 (并删除不需要的值，如 `api_location`)：
+
+ - **`app_location`**: `/`
+ - **`output_location`**: `docs/.vitepress/dist`
+ - **`app_build_command`**: `npm run docs:build`
+
+### Firebase {#firebase}
+
+1. 在项目的根目录下创建 `firebase.json` 和 `.firebaserc`：
+
+ `firebase.json`:
+
+ ```json
+ {
+ "hosting": {
+ "public": "docs/.vitepress/dist",
+ "ignore": []
+ }
+ }
+ ```
+
+ `.firebaserc`:
+
+ ```json
+ {
+ "projects": {
+ "default": ""
+ }
+ }
+ ```
+
+2. 运行 `npm run docs:build` 后，运行此命令进行部署：
+
+ ```sh
+ firebase deploy
+ ```
+
+### Surge
+
+1. 运行 `npm run docs:build` 后，运行此命令进行部署：
+
+ ```sh
+ npx surge docs/.vitepress/dist
+ ```
+
+### Heroku
+
+1. 参考 [`heroku-buildpack-static`](https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-static) 中给出的文档和指南。
+
+2. 使用以下内容在项目的根目录中创建一个名为 `static.json` 的文件：
+
+ ```json
+ {
+ "root": "docs/.vitepress/dist"
+ }
+ ```
+
+### Edgio
+
+请参阅[创建并部署 VitePress 应用程序到 Edgio](https://docs.edg.io/guides/vitepress)。
+
+### Kinsta 静态站点托管 {#kinsta-static-site-hosting}
+
+你可以按照这些[说明](https://kinsta.com/docs/vitepress-static-site-example/) 在 [Kinsta](https://kinsta.com/static-site-hosting/) 上部署 Vitepress 站点。
diff --git a/docs/zh/guide/extending-default-theme.md b/docs/zh/guide/extending-default-theme.md
new file mode 100644
index 00000000..4bb495fa
--- /dev/null
+++ b/docs/zh/guide/extending-default-theme.md
@@ -0,0 +1,340 @@
+---
+outline: deep
+---
+
+# 扩展默认主题 {#extending-the-default-theme}
+
+VitePress 默认的主题已经针对文档进行了优化，并且可以进行自定义。请参考[默认主题配置概览](../reference/default-theme-config)获取完整的选项列表。
+
+但是有一些情况仅靠配置是不够的。例如：
+
+1. 需要调整 CSS 样式；
+2. 需要修改 Vue 应用实例，例如注册全局组件；
+3. 需要通过 layout 插槽将自定义内容注入到主题中；
+
+这些高级自定义配置将需要使用自定义主题来“拓展”默认主题。
+
+:::tip
+在继续之前，请确保首先阅读[自定义主题](./custom-theme)以了解其工作原理。
+:::
+
+## 自定义 CSS {#customizing-css}
+
+可以通过覆盖根级别的 CSS 变量来自定义默认主题的 CSS：
+
+```js
+// .vitepress/theme/index.js
+import DefaultTheme from 'vitepress/theme'
+import './custom.css'
+
+export default DefaultTheme
+```
+
+```css
+/* .vitepress/theme/custom.css */
+:root {
+ --vp-c-brand-1: #646cff;
+ --vp-c-brand-2: #747bff;
+}
+```
+
+查看[默认主题 CSS 变量](https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css)来获取可以被覆盖的变量。
+
+## 使用自定义字体 {#using-different-fonts}
+
+VitePress 使用 [Inter](https://rsms.me/inter/) 作为默认字体，并且将其包含在生成的输出中。该字体在生产环境中也会自动预加载。但是如果要使用不同的字体，这可能不是很好。
+
+为了避免在生成后的输出中包含 Inter 字体，请从 `vitepress/theme-without-fonts` 中导入主题：
+
+```js
+// .vitepress/theme/index.js
+import DefaultTheme from 'vitepress/theme-without-fonts'
+import './my-fonts.css'
+
+export default DefaultTheme
+```
+
+```css
+/* .vitepress/theme/custom.css */
+:root {
+ --vp-font-family-base: /* normal text font */
+ --vp-font-family-mono: /* code font */
+}
+```
+
+::: warning
+如果你在使用像是[团队页](/reference/default-theme-team-page)这样的组件，请确保也从 `vitepress/theme-without-fonts` 中导入它们！
+:::
+
+如果字体是通过 `@font-face` 引用的本地文件，它将会被作为资源被包含在 `.vitepress/dist/asset` 目录下，并且使用哈希后的文件名。为了预加载这个文件，请使用 [transformHead](/reference/site-config#transformhead) 构建钩子：
+
+```js
+// .vitepress/config.js
+export default {
+ transformHead({ assets }) {
+ // 相应地调整正则表达式以匹配字体
+ const myFontFile = assets.find(file => /font-name\.\w+\.woff2/)
+ if (myFontFile) {
+ return [
+ [
+ 'link',
+ {
+ rel: 'preload',
+ href: myFontFile,
+ as: 'font',
+ type: 'font/woff2',
+ crossorigin: ''
+ }
+ ]
+ ]
+ }
+ }
+}
+```
+
+## 注册全局组件 {#registering-global-components}
+
+```js
+// .vitepress/theme/index.js
+import DefaultTheme from 'vitepress/theme'
+
+/** @type {import('vitepress').Theme} */
+export default {
+ extends: DefaultTheme,
+ enhanceApp({ app }) {
+ // 注册自定义全局组件
+ app.component('MyGlobalComponent' /* ... */)
+ }
+}
+```
+
+如果使用 TypeScript:
+```ts
+// .vitepress/theme/index.ts
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+
+export default {
+ extends: DefaultTheme,
+ enhanceApp({ app }) {
+ // 注册自定义全局组件
+ app.component('MyGlobalComponent' /* ... */)
+ }
+} satisfies Theme
+```
+
+因为我们使用 Vite，还可以利用 Vite 的 [glob 导入功能](https://cn.vitejs.dev/guide/features.html#glob-import)来自动注册一个组件目录。
+
+## 布局插槽 {#layout-slots}
+
+默认主题的 `
+
+ My custom sidebar top content
+
+
+
+```
+
+也可以使用渲染函数。
+
+```js
+// .vitepress/theme/index.js
+import { h } from 'vue'
+import DefaultTheme from 'vitepress/theme'
+import MyComponent from './MyComponent.vue'
+
+export default {
+ extends: DefaultTheme,
+ Layout() {
+ return h(DefaultTheme.Layout, null, {
+ 'aside-outline-before': () => h(MyComponent)
+ })
+ }
+}
+```
+
+默认主题布局的全部可用插槽如下：
+
+- 当 `layout: 'doc'` (默认) 在 frontmatter 中被启用时：
+ - `doc-top`
+ - `doc-bottom`
+ - `doc-footer-before`
+ - `doc-before`
+ - `doc-after`
+ - `sidebar-nav-before`
+ - `sidebar-nav-after`
+ - `aside-top`
+ - `aside-bottom`
+ - `aside-outline-before`
+ - `aside-outline-after`
+ - `aside-ads-before`
+ - `aside-ads-after`
+- 当 `layout: 'home'` 在 frontmatter 中被启用时:
+ - `home-hero-before`
+ - `home-hero-info-before`
+ - `home-hero-info`
+ - `home-hero-info-after`
+ - `home-hero-actions-after`
+ - `home-hero-image`
+ - `home-hero-after`
+ - `home-features-before`
+ - `home-features-after`
+- 当 `layout: 'page'` 在 frontmatter 中被启用时:
+ - `page-top`
+ - `page-bottom`
+- 当未找到页面 (404) 时:
+ - `not-found`
+- 总是启用:
+ - `layout-top`
+ - `layout-bottom`
+ - `nav-bar-title-before`
+ - `nav-bar-title-after`
+ - `nav-bar-content-before`
+ - `nav-bar-content-after`
+ - `nav-screen-content-before`
+ - `nav-screen-content-after`
+
+## 使用视图过渡 API
+
+### 关于外观切换 {#on-appearance-toggle}
+
+可以扩展默认主题以在切换颜色模式时提供自定义过渡动画。例如：
+
+```vue
+
+
+
+
+
+ Demo
+
+
+
+
+
+有关视图过渡动画的更多详细信息，请参阅 [Chrome 文档](https://developer.chrome.com/docs/web-platform/view-transitions/)。
+
+### 路由切换时 {#on-route-change}
+
+即将到来。
+
+## 重写内部组件 {#overriding-internal-components}
+
+可以使用 Vite 的 [aliases](https://vitejs.dev/config/shared-options.html#resolve-alias) 来用自定义组件替换默认主题的组件：
+
+```ts
+import { fileURLToPath, URL } from 'node:url'
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ vite: {
+ resolve: {
+ alias: [
+ {
+ find: /^.*\/VPNavBar\.vue$/,
+ replacement: fileURLToPath(
+ new URL('./components/CustomNavBar.vue', import.meta.url)
+ )
+ }
+ ]
+ }
+ }
+})
+```
+
+想要了解组件的确切名称请参考我们的[源代码](https://github.com/vuejs/vitepress/tree/main/src/client/theme-default/components)。因为组件是内部的，因此在小版本更迭中，它们名字改动的可能性很小。
diff --git a/docs/zh/guide/frontmatter.md b/docs/zh/guide/frontmatter.md
new file mode 100644
index 00000000..4bcec7ea
--- /dev/null
+++ b/docs/zh/guide/frontmatter.md
@@ -0,0 +1,48 @@
+# frontmatter
+
+## 用法 {#usage}
+
+VitePress 支持在所有 Markdown 文件中使用 YAML frontmatter，并使用 [gray-matter](https://github.com/jonschlinkert/gray-matter) 解析。frontmatter 必须位于 Markdown 文件的顶部 (在任何元素之前，包括 `
+
+
+ , 或者 。需要配置 PostCSS 插件，使用 `:where([dir="ltr"])` 和 `:where([dir="rtl"])` 作为前缀，以防止 CSS 特异性问题。
diff --git a/docs/zh/guide/markdown.md b/docs/zh/guide/markdown.md
new file mode 100644
index 00000000..b5dc779d
--- /dev/null
+++ b/docs/zh/guide/markdown.md
@@ -0,0 +1,928 @@
+# Markdown 扩展 {#markdown-extensions}
+
+VitePress 带有内置的 Markdown 扩展。
+
+## 标题锚点 {#header-anchors}
+
+标题会自动应用锚点。可以使用 `markdown.anchor` 选项配置锚点的渲染。
+
+### 自定义锚点 {#custom-anchors}
+
+要为标题指定自定义锚点而不是使用自动生成的锚点，请向标题添加后缀：
+
+```
+# 使用自定义锚点 {#my-anchor}
+```
+
+这允许将标题链接为 `#my-anchor`，而不是默认的 `#使用自定义锚点`。
+
+## 链接 {#links}
+
+内部和外部链接都会被特殊处理。
+
+### 内部链接 {#internal-links}
+
+内部链接将转换为单页导航的路由链接。此外，子目录中包含的每个 `index.md` 都会自动转换为 `index.html`，并带有相应的 URL `/`。
+
+例如，给定以下目录结构：
+
+```
+.
+├─ index.md
+├─ foo
+│ ├─ index.md
+│ ├─ one.md
+│ └─ two.md
+└─ bar
+ ├─ index.md
+ ├─ three.md
+ └─ four.md
+```
+
+假设现在处于 `foo/one.md` 文件中：
+
+```md
+[Home](/)
+[foo](/foo/)
+[foo heading](./#heading)
+[bar - three](../bar/three)
+[bar - three](../bar/three.md)
+[bar - four](../bar/four.html)
+```
+
+### 页面后缀 {#page-suffix}
+
+默认情况下，生成的页面和内部链接带有 `.html` 后缀。
+
+### 外部链接 {#external-links}
+
+外部链接带有 `target="_blank" rel="noreferrer"`：
+
+- [vuejs.org](https://cn.vuejs.org)
+- [VitePress on GitHub](https://github.com/vuejs/vitepress)
+
+## frontmatter {#frontmatter}
+
+[YAML 格式的 frontmatter](https://jekyllrb.com/docs/front-matter/) 开箱即用：
+
+```yaml
+---
+title: Blogging Like a Hacker
+lang: en-US
+---
+```
+
+此数据将可用于页面的其余部分，以及所有自定义和主题组件。
+
+更多信息，参见 [frontmatter](../reference/frontmatter-config)。
+
+## GitHub 风格的表格 {#github-style-tables}
+
+**输入**
+
+```
+| Tables | Are | Cool |
+| ------------- | :-----------: | ----: |
+| col 3 is | right-aligned | $1600 |
+| col 2 is | centered | $12 |
+| zebra stripes | are neat | $1 |
+```
+
+**输出**
+
+| Tables | Are | Cool |
+| ------------- | :-----------: | -----: |
+| col 3 is | right-aligned | \$1600 |
+| col 2 is | centered | \$12 |
+| zebra stripes | are neat | \$1 |
+
+## Emoji :tada:
+
+**输入**
+
+```
+:tada: :100:
+```
+
+**输出**
+
+:tada: :100:
+
+这里可以找到[所有支持的 emoji 列表](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/full.mjs)。
+
+## 目录表 (TOC) {#table-of-contents}
+
+**输入**
+
+```
+[[toc]]
+```
+
+**输出**
+
+[[toc]]
+
+可以使用 `markdown.toc` 选项配置 TOC 的呈现效果。
+
+## 自定义容器 {#custom-containers}
+
+自定义容器可以通过它们的类型、标题和内容来定义。
+
+### 默认标题 {#default-title}
+
+**输入**
+
+```md
+::: info
+This is an info box.
+:::
+
+::: tip
+This is a tip.
+:::
+
+::: warning
+This is a warning.
+:::
+
+::: danger
+This is a dangerous warning.
+:::
+
+::: details
+This is a details block.
+:::
+```
+
+**输出**
+
+::: info
+This is an info box.
+:::
+
+::: tip
+This is a tip.
+:::
+
+::: warning
+This is a warning.
+:::
+
+::: danger
+This is a dangerous warning.
+:::
+
+::: details
+This is a details block.
+:::
+
+### 自定义标题 {#custom-title}
+
+可以通过在容器的 "type" 之后附加文本来设置自定义标题。
+
+**输入**
+
+````md
+::: danger STOP
+危险区域，请勿继续
+:::
+
+::: details 点我查看代码
+```js
+console.log('Hello, VitePress!')
+```
+:::
+````
+
+**输出**
+
+::: danger STOP
+危险区域，请勿继续
+:::
+
+::: details 点我查看代码
+```js
+console.log('Hello, VitePress!')
+```
+:::
+
+此外，可以通过在站点配置中添加以下内容来全局设置自定义标题，如果不是用英语书写，这会很有帮助：
+
+```ts
+// config.ts
+export default defineConfig({
+ // ...
+ markdown: {
+ container: {
+ tipLabel: '提示',
+ warningLabel: '警告',
+ dangerLabel: '危险',
+ infoLabel: '信息',
+ detailsLabel: '详细信息'
+ }
+ }
+ // ...
+})
+```
+
+### `raw`
+
+这是一个特殊的容器，可以用来防止与 VitePress 的样式和路由冲突。这在记录组件库时特别有用。可能还想查看 [whyframe](https://whyframe.dev/docs/integrations/vitepress) 以获得更好的隔离。
+
+**语法**
+
+```md
+::: raw
+Wraps in a
+:::
+```
+
+`vp-raw` class 也可以直接用于元素。样式隔离目前是可选的：
+
+- 使用喜欢的包管理器来安装需要的依赖项：
+
+ ```sh
+ $ npm add -D postcss
+ ```
+
+- 创建 `docs/.postcssrc.cjs` 文件并将以下内容添加到其中：
+
+ ```js
+ import { postcssIsolateStyles } from 'vitepress'
+
+ export default {
+ plugins: [postcssIsolateStyles()]
+ }
+ ```
+
+ 它在底层使用 [`postcss-prefix-selector`](https://github.com/postcss/postcss-load-config)。你可以像这样传递它的选项：
+
+ ```js
+ postcssIsolateStyles({
+ includeFiles: [/vp-doc\.css/] // 默认为 /base\.css/
+ })
+ ```
+
+## 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)的渲染方式相同。
+
+```md
+> [!NOTE]
+> 强调用户在快速浏览文档时也不应忽略的重要信息。
+
+> [!TIP]
+> 有助于用户更顺利达成目标的建议性信息。
+
+> [!IMPORTANT]
+> 对用户达成目标至关重要的信息。
+
+> [!WARNING]
+> 因为可能存在风险，所以需要用户立即关注的关键内容。
+
+> [!CAUTION]
+> 行为可能带来的负面影响。
+```
+
+> [!NOTE]
+> 强调用户在快速浏览文档时也不应忽略的重要信息。
+
+> [!TIP]
+> 有助于用户更顺利达成目标的建议性信息。
+
+> [!IMPORTANT]
+> 对用户达成目标至关重要的信息。
+
+> [!WARNING]
+> 因为可能存在风险，所以需要用户立即关注的关键内容。
+
+> [!CAUTION]
+> 行为可能带来的负面影响。
+
+## 代码块中的语法高亮 {#syntax-highlighting-in-code-blocks}
+
+VitePress 使用 [Shiki](https://github.com/shikijs/shiki) 在 Markdown 代码块中使用彩色文本实现语法高亮。Shiki 支持多种编程语言。需要做的就是将有效的语言别名附加到代码块的开头：
+
+**输入**
+
+````
+```js
+export default {
+ name: 'MyComponent',
+ // ...
+}
+```
+````
+
+````
+```html
+
+ -
+ {{ todo.text }}
+
+
+```
+````
+
+**输出**
+
+```js
+export default {
+ name: 'MyComponent'
+ // ...
+}
+```
+
+```html
+
+ -
+ {{ todo.text }}
+
+
+```
+
+在 Shiki 的代码仓库中，可以找到[合法的编程语言列表](https://shiki.style/languages)。
+
+还可以全局配置中自定义语法高亮主题。有关详细信息，参见 [`markdown` 选项](../reference/site-config#markdown)得到更多信息。
+
+## 在代码块中实现行高亮 {#line-highlighting-in-code-blocks}
+
+**输入**
+
+````
+```js{4}
+export default {
+ data () {
+ return {
+ msg: 'Highlighted!'
+ }
+ }
+}
+```
+````
+
+**输出**
+
+```js{4}
+export default {
+ data () {
+ return {
+ msg: 'Highlighted!'
+ }
+ }
+}
+```
+
+除了单行之外，还可以指定多个单行、多行，或两者均指定：
+
+- 多行：例如 `{5-8}`、`{3-10}`、`{10-17}`
+- 多个单行：例如 `{4,7,9}`
+- 多行与单行：例如 `{4,7-13,16,23-27,40}`
+
+**输入**
+
+````
+```js{1,4,6-8}
+export default { // Highlighted
+ data () {
+ return {
+ msg: `Highlighted!
+ This line isn't highlighted,
+ but this and the next 2 are.`,
+ motd: 'VitePress is awesome',
+ lorem: 'ipsum'
+ }
+ }
+}
+```
+````
+
+**输出**
+
+```js{1,4,6-8}
+export default { // Highlighted
+ data () {
+ return {
+ msg: `Highlighted!
+ This line isn't highlighted,
+ but this and the next 2 are.`,
+ motd: 'VitePress is awesome',
+ lorem: 'ipsum',
+ }
+ }
+}
+```
+
+也可以使用 `// [!code highlight]` 注释实现行高亮。
+
+**输入**
+
+````
+```js
+export default {
+ data () {
+ return {
+ msg: 'Highlighted!' // [!!code highlight]
+ }
+ }
+}
+```
+````
+
+**输出**
+
+```js
+export default {
+ data() {
+ return {
+ msg: 'Highlighted!' // [!code highlight]
+ }
+ }
+}
+```
+
+## 代码块中聚焦 {#focus-in-code-blocks}
+
+在某一行上添加 `// [!code focus]` 注释将聚焦它并模糊代码的其他部分。
+
+此外，可以使用 `// [!code focus:]` 定义要聚焦的行数。
+
+**输入**
+
+````
+```js
+export default {
+ data () {
+ return {
+ msg: 'Focused!' // [!!code focus]
+ }
+ }
+}
+```
+````
+
+**输出**
+
+```js
+export default {
+ data() {
+ return {
+ msg: 'Focused!' // [!code focus]
+ }
+ }
+}
+```
+
+## 代码块中的颜色差异 {#colored-diffs-in-code-blocks}
+
+在某一行添加 `// [!code --]` 或 `// [!code ++]` 注释将会为该行创建 diff，同时保留代码块的颜色。
+
+**输入**
+
+````
+```js
+export default {
+ data () {
+ return {
+ msg: 'Removed' // [!!code --]
+ msg: 'Added' // [!!code ++]
+ }
+ }
+}
+```
+````
+
+**输出**
+
+```js
+export default {
+ data () {
+ return {
+ msg: 'Removed' // [!code --]
+ msg: 'Added' // [!code ++]
+ }
+ }
+}
+```
+
+## 高亮“错误”和“警告” {#errors-and-warnings-in-code-blocks}
+
+在某一行添加 `// [!code warning]` 或 `// [!code error]` 注释将会为该行相应的着色。
+
+**输入**
+
+````
+```js
+export default {
+ data () {
+ return {
+ msg: 'Error', // [!!code error]
+ msg: 'Warning' // [!!code warning]
+ }
+ }
+}
+```
+````
+
+**输出**
+
+```js
+export default {
+ data() {
+ return {
+ msg: 'Error', // [!code error]
+ msg: 'Warning' // [!code warning]
+ }
+ }
+}
+```
+
+## 行号 {#line-numbers}
+
+可以通过以下配置为每个代码块启用行号：
+
+```js
+export default {
+ markdown: {
+ lineNumbers: true
+ }
+}
+```
+
+查看 [`markdown` 选项](../reference/site-config#markdown) 获取更多信息。
+
+可以在代码块中添加 `:line-numbers` / `:no-line-numbers` 标记来覆盖在配置中的设置。
+
+还可以通过在 `:line-numbers` 之后添加 `=` 来自定义起始行号，例如 `:line-numbers=2` 表示代码块中的行号从 2 开始。
+
+**输入**
+
+````md
+```ts {1}
+// 默认禁用行号
+const line2 = 'This is line 2'
+const line3 = 'This is line 3'
+```
+
+```ts:line-numbers {1}
+// 启用行号
+const line2 = 'This is line 2'
+const line3 = 'This is line 3'
+```
+
+```ts:line-numbers=2 {1}
+// 行号已启用，并从 2 开始
+const line3 = 'This is line 3'
+const line4 = 'This is line 4'
+```
+````
+
+**输出**
+
+```ts {1}
+// 默认禁用行号
+const line2 = 'This is line 2'
+const line3 = 'This is line 3'
+```
+
+```ts:line-numbers {1}
+// 启用行号
+const line2 = 'This is line 2'
+const line3 = 'This is line 3'
+```
+
+```ts:line-numbers=2 {1}
+// 行号已启用，并从 2 开始
+const line3 = 'This is line 3'
+const line4 = 'This is line 4'
+```
+
+## 导入代码片段 {#import-code-snippets}
+
+可以通过下面的语法来从现有文件中导入代码片段：
+
+```md
+<<< @/filepath
+```
+
+此语法同时支持[行高亮](#line-highlighting-in-code-blocks)：
+
+```md
+<<< @/filepath{highlightLines}
+```
+
+**输入**
+
+```md
+<<< @/snippets/snippet.js{2}
+```
+
+**Code file**
+
+<<< @/snippets/snippet.js
+
+**输出**
+
+<<< @/snippets/snippet.js{2}
+
+::: tip
+`@` 的值对应于源代码根目录，默认情况下是 VitePress 项目根目录，除非配置了 `srcDir`。或者也可以从相对路径导入：
+
+```md
+<<< ../snippets/snippet.js
+```
+
+:::
+
+也可以使用 [VS Code region](https://code.visualstudio.com/docs/editor/codebasics#_folding) 来只包含代码文件的相应部分。可以在文件目录后面的 `#` 符号后提供一个自定义的区域名：
+
+**输入**
+
+```md
+<<< @/snippets/snippet-with-region.js#snippet{1}
+```
+
+**Code file**
+
+<<< @/snippets/snippet-with-region.js
+
+**输出**
+
+<<< @/snippets/snippet-with-region.js#snippet{1}
+
+也可以像这样在大括号内(`{}`)指定语言：
+
+```md
+<<< @/snippets/snippet.cs{c#}
+
+
+
+<<< @/snippets/snippet.cs{1,2,4-6 c#}
+
+
+
+<<< @/snippets/snippet.cs{1,2,4-6 c#:line-numbers}
+```
+
+如果无法从文件扩展名推测出源语言，这将会很有帮助
+
+## 代码组 {#code-groups}
+
+可以像这样对多个代码块进行分组：
+
+**输入**
+
+````md
+::: code-group
+
+```js [config.js]
+/**
+ * @type {import('vitepress').UserConfig}
+ */
+const config = {
+ // ...
+}
+
+export default config
+```
+
+```ts [config.ts]
+import type { UserConfig } from 'vitepress'
+
+const config: UserConfig = {
+ // ...
+}
+
+export default config
+```
+
+:::
+````
+
+**输出**
+
+::: code-group
+
+```js [config.js]
+/**
+ * @type {import('vitepress').UserConfig}
+ */
+const config = {
+ // ...
+}
+
+export default config
+```
+
+```ts [config.ts]
+import type { UserConfig } from 'vitepress'
+
+const config: UserConfig = {
+ // ...
+}
+
+export default config
+```
+
+:::
+
+也可以在代码组中[导入代码片段](#import-code-snippets)：
+
+**输入**
+
+```md
+::: code-group
+
+
+
+<<< @/snippets/snippet.js
+
+
+
+<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region]
+
+:::
+```
+
+**输出**
+
+::: code-group
+
+<<< @/snippets/snippet.js
+
+<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region]
+
+:::
+
+## 包含 markdown 文件 {#markdown-file-inclusion}
+
+可以像这样在一个 markdown 文件中包含另一个 markdown 文件，甚至是内嵌的。
+
+::: tip
+也可以使用 `@`，它的值对应于源代码根目录，默认情况下是 VitePress 项目根目录，除非配置了 `srcDir`。
+:::
+
+例如，可以这样用相对路径包含 Markdown 文件：
+
+**输入**
+
+```md
+# Docs
+
+## Basics
+
+
+```
+
+**Part file** (`parts/basics.md`)
+
+```md
+Some getting started stuff.
+
+### Configuration
+
+Can be created using `.foorc.json`.
+```
+
+**等价代码**
+
+```md
+# Docs
+
+## Basics
+
+Some getting started stuff.
+
+### Configuration
+
+Can be created using `.foorc.json`.
+```
+
+它还支持选择行范围：
+
+**输入**
+
+```md
+# Docs
+
+## Basics
+
+
+```
+
+**Part file** (`parts/basics.md`)
+
+```md
+Some getting started stuff.
+
+### Configuration
+
+Can be created using `.foorc.json`.
+```
+
+**等价代码**
+
+```md
+# Docs
+
+## Basics
+
+### Configuration
+
+Can be created using `.foorc.json`.
+```
+
+所选行范围的格式可以是： `{3,}`、 `{,10}`、`{1,10}`
+
+::: warning
+如果指定的文件不存在，这将不会产生错误。因此，在使用这个功能的时候请保证内容按预期呈现。
+:::
+
+## 数学方程 {#math-equations}
+
+现在这是可选的。要启用它, 需要安装 `markdown-it-mathjax3`，在配置文件中设置`markdown.math` 为 `true`：
+
+```sh
+npm add -D markdown-it-mathjax3
+```
+
+```ts
+// .vitepress/config.ts
+export default {
+ markdown: {
+ math: true
+ }
+}
+```
+
+**输入**
+
+```md
+When $a \ne 0$, there are two solutions to $(ax^2 + bx + c = 0)$ and they are
+$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
+
+**Maxwell's equations:**
+
+| equation | description |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| $\nabla \cdot \vec{\mathbf{B}} = 0$ | divergence of $\vec{\mathbf{B}}$ is zero |
+| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}$ | curl of $\vec{\mathbf{E}}$ is proportional to the rate of change of $\vec{\mathbf{B}}$ |
+| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _wha?_ |
+```
+
+**输出**
+
+When $a \ne 0$, there are two solutions to $(ax^2 + bx + c = 0)$ and they are
+$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
+
+**Maxwell's equations:**
+
+| equation | description |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| $\nabla \cdot \vec{\mathbf{B}} = 0$ | divergence of $\vec{\mathbf{B}}$ is zero |
+| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}$ | curl of $\vec{\mathbf{E}}$ is proportional to the rate of change of $\vec{\mathbf{B}}$ |
+| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _wha?_ |
+
+## 图片懒加载 {#image-lazy-loading}
+
+通过在配置文件中将 `lazyLoading` 设置为 `true`，可以为通过 markdown 添加的每张图片启用懒加载。
+
+```js
+export default {
+ markdown: {
+ image: {
+ // 默认禁用图片懒加载
+ lazyLoading: true
+ }
+ }
+}
+```
+
+## 高级配置 {#advanced-configuration}
+
+VitePress 使用 [markdown-it](https://github.com/markdown-it/markdown-it) 作为 Markdown 渲染器。上面提到的很多扩展功能都是通过自定义插件实现的。可以使用 `.vitepress/config.js` 中的 `markdown` 选项来进一步自定义 `markdown-it` 实例。
+
+```js
+import { defineConfig } from 'vitepress'
+import markdownItAnchor from 'markdown-it-anchor'
+import markdownItFoo from 'markdown-it-foo'
+
+export default defineConfig({
+ markdown: {
+ // markdown-it-anchor 的选项
+ // https://github.com/valeriangalliat/markdown-it-anchor#usage
+ anchor: {
+ permalink: markdownItAnchor.permalink.headerLink()
+ },
+ // @mdit-vue/plugin-toc 的选项
+ // https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
+ toc: { level: [1, 2] },
+ config: (md) => {
+ // 使用更多的 Markdown-it 插件！
+ md.use(markdownItFoo)
+ }
+ }
+})
+```
+
+请查看[配置参考：站点配置](../reference/site-config#markdown)来获取完整的可配置属性列表。
diff --git a/docs/zh/guide/migration-from-vitepress-0.md b/docs/zh/guide/migration-from-vitepress-0.md
new file mode 100644
index 00000000..fc2bf97a
--- /dev/null
+++ b/docs/zh/guide/migration-from-vitepress-0.md
@@ -0,0 +1,23 @@
+n# 从 VitePress 0.x 迁移 {#migration-from-vitepress-0-x}
+
+如果你来自 VitePress 0.x 版本，VitePress 有了一些重大更改。请按照本指南了解如何将应用程序迁移到最新的 VitePress。
+
+## 应用配置 {#app-config}
+
+- 国际化功能尚未实现。
+
+## 主题配置 {#theme-config}
+
+- `sidebar` 选项改变了它的结构。
+ - `children` 现在命名为 `items`。
+ - 顶级侧边栏不包含 `link`。我们打算把它改回来。
+- 删除了 `repo`、`repoLabel`、`docsDir`、`docsBranch`、`editLinks`、`editLinkText`，以支持更灵活的api。
+ - 要将带有图标的 GitHub 链接添加到导航，请使用 [社交链接](../reference/default-theme-config#nav) 功能。
+ - 要添加“编辑此页面”功能，请使用 [编辑链接](../reference/default-theme-edit-link) 功能。
+- `lastUpdated` 选项现在分为` config.lastUpdated` 和 `themeConfig.lastUpdatedText`。
+- `carbonAds.carbon` 更改为 `carbonAds.code`.
+
+## frontmatter 配置 {#frontmatter-config}
+
+- `home: true` 选项已更改为 `layout: home`。此外，还修改了许多与主页相关的设置以提供附加功能。详情请参阅 [主页指南](../reference/default-theme-home-page)。
+- `footer` 选项移至 [`themeConfig.footer`](../reference/default-theme-footer).
diff --git a/docs/zh/guide/migration-from-vuepress.md b/docs/zh/guide/migration-from-vuepress.md
new file mode 100644
index 00000000..c21000cc
--- /dev/null
+++ b/docs/zh/guide/migration-from-vuepress.md
@@ -0,0 +1,30 @@
+# 从 VuePress 迁移 {#migration-from-vuepress}
+
+## 配置 {#config}
+
+### 侧边栏 {#sidebar}
+
+侧边栏不再从 frontmatter 中自动获取。你可以自行阅读 [`frontmatter`](https://github.com/vuejs/vitepress/issues/572#issuecomment-1170116225) 来动态填充侧边栏。[迁移工具](https://github.com/vuejs/vitepress/issues/96)将来可能会提供。
+
+## Markdown {#markdown}
+
+### 图片 {#images}
+
+与 VuePress 不同，在使用静态图片时，VitePress 会根据配置自动处理这些 [`base`](./asset-handling#base-url)。
+
+因此，现在可以在没有 `img` 标签的情况下渲染图像。
+
+```diff
+- ![foo]()
++ 
+```
+
+::: warning
+对于动态图像，仍然需要 `withBase`，如 [Base URL](./asset-handling#base-url) 中所示。
+:::
+
+使用 `` 正则表达式查找并替换为 `` 用 `` 语法替换所有图像。
+
+---
+
+更多请继续关注...
diff --git a/docs/zh/guide/mpa-mode.md b/docs/zh/guide/mpa-mode.md
new file mode 100644
index 00000000..80bf92f7
--- /dev/null
+++ b/docs/zh/guide/mpa-mode.md
@@ -0,0 +1,23 @@
+# MPA 模式 ` 标签，可以启用 [`lastUpdated`](../reference/default-theme-last-updated) 选项。
+
+## 选项 {#options}
+
+VitePress 的 sitemap 由 [`sitemap`](https://www.npmjs.com/package/sitemap) 模块提供支持。可以将该模块支持的选项传递给配置文件中的 `sitemap` 选项。这些选项将直接传递给 `SitemapStream` 构造函数。有关更多详细信息，请参阅 [`sitemap` 文档](https://www.npmjs.com/package/sitemap#options-you-can-pass)。例如：
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ sitemap: {
+ hostname: 'https://example.com',
+ lastmodDateOnly: false
+ }
+})
+```
+
+## `transformItems` Hook
+
+在将 sitemap 写入 `sitemap.xml` 文件之前，可以使用 `sitemap.transformItems` 钩子来修改 sitemap。使用 sitemap 调用该钩子，应返回 sitemap 数组。例如：
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ sitemap: {
+ hostname: 'https://example.com',
+ transformItems: (items) => {
+ // 添加新选项或修改/过滤现有选项
+ items.push({
+ url: '/extra-page',
+ changefreq: 'monthly',
+ priority: 0.8
+ })
+ return items
+ }
+ }
+})
+```
diff --git a/docs/zh/guide/ssr-compat.md b/docs/zh/guide/ssr-compat.md
new file mode 100644
index 00000000..0e980f4a
--- /dev/null
+++ b/docs/zh/guide/ssr-compat.md
@@ -0,0 +1,136 @@
+---
+outline: deep
+---
+
+# SSR 兼容性 {#ssr-compatibility}
+
+通过使用 Vue 的服务器端渲染 (SSR) 功能，VitePress 能够在生产构建期间在 Node.js 中预渲染应用程序。这意味着主题组件中的所有自定义代码都需要考虑 SSR 兼容性。
+
+[Vue 官方文档的 SSR 部分](https://cn.vuejs.org/guide/scaling-up/ssr.html)提供了更多有关 SSR 是什么，SSR / SSG 之间的关系以及编写 SSR 友好的代码的常见注意事项等信息。原则上只在 Vue 组件的 `beforeMount` 或 `mounted` 钩子中访问浏览器或 DOM API。
+
+## ``
+
+如果正在使用或演示不支持 SSR 的组件 (例如，包含自定义指令)，则可以将它们包装在内置的 `` 组件中：
+
+```md
+
+
+```
+
+## 在导入时访问浏览器 API 的库 {#libraries-that-access-browser-api-on-import}
+
+一些组件或库在**导入时**访问浏览器 API。要使用假定在导入时处于浏览器环境的代码，需要动态导入它们。
+
+### 在 mounted 钩子中导入 {#importing-in-mounted-hook}
+
+```vue
+
+```
+
+### 条件导入 {#conditional-import}
+
+也可以使用 `import.meta.env.SSR` 标志 ([Vite 环境变量](https://cn.vitejs.dev/guide/env-and-mode.html#env-variables)的一部分) 来有条件地导入依赖项：
+
+```js
+if (!import.meta.env.SSR) {
+ import('./lib-that-access-window-on-import').then((module) => {
+ // use code
+ })
+}
+```
+
+因为 [`Theme.enhanceApp`](/guide/custom-theme#theme-interface) 可以是异步的，所以可以有条件地导入并注册访问浏览器 API 的 Vue 插件：
+
+```js
+// .vitepress/theme/index.js
+/** @type {import('vitepress').Theme} */
+export default {
+ // ...
+ async enhanceApp({ app }) {
+ if (!import.meta.env.SSR) {
+ const plugin = await import('plugin-that-access-window-on-import')
+ app.use(plugin.default)
+ }
+ }
+}
+```
+
+如果使用 TypeScript:
+```ts
+// .vitepress/theme/index.ts
+import type { Theme } from 'vitepress'
+
+export default {
+ // ...
+ async enhanceApp({ app }) {
+ if (!import.meta.env.SSR) {
+ const plugin = await import('plugin-that-access-window-on-import')
+ app.use(plugin.default)
+ }
+ }
+} satisfies Theme
+```
+
+### `defineClientComponent`
+
+VitePress 为导入 Vue 组件提供了一个方便的辅助函数，该组件可以在导入时访问浏览器 API。
+
+```vue
+
+
+
+ ` 组件中，或者通过 [postRender 钩子](../reference/site-config#postrender)将 teleport 标签注入到最终页面 HTML 中的正确位置。
+
+
+
+
+ // ...
+
+
+
+```
+
+
+
+
diff --git a/docs/zh/guide/what-is-vitepress.md b/docs/zh/guide/what-is-vitepress.md
new file mode 100644
index 00000000..cee35162
--- /dev/null
+++ b/docs/zh/guide/what-is-vitepress.md
@@ -0,0 +1,57 @@
+# VitePress 是什么？ {#what-is-vitepress}
+
+VitePress 是一个[静态站点生成器](https://en.wikipedia.org/wiki/Static_site_generator) (SSG)，专为构建快速、以内容为中心的站点而设计。简而言之，VitePress 获取用 Markdown 编写的内容，对其应用主题，并生成可以轻松部署到任何地方的静态 HTML 页面。
+
+
+
+只是想尝试一下？跳到[快速开始](./getting-started)。
+
+
+
+## 使用场景 {#use-cases}
+
+- **文档**
+
+ 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://cn.vuejs.org/)也是基于 VitePress 的。但是为了可以在不同的翻译文档之间切换，它自定义了自己的主题。
+
+- **博客、档案和营销网站**
+
+ VitePress 支持[完全的自定义主题](./custom-theme)，具有标准 Vite + Vue 应用程序的开发体验。基于 Vite 构建还意味着可以直接利用其生态系统中丰富的 Vite 插件。此外，VitePress 提供了灵活的 API 来[加载数据](./data-loading) (本地或远程)，也可以[动态生成路由](./routing#dynamic-routes)。只要可以在构建时确定数据，就可以使用它来构建几乎任何东西。
+
+ [Vue.js 官方博客](https://blog.vuejs.org/)是一个简单的博客页面，它根据本地内容生成其索引页面。
+
+## 开发体验 {#developer-experience}
+
+VitePress 旨在使用 Markdown 生成内容时提供出色的开发体验。
+
+- **[Vite 驱动](https://cn.vitejs.dev/)**：即时服务器启动，始终立即反映 (<100ms) 编辑变化，无需重新加载页面。
+
+- **[内置 Markdown 扩展](./markdown)**：frontmatter、表格、语法高亮……应有尽有。具体来说，VitePress 提供了许多用于处理代码块的高级功能，使其真正成为技术文档的理想选择。
+
+- **[Vue 增强的 Markdown](./using-vue)**：每个 Markdown 页面都是 Vue [单文件组件](https://cn.vuejs.org/guide/scaling-up/sfc.html)，这要归功于 Vue 模板与 HTML 的 100% 语法兼容性。可以使用 Vue 模板语法或导入的 Vue 组件在静态内容中嵌入交互性。
+
+## 性能 {#performance}
+
+与许多传统的 SSG 不同，每次导航都会导致页面完全重新加载，VitePress 生成的网站在初次访问时提供静态 HTML，但它变成了[单页应用程序](https://en.wikipedia.org/wiki/Single-page_application)（SPA）进行站点内的后续导航。我们认为，这种模式为性能提供了最佳平衡：
+
+- **快速的初始加载**
+
+ 对任何页面的初次访问都将会是静态的、预呈现的 HTML，以实现极快的加载速度和最佳的 SEO。然后页面加载一个 JavaScript bundle，将页面变成 Vue SPA (这被称为“激活”)。与 SPA 激活缓慢的常见假设不同，由于 Vue 3 良好的原始性能和编译优化，这个过程实际上非常快。在 [PageSpeed Insights](https://pagespeed.web.dev/report?url=https%3A%2F%2Fvitepress.dev%2F) 上，典型的 VitePress 站点即使在网络速度较慢的低端移动设备上也能获得近乎完美的性能分数。
+
+- **加载完成后可以快速切换**
+
+ 更重要的是，SPA 模型在首次加载后能够提升用户体验。用户在站点内导航时，不会再触发整个页面的刷新。而是通过获取并动态更新页面的内容来实现切换。VitePress 还会自动预加载视口范围内链接对应的页面片段。这样一来，大部分情况下，用户在加载完成后就能立即浏览新页面。
+
+- **高效的交互**
+
+ 为了能够嵌入静态 Markdown 中的动态 Vue 部分，每个 Markdown 页面都被处理为 Vue 组件并编译成 JavaScript。这听起来可能效率低下，但 Vue 编译器足够聪明，可以将静态和动态部分分开，从而最大限度地减少激活成本和有效负载大小。对于初始的页面加载，静态部分会自动从 JavaScript 有效负载中删除，并在激活期间跳过。
+
+## VuePress 又是什么？ {#what-about-vuepress}
+
+VitePress 灵感来源于 VuePress。最初的 VuePress 基于 Vue 2 和 webpack。借助 Vue 3 和 Vite，VitePress 提供了更好的开发体验、更好的生产性能、更精美的默认主题和更灵活的自定义 API。
+
+VitePress 和 VuePress 之间的 API 区别主要在于主题和自定义。如果使用的是带有默认主题的 VuePress 1，迁移到 VitePress 应该相对简单。
+
+VuePress 2 我们也投入了精力，它也支持 Vue 3 和 Vite，与 VuePress 1 的兼容性更好。但是，并行维护两个 SSG 是难以持续的，因此 Vue 团队决定将重点放在 VitePress，作为长期的主要 SSG 选择推荐。
diff --git a/docs/zh/index.md b/docs/zh/index.md
new file mode 100644
index 00000000..23299c1f
--- /dev/null
+++ b/docs/zh/index.md
@@ -0,0 +1,59 @@
+---
+layout: home
+
+title: VitePress
+titleTemplate: 由 Vite 和 Vue 驱动的静态站点生成器
+
+hero:
+ name: VitePress
+ text: 由 Vite 和 Vue 驱动的静态站点生成器
+ tagline: 将 Markdown 变成优雅的文档，只需几分钟
+ actions:
+ - theme: brand
+ text: 什么是 VitePress?
+ link: /zh/guide/what-is-vitepress
+ - theme: alt
+ text: 快速开始
+ link: /zh/guide/getting-started
+ - theme: alt
+ text: GitHub
+ link: https://github.com/vuejs/vitepress
+ image:
+ src: /vitepress-logo-large.webp
+ alt: VitePress
+
+features:
+ - icon: 📝
+ title: 专注内容
+ details: 只需 Markdown 即可轻松创建美观的文档站点。
+ - icon:
+ title: 享受 Vite 无可比拟的体验
+ details: 服务器即时启动，闪电般的热更新，还可以使用基于 Vite 生态的插件。
+ - icon:
+ title: 使用 Vue 自定义
+ details: 直接在 Markdown 中使用 Vue 语法和组件，或者使用 Vue 组件构建自定义主题。
+ - icon: 🚀
+ title: 速度真的很快！
+ details: 采用静态 HTML 实现快速的页面初次加载，使用客户端路由实现快速的页面切换导航。
+---
+
diff --git a/docs/zh/reference/cli.md b/docs/zh/reference/cli.md
new file mode 100644
index 00000000..71d892c6
--- /dev/null
+++ b/docs/zh/reference/cli.md
@@ -0,0 +1,74 @@
+# 命令行接口 {#command-line-interface}
+
+## `vitepress dev`
+
+使用指定目录作为根目录来启动 VitePress 开发服务器。默认为当前目录。在当前目录下运行时也可以省略 `dev` 命令。
+
+### 用法
+
+```sh
+# 从当前目录启动，省略 `dev`
+vitepress
+
+# 从子目录启动
+vitepress dev [root]
+```
+
+### 选项 {#options}
+
+| 选项 | 说明 |
+| --------------- | ------------------------------------------ |
+| `--open [path]` | 启动时打开浏览器 (`boolean \| string`) |
+| `--port ` | 指定端口 (`number`) |
+| `--base ` | public base URL (默认值: `/`) (`string`) |
+| `--cors` | 启用 CORS |
+| `--strictPort` | 如果指定的端口已被占用则退出 (`boolean`) |
+| `--force` | 强制优化程序忽略缓存并重新绑定 (`boolean`) |
+
+## `vitepress build`
+
+构建用于生产环境的 VitePress 站点。
+
+### 用法
+
+```sh
+vitepress build [root]
+```
+
+### 选项\
+
+| 选项 | 说明 |
+| ------------------------------ | ------------------------------------------------------------------------------------------------- |
+| `--mpa` (experimental) | [MPA 模式](../guide/mpa-mode) 下构建，无需客户端激活 (`boolean`) |
+| `--base ` | public base URL (默认值: `/`) (`string`) |
+| `--target ` | 转译目标 (默认值：`"modules"`) (`string`) |
+| `--outDir ` | 输出目录 (默认值：`.vitepress/dist`) (`string`) |
+| `--minify [minifier]` | 启用/禁用压缩，或指定要使用的压缩程序 (默认值：`"esbuild"`) (`boolean \| "terser" \| "esbuild"`) |
+| `--assetsInlineLimit ` | 静态资源 base64 内联阈值（以字节为单位）(默认值：`4096`) (`number`) |
+
+## `vitepress preview`
+
+在本地预览生产版本。
+
+### 用法
+
+```sh
+vitepress preview [root]
+```
+
+### 选项
+
+| 选项 | 说明 |
+| --------------- | -------------------------------------- |
+| `--base ` | public base URL (默认值: `/`) (`string`) |
+| `--port ` | 指定端口 (`number`) |
+
+## `vitepress init`
+
+在当前目录中启动[安装向导](../guide/getting-started#setup-wizard)。
+
+### 用法
+
+```sh
+vitepress init
+```
diff --git a/docs/zh/reference/default-theme-badge.md b/docs/zh/reference/default-theme-badge.md
new file mode 100644
index 00000000..c19cb129
--- /dev/null
+++ b/docs/zh/reference/default-theme-badge.md
@@ -0,0 +1,69 @@
+# 徽标 {#badge}
+
+徽标可让你为标题添加状态。例如，指定部分的类型或支持的版本可能很有用。
+
+## 用法 {#usage}
+
+可以使用全局组件 `Badge` 。
+
+```html
+### Title ` 接受 `children`，这将显示在徽标中。
+
+```html
+### Title custom element
+```
+
+### Title custom element
+
+## 自定义不同类型徽标的背景色 {#customize-type-color}
+
+可以通过覆盖 css 来自定义不同类型 ``
+
+`` 组件接受以下属性：
+
+```ts
+interface Props {
+ // 当传递 `` 时，该值将被忽略
+ text?: string
+
+ // 默认为 `tip`.
+ type?: 'info' | 'tip' | 'warning' | 'danger'
+}
+```
diff --git a/docs/zh/reference/default-theme-carbon-ads.md b/docs/zh/reference/default-theme-carbon-ads.md
new file mode 100644
index 00000000..1633b281
--- /dev/null
+++ b/docs/zh/reference/default-theme-carbon-ads.md
@@ -0,0 +1,22 @@
+# Carbon Ads {#carbon-ads}
+
+VitePress 内置了对 [Carbon Ads](https://www.carbonads.net/) 的原生支持。通过在配置中定义 Carbon Ads 凭据，VitePress 将在页面上显示广告。
+
+```js
+export default {
+ themeConfig: {
+ carbonAds: {
+ code: 'your-carbon-code',
+ placement: 'your-carbon-placement'
+ }
+ }
+}
+```
+
+这些值用于调用 carbon CDN 脚本，如下所示。
+
+```js
+`//cdn.carbonads.com/carbon.js?serve=${code}&placement=${placement}`
+```
+
+要了解有关 Carbon Ads 配置的更多信息，请访问 [Carbon Ads 站点](https://www.carbonads.net/)。
diff --git a/docs/zh/reference/default-theme-config.md b/docs/zh/reference/default-theme-config.md
new file mode 100644
index 00000000..a7028f16
--- /dev/null
+++ b/docs/zh/reference/default-theme-config.md
@@ -0,0 +1,452 @@
+# 默认主题配置 {#default-theme-config}
+
+主题配置可以让你能够自定义主题。可以通过将 `themeConfig` 添加到配置文件来进行主题配置：
+
+```ts
+export default {
+ lang: 'en-US',
+ title: 'VitePress',
+ description: 'Vite & Vue powered static site generator.',
+
+ // 主题相关配置
+ themeConfig: {
+ logo: '/logo.svg',
+ nav: [...],
+ sidebar: { ... }
+ }
+}
+```
+
+**此页面上记录的选项仅适用于默认主题**。不同的主题需要不同的主题配置。使用自定义主题时，主题配置对象将传递给主题，以便主题可以基于它作出不同表现。
+
+## i18nRouting
+
+- 类型：`boolean`
+
+将本地语言更改为 `zh` 会将 URL 从 `/foo`（或 `/en/foo/`）更改为 `/zh/foo`。可以通过将 `themeConfig.i18nRouting` 设置为 `false` 来禁用此行为。
+
+## logo
+
+- 类型：`ThemeableImage`
+
+导航栏上显示的 Logo，位于站点标题前。可以接受一个路径字符串，或者一个对象来设置在浅色/深色模式下不同的 Logo。
+
+```ts
+export default {
+ themeConfig: {
+ logo: '/logo.svg'
+ }
+}
+```
+
+```ts
+type ThemeableImage =
+ | string
+ | { src: string; alt?: string }
+ | { light: string; dark: string; alt?: string }
+```
+
+## siteTitle
+
+- 类型：`string | false`
+
+可以自定义此项以替换导航中的默认站点标题 (应用配置中的 `title`)。当设置为 `false` 时，导航中的标题将被禁用。这在当 `logo` 已经包含站点标题文本时很有用。
+
+```ts
+export default {
+ themeConfig: {
+ siteTitle: 'Hello World'
+ }
+}
+```
+
+## nav
+
+- 类型：`NavItem`
+
+导航菜单项的配置。可以在[默认主题: 导航栏](./default-theme-nav#navigation-links) 了解更多详情。
+
+```ts
+export default {
+ themeConfig: {
+ nav: [
+ { text: 'Guide', link: '/guide' },
+ {
+ text: 'Dropdown Menu',
+ items: [
+ { text: 'Item A', link: '/item-1' },
+ { text: 'Item B', link: '/item-2' },
+ { text: 'Item C', link: '/item-3' }
+ ]
+ }
+ ]
+ }
+}
+```
+
+```ts
+type NavItem = NavItemWithLink | NavItemWithChildren
+
+interface NavItemWithLink {
+ text: string
+ link: string
+ activeMatch?: string
+ target?: string
+ rel?: string
+ noIcon?: boolean
+}
+
+interface NavItemChildren {
+ text?: string
+ items: NavItemWithLink[]
+}
+
+interface NavItemWithChildren {
+ text?: string
+ items: (NavItemChildren | NavItemWithLink)[]
+ activeMatch?: string
+}
+```
+
+## sidebar
+
+- 类型：`Sidebar`
+
+侧边栏菜单项的配置。可以在[默认主题: 侧边栏](./default-theme-sidebar)了解更多详情。
+
+```ts
+export default {
+ themeConfig: {
+ sidebar: [
+ {
+ text: 'Guide',
+ items: [
+ { text: 'Introduction', link: '/introduction' },
+ { text: 'Getting Started', link: '/getting-started' },
+ ...
+ ]
+ }
+ ]
+ }
+}
+```
+
+```ts
+export type Sidebar = SidebarItem[] | SidebarMulti
+
+export interface SidebarMulti {
+ [path: string]: SidebarItem[]
+}
+
+export type SidebarItem = {
+ /**
+ * 侧边栏项的文本标签
+ */
+ text?: string
+
+ /**
+ * 侧边栏项的链接
+ */
+ link?: string
+
+ /**
+ * 侧边栏项的子项
+ */
+ items?: SidebarItem[]
+
+ /**
+ * 如果未指定，侧边栏组不可折叠
+ *
+ * 如果为 `true`，则侧边栏组可折叠并且默认折叠
+ *
+ * 如果为 `false`，则侧边栏组可折叠但默认展开
+ */
+ collapsed?: boolean
+}
+```
+
+## aside
+
+- 类型：`boolean | 'left'`
+- 默认值：`true`
+- 每个页面可以通过 [frontmatter](./frontmatter-config#aside) 覆盖
+
+将此值设置为 `false` 可禁用 aside 容器。\
+将此值设置为 `true` 将在页面右侧渲染。\
+将此值设置为 `left` 将在页面左侧渲染。
+
+如果想对所有页面禁用它，应该使用 `outline: false`。
+
+## outline
+
+- 类型：`Outline | Outline['level'] | false`
+- 每个页面可以通过 [frontmatter](./frontmatter-config#outline) 覆盖层级
+
+将此值设置为 `false` 可禁止渲染大纲容器。更多详情请参考该接口：
+
+```ts
+interface Outline {
+ /**
+ * outline 中要显示的标题级别。
+ * 单个数字表示只显示该级别的标题。
+ * 如果传递的是一个元组，第一个数字是最小级别，第二个数字是最大级别。
+ * `'deep'` 与 `[2, 6]` 相同，将显示从 `` 到 `` 的所有标题。
+ *
+ * @default 2
+ */
+ level?: number | [number, number] | 'deep'
+
+ /**
+ * 显示在 outline 上的标题。
+ *
+ * @default 'On this page'
+ */
+ label?: string
+}
+```
+
+## socialLinks
+
+- 类型：`SocialLink[]`
+
+可以定义此选项以在导航栏中展示带有图标的社交帐户链接。
+
+```ts
+export default {
+ themeConfig: {
+ socialLinks: [
+ { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
+ { icon: 'twitter', link: '...' },
+ // 可以通过将 SVG 作为字符串传递来添加自定义图标：
+ {
+ icon: {
+ svg: ''
+ },
+ link: '...',
+ // 也可以为无障碍添加一个自定义标签 (可选但推荐):
+ ariaLabel: 'cool link'
+ }
+ ]
+ }
+}
+```
+
+```ts
+interface SocialLink {
+ icon: SocialLinkIcon
+ link: string
+ ariaLabel?: string
+}
+
+type SocialLinkIcon =
+ | 'discord'
+ | 'facebook'
+ | 'github'
+ | 'instagram'
+ | 'linkedin'
+ | 'mastodon'
+ | 'npm'
+ | 'slack'
+ | 'twitter'
+ | 'x'
+ | 'youtube'
+ | { svg: string }
+```
+
+## footer
+
+- 类型：`Footer`
+- 可以通过 [frontmatter](./frontmatter-config#footer) 进行覆盖。
+
+页脚配置。可以添加 message 和 copyright。由于设计原因，仅当页面不包含侧边栏时才会显示页脚。
+
+```ts
+export default {
+ themeConfig: {
+ footer: {
+ message: 'Released under the MIT License.',
+ copyright: 'Copyright © 2019-present Evan You'
+ }
+ }
+}
+```
+
+```ts
+export interface Footer {
+ message?: string
+ copyright?: string
+}
+```
+
+## editLink
+
+- 类型：`EditLink`
+- 每个页面可以通过 [frontmatter](./frontmatter-config#editlink) 覆盖
+
+编辑链接可让显示链接以编辑 Git 管理服务 (例如 GitHub 或 GitLab) 上的页面。有关详细信息，请参阅[默认主题：编辑链接](./default-theme-edit-link)。
+
+```ts
+export default {
+ themeConfig: {
+ editLink: {
+ pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
+ text: 'Edit this page on GitHub'
+ }
+ }
+}
+```
+
+```ts
+export interface EditLink {
+ pattern: string
+ text?: string
+}
+```
+
+## lastUpdated
+
+- 类型：`LastUpdatedOptions`
+
+允许自定义上次更新的文本和日期格式。
+
+```ts
+export default {
+ themeConfig: {
+ lastUpdated: {
+ text: 'Updated at',
+ formatOptions: {
+ dateStyle: 'full',
+ timeStyle: 'medium'
+ }
+ }
+ }
+}
+```
+
+```ts
+export interface LastUpdatedOptions {
+ /**
+ * @default 'Last updated'
+ */
+ text?: string
+
+ /**
+ * @default
+ * { dateStyle: 'short', timeStyle: 'short' }
+ */
+ formatOptions?: Intl.DateTimeFormatOptions & { forceLocale?: boolean }
+}
+```
+
+## algolia
+
+- 类型：`AlgoliaSearch`
+
+支持使用 [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch) 搜索站点文档。在[默认主题：搜索](./default-theme-search) 中了解更多信息。
+
+```ts
+export interface AlgoliaSearchOptions extends DocSearchProps {
+ locales?: Record>
+}
+```
+
+在[这里](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts)查看完整配置。
+
+## carbonAds {#carbon-ads}
+
+- 类型：`CarbonAdsOptions`
+
+一个配置即可展示 [Carbon Ads](https://www.carbonads.net/)。
+
+```ts
+export default {
+ themeConfig: {
+ carbonAds: {
+ code: 'your-carbon-code',
+ placement: 'your-carbon-placement'
+ }
+ }
+}
+```
+
+```ts
+export interface CarbonAdsOptions {
+ code: string
+ placement: string
+}
+```
+
+在 [Default Theme: Carbon Ads](./default-theme-carbon-ads) 中了解更多信息。
+
+## docFooter
+
+- 类型：`DocFooter`
+
+可用于自定义出现在上一页和下一页链接上方的文本。如果不是用英语编写文档，这很有帮助。也可用于全局禁用上一页/下一页链接。如果想有选择地启用/禁用上一个/下一个链接，可以使用 [frontmatter](./default-theme-prev-next-links)。
+
+```ts
+export default {
+ themeConfig: {
+ docFooter: {
+ prev: 'Pagina prior',
+ next: 'Proxima pagina'
+ }
+ }
+}
+```
+
+```ts
+export interface DocFooter {
+ prev?: string | false
+ next?: string | false
+}
+```
+
+## darkModeSwitchLabel
+
+- 类型：`string`
+- 默认值：`Appearance`
+
+用于自定义深色模式开关标签，该标签仅在移动端视图中显示。
+
+## lightModeSwitchTitle
+
+- 类型：`string`
+- 默认值：`Switch to light theme`
+
+用于自定义悬停时显示的浅色模式开关标题。
+
+## darkModeSwitchTitle
+
+- 类型：`string`
+- 默认值：`Switch to dark theme`
+
+用于自定义悬停时显示的深色模式开关标题。
+
+## sidebarMenuLabel
+
+- 类型：`string`
+- 默认值：`Menu`
+
+用于自定义侧边栏菜单标签，该标签仅在移动端视图中显示。
+
+## returnToTopLabel
+
+- 类型：`string`
+- 默认值：`Return to top`
+
+用于自定义返回顶部按钮的标签，该标签仅在移动端视图中显示。
+
+## langMenuLabel
+
+- 类型：`string`
+- 默认值：`Change language`
+
+用于自定义导航栏中语言切换按钮的 aria-label，仅当使用 [i18n](../guide/i18n) 时才使用此选项。
+
+## externalLinkIcon
+
+- 类型：`boolean`
+- 默认值：`false`
+
+是否在 markdown 中的外部链接旁显示外部链接图标。
diff --git a/docs/zh/reference/default-theme-edit-link.md b/docs/zh/reference/default-theme-edit-link.md
new file mode 100644
index 00000000..92f3cd25
--- /dev/null
+++ b/docs/zh/reference/default-theme-edit-link.md
@@ -0,0 +1,60 @@
+# 编辑链接 {#edit-link}
+
+## 站点级配置 {#site-level-config}
+
+编辑链接让你可以显示一个链接，以在 GitHub 或 GitLab 等 Git 管理服务上编辑页面。要启用它，请将 `themeConfig.editLink` 选项添加到配置中。
+
+```js
+export default {
+ themeConfig: {
+ editLink: {
+ pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path'
+ }
+ }
+}
+```
+
+`pattern` 选项定义链接的 URL 结构，并且 `:path` 将被替换为页面路径。
+
+你还可以放置一个接受 [`PageData`](./runtime-api#usedata) 作为参数并返回 URL 字符串的纯函数。
+
+```js
+export default {
+ themeConfig: {
+ editLink: {
+ pattern: ({ filePath }) => {
+ if (filePath.startsWith('packages/')) {
+ return `https://github.com/acme/monorepo/edit/main/${filePath}`
+ } else {
+ return `https://github.com/acme/monorepo/edit/main/docs/${filePath}`
+ }
+ }
+ }
+ }
+}
+```
+
+它不应该有副作用，也不应该访问其范围之外的任何东西，因为它将在浏览器中被序列化和执行。
+
+默认情况下，这将在文档页面底部添加链接文本“Edit this page”。可以通过定义 `text` 选项来自定义此文本。
+
+```js
+export default {
+ themeConfig: {
+ editLink: {
+ pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
+ text: 'Edit this page on GitHub'
+ }
+ }
+}
+```
+
+## frontmatter 配置 {#frontmatter-config}
+
+可以使用 frontmatter 上的 `editLink` 选项单独禁用某个页面的编辑链接：
+
+```yaml
+---
+editLink: false
+---
+```
diff --git a/docs/zh/reference/default-theme-footer.md b/docs/zh/reference/default-theme-footer.md
new file mode 100644
index 00000000..7499089f
--- /dev/null
+++ b/docs/zh/reference/default-theme-footer.md
@@ -0,0 +1,53 @@
+# 页脚 {#footer}
+
+配置好 `themeConfig.footer`，VitePress 将在全局页面底部显示页脚。
+
+```ts
+export default {
+ themeConfig: {
+ footer: {
+ message: 'Released under the MIT License.',
+ copyright: 'Copyright © 2019-present Evan You'
+ }
+ }
+}
+```
+
+```ts
+export interface Footer {
+ // 版权前显示的信息
+ message?: string
+
+ // 实际的版权文本
+ copyright?: string
+}
+```
+
+上面的配置也支持 HTML 字符串。所以，例如，如果想配置页脚文本有一些链接，可以调整配置如下：
+
+```ts
+export default {
+ themeConfig: {
+ footer: {
+ message: 'Released under the MIT License.',
+ copyright: 'Copyright © 2019-present Evan You'
+ }
+ }
+}
+```
+
+::: warning
+只有内联元素可以在 `message` 和 `copyright` 中使用，因为它们渲染在 `` 元素中。如果想添加块元素，请考虑使用 [`layout-bottom`](../guide/extending-default-theme#layout-slots) 插槽。
+:::
+
+请注意，当[侧边栏](./default-theme-sidebar)可见时，不会显示页脚。
+
+## frontmatter 配置 {#frontmatter-config}
+
+可以使用 frontmatter 上的 `footer` 选项在单独页面上禁用此功能：
+
+```yaml
+---
+footer: false
+---
+```
diff --git a/docs/zh/reference/default-theme-home-page.md b/docs/zh/reference/default-theme-home-page.md
new file mode 100644
index 00000000..b83364f9
--- /dev/null
+++ b/docs/zh/reference/default-theme-home-page.md
@@ -0,0 +1,195 @@
+# 主页 {#home-page}
+
+VitePress 默认主题提供了一个首页布局，也可以在[此站点首页](../)看到。可以通过 [frontmatter](./frontmatter-config) 指定 `layout: home` 在任何页面上使用它
+
+```yaml
+---
+layout: home
+---
+```
+
+但是，仅做这个配置不会有太大作用。可以通过设置其他选项 (例如 `hero` 和 `features`) 向主页添加几个不同的预设。
+
+## Hero 部分 {#hero-section}
+
+Hero 部分位于主页顶部。以下是配置 Hero 的方法。
+
+```yaml
+---
+layout: home
+
+hero:
+ name: VitePress
+ text: Vite & Vue powered static site generator.
+ tagline: Lorem ipsum...
+ image:
+ src: /logo.png
+ alt: VitePress
+ actions:
+ - theme: brand
+ text: Get Started
+ link: /guide/what-is-vitepress
+ - theme: alt
+ text: View on GitHub
+ link: https://github.com/vuejs/vitepress
+---
+```
+
+```ts
+interface Hero {
+ // `text` 上方的字符，带有品牌颜色
+ // 预计简短，例如产品名称
+ name?: string
+
+ // hero 部分的主要文字，
+ // 被定义为 `h1` 标签
+ text: string
+
+ // `text` 下方的标语
+ tagline?: string
+
+ // text 和 tagline 区域旁的图片
+ image?: ThemeableImage
+
+ // 主页 hero 部分的操作按钮
+ actions?: HeroAction[]
+}
+
+type ThemeableImage =
+ | string
+ | { src: string; alt?: string }
+ | { light: string; dark: string; alt?: string }
+
+interface HeroAction {
+ // 按钮的颜色主题，默认为 `brand`
+ theme?: 'brand' | 'alt'
+
+ // 按钮的标签
+ text: string
+
+ // 按钮的目标链接
+ link: string
+
+ // 链接的 target 属性
+ target?: string
+
+ // 链接的 rel 属性
+ rel?: string
+}
+```
+
+### 自定义 name 的颜色 {#customizing-the-name-color}
+
+VitePress 通过 (`--vp-c-brand-1`) 设置 `name` 的颜色 .但是，可以通过覆盖 `--vp-home-hero-name-color` 变量来自定义此颜色。
+
+```css
+:root {
+ --vp-home-hero-name-color: blue;
+}
+```
+
+也可以通过组合 `--vp-home-hero-name-background` 来进一步自定义 `name` 为渐变色。
+
+```css
+:root {
+ --vp-home-hero-name-color: transparent;
+ --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe, #41d1ff);
+}
+```
+
+## Features 部分 {#features-section}
+
+在 Features 部分，可以在 Hero 部分之后列出任意数量的 Feature。可以在 frontmatter 中配置 `features`。
+
+可以为每个 feature 提供一个图标，可以是表情符号或任何类型的图像。当配置的图标是图片（svg, png, jpeg...）时，必须提供合适的宽度和高度的图标；还可以在需要时配置其描述、固有大小以及深色和浅色主题下的不同表现。
+
+```yaml
+---
+layout: home
+
+features:
+ - icon: 🛠️
+ title: Simple and minimal, always
+ details: Lorem ipsum...
+ - icon:
+ src: /cool-feature-icon.svg
+ title: Another cool feature
+ details: Lorem ipsum...
+ - icon:
+ dark: /dark-feature-icon.svg
+ light: /light-feature-icon.svg
+ title: Another cool feature
+ details: Lorem ipsum...
+---
+```
+
+```ts
+interface Feature {
+ // 在每个 feature 框中显示图标
+ icon?: FeatureIcon
+
+ // feature 的标题
+ title: string
+
+ // feature 的详情
+ details: string
+
+ // 点击 feature 组件时的链接，可以是内部链接，也可以是外部链接。
+ //
+ //
+ // 例如 `guide/reference/default-theme-home-page` 或 `https://example.com`
+ link?: string
+
+ // feature 组件内显示的链接文本，最好与 `link` 选项一起使用
+ //
+ //
+ // 例如 `Learn more`, `Visit page` 等
+ linkText?: string
+
+ // `link` 选项的链接 rel 属性
+ //
+ // 例如 `external`
+ rel?: string
+
+ // `link` 选项的链接 target 属性
+ target?: string
+}
+
+type FeatureIcon =
+ | string
+ | { src: string; alt?: string; width?: string; height: string }
+ | {
+ light: string
+ dark: string
+ alt?: string
+ width?: string
+ height: string
+ }
+```
+
+## Markdown 内容 {#markdown-content}
+
+可以在 frontmatter 的分隔符 `---` 下方为站点主页添加额外的 Markdown 内容。
+
+````md
+---
+layout: home
+
+hero:
+ name: VitePress
+ text: Vite & Vue powered static site generator.
+---
+
+## Getting Started
+
+You can get started using VitePress right away using `npx`!
+
+```sh
+npm init
+npx vitepress init
+```
+````
+
+::: info
+VitePress 并不总是为 `layout: home` 页面里额外的内容自动添加样式。要回到以前的行为，可以在 frontmatter 中添加 `markdownStyles: false`。
+:::
diff --git a/docs/zh/reference/default-theme-last-updated.md b/docs/zh/reference/default-theme-last-updated.md
new file mode 100644
index 00000000..6c04a2c6
--- /dev/null
+++ b/docs/zh/reference/default-theme-last-updated.md
@@ -0,0 +1,27 @@
+# 最后更新于 {#last-updated}
+
+最近一条内容的更新时间会显示在页面右下角。要启用它，请将 `lastUpdated` 选项添加到配置中。
+
+::: tip
+你必须提交 markdown 文件才能看到最后更新时间。
+:::
+
+## 全局配置 {#site-level-config}
+
+```js
+export default {
+ lastUpdated: true
+}
+```
+
+## frontmatter 配置 {#frontmatter-config}
+
+可以使用 frontmatter 上的 `lastUpdated` 选项单独禁用某个页面的最后更新展示：
+
+```yaml
+---
+lastUpdated: false
+---
+```
+
+另请参阅[默认主题：最后更新时间](./default-theme-config#lastupdated) 了解更多详细信息。主题级别的任何 [truthy](https://developer.mozilla.org/zh-CN/docs/Glossary/Truthy) 值也将启用该功能，除非在站点或页面级别明确禁用。
diff --git a/docs/zh/reference/default-theme-layout.md b/docs/zh/reference/default-theme-layout.md
new file mode 100644
index 00000000..87015218
--- /dev/null
+++ b/docs/zh/reference/default-theme-layout.md
@@ -0,0 +1,62 @@
+# 布局 {#layout}
+
+可以通过设置页面 [frontmatter](./frontmatter-config) 选项来选择页面布局。有 3 种布局选项 `doc`、`page` 和 `home`。如果未指定任何内容，则该页面将被视为 `doc` 页面。
+
+```yaml
+---
+layout: doc
+---
+```
+
+## doc 布局 {#doc-layout}
+
+`doc` 是默认布局，它将整个 Markdown 内容设置为“documentation”外观。它的工作原理是将整个内容包装在 css `vp-doc` 类中，并将样式应用于它下面的元素。
+
+几乎所有通用元素，例如 `p`, 或 `h2` 都有特殊的样式。因此，请记住，如果在 Markdown 内容中添加任何自定义 HTML，这些内容也会受到这些样式的影响。
+
+它还提供下面列出的文档特定功能。这些功能仅在此布局中启用。
+
+- [编辑链接](./default-theme-edit-link)
+- [上下页链接](./default-theme-prev-next-links)
+- [大纲](./default-theme-config#outline)
+- [Carbon Ads](./default-theme-carbon-ads)
+
+## page 布局 {#page-layout}
+
+`page` 被视为“空白页”。Markdown 仍然会被解析，所有的 [Markdown 扩展](../guide/markdown) 都和 `doc` 布局一样运行，但它没有任何默认样式。
+
+`page` 布局将使可以自行设计所有内容，而不会受 VitePress 主题影响。当想要创建自己的自定义页面时，这很有用。
+
+请注意，即使在此布局中，如果页面具有匹配的侧边栏配置，侧边栏仍会显示。
+
+## home 布局 {#home-layout}
+
+`home` 将生成模板化的“主页”。在此布局中，可以设置额外的选项，例如 `hero` 和 `features` 以进一步自定义内容。请访问[默认主题: 主页](./default-theme-home-page)了解更多详情。
+
+## 无布局 {#no-layout}
+
+如果不想要任何布局，可以通过 frontmatter 传递 `layout: false`。如果想要一个完全可自定义的登录页面（默认情况下没有任何侧边栏、导航栏或页脚），此选项很有用。
+
+## 自定义布局 {#custom-layout}
+
+也可以使用自定义布局：
+
+```md
+---
+layout: foo
+---
+```
+
+这将在上下文中查找注册名为 `foo` 的组件。例如，可以在 `.vitepress/theme/index.ts`中全局注册组件：
+
+```ts
+import DefaultTheme from 'vitepress/theme'
+import Foo from './Foo.vue'
+
+export default {
+ extends: DefaultTheme,
+ enhanceApp({ app }) {
+ app.component('foo', Foo)
+ }
+}
+```
diff --git a/docs/zh/reference/default-theme-nav.md b/docs/zh/reference/default-theme-nav.md
new file mode 100644
index 00000000..be9feaac
--- /dev/null
+++ b/docs/zh/reference/default-theme-nav.md
@@ -0,0 +1,161 @@
+# 导航栏 {#nav}
+
+Nav 是显示在页面顶部的导航栏。它包含站点标题、全局菜单链接等。
+
+## 站点标题和图标 {#site-title-and-logo}
+
+默认情况下，nav 显示 [`config.title`](./site-config#title) 作为站点的标题。如果想更改导航栏上显示的内容，可以在 `themeConfig.siteTitle` 选项中定义自定义文本。
+
+```js
+export default {
+ themeConfig: {
+ siteTitle: 'My Custom Title'
+ }
+}
+```
+
+如果站点有图标，则可以通过传递图片路径来显示它。应该将图标直接放在 `public` 中，并赋值该绝对路径。
+
+```js
+export default {
+ themeConfig: {
+ logo: '/my-logo.svg'
+ }
+}
+```
+
+添加图标时，它会与站点标题一起显示。如果只需要图标并且想要隐藏站点标题文本，请将 `siteTitle` 选项设置为 `false`。
+
+```js
+export default {
+ themeConfig: {
+ logo: '/my-logo.svg',
+ siteTitle: false
+ }
+}
+```
+
+如果想添加 `alt` 属性或根据深色/浅色模式自定义，还可以将图标作为对象传递。有关详细信息，请参阅 [`themeConfig.logo`](./default-theme-config#logo)。
+
+## 导航链接 {#navigation-links}
+
+可以定义 `themeConfig.nav` 选项以将链接添加到导航栏。
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ { text: 'Guide', link: '/guide' },
+ { text: 'Config', link: '/config' },
+ { text: 'Changelog', link: 'https://github.com/...' }
+ ]
+ }
+}
+```
+
+`text` 是 nav 中显示的实际文本，而 `link` 是单击文本时将导航到的链接。对于链接，将路径设置为不带 `.md` 后缀的实际文件，并且始终以 `/` 开头。
+
+导航链接也可以是下拉菜单。为此，请替换 `link` 选项，设置 `items` 数组。
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ { text: 'Guide', link: '/guide' },
+ {
+ text: 'Dropdown Menu',
+ items: [
+ { text: 'Item A', link: '/item-1' },
+ { text: 'Item B', link: '/item-2' },
+ { text: 'Item C', link: '/item-3' }
+ ]
+ }
+ ]
+ }
+}
+```
+
+请注意，下拉菜单标题 (上例中的 `Dropdown Menu`) 不能具有 `link` 属性，因为它是打开下拉对话框的按钮。
+
+还可以通过传入更多嵌套项来进一步向下拉菜单项添加“sections”。
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ { text: 'Guide', link: '/guide' },
+ {
+ text: 'Dropdown Menu',
+ items: [
+ {
+ // 该部分的标题
+ text: 'Section A Title',
+ items: [
+ { text: 'Section A Item A', link: '...' },
+ { text: 'Section B Item B', link: '...' }
+ ]
+ }
+ ]
+ },
+ {
+ text: 'Dropdown Menu',
+ items: [
+ {
+ // 也可以省略标题
+ items: [
+ { text: 'Section A Item A', link: '...' },
+ { text: 'Section B Item B', link: '...' }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+### 自定义链接的路由匹配状态 {#customize-link-s-active-state}
+
+当前页面位于匹配路径下时，导航菜单项将突出显示。如果想自定义要匹配的路径，请将 `activeMatch` 属性和正则表达式定义为字符串值。
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ // 当用户位于 `/config/` 路径时，该链接处于激活状态
+ {
+ text: 'Guide',
+ link: '/guide',
+ activeMatch: '/config/'
+ }
+ ]
+ }
+}
+```
+
+::: warning
+`activeMatch` 应为正则表达式字符串，但必须将其定义为字符串。我们不能在这里使用实际的 RegExp 对象，因为它在构建期间不可序列化。
+:::
+
+### 自定义链接的“target”和“rel”属性 {#customize-link-s-target-and-rel-attributes}
+
+默认情况下，VitePress 会根据链接是否为外部链接自动判断 `target` 和 `rel` 属性。但如果愿意，也可以自定义它们。
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ {
+ text: 'Merchandise',
+ link: 'https://www.thegithubshop.com/',
+ target: '_self',
+ rel: 'sponsored'
+ }
+ ]
+ }
+}
+```
+
+## 社交链接 {#social-links}
+
+参考 [`socialLinks`](./default-theme-config#sociallinks)。
diff --git a/docs/zh/reference/default-theme-prev-next-links.md b/docs/zh/reference/default-theme-prev-next-links.md
new file mode 100644
index 00000000..cdbe8434
--- /dev/null
+++ b/docs/zh/reference/default-theme-prev-next-links.md
@@ -0,0 +1,43 @@
+# 上下页链接 {#prev-next-links}
+
+可以自定义上一页和下一页的文本和链接 (显示在文档页脚处)。如果要使其与侧边栏上的文本不同，这会很有帮助。此外，你可能会发现，要禁用未包含在侧边栏中的页面的页脚或链接时，这很有用。
+
+## prev
+
+- 类型：`string | false | { text?: string; link?: string }`
+
+- 说明：
+
+ 指定要在指向上一页的链接上显示的文本/链接。如果没有在 frontmatter 中设置它，文本/链接将从侧边栏配置中推断出来。
+
+- 示例：
+
+ - 仅自定义文本：
+
+ ```yaml
+ ---
+ prev: 'Get Started | Markdown'
+ ---
+ ```
+
+ - 自定义文本和链接：
+
+ ```yaml
+ ---
+ prev:
+ text: 'Markdown'
+ link: '/guide/markdown'
+ ---
+ ```
+
+ - 隐藏上一页：
+
+ ```yaml
+ ---
+ prev: false
+ ---
+ ```
+
+## next
+
+与 `prev` 相同，但用于下一页。
diff --git a/docs/zh/reference/default-theme-search.md b/docs/zh/reference/default-theme-search.md
new file mode 100644
index 00000000..fdd97200
--- /dev/null
+++ b/docs/zh/reference/default-theme-search.md
@@ -0,0 +1,379 @@
+---
+outline: deep
+---
+
+# 搜索 {#search}
+
+## 本地搜索 {#local-search}
+
+得益于 [minisearch](https://github.com/lucaong/minisearch/)，VitePress 支持使用浏览器内索引进行模糊全文搜索。要启用此功能，只需在 `.vitepress/config.ts` 文件中将 `themeConfig.search.provider` 选项设置为 `'local'` 即可：
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local'
+ }
+ }
+})
+```
+
+示例结果：
+
+
+
+或者，你可以使用 [Algolia DocSearch](#algolia-search) 或一些社区插件，例如： 或者 。
+
+### i18n {#local-search-i18n}
+
+你可以使用这样的配置来使用多语言搜索：
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local',
+ options: {
+ locales: {
+ zh: {
+ translations: {
+ button: {
+ buttonText: '搜索文档',
+ buttonAriaLabel: '搜索文档'
+ },
+ modal: {
+ noResultsText: '无法找到相关结果',
+ resetButtonTitle: '清除查询条件',
+ footer: {
+ selectText: '选择',
+ navigateText: '切换'
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+})
+```
+
+### MiniSearch 配置项 {#mini-search-options}
+
+你可以像这样配置 MiniSearch ：
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local',
+ options: {
+ miniSearch: {
+ /**
+ * @type {Pick}
+ */
+ options: {
+ /* ... */
+ },
+ /**
+ * @type {import('minisearch').SearchOptions}
+ * @default
+ * { fuzzy: 0.2, prefix: true, boost: { title: 4, text: 2, titles: 1 } }
+ */
+ searchOptions: {
+ /* ... */
+ }
+ }
+ }
+ }
+ }
+})
+```
+
+参阅 [MiniSearch 文档](https://lucaong.github.io/minisearch/classes/MiniSearch.MiniSearch.html)了解更多信息。
+
+### 自定义渲染内容 {#custom-content-renderer}
+
+可以在索引之前自定义用于渲染 Markdown 内容的函数：
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local',
+ options: {
+ /**
+ * @param {string} src
+ * @param {import('vitepress').MarkdownEnv} env
+ * @param {import('markdown-it')} md
+ */
+ _render(src, env, md) {
+ // 返回 html 字符串
+ }
+ }
+ }
+ }
+})
+```
+
+该函数将从客户端站点数据中剥离，因此你可以在其中使用 Node.js API。
+
+#### 示例：从搜索中排除页面 {#example-excluding-pages-from-search}
+
+你可以通过将 `search: false` 添加到页面的 `frontmatter` 来从搜索中排除页面。或者：
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local',
+ options: {
+ _render(src, env, md) {
+ const html = md.render(src, env)
+ if (env.frontmatter?.search === false) return ''
+ if (env.relativePath.startsWith('some/path')) return ''
+ return html
+ }
+ }
+ }
+ }
+})
+```
+
+::: warning 注意
+如果提供了自定义的 `_render` 函数，你需要自己处理 `search: false` 的 frontmatter。此外，在调用 `md.render` 之前，`env` 对象不会完全填充，因此对可选 `env` 属性 (如 `frontmatter`) 的任何检查都应该在此之后完成。
+:::
+
+#### 示例：转换内容——添加锚点 {#example-transforming-content-adding-anchors}
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local',
+ options: {
+ _render(src, env, md) {
+ const html = md.render(src, env)
+ if (env.frontmatter?.title)
+ return md.render(`# ${env.frontmatter.title}`) + html
+ return html
+ }
+ }
+ }
+ }
+})
+```
+
+## Algolia Search {#algolia-search}
+
+VitePress 支持使用 [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch) 搜索文档站点。请参阅他们的入门指南。在你的 `.vitepress/config.ts` 中，你至少需要提供以下内容才能使其正常工作：
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'algolia',
+ options: {
+ appId: '...',
+ apiKey: '...',
+ indexName: '...'
+ }
+ }
+ }
+})
+```
+
+### i18n {#algolia-search-i18n}
+
+你可以使用这样的配置来使用多语言搜索：
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'algolia',
+ options: {
+ appId: '...',
+ apiKey: '...',
+ indexName: '...',
+ locales: {
+ zh: {
+ placeholder: '搜索文档',
+ translations: {
+ button: {
+ buttonText: '搜索文档',
+ buttonAriaLabel: '搜索文档'
+ },
+ modal: {
+ searchBox: {
+ resetButtonTitle: '清除查询条件',
+ resetButtonAriaLabel: '清除查询条件',
+ cancelButtonText: '取消',
+ cancelButtonAriaLabel: '取消'
+ },
+ startScreen: {
+ recentSearchesTitle: '搜索历史',
+ noRecentSearchesText: '没有搜索历史',
+ saveRecentSearchButtonTitle: '保存至搜索历史',
+ removeRecentSearchButtonTitle: '从搜索历史中移除',
+ favoriteSearchesTitle: '收藏',
+ removeFavoriteSearchButtonTitle: '从收藏中移除'
+ },
+ errorScreen: {
+ titleText: '无法获取结果',
+ helpText: '你可能需要检查你的网络连接'
+ },
+ footer: {
+ selectText: '选择',
+ navigateText: '切换',
+ closeText: '关闭',
+ searchByText: '搜索提供者'
+ },
+ noResultsScreen: {
+ noResultsText: '无法找到相关结果',
+ suggestedQueryText: '你可以尝试查询',
+ reportMissingResultsText: '你认为该查询应该有结果？',
+ reportMissingResultsLinkText: '点击反馈'
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+})
+```
+
+[这些选项](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts)可以被覆盖。请参阅 Algolia 官方文档以了解更多信息。
+
+### 爬虫配置 {#crawler-config}
+
+以下是基于此站点使用的示例配置：
+
+```ts
+new Crawler({
+ appId: '...',
+ apiKey: '...',
+ rateLimit: 8,
+ startUrls: ['https://vitepress.dev/'],
+ renderJavaScript: false,
+ sitemaps: [],
+ exclusionPatterns: [],
+ ignoreCanonicalTo: false,
+ discoveryPatterns: ['https://vitepress.dev/**'],
+ schedule: 'at 05:10 on Saturday',
+ actions: [
+ {
+ indexName: 'vitepress',
+ pathsToMatch: ['https://vitepress.dev/**'],
+ recordExtractor: ({ $, helpers }) => {
+ return helpers.docsearch({
+ recordProps: {
+ lvl1: '.content h1',
+ content: '.content p, .content li',
+ lvl0: {
+ selectors: '',
+ defaultValue: 'Documentation'
+ },
+ lvl2: '.content h2',
+ lvl3: '.content h3',
+ lvl4: '.content h4',
+ lvl5: '.content h5'
+ },
+ indexHeadings: true
+ })
+ }
+ }
+ ],
+ initialIndexSettings: {
+ vitepress: {
+ attributesForFaceting: ['type', 'lang'],
+ attributesToRetrieve: ['hierarchy', 'content', 'anchor', 'url'],
+ attributesToHighlight: ['hierarchy', 'hierarchy_camel', 'content'],
+ attributesToSnippet: ['content:10'],
+ camelCaseAttributes: ['hierarchy', 'hierarchy_radio', 'content'],
+ searchableAttributes: [
+ 'unordered(hierarchy_radio_camel.lvl0)',
+ 'unordered(hierarchy_radio.lvl0)',
+ 'unordered(hierarchy_radio_camel.lvl1)',
+ 'unordered(hierarchy_radio.lvl1)',
+ 'unordered(hierarchy_radio_camel.lvl2)',
+ 'unordered(hierarchy_radio.lvl2)',
+ 'unordered(hierarchy_radio_camel.lvl3)',
+ 'unordered(hierarchy_radio.lvl3)',
+ 'unordered(hierarchy_radio_camel.lvl4)',
+ 'unordered(hierarchy_radio.lvl4)',
+ 'unordered(hierarchy_radio_camel.lvl5)',
+ 'unordered(hierarchy_radio.lvl5)',
+ 'unordered(hierarchy_radio_camel.lvl6)',
+ 'unordered(hierarchy_radio.lvl6)',
+ 'unordered(hierarchy_camel.lvl0)',
+ 'unordered(hierarchy.lvl0)',
+ 'unordered(hierarchy_camel.lvl1)',
+ 'unordered(hierarchy.lvl1)',
+ 'unordered(hierarchy_camel.lvl2)',
+ 'unordered(hierarchy.lvl2)',
+ 'unordered(hierarchy_camel.lvl3)',
+ 'unordered(hierarchy.lvl3)',
+ 'unordered(hierarchy_camel.lvl4)',
+ 'unordered(hierarchy.lvl4)',
+ 'unordered(hierarchy_camel.lvl5)',
+ 'unordered(hierarchy.lvl5)',
+ 'unordered(hierarchy_camel.lvl6)',
+ 'unordered(hierarchy.lvl6)',
+ 'content'
+ ],
+ distinct: true,
+ attributeForDistinct: 'url',
+ customRanking: [
+ 'desc(weight.pageRank)',
+ 'desc(weight.level)',
+ 'asc(weight.position)'
+ ],
+ ranking: [
+ 'words',
+ 'filters',
+ 'typo',
+ 'attribute',
+ 'proximity',
+ 'exact',
+ 'custom'
+ ],
+ highlightPreTag: '',
+ highlightPostTag: '',
+ minWordSizefor1Typo: 3,
+ minWordSizefor2Typos: 7,
+ allowTyposOnNumericTokens: false,
+ minProximity: 1,
+ ignorePlurals: true,
+ advancedSyntax: true,
+ attributeCriteriaComputedByMinProximity: true,
+ removeWordsIfNoResults: 'allOptional'
+ }
+ }
+})
+```
+
+
diff --git a/docs/zh/reference/default-theme-sidebar.md b/docs/zh/reference/default-theme-sidebar.md
new file mode 100644
index 00000000..ba9a9adc
--- /dev/null
+++ b/docs/zh/reference/default-theme-sidebar.md
@@ -0,0 +1,213 @@
+# 侧边栏 {#sidebar}
+
+侧边栏是文档的主要导航块。可以在 [`themeConfig.sidebar`](./default-theme-config#sidebar) 中配置侧边栏菜单。
+
+```js
+export default {
+ themeConfig: {
+ sidebar: [
+ {
+ text: 'Guide',
+ items: [
+ { text: 'Introduction', link: '/introduction' },
+ { text: 'Getting Started', link: '/getting-started' },
+ ...
+ ]
+ }
+ ]
+ }
+}
+```
+
+## 基本用法 {#the-basics}
+
+侧边栏菜单的最简单形式是传入一个链接数组。第一级项目定义侧边栏的“部分”。它应该包含作为小标题的 `text` 和作为实际导航链接的 `items`。
+
+```js
+export default {
+ themeConfig: {
+ sidebar: [
+ {
+ text: 'Section Title A',
+ items: [
+ { text: 'Item A', link: '/item-a' },
+ { text: 'Item B', link: '/item-b' },
+ ...
+ ]
+ },
+ {
+ text: 'Section Title B',
+ items: [
+ { text: 'Item C', link: '/item-c' },
+ { text: 'Item D', link: '/item-d' },
+ ...
+ ]
+ }
+ ]
+ }
+}
+```
+
+每个 `link` 都应指定以 `/` 开头的实际文件的路径。如果在链接末尾添加斜杠，它将显示相应目录的 `index.md`。
+
+```js
+export default {
+ themeConfig: {
+ sidebar: [
+ {
+ text: 'Guide',
+ items: [
+ // 显示的是 `/guide/index.md` 页面
+ { text: 'Introduction', link: '/guide/' }
+ ]
+ }
+ ]
+ }
+}
+```
+
+可以进一步将侧边栏项目嵌入到 6 级深度，从根级别上计数。请注意，深度超过 6 级将被忽略，并且不会在侧边栏上显示。
+
+```js
+export default {
+ themeConfig: {
+ sidebar: [
+ {
+ text: 'Level 1',
+ items: [
+ {
+ text: 'Level 2',
+ items: [
+ {
+ text: 'Level 3',
+ items: [
+ ...
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+## 多侧边栏 {#multiple-sidebars}
+
+可能会根据页面路径显示不同的侧边栏。例如，如本站点所示，可能希望在文档中创建单独的侧边栏，例如“指南”页面和“配置参考”页面。
+
+为此，首先将你的页面组织到每个所需部分的目录中：
+
+```
+.
+├─ guide/
+│ ├─ index.md
+│ ├─ one.md
+│ └─ two.md
+└─ config/
+ ├─ index.md
+ ├─ three.md
+ └─ four.md
+```
+
+然后，更新配置以定义每个部分的侧边栏。这一次，应该传递一个对象而不是数组。
+
+```js
+export default {
+ themeConfig: {
+ sidebar: {
+ // 当用户位于 `guide` 目录时，会显示此侧边栏
+ '/guide/': [
+ {
+ text: 'Guide',
+ items: [
+ { text: 'Index', link: '/guide/' },
+ { text: 'One', link: '/guide/one' },
+ { text: 'Two', link: '/guide/two' }
+ ]
+ }
+ ],
+
+ // 当用户位于 `config` 目录时，会显示此侧边栏
+ '/config/': [
+ {
+ text: 'Config',
+ items: [
+ { text: 'Index', link: '/config/' },
+ { text: 'Three', link: '/config/three' },
+ { text: 'Four', link: '/config/four' }
+ ]
+ }
+ ]
+ }
+ }
+}
+```
+
+## 可折叠的侧边栏组 {#collapsible-sidebar-groups}
+
+通过向侧边栏组添加 `collapsed` 选项，它会显示一个切换按钮来隐藏/显示每个部分。
+
+```js
+export default {
+ themeConfig: {
+ sidebar: [
+ {
+ text: 'Section Title A',
+ collapsed: false,
+ items: [...]
+ }
+ ]
+ }
+}
+```
+
+默认情况下，所有部分都是“打开”的。如果希望它们在初始页面加载时“关闭”，请将 `collapsed` 选项设置为 `true`。
+
+```js
+export default {
+ themeConfig: {
+ sidebar: [
+ {
+ text: 'Section Title A',
+ collapsed: true,
+ items: [...]
+ }
+ ]
+ }
+}
+```
+
+## `useSidebar`
+ sidebar: ComputedRef
+ sidebarGroups: ComputedRef
+ hasSidebar: ComputedRef
+ hasAside: ComputedRef
+ leftAside: ComputedRef
+ isSidebarEnabled: ComputedRef
+ open: () => void
+ close: () => void
+ toggle: () => void
+}
+```
+
+**示例：**
+
+```vue
+
+
+
+ Only show when sidebar exists
+
+```
diff --git a/docs/zh/reference/default-theme-team-page.md b/docs/zh/reference/default-theme-team-page.md
new file mode 100644
index 00000000..0341f0f2
--- /dev/null
+++ b/docs/zh/reference/default-theme-team-page.md
@@ -0,0 +1,257 @@
+
+
+# 团队页 {#team-page}
+
+如果你想介绍你的团队，你可以使用 Team components 来构建团队页面。有两种使用这些组件的方法。一种是将其嵌入文档页面，另一种是创建完整的团队页面。
+
+## 在页面中显示团队成员 {#show-team-members-in-a-page}
+
+你可以在任何页面上使用从 `vitepress/theme` 暴露出的公共组件 `` 显示团队成员。
+
+```html
+
+
+# Our Team
+
+Say hello to our awesome team.
+
+` 组件有 2 种不同的尺寸，`small` 和 `medium`。虽然它取决于你的偏好，但通常尺寸在文档页面中使用时 `small` 应该更适合。此外，你可以为每个成员添加更多属性，例如添加“描述”或“赞助”按钮。在 [``](#vpteammembers) 中了解更多信息。
+
+在文档页面中嵌入团队成员对于小型团队来说非常有用，某种情况下，完整的贡献团队可能太大了，可以引入部分成员作为文档上下文的参考。
+
+如果你有大量成员，或者只是想有更多空间来展示团队成员，请考虑[创建一个完整的团队页面](#create-a-full-team-page)。
+
+## 创建一个完整的团队页面 {#create-a-full-team-page}
+
+除了将团队成员添加到 doc 页面，你还可以创建一个完整的团队页面，类似于创建自定义[默认主题：主页](./default-theme-home-page)的方式。
+
+要创建团队页面，首先，创建一个新的 md 文件。文件名无所谓，这里我们就叫它 `team.md` 吧。在这个文件中，在 frontmatter 设置 `layout: page`，然后你可以使用 `TeamPage` 组件来组成页面结构。
+
+```html
+---
+layout: page
+---
+
+
+
+
+
+ Our Team
+
+
+ The development of VitePress is guided by an international
+ team, some of whom have chosen to be featured below.
+
+
+
+```
+
+创建完整的团队页面时，请记住用 `` 组件包装所有团队相关组件，以获得正确的布局结构，如间距。
+
+`` 组件添加页面标题部分。标题是 `` 标题。使用 `#title` 和 `#lead` 插槽来介绍你的团队。
+
+`` 和在 doc 页面中使用时一样。它将显示成员列表。
+
+### 添加 section 以划分团队成员 {#add-sections-to-divide-team-members}
+
+你可以将“section”添加到团队页面。例如，你可能有不同类型的团队成员，例如核心团队成员和社区合作伙伴。你可以将这些成员分成几个部分，以更好地解释每组的角色。
+
+为此，将 `` 组件添加到我们之前创建的 `team.md` 文件中。
+
+```html
+---
+layout: page
+---
+
+
+
+
+ Our Team
+ ...
+
+
+ Partners
+ ...
+
+
+
+```
+
+`` 组件可以有类似于 `VPTeamPageTitle` 组件的 `#title` 和 `#lead` 插槽，还有用于显示团队成员的 `#members` 插槽。
+
+请记住将 `` 组件放入 `#members` 插槽中。
+
+## ``
+
+`` 组件显示给定的成员列表。
+
+```html
+`
+
+创建完整团队页面时的根组件。它只接受一个插槽。它将设置所有传入的团队相关组件的样式。
+
+## ``
+
+添加页面的标题。最好在一开始就在 `` 下使用。它接受 `#title` 和 `#lead` 插槽。
+
+```html
+
+
+
+ Our Team
+
+
+ The development of VitePress is guided by an international
+ team, some of whom have chosen to be featured below.
+
+
+
+```
+
+## ``
+
+在团队页面中创建一个“section”。它接受 `#title`、`#lead` 和 `#members` 插槽。你可以在 `` 中添加任意数量的section。
+
+```html
+
+ ...
+
+ Partners
+ Lorem ipsum...
+
+
+
+```
diff --git a/docs/zh/reference/frontmatter-config.md b/docs/zh/reference/frontmatter-config.md
new file mode 100644
index 00000000..2cf0eaaa
--- /dev/null
+++ b/docs/zh/reference/frontmatter-config.md
@@ -0,0 +1,221 @@
+---
+outline: deep
+---
+
+# frontmatter 配置 {#frontmatter-config}
+
+frontmatter 支持基于页面的配置。在每个 markdown 文件中，可以使用 frontmatter 配置来覆盖站点级别或主题级别的配置选项。此外，还有一些配置选项只能在 frontmatter 中定义。
+
+示例用法：
+
+```md
+---
+title: Docs with VitePress
+editLink: true
+---
+```
+
+可以通过 Vue 表达式中的 `$frontmatter` 全局变量访问 frontmatter 数据：
+
+```md
+{{ $frontmatter.title }}
+```
+
+## title
+
+- 类型：`string`
+
+页面的标题。它与 [config.title](./site-config#title) 相同，并且覆盖站点级配置。
+
+```yaml
+---
+title: VitePress
+---
+```
+
+## titleTemplate
+
+- 类型：`string | boolean`
+
+标题的后缀。它与 [config.titleTemplate](./site-config#titletemplate) 相同，它会覆盖站点级别的配置。
+
+```yaml
+---
+title: VitePress
+titleTemplate: Vite & Vue powered static site generator
+---
+```
+
+## description
+
+- 类型：`string`
+
+页面的描述。它与 [config.description](./site-config#description) 相同，它会覆盖站点级别的配置。
+
+```yaml
+---
+description: VitePress
+---
+```
+
+## head
+
+- 类型：`HeadConfig[]`
+
+指定要为当前页面注入的额外 head 标签。将附加在站点级配置注入的头部标签之后。
+
+```yaml
+---
+head:
+ - - meta
+ - name: description
+ content: hello
+ - - meta
+ - name: keywords
+ content: super duper SEO
+---
+```
+
+```ts
+type HeadConfig =
+ | [string, Record]
+ | [string, Record, string]
+```
+
+## 仅默认主题 {#default-theme-only}
+
+以下 frontmatter 选项仅在使用默认主题时适用。
+
+### layout
+
+- 类型：`doc | home | page`
+- 默认值：`doc`
+
+指定页面的布局。
+
+- `doc`——它将默认文档样式应用于 markdown 内容。
+- `home`——“主页”的特殊布局。可以添加额外的选项，例如 `hero` 和 `features`，以快速创建漂亮的落地页。
+- `page`——表现类似于 `doc`，但它不对内容应用任何样式。当想创建一个完全自定义的页面时很有用。
+
+```yaml
+---
+layout: doc
+---
+```
+
+### hero {{ theme.footer.copyright }}
+
+```
+
+## `useRoute`
+ /**
+ * 在路由更改前调用。返回 `false` 表示取消导航
+ */
+ onBeforeRouteChange?: (to: string) => Awaitable
+ /**
+ * 在页面组件加载前（history 状态更新后）调用。返回 `false` 表示取消导航
+ */
+ onBeforePageLoad?: (to: string) => Awaitable
+ /**
+ * 在路由更改后调用
+ */
+ onAfterRouteChanged?: (to: string) => Awaitable
+}
+```
+
+## `withBase` Custom Layout!
+
+
+```
+
+- 相关文档：[SSR 兼容性](../guide/ssr-compat)
+
+## `$frontmatter` /.vitepress/config.[ext]` 解析，其中 `` 是 VitePress [项目根目录](../guide/routing#root-and-source-directory)，`[ext]` 是支持的文件扩展名之一。开箱即用地支持 TypeScript。支持的扩展名包括 `.js`、`.ts`、`.mjs` 和 `.mts`。
+
+建议在配置文件中使用 ES 模块语法。配置文件应该默认导出一个对象：
+
+```ts
+export default {
+ // 应用级配置选项
+ lang: 'en-US',
+ title: 'VitePress',
+ description: 'Vite & Vue powered static site generator.',
+ ...
+}
+```
+
+:::details 异步的动态配置
+
+如果需要动态生成配置，也可以默认导出一个函数，例如：
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default async () => {
+ const posts = await (await fetch('https://my-cms.com/blog-posts')).json()
+
+ return defineConfig({
+ // 应用级配置选项
+ lang: 'en-US',
+ title: 'VitePress',
+ description: 'Vite & Vue powered static site generator.',
+
+ // 主题级配置选项
+ themeConfig: {
+ sidebar: [
+ ...posts.map((post) => ({
+ text: post.name,
+ link: `/posts/${post.name}`
+ }))
+ ]
+ }
+ })
+}
+```
+
+也可以在最外层使用 `await`。例如：
+
+```ts
+import { defineConfig } from 'vitepress'
+
+const posts = await (await fetch('https://my-cms.com/blog-posts')).json()
+
+export default defineConfig({
+ // 应用级配置选项
+ lang: 'en-US',
+ title: 'VitePress',
+ description: 'Vite & Vue powered static site generator.',
+
+ // 主题级别配置选项
+ themeConfig: {
+ sidebar: [
+ ...posts.map((post) => ({
+ text: post.name,
+ link: `/posts/${post.name}`
+ }))
+ ]
+ }
+})
+```
+
+:::
+
+### 配置智能提示 {#config-intellisense}
+
+使用 `defineConfig` 辅助函数将为配置选项提供 TypeScript 支持的智能提示。假设 IDE 支持它，那么在 JavaScript 和 TypeScript 中都将触发智能提示。
+
+```js
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ // ...
+})
+```
+
+### 主题类型提示 {#typed-theme-config}
+
+默认情况下，`defineConfig` 辅助函数期望默认主题的主题配置数据类型为：
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ // 类型为 `DefaultTheme.Config`
+ }
+})
+```
+
+如果使用自定义主题并希望对主题配置进行类型检查，则需要改用 `defineConfigWithTheme`，并通过通用参数传递自定义主题的配置类型：
+
+```ts
+import { defineConfigWithTheme } from 'vitepress'
+import type { ThemeConfig } from 'your-theme'
+
+export default defineConfigWithTheme
`. Se você quiser adicionar elementos de tipo _block_, considere usar o _slot_ [`layout-bottom`](../guide/extending-default-theme#layout-slots).
+:::
+
+Note que o rodapé não será mostrado quando a [Barra Lateral](./default-theme-sidebar) estiver visível.
+
+## Configuração Frontmatter {#frontmatter-config}
+
+Isso pode ser desabilitado por página usando a opção `footer` em frontmatter:
+
+```yaml
+---
+footer: false
+---
+```
\ No newline at end of file
diff --git a/docs/pt/reference/default-theme-home-page.md b/docs/pt/reference/default-theme-home-page.md
new file mode 100644
index 00000000..460c55bf
--- /dev/null
+++ b/docs/pt/reference/default-theme-home-page.md
@@ -0,0 +1,168 @@
+# Página Inicial {#home-page}
+
+O tema padrão VitePress fornece um layout de página inicial, que você também pode ver em uso [na página inicial deste site](../). Você pode usá-lo em qualquer uma de suas páginas especificando `layout: home` em [frontmatter](./frontmatter-config).
+
+```yaml
+---
+layout: home
+---
+```
+
+No entanto, essa opção sozinha não faz muito. Você pode adicionar várias "seções" diferentes pré-modeladas à página inicial definindo opções adicionais como `hero` e `features`.
+
+## Seção Hero {#hero-section}
+
+A seção _Hero_ fica no topo da página inicial. Aqui segue como você pode configurar a seção _Hero_.
+
+```yaml
+---
+layout: home
+
+hero:
+ name: VitePress
+ text: Gerador de site estático com Vite & Vue.
+ tagline: Lorem ipsum...
+ image:
+ src: /logo.png
+ alt: VitePress
+ actions:
+ - theme: brand
+ text: Iniciar
+ link: /guide/what-is-vitepress
+ - theme: alt
+ text: Ver no GitHub
+ link: https://github.com/vuejs/vitepress
+---
+```
+
+```ts
+interface Hero {
+ // A string mostrada acima de `text`. Vem com a cor da marca
+ // e espera-se que seja curta, como o nome do produto.
+ name?: string
+
+ // O texto principal para a seção hero.
+ // Isso será definido como uma tag `h1`.
+ text: string
+
+ // Slogan exibido abaixo de `text`.
+ tagline?: string
+
+ // A imagem é exibida ao lado da área de texto e slogan.
+ image?: ThemeableImage
+
+ // Botões acionáveis para exibir na seção hero da página inicial.
+ actions?: HeroAction[]
+}
+
+type ThemeableImage =
+ | string
+ | { src: string; alt?: string }
+ | { light: string; dark: string; alt?: string }
+
+interface HeroAction {
+ // Tema de cor do botão. Padrão: `brand`.
+ theme?: 'brand' | 'alt'
+
+ // Rótulo do botão.
+ text: string
+
+ // Destino do link do botão.
+ link: string
+
+ // Atributo target do link.
+ target?: string
+
+ // Atributo rel do link.
+ rel?: string
+}
+```
+
+### Personalizando a cor do nome {#customizing-the-name-color}
+
+VitePress usa a cor da marca (`--vp-c-brand-1`) para `name`. No entanto, você pode personalizar essa cor sobrescrevendo a variável `--vp-home-hero-name-color`.
+
+```css
+:root {
+ --vp-home-hero-name-color: blue;
+}
+```
+
+Você também pode personalizá-la ainda mais combinando `--vp-home-hero-name-background` para dar ao `name` uma cor degradê.
+
+```css
+:root {
+ --vp-home-hero-name-color: transparent;
+ --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe, #41d1ff);
+}
+```
+
+## Seção de Funcionalidades {#features-section}
+
+Na seção de funcionalidades, você pode listar qualquer número de funcionalidades que deseja mostrar imediatamente após a seção _Hero_. Para configurá-la, passe a opção `features` para o frontmatter.
+
+Você pode fornecer um ícone para cada funcionalidade, que pode ser um emoji ou qualquer tipo de imagem. Quando o ícone configurado é uma imagem (svg, png, jpeg...), você deve fornecer o ícone com a largura e altura apropriadas; você também pode fornecer a descrição, seu tamanho intrínseco, bem como suas variantes para temas escuros e claros quando necessário.
+
+```yaml
+---
+layout: home
+
+features:
+ - icon: 🛠️
+ title: Simples e minimalista, sempre
+ details: Lorem ipsum...
+ - icon:
+ src: /cool-feature-icon.svg
+ title: Outro recurso legal
+ details: Lorem ipsum...
+ - icon:
+ dark: /dark-feature-icon.svg
+ light: /light-feature-icon.svg
+ title: Outro recurso legal
+ details: Lorem ipsum...
+---
+```
+
+```ts
+interface Feature {
+ // Mostra ícone em cada bloco de funcionalide.
+ icon?: FeatureIcon
+
+ // Título da funcionalidade.
+ title: string
+
+ // Detalhes da funcionalidade.
+ details: string
+
+ // Link quando clicado no componente de funcionalidade.
+ // O link pode ser interno ou externo.
+ //
+ // ex. `guide/reference/default-theme-home-page` ou `https://example.com`
+ link?: string
+
+ // Texto do link a ser exibido dentro do componente de funcionalidade.
+ // Melhor usado com a opção `link`.
+ //
+ // ex. `Saiba mais`, `Visitar página`, etc.
+ linkText?: string
+
+ // Atributo rel do link para a opção `link`.
+ //
+ // ex. `external`
+ rel?: string
+
+ // Atributo target do link para a opção `link`.
+ target?: string
+}
+
+type FeatureIcon =
+ | string
+ | { src: string; alt?: string; width?: string; height: string }
+ | {
+ light: string
+ dark: string
+ alt?: string
+ width?: string
+ height: string
+ }
+```
diff --git a/docs/pt/reference/default-theme-last-updated.md b/docs/pt/reference/default-theme-last-updated.md
new file mode 100644
index 00000000..5bc782e1
--- /dev/null
+++ b/docs/pt/reference/default-theme-last-updated.md
@@ -0,0 +1,27 @@
+# Última Atualização {#last-updated}
+
+O tempo em que o conteúdo foi atualizado pela última vez será mostrado no canto inferior direito da página. Para habilitar, adicione a opção `lastUpdated` na sua configuração.
+
+::: tip
+Você precisa fazer _commit_ no arquivo markdown para ver o tempo atualizado.
+:::
+
+## Configuração a nível de Site {#site-level-config}
+
+```js
+export default {
+ lastUpdated: true
+}
+```
+
+## Configuração Frontmatter {#frontmatter-config}
+
+Isso pode ser desabilitado por página usando a opção `lastUpdated` no frontmatter:
+
+```yaml
+---
+lastUpdated: false
+---
+```
+
+Refira-se ao [Tema Padrão: Última Atualização](./default-theme-config#lastupdated) para mais detalhes. Qualquer valor positivo a nível de tema também habilitará a funcionalidade a não ser que esteja explicitamente desabilitada a nível de página ou de site.
diff --git a/docs/pt/reference/default-theme-layout.md b/docs/pt/reference/default-theme-layout.md
new file mode 100644
index 00000000..0e4d0162
--- /dev/null
+++ b/docs/pt/reference/default-theme-layout.md
@@ -0,0 +1,62 @@
+# Layout {#layout}
+
+Você pode escolher o layout da página definindo a opção de `layout` para o [frontmatter](./frontmatter-config) da página. Há três opções de layout: `doc`, `page` e `home`. Se nada for especificado, a página será tratada como página `doc`.
+
+```yaml
+---
+layout: doc
+---
+```
+
+## Layout do documento {#doc-layout}
+
+A opção `doc` é o layout padrão e estiliza todo o conteúdo Markdown com o visual de "documentação". Ela funciona agrupando todo o conteúdo na classe CSS `vp-doc`, e aplicando os estilos aos elementos abaixo dela.
+
+Quase todos os elementos genéricos, como `p` ou `h2`, recebem um estilo especial. Portanto, lembre-se de que se você adicionar qualquer HTML personalizado dentro de um conteúdo Markdown, ele também será afetado por esses estilos.
+
+Ele também fornece recursos específicos de documentação listados abaixo. Esses recursos estão habilitados apenas neste layout.
+
+- Editar link
+- Links Anterior e Próximo
+- _Outline_
+- [Carbon Ads](./default-theme-carbon-ads)
+
+## Layout da Página {#page-layout}
+
+A opção `page` é tratada como "página em branco". O Markdown ainda será processado e todas as [Extensões Markdown](../guide/markdown) funcionarão da mesma forma que o layout `doc`, mas este não receberá nenhum estilo padrão.
+
+O layout da página permitirá que você estilize tudo sem que o tema VitePress afete a marcação. Isso é útil quando você deseja criar sua própria página personalizada.
+
+Observe que mesmo neste layout, a barra lateral ainda aparecerá se a página tiver uma configuração de barra lateral correspondente.
+
+## Layout da Home {#home-layout}
+
+A opção `home` gerará um modelo de _"Homepage"_. Nesse layout você pode definir opções extras, como `hero` e `features`, para personalizar ainda mais o conteúdo. Visite [Tema padrão: Página Inicial](./default-theme-home-page) para obter mais detalhes.
+
+## Sem Layout {#no-layout}
+
+Se você não quiser nenhum layout, pode passar `layout: false` pelo frontmatter. Esta opção é útil se você deseja uma página de destino totalmente personalizável (sem barra lateral, barra de navegação ou rodapé por padrão).
+
+## Layout Personalizado {#custom-layout}
+
+Você também pode usar um layout personalizado:
+
+```md
+---
+layout: foo
+---
+```
+
+Isto irá procurar um componente chamado `foo` registrado no contexto. Por exemplo, você pode registrar seu componente globalmente em `.vitepress/theme/index.ts`:
+
+```ts
+import DefaultTheme from 'vitepress/theme'
+import Foo from './Foo.vue'
+
+export default {
+ extends: DefaultTheme,
+ enhanceApp({ app }) {
+ app.component('foo', Foo)
+ }
+}
+```
diff --git a/docs/pt/reference/default-theme-nav.md b/docs/pt/reference/default-theme-nav.md
new file mode 100644
index 00000000..5f0d2399
--- /dev/null
+++ b/docs/pt/reference/default-theme-nav.md
@@ -0,0 +1,162 @@
+# Navegação {#nav}
+
+Referente a barra de navegação exibida no topo da página. Ela contém o título do site, links do menu global, e etc.
+
+## Título do Site e Logo {#site-title-and-logo}
+
+Por padrão, a navegação mostra o título do site referenciando o valor de [`config.title`](./site-config#title). Se desejar alterar o que é exibido na navegação, você pode definir um texto personalizado na opção `themeConfig.siteTitle`.
+
+```js
+export default {
+ themeConfig: {
+ siteTitle: 'Meu Título Personalizado'
+ }
+}
+```
+
+Se você tiver um logo para seu site, pode mostrá-lo passando o caminho para a imagem. Você deve colocar o logo diretamente dentro da pasta `public`, e definir o caminho absoluto para ele.
+
+```js
+export default {
+ themeConfig: {
+ logo: '/my-logo.svg'
+ }
+}
+```
+
+Ao adicionar um logo, ele é mostrado juntamente com o título do site. Se seu logo tem tudo o que você precisa e se você desejar ocultar o texto do título, defina `false` na opção `siteTitle`.
+
+```js
+export default {
+ themeConfig: {
+ logo: '/my-logo.svg',
+ siteTitle: false
+ }
+}
+```
+
+Você também pode passar um objeto como logo se quiser adicionar um atributo `alt` ou personalizá-lo com base no modo claro/escuro. Consulte [`themeConfig.logo`](./default-theme-config#logo) para obter detalhes.
+
+## Links de Navegação {#navigation-links}
+
+Você pode definir a opção `themeConfig.nav` para adicionar links à sua navegação.
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ { text: 'Guia', link: '/guide' },
+ { text: 'Configuração', link: '/config' },
+ { text: 'Registro de Alterações', link: 'https://github.com/...' }
+ ]
+ }
+}
+```
+
+`text` é o próprio texto mostrado na navegação, e o `link` é o link para o qual será navegado quando o texto for clicado. Para o link, defina o caminho para o próprio arquivo sem o prefixo `.md` e sempre comece com `/`.
+
+Links de navegação também podem ser menus _dropdown_. Para fazer isso, defina a chave `items` na opção do link.
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ { text: 'Guia', link: '/guide' },
+ {
+ text: 'Menu Dropdown',
+ items: [
+ { text: 'Item A', link: '/item-1' },
+ { text: 'Item B', link: '/item-2' },
+ { text: 'Item C', link: '/item-3' }
+ ]
+ }
+ ]
+ }
+}
+```
+
+Note que o título do menu _dropdown_ (`Menu Dropdown` no exemplo acima) não pode ter a propriedade `link`, pois ele se torna um botão para abrir o diálogo dropdown.
+
+Você também pode adicionar "seções" aos itens do menu _dropdown_ passando mais itens aninhados.
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ { text: 'Guia', link: '/guia' },
+ {
+ text: 'Menu Dropdown',
+ items: [
+ {
+ // Título da seção.
+ text: 'Título da Seção A',
+ items: [
+ { text: 'Item A da Seção A', link: '...' },
+ { text: 'Item B da Seção B', link: '...' }
+ ]
+ }
+ ]
+ },
+ {
+ text: 'Menu Dropdown',
+ items: [
+ {
+ // Você também pode omitir o título.
+ items: [
+ { text: 'Item A da Seção A', link: '...' },
+ { text: 'Item B da Seção B', link: '...' }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+### Personalizar o estado "ativo" do link {#customize-link-s-active-state}
+
+Os itens do menu de navegação serão destacados quando a página atual estiver no caminho correspondente. Se desejar personalizar o caminho a ser correspondido, defina a propriedade `activeMatch` e regex como um valor em string.
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ // Este link fica no estado ativo quando
+ // o usuário está no caminho `/config/`.
+ {
+ text: 'Guia',
+ link: '/guide',
+ activeMatch: '/config/'
+ }
+ ]
+ }
+}
+```
+
+::: warning
+`activeMatch` deve ser uma string regex, mas você deve defini-la como uma string. Não podemos usar um objeto RegExp real aqui porque ele não é serializável durante o momento de construção.
+:::
+
+### Personalizar os atributos "target" e "rel" de links {#customize-link-s-target-and-rel-attributes}
+
+Por padrão, VitePress determina automaticamente os atributos `target` e `rel` baseado em um link externo ou não. Mas se você quiser, também pode personalizá-los.
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ {
+ text: 'Merchandise',
+ link: 'https://www.thegithubshop.com/',
+ target: '_self',
+ rel: 'sponsored'
+ }
+ ]
+ }
+}
+```
+
+## Links Sociais {#social-links}
+
+Consulte [`socialLinks`](./default-theme-config#sociallinks).
diff --git a/docs/pt/reference/default-theme-prev-next-links.md b/docs/pt/reference/default-theme-prev-next-links.md
new file mode 100644
index 00000000..c9472a24
--- /dev/null
+++ b/docs/pt/reference/default-theme-prev-next-links.md
@@ -0,0 +1,43 @@
+# Links Anterior e Próximo {#prev-next-links}
+
+Você pode personalizar o texto e o link para os botões de Anterior e Próximo mostrados ao fim da página. Isso é útil quando você quer mostrar um texto diferente daquele que você tem na barra lateral. Além disso, você pode achar útil desabilitar o rodapé ou link para a página para ela não ser incluída na sua barra lateral.
+
+## prev
+
+- Tipo: `string | false | { text?: string; link?: string }`
+
+- Detalhes:
+
+ Especifica o texto/link para mostrar no link para a página anterior. Se você não ver isso no frontmatter, o texto/link será inferido da configuração da barra lateral.
+
+- Exemplos:
+
+ - Para personalizar apenas o texto:
+
+ ```yaml
+ ---
+ prev: 'Iniciar | Markdown'
+ ---
+ ```
+
+ - Para personalizar ambos texto e link:
+
+ ```yaml
+ ---
+ prev:
+ text: 'Markdown'
+ link: '/guide/markdown'
+ ---
+ ```
+
+ - Para esconder a página anterior:
+
+ ```yaml
+ ---
+ prev: false
+ ---
+ ```
+
+## next
+
+O mesmo que `prev` mas para a próxima página.
diff --git a/docs/pt/reference/default-theme-search.md b/docs/pt/reference/default-theme-search.md
new file mode 100644
index 00000000..35b0d812
--- /dev/null
+++ b/docs/pt/reference/default-theme-search.md
@@ -0,0 +1,379 @@
+---
+outline: deep
+---
+
+# Pesquisa {#search}
+
+## Pesquisa Local {#local-search}
+
+VitePress oferece suporte à pesquisa de texto completa usando um índice no navegador graças ao [minisearch](https://github.com/lucaong/minisearch/). Para habilitar esse recurso, basta definir a opção `themeConfig.search.provider` como `'local'` no arquivo `.vitepress/config.ts`:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local'
+ }
+ }
+})
+```
+
+Exemplo de resultado:
+
+
+
+Alternativamente, você pode usar [Algolia DocSearch](#algolia-search) ou alguns plugins da comunidade como Привет из модального окна! `. Если вы хотите добавить блочные элементы, рассмотрите возможность использования слота [`layout-bottom`](../guide/extending-default-theme#layout-slots).
+:::
+
+Обратите внимание, что подвал не будет отображаться, если виден [Сайдбар](./default-theme-sidebar).
+
+## Настройка в метаданных {#frontmatter-config}
+
+Отображение подвала можно отключить на конкретной странице с помощью опции `footer` в метаданных:
+
+```yaml
+---
+footer: false
+---
+```
diff --git a/docs/ru/reference/default-theme-home-page.md b/docs/ru/reference/default-theme-home-page.md
new file mode 100644
index 00000000..fedf2b53
--- /dev/null
+++ b/docs/ru/reference/default-theme-home-page.md
@@ -0,0 +1,196 @@
+# Главная страница {#home-page}
+
+Тема VitePress по умолчанию предоставляет макет главной страницы, который вы также можете увидеть на [главной странице этого сайта](../). Вы можете использовать его на любой из своих страниц, указав `layout: home` в [метаданных](./frontmatter-config) страницы.
+
+```yaml
+---
+layout: home
+---
+```
+
+Однако сам по себе этот вариант мало что даст. Вы можете добавить несколько различных готовых «секций» на главную страницу, установив дополнительные опции, такие как `hero` и `features`.
+
+## Секция `hero` {#hero-section}
+
+Секция `hero` находится в верхней части главной страницы. Вот как можно её настроить:
+
+```yaml
+---
+layout: home
+
+hero:
+ name: VitePress
+ text: Генератор статических сайтов на основе Vite и Vue.
+ tagline: Lorem ipsum...
+ image:
+ src: /logo.png
+ alt: VitePress
+ actions:
+ - theme: brand
+ text: Начать
+ link: /guide/what-is-vitepress
+ - theme: alt
+ text: Посмотреть на GitHub
+ link: https://github.com/vuejs/vitepress
+---
+```
+
+```ts
+interface Hero {
+ // Строка, отображаемая поверх `text`. Поставляется в фирменном цвете и,
+ // как ожидается, будет короткой — например, название продукта
+ name?: string
+
+ // Основной текст секции. Будет использоваться внутри тега `h1`
+ text: string
+
+ // Заголовок, отображаемый под `text`
+ tagline?: string
+
+ // Изображение отображается рядом с `text` и `tagline`
+ image?: ThemeableImage
+
+ // Кнопки действий для отображения в секции
+ actions?: HeroAction[]
+}
+
+type ThemeableImage =
+ | string
+ | { src: string; alt?: string }
+ | { light: string; dark: string; alt?: string }
+
+interface HeroAction {
+ // Цветовая тема кнопки. По умолчанию принимает значение `brand`.
+ theme?: 'brand' | 'alt'
+
+ // Метка кнопки.
+ text: string
+
+ // Ссылка назначения кнопки.
+ link: string
+
+ // Атрибут цели ссылки.
+ target?: string
+
+ // Атрибут rel ссылки.
+ rel?: string
+}
+```
+
+### Настройка цвета заголовка секции {#customizing-the-name-color}
+
+VitePress использует фирменный цвет (`--vp-c-brand-1`) для атрибута `name` в секции `hero`. Однако вы можете настроить этот цвет, переопределив переменную `--vp-home-hero-name-color`.
+
+```css
+:root {
+ --vp-home-hero-name-color: blue;
+}
+```
+
+Также вы можете настроить его ещё больше, комбинируя `--vp-home-hero-name-background`, чтобы придать `name` градиентный цвет.
+
+```css
+:root {
+ --vp-home-hero-name-color: transparent;
+ --vp-home-hero-name-background: -webkit-linear-gradient(
+ 120deg,
+ #bd34fe,
+ #41d1ff
+ );
+}
+```
+
+## Секция `features` {#features-section}
+
+В секции `features` можно перечислить любое количество функций, которые вы хотели бы показать сразу после секции `hero`. Чтобы настроить её, передайте опцию `features` в метаданных страницы.
+
+Для каждой функции можно указать иконку, который может быть эмодзи или любым другим изображением. Если настраиваемая иконка представляет собой изображение (svg, png, jpeg...), вы должны предоставить ей соответствующую ширину и высоту. При необходимости можно указать описание, собственный размер, а также варианты для тёмной и светлой темы.
+
+```yaml
+---
+layout: home
+
+features:
+ - icon: 🛠️
+ title: Просто и минималистично, всегда
+ details: Lorem ipsum...
+ - icon:
+ src: /cool-feature-icon.svg
+ title: Ещё одна интересная функция
+ details: Lorem ipsum...
+ - icon:
+ dark: /dark-feature-icon.svg
+ light: /light-feature-icon.svg
+ title: Ещё одна интересная функция
+ details: Lorem ipsum...
+---
+```
+
+```ts
+interface Feature {
+ // Иконка
+ icon?: FeatureIcon
+
+ // Заголовок фичи
+ title: string
+
+ // Описание фичи
+ details: string
+
+ // Ссылка при нажатии на компонент функции. Ссылка может быть как внутренней, так и внешней.
+ //
+ // например, `guide/reference/default-theme-home-page` или `https://example.com`
+ link?: string
+
+ // Текст ссылки, который будет отображаться внутри компонента функции. Лучше всего использовать с опцией `link`.
+ //
+ // например, `Узнать подробнее`, `Посетить страницу` и т. д.
+ linkText?: string
+
+ // Атрибут rel для опции `link`
+ //
+ // например, `external`
+ rel?: string
+
+ // Атрибут target для опции `link`
+ target?: string
+}
+
+type FeatureIcon =
+ | string
+ | { src: string; alt?: string; width?: string; height: string }
+ | {
+ light: string
+ dark: string
+ alt?: string
+ width?: string
+ height: string
+ }
+```
+
+## Содержимое Markdown {#markdown-content}
+
+Вы можете добавить дополнительный контент на главную страницу вашего сайта, просто добавив Markdown под разделителем `---`.
+
+````md
+---
+layout: home
+
+hero:
+ name: VitePress
+ text: Генератор статических сайтов на основе Vite и Vue.
+---
+
+## Начало работы
+
+Вы можете начать использовать VitePress прямо сейчас, используя `npx`!
+
+```sh
+npm init
+npx vitepress init
+```
+````
+
+::: info ПРИМЕЧАНИЕ
+VitePress не всегда автоматически стилизовал дополнительный контент страницы с макетом `layout: home`. Чтобы вернуться к старому поведению, добавьте `markdownStyles: false` в метаданных.
+:::
diff --git a/docs/ru/reference/default-theme-last-updated.md b/docs/ru/reference/default-theme-last-updated.md
new file mode 100644
index 00000000..7d926dc5
--- /dev/null
+++ b/docs/ru/reference/default-theme-last-updated.md
@@ -0,0 +1,27 @@
+# Последнее обновление {#last-updated}
+
+Время последнего обновления содержимого будет отображаться в правом нижнем углу страницы. Чтобы включить его, добавьте опцию `lastUpdated` в свой конфиг.
+
+::: tip Совет
+Чтобы увидеть обновленное время, необходимо зафиксировать файл Markdown.
+:::
+
+## Настройка в файле конфигурации {#site-level-config}
+
+```js
+export default {
+ lastUpdated: true
+}
+```
+
+## Настройка в метаданных {#frontmatter-config}
+
+Эту информацию можно отключить на конкретной странице с помощью опции `lastUpdated` в метаданных:
+
+```yaml
+---
+lastUpdated: false
+---
+```
+
+Также смотрите [Тема по умолчанию: `lastUpdated`](./default-theme-config#lastupdated) для получения более подробной информации. Любое истинное значение на уровне темы также включит функцию, если только она не будет явно отключена на уровне сайта или страницы.
diff --git a/docs/ru/reference/default-theme-layout.md b/docs/ru/reference/default-theme-layout.md
new file mode 100644
index 00000000..f02af7d5
--- /dev/null
+++ b/docs/ru/reference/default-theme-layout.md
@@ -0,0 +1,62 @@
+# Макет {#layout}
+
+Вы можете выбрать макет страницы, установив опцию `layout` в [метаданных](./frontmatter-config). Изначально есть 3 макета: `doc`, `page` и `home`. Если ничего не указано, то страница будет использовать макет `doc`.
+
+```yaml
+---
+layout: doc
+---
+```
+
+## Макет `doc` {#doc-layout}
+
+Вариант `doc` — это макет по умолчанию, который стилизует всё содержимое Markdown в виде «документации». Он работает, оборачивая весь контент в CSS-класс `vp-doc` и применяя стили к вложенным элементам.
+
+Почти все общие элементы, такие как `p` или `h2`, получают специальную стилизацию. Поэтому имейте в виду, что если вы добавите какой-либо пользовательский HTML внутри Markdown-контента, то он также будет подвержен влиянию этих стилей.
+
+Кроме того, в нём предусмотрены специальные функции, перечисленные ниже. Эти функции включены только в данном макете.
+
+- Ссылка «Редактировать»
+- Ссылки предыдущая/следующая
+- Оглавление
+- Реклама [Carbon Ads](./default-theme-carbon-ads)
+
+## Макет `page` {#page-layout}
+
+Вариант `page` сгенерирует «пустую страницу». Markdown всё равно будет разобран, и все [расширения Markdown](../guide/markdown) будут работать так же, как и с макетом `doc`, но никаких стилей по умолчанию применено не будет.
+
+Макет `page` позволит вам оформить всё самостоятельно, без влияния темы VitePress на разметку. Это удобно, когда вы хотите создать свою собственную страницу.
+
+Обратите внимание, что даже при таком раскладе сайдбар всё равно будет отображаться, если у страницы есть соответствующая конфигурация сайдбара.
+
+## Макет `home` {#home-layout}
+
+Вариант `home` сгенерирует шаблонную «домашнюю страницу». В этом макете вы можете установить дополнительные параметры, такие как `hero` и `features`, для дальнейшей настройки контента. Посетите секцию [Тема по умолчанию: Домашняя страница](./default-theme-home-page) для получения более подробной информации.
+
+## Без макета {#no-layout}
+
+Если вам не нужен макет, вы можете указать `layout: false` в метаданных. Этот параметр полезен, если вам нужна полностью настраиваемая целевая страница (по умолчанию без сайдбара, панели навигации или подвала).
+
+## Свой макет {#custom-layout}
+
+Вы также можете использовать собственный макет:
+
+```md
+---
+layout: foo
+---
+```
+
+Будет выполнен поиск компонента с именем `foo`, зарегистрированного в контексте. Например, вы можете зарегистрировать свой компонент глобально в `.vitepress/theme/index.ts`:
+
+```ts
+import DefaultTheme from 'vitepress/theme'
+import Foo from './Foo.vue'
+
+export default {
+ extends: DefaultTheme,
+ enhanceApp({ app }) {
+ app.component('foo', Foo)
+ }
+}
+```
diff --git a/docs/ru/reference/default-theme-nav.md b/docs/ru/reference/default-theme-nav.md
new file mode 100644
index 00000000..9ff77659
--- /dev/null
+++ b/docs/ru/reference/default-theme-nav.md
@@ -0,0 +1,162 @@
+# Навигация {#nav}
+
+Ключ `nav` в конфигурации — это панель навигации, отображаемая в верхней части страницы. Она содержит заголовок сайта, ссылки глобального меню и т. д.
+
+## Название и логотип сайта {#site-title-and-logo}
+
+По умолчанию навигация отображает название сайта, ссылаясь на значение [`config.title`](./site-config#title). Если вы хотите изменить то, что отображается в панели навигации, задайте пользовательский текст в опции `themeConfig.siteTitle`.
+
+```js
+export default {
+ themeConfig: {
+ siteTitle: 'Мой заголовок'
+ }
+}
+```
+
+Если у вас есть логотип для вашего сайта, вы можете отобразить его, передав путь к изображению. Вы должны поместить логотип непосредственно в директорию `public` и указать абсолютный путь к нему.
+
+```js
+export default {
+ themeConfig: {
+ logo: '/my-logo.svg'
+ }
+}
+```
+
+При добавлении логотипа он отображается вместе с названием сайта. Если вам нужен только логотип и вы хотите скрыть текст заголовка сайта, установите `false` для параметра `SiteTitle`.
+
+```js
+export default {
+ themeConfig: {
+ logo: '/my-logo.svg',
+ siteTitle: false
+ }
+}
+```
+
+Вы также можете передать объект в качестве логотипа, если хотите добавить атрибут `alt` или настроить его в зависимости от тёмного/светлого режима. Подробности смотрите в [`themeConfig.logo`](./default-theme-config#logo).
+
+## Навигационные ссылки {#navigation-links}
+
+Вы можете определить опцию `themeConfig.nav`, чтобы добавить ссылки в панель навигации:
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ { text: 'Руководство', link: '/guide' },
+ { text: 'Настройка', link: '/config' },
+ { text: 'Изменения', link: 'https://github.com/...' }
+ ]
+ }
+}
+```
+
+`text` — это текст, отображаемый в навигации, а `link` — это ссылка, на которую будет осуществлён переход при нажатии на текст. Для ссылки задайте путь к фактическому файлу без префикса `.md` и всегда начинайте с `/`.
+
+Навигационные ссылки также могут быть выпадающими меню. Для этого установите ключ `items` вместо ключа `link`:
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ { text: 'Руководство', link: '/guide' },
+ {
+ text: 'Выпадающее меню',
+ items: [
+ { text: 'Пункт A', link: '/item-1' },
+ { text: 'Пункт B', link: '/item-2' },
+ { text: 'Пункт C', link: '/item-3' }
+ ]
+ }
+ ]
+ }
+}
+```
+
+Обратите внимание, что заголовок выпадающего меню (`Выпадающее меню` в примере выше) не может иметь свойство `link`, так как он становится кнопкой для открытия выпадающего диалога.
+
+Вы можете добавить «секции» в пункты выпадающего меню, передавая больше вложенных элементов:
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ { text: 'Руководство', link: '/guide' },
+ {
+ text: 'Выпадающее меню',
+ items: [
+ {
+ // Заголовок секции
+ text: 'Секция A',
+ items: [
+ { text: 'Пункт A в секции A', link: '...' },
+ { text: 'Пункт B в секции A', link: '...' }
+ ]
+ }
+ ]
+ },
+ {
+ text: 'Выпадающее меню',
+ items: [
+ {
+ // Заголовок можно опустить
+ items: [
+ { text: 'Пункт A в секции A', link: '...' },
+ { text: 'Пункт B в секции A', link: '...' }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+### Настройка «активного» состояния ссылки {#customize-link-s-active-state}
+
+Пункты меню навигации будут выделены, если текущая страница находится под соответствующим путём. Если вы хотите настроить сопоставление путей, определите свойство `activeMatch` и регулярное выражение в качестве строкового значения.
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ // Эта ссылка получает активное состояние, когда пользователь
+ // переходит по пути `/config/`.
+ {
+ text: 'Руководство',
+ link: '/guide',
+ activeMatch: '/config/'
+ }
+ ]
+ }
+}
+```
+
+::: warning ПРЕДУПРЕЖДЕНИЕ
+Ожидается, что `activeMatch` будет регулярным выражением, но вы должны определить его как строку. Мы не можем использовать здесь реальный объект RegExp, потому что он не сериализуется во время сборки.
+:::
+
+### Настройка атрибутов «target» и «rel» {#customize-link-s-target-and-rel-attributes}
+
+По умолчанию VitePress автоматически определяет атрибуты `target` и `rel` в зависимости от того, является ли ссылка внешней. Но при желании их можно настроить и вручную.
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ {
+ text: 'Товары',
+ link: 'https://www.thegithubshop.com/',
+ target: '_self',
+ rel: 'sponsored'
+ }
+ ]
+ }
+}
+```
+
+## Социальные ссылки {#social-links}
+
+См. [`socialLinks`](./default-theme-config#sociallinks).
diff --git a/docs/ru/reference/default-theme-prev-next-links.md b/docs/ru/reference/default-theme-prev-next-links.md
new file mode 100644
index 00000000..e2da9501
--- /dev/null
+++ b/docs/ru/reference/default-theme-prev-next-links.md
@@ -0,0 +1,43 @@
+# Предыдущая и следующая страницы {#prev-next-links}
+
+Вы можете настроить текст и ссылку для предыдущей и следующей страниц (отображаются в нижней части страницы). Это полезно, если вы хотите, чтобы текст отличался от того, что находится в сайдбаре. Кроме того, вы можете счесть полезным отключить подвал или ссылку на страницу, которая не включена в сайдбар.
+
+## prev {#prev}
+
+- Тип: `string | false | { text?: string; link?: string }`
+
+- Подробности:
+
+ Указывает текст/ссылку, который должен отображаться при переходе на предыдущую страницу. Если вы не зададите это в метаданных, текст/ссылка будет определяться из конфигурации сайдбара.
+
+- Примеры:
+
+ - Для настройки только текста:
+
+ ```yaml
+ ---
+ prev: 'Начать | Markdown'
+ ---
+ ```
+
+ - Для настройки текста и ссылки:
+
+ ```yaml
+ ---
+ prev:
+ text: 'Markdown'
+ link: '/guide/markdown'
+ ---
+ ```
+
+ - Для скрытия предыдущей страницы:
+
+ ```yaml
+ ---
+ prev: false
+ ---
+ ```
+
+## next {#next}
+
+Аналогично параметру `prev`, но для следующей страницы.
diff --git a/docs/ru/reference/default-theme-search.md b/docs/ru/reference/default-theme-search.md
new file mode 100644
index 00000000..dae85f47
--- /dev/null
+++ b/docs/ru/reference/default-theme-search.md
@@ -0,0 +1,382 @@
+---
+outline: deep
+---
+
+# Поиск {#search}
+
+## Локальный поиск {#local-search}
+
+VitePress поддерживает нечёткий полнотекстовый поиск с использованием внутрибраузерного индекса благодаря [MiniSearch](https://github.com/lucaong/minisearch/). Чтобы включить эту функцию, просто установите значение `'local'` для опции `themeConfig.search.provider` в файле `.vitepress/config.ts`:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local'
+ }
+ }
+})
+```
+
+Пример результата:
+
+
+
+В качестве альтернативы можно использовать [Algolia DocSearch](#algolia-search) или некоторые плагины сообщества, например ` 元素中。如果想添加块元素，请考虑使用 [`layout-bottom`](../guide/extending-default-theme#layout-slots) 插槽。
+:::
+
+请注意，当[侧边栏](./default-theme-sidebar)可见时，不会显示页脚。
+
+## frontmatter 配置 {#frontmatter-config}
+
+可以使用 frontmatter 上的 `footer` 选项在单独页面上禁用此功能：
+
+```yaml
+---
+footer: false
+---
+```
diff --git a/docs/zh/reference/default-theme-home-page.md b/docs/zh/reference/default-theme-home-page.md
new file mode 100644
index 00000000..b83364f9
--- /dev/null
+++ b/docs/zh/reference/default-theme-home-page.md
@@ -0,0 +1,195 @@
+# 主页 {#home-page}
+
+VitePress 默认主题提供了一个首页布局，也可以在[此站点首页](../)看到。可以通过 [frontmatter](./frontmatter-config) 指定 `layout: home` 在任何页面上使用它
+
+```yaml
+---
+layout: home
+---
+```
+
+但是，仅做这个配置不会有太大作用。可以通过设置其他选项 (例如 `hero` 和 `features`) 向主页添加几个不同的预设。
+
+## Hero 部分 {#hero-section}
+
+Hero 部分位于主页顶部。以下是配置 Hero 的方法。
+
+```yaml
+---
+layout: home
+
+hero:
+ name: VitePress
+ text: Vite & Vue powered static site generator.
+ tagline: Lorem ipsum...
+ image:
+ src: /logo.png
+ alt: VitePress
+ actions:
+ - theme: brand
+ text: Get Started
+ link: /guide/what-is-vitepress
+ - theme: alt
+ text: View on GitHub
+ link: https://github.com/vuejs/vitepress
+---
+```
+
+```ts
+interface Hero {
+ // `text` 上方的字符，带有品牌颜色
+ // 预计简短，例如产品名称
+ name?: string
+
+ // hero 部分的主要文字，
+ // 被定义为 `h1` 标签
+ text: string
+
+ // `text` 下方的标语
+ tagline?: string
+
+ // text 和 tagline 区域旁的图片
+ image?: ThemeableImage
+
+ // 主页 hero 部分的操作按钮
+ actions?: HeroAction[]
+}
+
+type ThemeableImage =
+ | string
+ | { src: string; alt?: string }
+ | { light: string; dark: string; alt?: string }
+
+interface HeroAction {
+ // 按钮的颜色主题，默认为 `brand`
+ theme?: 'brand' | 'alt'
+
+ // 按钮的标签
+ text: string
+
+ // 按钮的目标链接
+ link: string
+
+ // 链接的 target 属性
+ target?: string
+
+ // 链接的 rel 属性
+ rel?: string
+}
+```
+
+### 自定义 name 的颜色 {#customizing-the-name-color}
+
+VitePress 通过 (`--vp-c-brand-1`) 设置 `name` 的颜色 .但是，可以通过覆盖 `--vp-home-hero-name-color` 变量来自定义此颜色。
+
+```css
+:root {
+ --vp-home-hero-name-color: blue;
+}
+```
+
+也可以通过组合 `--vp-home-hero-name-background` 来进一步自定义 `name` 为渐变色。
+
+```css
+:root {
+ --vp-home-hero-name-color: transparent;
+ --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe, #41d1ff);
+}
+```
+
+## Features 部分 {#features-section}
+
+在 Features 部分，可以在 Hero 部分之后列出任意数量的 Feature。可以在 frontmatter 中配置 `features`。
+
+可以为每个 feature 提供一个图标，可以是表情符号或任何类型的图像。当配置的图标是图片（svg, png, jpeg...）时，必须提供合适的宽度和高度的图标；还可以在需要时配置其描述、固有大小以及深色和浅色主题下的不同表现。
+
+```yaml
+---
+layout: home
+
+features:
+ - icon: 🛠️
+ title: Simple and minimal, always
+ details: Lorem ipsum...
+ - icon:
+ src: /cool-feature-icon.svg
+ title: Another cool feature
+ details: Lorem ipsum...
+ - icon:
+ dark: /dark-feature-icon.svg
+ light: /light-feature-icon.svg
+ title: Another cool feature
+ details: Lorem ipsum...
+---
+```
+
+```ts
+interface Feature {
+ // 在每个 feature 框中显示图标
+ icon?: FeatureIcon
+
+ // feature 的标题
+ title: string
+
+ // feature 的详情
+ details: string
+
+ // 点击 feature 组件时的链接，可以是内部链接，也可以是外部链接。
+ //
+ //
+ // 例如 `guide/reference/default-theme-home-page` 或 `https://example.com`
+ link?: string
+
+ // feature 组件内显示的链接文本，最好与 `link` 选项一起使用
+ //
+ //
+ // 例如 `Learn more`, `Visit page` 等
+ linkText?: string
+
+ // `link` 选项的链接 rel 属性
+ //
+ // 例如 `external`
+ rel?: string
+
+ // `link` 选项的链接 target 属性
+ target?: string
+}
+
+type FeatureIcon =
+ | string
+ | { src: string; alt?: string; width?: string; height: string }
+ | {
+ light: string
+ dark: string
+ alt?: string
+ width?: string
+ height: string
+ }
+```
+
+## Markdown 内容 {#markdown-content}
+
+可以在 frontmatter 的分隔符 `---` 下方为站点主页添加额外的 Markdown 内容。
+
+````md
+---
+layout: home
+
+hero:
+ name: VitePress
+ text: Vite & Vue powered static site generator.
+---
+
+## Getting Started
+
+You can get started using VitePress right away using `npx`!
+
+```sh
+npm init
+npx vitepress init
+```
+````
+
+::: info
+VitePress 并不总是为 `layout: home` 页面里额外的内容自动添加样式。要回到以前的行为，可以在 frontmatter 中添加 `markdownStyles: false`。
+:::
diff --git a/docs/zh/reference/default-theme-last-updated.md b/docs/zh/reference/default-theme-last-updated.md
new file mode 100644
index 00000000..6c04a2c6
--- /dev/null
+++ b/docs/zh/reference/default-theme-last-updated.md
@@ -0,0 +1,27 @@
+# 最后更新于 {#last-updated}
+
+最近一条内容的更新时间会显示在页面右下角。要启用它，请将 `lastUpdated` 选项添加到配置中。
+
+::: tip
+你必须提交 markdown 文件才能看到最后更新时间。
+:::
+
+## 全局配置 {#site-level-config}
+
+```js
+export default {
+ lastUpdated: true
+}
+```
+
+## frontmatter 配置 {#frontmatter-config}
+
+可以使用 frontmatter 上的 `lastUpdated` 选项单独禁用某个页面的最后更新展示：
+
+```yaml
+---
+lastUpdated: false
+---
+```
+
+另请参阅[默认主题：最后更新时间](./default-theme-config#lastupdated) 了解更多详细信息。主题级别的任何 [truthy](https://developer.mozilla.org/zh-CN/docs/Glossary/Truthy) 值也将启用该功能，除非在站点或页面级别明确禁用。
diff --git a/docs/zh/reference/default-theme-layout.md b/docs/zh/reference/default-theme-layout.md
new file mode 100644
index 00000000..87015218
--- /dev/null
+++ b/docs/zh/reference/default-theme-layout.md
@@ -0,0 +1,62 @@
+# 布局 {#layout}
+
+可以通过设置页面 [frontmatter](./frontmatter-config) 选项来选择页面布局。有 3 种布局选项 `doc`、`page` 和 `home`。如果未指定任何内容，则该页面将被视为 `doc` 页面。
+
+```yaml
+---
+layout: doc
+---
+```
+
+## doc 布局 {#doc-layout}
+
+`doc` 是默认布局，它将整个 Markdown 内容设置为“documentation”外观。它的工作原理是将整个内容包装在 css `vp-doc` 类中，并将样式应用于它下面的元素。
+
+几乎所有通用元素，例如 `p`, 或 `h2` 都有特殊的样式。因此，请记住，如果在 Markdown 内容中添加任何自定义 HTML，这些内容也会受到这些样式的影响。
+
+它还提供下面列出的文档特定功能。这些功能仅在此布局中启用。
+
+- [编辑链接](./default-theme-edit-link)
+- [上下页链接](./default-theme-prev-next-links)
+- [大纲](./default-theme-config#outline)
+- [Carbon Ads](./default-theme-carbon-ads)
+
+## page 布局 {#page-layout}
+
+`page` 被视为“空白页”。Markdown 仍然会被解析，所有的 [Markdown 扩展](../guide/markdown) 都和 `doc` 布局一样运行，但它没有任何默认样式。
+
+`page` 布局将使可以自行设计所有内容，而不会受 VitePress 主题影响。当想要创建自己的自定义页面时，这很有用。
+
+请注意，即使在此布局中，如果页面具有匹配的侧边栏配置，侧边栏仍会显示。
+
+## home 布局 {#home-layout}
+
+`home` 将生成模板化的“主页”。在此布局中，可以设置额外的选项，例如 `hero` 和 `features` 以进一步自定义内容。请访问[默认主题: 主页](./default-theme-home-page)了解更多详情。
+
+## 无布局 {#no-layout}
+
+如果不想要任何布局，可以通过 frontmatter 传递 `layout: false`。如果想要一个完全可自定义的登录页面（默认情况下没有任何侧边栏、导航栏或页脚），此选项很有用。
+
+## 自定义布局 {#custom-layout}
+
+也可以使用自定义布局：
+
+```md
+---
+layout: foo
+---
+```
+
+这将在上下文中查找注册名为 `foo` 的组件。例如，可以在 `.vitepress/theme/index.ts`中全局注册组件：
+
+```ts
+import DefaultTheme from 'vitepress/theme'
+import Foo from './Foo.vue'
+
+export default {
+ extends: DefaultTheme,
+ enhanceApp({ app }) {
+ app.component('foo', Foo)
+ }
+}
+```
diff --git a/docs/zh/reference/default-theme-nav.md b/docs/zh/reference/default-theme-nav.md
new file mode 100644
index 00000000..be9feaac
--- /dev/null
+++ b/docs/zh/reference/default-theme-nav.md
@@ -0,0 +1,161 @@
+# 导航栏 {#nav}
+
+Nav 是显示在页面顶部的导航栏。它包含站点标题、全局菜单链接等。
+
+## 站点标题和图标 {#site-title-and-logo}
+
+默认情况下，nav 显示 [`config.title`](./site-config#title) 作为站点的标题。如果想更改导航栏上显示的内容，可以在 `themeConfig.siteTitle` 选项中定义自定义文本。
+
+```js
+export default {
+ themeConfig: {
+ siteTitle: 'My Custom Title'
+ }
+}
+```
+
+如果站点有图标，则可以通过传递图片路径来显示它。应该将图标直接放在 `public` 中，并赋值该绝对路径。
+
+```js
+export default {
+ themeConfig: {
+ logo: '/my-logo.svg'
+ }
+}
+```
+
+添加图标时，它会与站点标题一起显示。如果只需要图标并且想要隐藏站点标题文本，请将 `siteTitle` 选项设置为 `false`。
+
+```js
+export default {
+ themeConfig: {
+ logo: '/my-logo.svg',
+ siteTitle: false
+ }
+}
+```
+
+如果想添加 `alt` 属性或根据深色/浅色模式自定义，还可以将图标作为对象传递。有关详细信息，请参阅 [`themeConfig.logo`](./default-theme-config#logo)。
+
+## 导航链接 {#navigation-links}
+
+可以定义 `themeConfig.nav` 选项以将链接添加到导航栏。
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ { text: 'Guide', link: '/guide' },
+ { text: 'Config', link: '/config' },
+ { text: 'Changelog', link: 'https://github.com/...' }
+ ]
+ }
+}
+```
+
+`text` 是 nav 中显示的实际文本，而 `link` 是单击文本时将导航到的链接。对于链接，将路径设置为不带 `.md` 后缀的实际文件，并且始终以 `/` 开头。
+
+导航链接也可以是下拉菜单。为此，请替换 `link` 选项，设置 `items` 数组。
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ { text: 'Guide', link: '/guide' },
+ {
+ text: 'Dropdown Menu',
+ items: [
+ { text: 'Item A', link: '/item-1' },
+ { text: 'Item B', link: '/item-2' },
+ { text: 'Item C', link: '/item-3' }
+ ]
+ }
+ ]
+ }
+}
+```
+
+请注意，下拉菜单标题 (上例中的 `Dropdown Menu`) 不能具有 `link` 属性，因为它是打开下拉对话框的按钮。
+
+还可以通过传入更多嵌套项来进一步向下拉菜单项添加“sections”。
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ { text: 'Guide', link: '/guide' },
+ {
+ text: 'Dropdown Menu',
+ items: [
+ {
+ // 该部分的标题
+ text: 'Section A Title',
+ items: [
+ { text: 'Section A Item A', link: '...' },
+ { text: 'Section B Item B', link: '...' }
+ ]
+ }
+ ]
+ },
+ {
+ text: 'Dropdown Menu',
+ items: [
+ {
+ // 也可以省略标题
+ items: [
+ { text: 'Section A Item A', link: '...' },
+ { text: 'Section B Item B', link: '...' }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+### 自定义链接的路由匹配状态 {#customize-link-s-active-state}
+
+当前页面位于匹配路径下时，导航菜单项将突出显示。如果想自定义要匹配的路径，请将 `activeMatch` 属性和正则表达式定义为字符串值。
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ // 当用户位于 `/config/` 路径时，该链接处于激活状态
+ {
+ text: 'Guide',
+ link: '/guide',
+ activeMatch: '/config/'
+ }
+ ]
+ }
+}
+```
+
+::: warning
+`activeMatch` 应为正则表达式字符串，但必须将其定义为字符串。我们不能在这里使用实际的 RegExp 对象，因为它在构建期间不可序列化。
+:::
+
+### 自定义链接的“target”和“rel”属性 {#customize-link-s-target-and-rel-attributes}
+
+默认情况下，VitePress 会根据链接是否为外部链接自动判断 `target` 和 `rel` 属性。但如果愿意，也可以自定义它们。
+
+```js
+export default {
+ themeConfig: {
+ nav: [
+ {
+ text: 'Merchandise',
+ link: 'https://www.thegithubshop.com/',
+ target: '_self',
+ rel: 'sponsored'
+ }
+ ]
+ }
+}
+```
+
+## 社交链接 {#social-links}
+
+参考 [`socialLinks`](./default-theme-config#sociallinks)。
diff --git a/docs/zh/reference/default-theme-prev-next-links.md b/docs/zh/reference/default-theme-prev-next-links.md
new file mode 100644
index 00000000..cdbe8434
--- /dev/null
+++ b/docs/zh/reference/default-theme-prev-next-links.md
@@ -0,0 +1,43 @@
+# 上下页链接 {#prev-next-links}
+
+可以自定义上一页和下一页的文本和链接 (显示在文档页脚处)。如果要使其与侧边栏上的文本不同，这会很有帮助。此外，你可能会发现，要禁用未包含在侧边栏中的页面的页脚或链接时，这很有用。
+
+## prev
+
+- 类型：`string | false | { text?: string; link?: string }`
+
+- 说明：
+
+ 指定要在指向上一页的链接上显示的文本/链接。如果没有在 frontmatter 中设置它，文本/链接将从侧边栏配置中推断出来。
+
+- 示例：
+
+ - 仅自定义文本：
+
+ ```yaml
+ ---
+ prev: 'Get Started | Markdown'
+ ---
+ ```
+
+ - 自定义文本和链接：
+
+ ```yaml
+ ---
+ prev:
+ text: 'Markdown'
+ link: '/guide/markdown'
+ ---
+ ```
+
+ - 隐藏上一页：
+
+ ```yaml
+ ---
+ prev: false
+ ---
+ ```
+
+## next
+
+与 `prev` 相同，但用于下一页。
diff --git a/docs/zh/reference/default-theme-search.md b/docs/zh/reference/default-theme-search.md
new file mode 100644
index 00000000..fdd97200
--- /dev/null
+++ b/docs/zh/reference/default-theme-search.md
@@ -0,0 +1,379 @@
+---
+outline: deep
+---
+
+# 搜索 {#search}
+
+## 本地搜索 {#local-search}
+
+得益于 [minisearch](https://github.com/lucaong/minisearch/)，VitePress 支持使用浏览器内索引进行模糊全文搜索。要启用此功能，只需在 `.vitepress/config.ts` 文件中将 `themeConfig.search.provider` 选项设置为 `'local'` 即可：
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local'
+ }
+ }
+})
+```
+
+示例结果：
+
+
+
+或者，你可以使用 [Algolia DocSearch](#algolia-search) 或一些社区插件，例如：`. Use os _slots_ `#title` e `#lead`para documentar sobre sua equipe.
+
+`
{{ theme.footer.copyright }}
+
+```
+
+## `useRoute` Layout Personalizado!
+ `, combinado com o título global como sufixo. Por exemplo, com a seguinte configuração e conteúdo da página:
+
+```ts
+export default {
+ title: 'Meu Site Incrível'
+}
+```
+
+```md
+# Olá
+```
+
+O título da página será `Olá | Meu Site Incrível`.
+
+### titleTemplate
+
+- Tipo: `string | boolean`
+- Pode ser substituído por página via [frontmatter](./frontmatter-config#titletemplate)
+
+Permite personalizar o sufixo do título de cada página ou o título inteiro. Por exemplo:
+
+```ts
+export default {
+ title: 'Meu Site Incrível',
+ titleTemplate: 'Sufixo Personalizado'
+}
+```
+
+```md
+# Olá
+```
+
+O título da página será `Olá | Sufixo Personalizado`.
+
+Para personalizar completamente como o título deve ser renderizado, você pode usar o símbolo `:title` em `titleTemplate`:
+
+```ts
+export default {
+ titleTemplate: ':title - Sufixo Personalizado'
+}
+```
+
+Aqui, `:title` será substituído pelo texto inferido do primeiro cabeçalho `
` da página. O título do exemplo anterior da página será `Olá - Sufixo Personalizado`.
+
+A opção pode ser definida como `false` para desativar sufixos de título.
+
+### description
+
+- Tipo: `string`
+- Padrão: `Um site VitePress`
+- Pode ser substituído por página via [frontmatter](./frontmatter-config#descrição)
+
+Descrição para o site. Isso será apresentado como uma tag `` na página HTML.
+
+```ts
+export default {
+ descrição: 'Um site VitePress'
+}
+```
+
+### head
+
+- Tipo: `HeadConfig[]`
+- Padrão: `[]`
+- Pode ser acrescentado por página via [frontmatter](./frontmatter-config#head)
+
+Elementos adicionais para adicionar na tag `` da página HTML. As tags adicionadas pelo usuário são mostradas antes da tag `head` de fechamento, após as tags VitePress.
+
+```ts
+type HeadConfig =
+ | [string, Record
+```
+
+В этом случае рекомендуется обернуть путь с помощью [хелпера `withBase`](../reference/runtime-api#withbase), предоставляемого VitePress:
+
+```vue
+
+
+
+
+
+```
diff --git a/docs/ru/guide/cms.md b/docs/ru/guide/cms.md
new file mode 100644
index 00000000..81542d2b
--- /dev/null
+++ b/docs/ru/guide/cms.md
@@ -0,0 +1,58 @@
+---
+outline: deep
+---
+
+# Подключение к CMS {#connecting-to-a-cms}
+
+## Общий рабочий процесс {#general-workflow}
+
+Подключение VitePress к CMS в значительной степени зависит от [динамических маршрутов](./routing#dynamic-routes). Прежде чем приступить к работе, убедитесь, что вы понимаете, как это работает.
+
+Поскольку каждая CMS работает по-своему, здесь мы можем предоставить лишь общую схему работы, которую вам нужно будет адаптировать под свой конкретный сценарий.
+
+1. Если ваша CMS требует аутентификации, создайте файл `.env` для хранения токенов API и загрузите его таким образом:
+
+ ```js
+ // posts/[id].paths.js
+ import { loadEnv } from 'vitepress'
+
+ const env = loadEnv('', process.cwd())
+ ```
+
+2. Получите необходимые данные из CMS и преобразуйте их в соответствующие пути:
+
+ ```js
+ export default {
+ async paths() {
+ // при необходимости используйте соответствующую клиентскую библиотеку CMS
+ const data = await (
+ await fetch('https://my-cms-api', {
+ headers: {
+ // токен, если необходимо
+ }
+ })
+ ).json()
+
+ return data.map((entry) => {
+ return {
+ params: { id: entry.id /* заголовок, автор, дата и т. д. */ },
+ content: entry.content
+ }
+ })
+ }
+ }
+ ```
+
+3. Отрисуйте содержимое страницы:
+
+ ```md
+ # {{ $params.title }}
+
+ - Автор: {{ $params.author }}, {{ $params.date }}
+
+
+ ```
+
+## Руководства по интеграции {#integration-guides}
+
+Если вы написали руководство по интеграции VitePress с конкретной CMS, воспользуйтесь ссылкой «Редактировать эту страницу», чтобы добавить его сюда!
diff --git a/docs/ru/guide/custom-theme.md b/docs/ru/guide/custom-theme.md
new file mode 100644
index 00000000..05ca3b23
--- /dev/null
+++ b/docs/ru/guide/custom-theme.md
@@ -0,0 +1,222 @@
+# Пользовательская тема {#using-a-custom-theme}
+
+## Разрешение темы {#theme-resolving}
+
+Вы можете включить пользовательскую тему, создав файл `.vitepress/theme/index.js` или `.vitepress/theme/index.ts` («файл входа темы»):
+
+```
+.
+├─ docs # корень проекта
+│ ├─ .vitepress
+│ │ ├─ theme
+│ │ │ └─ index.js # файл входа темы
+│ │ └─ config.js # файл конфигурации
+│ └─ index.md
+└─ package.json
+```
+
+VitePress всегда будет использовать пользовательскую тему вместо темы по умолчанию, если обнаружит наличие входного файла темы. Однако вы можете [расширить тему по умолчанию](./extending-default-theme), чтобы выполнить расширенные настройки поверх нее.
+
+## Интерфейс темы {#theme-interface}
+
+Пользовательская тема VitePress определяется как объект со следующим интерфейсом:
+
+```ts
+interface Theme {
+ /**
+ * Корневой компонент макета для каждой страницы
+ * @required
+ */
+ Layout: Component
+ /**
+ * Улучшение экземпляра приложения Vue
+ * @optional
+ */
+ enhanceApp?: (ctx: EnhanceAppContext) => Awaitable
Пользовательский макет!
+
+
+ Пользовательский макет!
+
+ Пользовательский макет!
+
+ Пользовательский макет!
+
+ {{ data }}
+```
+
+Результат:
+
+```json
+{
+ "hello": "мир"
+}
+```
+
+Вы заметите, что сам загрузчик данных не экспортирует `data`. Это VitePress вызывает метод `load()` за кулисами и неявно раскрывает результат через именованный экспорт `data`.
+
+Это работает, даже если загрузчик асинхронный:
+
+```js
+export default {
+ async load() {
+ // получение удалённых данных
+ return (await fetch('...')).json()
+ }
+}
+```
+
+## Данные из локальных файлов {#data-from-local-files}
+
+Если вам нужно генерировать данные на основе локальных файлов, используйте опцию `watch` в загрузчике данных, чтобы изменения, внесённые в эти файлы, вызывали горячие обновления.
+
+Опция `watch` удобна ещё и тем, что вы можете использовать [шаблоны glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) для соответствия нескольким файлам. Шаблоны могут быть относительными к самому файлу загрузчика, а функция `load()` будет получать совпадающие файлы в виде абсолютных путей.
+
+В следующем примере показана загрузка CSV-файлов и их преобразование в JSON с помощью [csv-parse](https://github.com/adaltas/node-csv/tree/master/packages/csv-parse/). Поскольку этот файл выполняется только во время сборки, вы не будете передавать CSV-парсер клиенту!
+
+```js
+import fs from 'node:fs'
+import { parse } from 'csv-parse/sync'
+
+export default {
+ watch: ['./data/*.csv'],
+ load(watchedFiles) {
+ // watchedFiles будет представлять собой массив абсолютных путей к найденным файлам.
+ // Формируем массив метаданных записи блога, которые можно использовать для визуализации списка в макете темы
+ return watchedFiles.map((file) => {
+ return parse(fs.readFileSync(file, 'utf-8'), {
+ columns: true,
+ skip_empty_lines: true
+ })
+ })
+ }
+}
+```
+
+## `createContentLoader` {#createcontentloader}
+
+При создании сайта, ориентированного на контент, нам часто приходится создавать страницы типа «архив», или «индекс», на которых мы перечисляем все доступные записи в нашей коллекции контента. Например, записи в блоге или страницы API. Мы **можем** реализовать это напрямую с помощью API загрузчика данных, но поскольку это очень распространённый случай использования, VitePress также предоставляет функцию `createContentLoader`, чтобы упростить эту задачу:
+
+```js
+// posts.data.js
+import { createContentLoader } from 'vitepress'
+
+export default createContentLoader('posts/*.md' /* параметры */)
+```
+
+Эта функция принимает шаблон glob относительно [исходного каталога](./routing#source-directory) и возвращает объект `{ watch, load }` загрузчика данных, который может быть использован в качестве экспорта по умолчанию в файле загрузчика данных. В нем также реализовано кэширование на основе временных меток изменения файлов для повышения производительности dev.
+
+Обратите внимание, что загрузчик работает только с файлами Markdown — совпадающие файлы, не относящиеся к Markdown, будут пропущены.
+
+Загруженные данные будут представлять собой массив с типом `ContentData[]`:
+
+```ts
+interface ContentData {
+ // отображаемый URL-адрес страницы, например: /posts/hello.html (не включает `base`)
+ // выполните итерацию вручную или используйте пользовательскую `трансформацию` для нормализации путей
+ url: string
+ // метаданные страницы
+ frontmatter: RecordВсе записи блога
+
+
+
+```
+
+### Параметры {#options}
+
+Данные по умолчанию могут не соответствовать всем требованиям — вы можете изменить данные с помощью параметров:
+
+```js
+// posts.data.js
+import { createContentLoader } from 'vitepress'
+
+export default createContentLoader('posts/*.md', {
+ includeSrc: true, // включить исходный текст в формате Markdown?
+ render: true, // включать в себя полный HTML страницы?
+ excerpt: true, // включить отрывок?
+ transform(rawData) {
+ // составляйте карты, сортируйте или фильтруйте исходные данные по своему усмотрению.
+ // конечный результат — это то, что будет отправлено клиенту.
+ return rawData
+ .sort((a, b) => {
+ return +new Date(b.frontmatter.date) - +new Date(a.frontmatter.date)
+ })
+ .map((page) => {
+ page.src // исходный текст в формате Markdown
+ page.html // отображение полной страницы HTML
+ page.excerpt // отображаемый отрывок HTML (содержимое выше первого `---`)
+ return {
+ /* ... */
+ }
+ })
+ }
+})
+```
+
+Посмотрите, как он используется в [блоге Vue.js](https://github.com/vuejs/blog/blob/main/.vitepress/theme/posts.data.ts).
+
+API `createContentLoader` также можно использовать внутри [хуков сборки](../reference/site-config#build-hooks):
+
+```js
+// .vitepress/config.js
+export default {
+ async buildEnd() {
+ const posts = await createContentLoader('posts/*.md').load()
+ // генерируем файлы на основе метаданных сообщений, например, RSS-канал
+ }
+}
+```
+
+**Types**
+
+```ts
+interface ContentOptionsДемонстрация
+
+
+
+
+
+```
+````
+
+**Результат**
+
+```js
+export default {
+ name: 'MyComponent'
+ // ...
+}
+```
+
+```html
+
+
+```
+
+[Список всех поддерживаемых языков](https://shiki.style/languages).
+
+Вы также можете настроить тему подсветки синтаксиса в конфигурации приложения. Более подробную информацию см. в секции [`markdown`](../reference/site-config#markdown).
+
+## Выделение строк в блоках кода {#line-highlighting-in-code-blocks}
+
+**Разметка**
+
+````
+```js{4}
+export default {
+ data () {
+ return {
+ msg: 'Подсвечено!'
+ }
+ }
+}
+```
+````
+
+**Результат**
+
+```js{4}
+export default {
+ data () {
+ return {
+ msg: 'Подсвечено!'
+ }
+ }
+}
+```
+
+Помимо одной строки, вы можете указать несколько отдельных строк, диапазонов или и то, и другое:
+
+– Диапазоны строк, например: `{5-8}`, `{3-10}`, `{10-17}`
+
+- Несколько одиночных строк, например: `{4,7,9}`
+- Диапазоны строк и отдельные строки, например: `{4,7-13,16,23-27,40}`
+
+**Разметка**
+
+````
+```js{1,4,6-8}
+export default { // Подсвечено
+ data () {
+ return {
+ msg: `Подсвечено!
+ Эта строка не выделена,
+ но эта и две следующих - да.`,
+ motd: 'VitePress - это потрясающе',
+ lorem: 'ipsum'
+ }
+ }
+}
+```
+````
+
+**Результат**
+
+```js{1,4,6-8}
+export default { // Подсвечено
+ data () {
+ return {
+ msg: `Подсвечено!
+ Эта строка не выделена,
+ но эта и две следующих - да.`,
+ motd: 'VitePress - это потрясающе',
+ lorem: 'ipsum',
+ }
+ }
+}
+```
+
+Кроме того, можно выделять непосредственно в строке, используя комментарий `// [!code highlight]`.
+
+**Разметка**
+
+````
+```js
+export default {
+ data () {
+ return {
+ msg: 'Подсвечено!' // [!!code highlight]
+ }
+ }
+}
+```
+````
+
+**Результат**
+
+```js
+export default {
+ data() {
+ return {
+ msg: 'Подсвечено!' // [!code highlight]
+ }
+ }
+}
+```
+
+## Фокус в блоках кода {#focus-in-code-blocks}
+
+Добавление комментария `// [!code focus]` к строке сфокусирует её и размоет остальные части кода.
+
+Кроме того, вы можете задать количество строк для фокусировки с помощью `// [!code focus:
++ 
+```
+
+::: warning ПРЕДУПРЕЖДЕНИЕ
+Для динамических изображений вам всё ещё нужно использовать `withBase`, как показано в [Руководстве по базовому URL](./asset-handling#base-url).
+:::
+
+Используйте регулярное выражение `
` до `
`.
+ *
+ * @default 2
+ */
+ level?: number | [number, number] | 'deep'
+
+ /**
+ * Заголовок, который будет отображаться в оглавлении.
+ *
+ * @default 'На этой странице'
+ */
+ label?: string
+}
+```
+
+## socialLinks {#sociallinks}
+
+- Тип: `SocialLink[]`
+
+Вы можете задать эту опцию, чтобы показывать ссылки на ваши социальные аккаунты с помощью иконок в панели навигации.
+
+```ts
+export default {
+ themeConfig: {
+ socialLinks: [
+ { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
+ { icon: 'twitter', link: '...' },
+ // Вы также можете добавить пользовательские иконки, передав SVG в виде строки:
+ {
+ icon: {
+ svg: ''
+ },
+ link: '...',
+ // Вы также можете включить пользовательский ярлык для доступности (необязательно, но рекомендуется):
+ ariaLabel: 'классная ссылка'
+ }
+ ]
+ }
+}
+```
+
+```ts
+interface SocialLink {
+ icon: SocialLinkIcon
+ link: string
+ ariaLabel?: string
+}
+
+type SocialLinkIcon =
+ | 'discord'
+ | 'facebook'
+ | 'github'
+ | 'instagram'
+ | 'linkedin'
+ | 'mastodon'
+ | 'npm'
+ | 'slack'
+ | 'twitter'
+ | 'x'
+ | 'youtube'
+ | { svg: string }
+```
+
+## footer {#footer}
+
+- Тип: `Footer`
+- Можно переопределить для каждой страницы с помощью [метаданных](./frontmatter-config#footer)
+
+Настройка подвала. Вы можете разместить в подвале сообщение или текст об авторских правах, однако он будет отображаться только в том случае, если страница не содержит боковой панели. Это объясняется соображениями дизайна.
+
+```ts
+export default {
+ themeConfig: {
+ footer: {
+ message: 'Опубликовано под лицензией MIT.',
+ copyright: '© 2019 – настоящее время, Эван Ю'
+ }
+ }
+}
+```
+
+```ts
+export interface Footer {
+ message?: string
+ copyright?: string
+}
+```
+
+## editLink {#editlink}
+
+- Тип: `EditLink`
+- Можно переопределить для каждой страницы с помощью [метаданных](./frontmatter-config#editlink)
+
+Ссылка для редактирования позволяет отобразить ссылку для редактирования страницы на сервисах управления Git, таких как GitHub или GitLab. См. секцию [Тема по умолчанию: Ссылка для редактирования](./default-theme-edit-link) для получения более подробной информации.
+
+```ts
+export default {
+ themeConfig: {
+ editLink: {
+ pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
+ text: 'Редактировать эту страницу на GitHub'
+ }
+ }
+}
+```
+
+```ts
+export interface EditLink {
+ pattern: string
+ text?: string
+}
+```
+
+## lastUpdated {#lastupdated}
+
+- Тип: `LastUpdatedOptions`
+
+Позволяет настраивать текст и формат даты последнего обновления.
+
+```ts
+export default {
+ themeConfig: {
+ lastUpdated: {
+ text: 'Обновлено',
+ formatOptions: {
+ dateStyle: 'full',
+ timeStyle: 'medium'
+ }
+ }
+ }
+}
+```
+
+```ts
+export interface LastUpdatedOptions {
+ /**
+ * @default 'Last updated'
+ */
+ text?: string
+
+ /**
+ * @default
+ * { dateStyle: 'short', timeStyle: 'short' }
+ */
+ formatOptions?: Intl.DateTimeFormatOptions & { forceLocale?: boolean }
+}
+```
+
+## algolia {#algolia}
+
+- Тип: `AlgoliaSearch`
+
+Опция для поддержки поиска на вашем сайте документации с помощью [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Подробнее в главе [Тема по умолчанию: Поиск](./default-theme-search)
+
+```ts
+export interface AlgoliaSearchOptions extends DocSearchProps {
+ locales?: Record
`. Используйте слоты `#title` и `#lead`, чтобы рассказать о своей команде.
+
+`
{{ theme.footer.copyright }}
+
+```
+
+## `useRoute` Пользовательский макет!
+ `, объединённое с глобальным `title` в качестве суффикса. Например, со следующей конфигурацией и содержимым страницы:
+
+```ts
+export default {
+ title: 'Мой замечательный сайт'
+}
+```
+
+```md
+# Привет
+```
+
+Заголовок страницы будет таким: `Привет | Мой замечательный сайт`.
+
+### titleTemplate {##titletemplate}
+
+- Тип: `string | boolean`
+- Можно переопределить для каждой страницы с помощью [метаданных](./frontmatter-config#titletemplate)
+
+Позволяет настраивать суффикс заголовка каждой страницы или весь заголовок. Например:
+
+```ts
+export default {
+ title: 'Мой замечательный сайт',
+ titleTemplate: 'Пользовательский суффикс'
+}
+```
+
+```md
+# Привет
+```
+
+Заголовок страницы будет таким: `Привет | Пользовательский суффикс`.
+
+Чтобы полностью настроить отображение заголовка, вы можете использовать символ `:title` в `titleTemplate`:
+
+```ts
+export default {
+ titleTemplate: ':title - Пользовательский суффикс'
+}
+```
+
+Здесь `:title` будет заменён текстом, выведенным из первого заголовка страницы `
`. Заголовок страницы предыдущего примера будет `Привет - Пользовательский суффикс`.
+
+Опция может быть установлена в значение `false`, чтобы отключить суффиксы заголовков.
+
+### description {#description}
+
+- Тип: `string`
+- По умолчанию: `A VitePress site`
+- Можно переопределить для каждой страницы с помощью [метаданных](./frontmatter-config#description)
+
+Описание для сайта. Это будет отображаться как тег `` в HTML-странице.
+
+```ts
+export default {
+ description: 'A VitePress site'
+}
+```
+
+### head {#head}
+
+- Тип: `HeadConfig[]`
+- По умолчанию: `[]`
+- Можно добавлять на страницу через [метаданные](./frontmatter-config#head)
+
+Дополнительные элементы для отображения в теге `` в HTML-странице. Добавленные пользователем теги выводятся перед закрывающим тегом `head`, после тегов VitePress.
+
+```ts
+type HeadConfig =
+ | [string, Record
+```
+
+在这种情况下，建议使用 VitePress 提供的 [`withBase` helper](../reference/runtime-api#withbase) 来包括路径：
+
+```vue
+
+
+
+
+
+```
diff --git a/docs/zh/guide/cms.md b/docs/zh/guide/cms.md
new file mode 100644
index 00000000..916ba050
--- /dev/null
+++ b/docs/zh/guide/cms.md
@@ -0,0 +1,56 @@
+---
+outline: deep
+---
+
+# 连接到 CMS {#connecting-to-a-cms}
+
+## 一般的工作流 {#general-workflow}
+
+将 VitePress 连接到 CMS 主要围绕[动态路由](./routing#dynamic-routes)展开。在继续阅读之前，请确保了解它的工作原理。
+
+由于每个 CMS 的工作方式都不同，因此我们只能提供一个通用的工作流，你需要根据具体情况进行调整。
+
+1. 如果你的 CMS 需要身份验证，请创建一个 `.env` 文件来存储你的 API token：
+
+ ```js
+ // posts/[id].paths.js
+ import { loadEnv } from 'vitepress'
+
+ const env = loadEnv('', process.cwd())
+ ```
+
+2. 从 CMS 获取必要的数据并将其格式调整为合适的路径数据：
+
+ ```js
+ export default {
+ async paths() {
+ // 如有需要，使用相应的 CMS 客户端库
+ const data = await (await fetch('https://my-cms-api', {
+ headers: {
+ // 如有必要，可使用 token
+ }
+ })).json()
+
+ return data.map(entry => {
+ return {
+ params: { id: entry.id, /* title, authors, date 等 */ },
+ content: entry.content
+ }
+ })
+ }
+ }
+ ```
+
+3. 在页面中渲染内容：
+
+ ```md
+ # {{ $params.title }}
+
+ - by {{ $params.author }} on {{ $params.date }}
+
+
+ ```
+
+## 整合指南 {#integration-guides}
+
+如果你已经写了一篇关于如何将 VitePress 与特定的 CMS 集成的指南，请点击下面的“在 GitHub 上编辑此页面”链接将它提交到这里！
diff --git a/docs/zh/guide/custom-theme.md b/docs/zh/guide/custom-theme.md
new file mode 100644
index 00000000..e5eb760b
--- /dev/null
+++ b/docs/zh/guide/custom-theme.md
@@ -0,0 +1,222 @@
+# 自定义主题 {#using-a-custom-theme}
+
+## 解析主题 {#theme-resolving}
+
+可以通过创建一个 `.vitepress/theme/index.js` 或 `.vitepress/theme/index.ts` 文件 (即“主题入口文件”) 来启用自定义主题：
+
+```
+.
+├─ docs # 项目根目录
+│ ├─ .vitepress
+│ │ ├─ theme
+│ │ │ └─ index.js # 主题入口
+│ │ └─ config.js # 配置文件
+│ └─ index.md
+└─ package.json
+```
+
+当检测到存在主题入口文件时，VitePress 总会使用自定义主题而不是默认主题。但你可以[扩展默认主题](./extending-default-theme)来在其基础上实现更高级的自定义。
+
+## 主题接口 {#theme-interface}
+
+VitePress 自定义主题是一个对象，该对象具有如下接口：
+
+```ts
+interface Theme {
+ /**
+ * 每个页面的根布局组件
+ * @required
+ */
+ Layout: Component
+ /**
+ * 增强 Vue 应用实例
+ * @optional
+ */
+ enhanceApp?: (ctx: EnhanceAppContext) => Awaitable
Custom Layout!
+
+
+ Custom Layout!
+
+ Custom Layout!
+
+ Custom Layout!
+
+ {{ data }}
+```
+
+输出：
+
+```json
+{
+ "hello": "world"
+}
+```
+
+你会注意到 data loader 本身并没有导出 `data`。这是因为 VitePress 在后台调用了 `load()` 方法，并通过名为 `data` 的具名导出隐式地暴露了结果。
+
+即使它是异步的，这也是有效的：
+
+```js
+export default {
+ async load() {
+ // 获取远程数据
+ return (await fetch('...')).json()
+ }
+}
+```
+
+## 使用本地文件生成数据 {#data-from-local-files}
+
+当需要基于本地文件生成数据时，需要在 data loader 中使用 `watch` 选项，以便这些文件改动时可以触发热更新。
+
+`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 解析器发送到客户端。
+
+```js
+import fs from 'node:fs'
+import { parse } from 'csv-parse/sync'
+
+export default {
+ watch: ['./data/*.csv'],
+ load(watchedFiles) {
+ // watchFiles 是一个所匹配文件的绝对路径的数组。
+ // 生成一个博客文章元数据数组
+ // 可用于在主题布局中呈现列表。
+ return watchedFiles.map((file) => {
+ return parse(fs.readFileSync(file, 'utf-8'), {
+ columns: true,
+ skip_empty_lines: true
+ })
+ })
+ }
+}
+```
+
+## `createContentLoader`
+
+当构建一个内容为主的站点时，我们经常需要创建一个“归档”或“索引”页面：一个我们可以列出内容中的所有可用条目的页面，例如博客文章或 API 页面。我们**可以**直接使用数据加载 API 实现这一点，但由于这会经常使用，VitePress 还提供了一个 `createContentLoader` 辅助函数来简化这个过程：
+
+```js
+// posts.data.js
+import { createContentLoader } from 'vitepress'
+
+export default createContentLoader('posts/*.md', /* options */)
+```
+
+该辅助函数接受一个相对于[源目录](./routing#source-directory)的 glob 模式，并返回一个 `{ watch, load }` 数据加载对象，该对象可以用作数据加载文件中的默认导出。它还基于文件修改时间戳实现了缓存以提高开发性能。
+
+请注意，数据加载仅适用于 Markdown 文件——匹配的非 Markdown 文件将被跳过。
+
+加载的数据将是一个类型为 `ContentData[]` 的数组：
+
+```ts
+interface ContentData {
+ // 页面的映射 URL，如 /posts/hello.html（不包括 base）
+ // 手动迭代或使用自定义 `transform` 来标准化路径
+ url: string
+ // 页面的 frontmatter 数据
+ frontmatter: RecordAll Blog Posts
+
+
+
+```
+
+### 选项 {#options}
+
+默认数据可能不适合所有需求——可以选择使用选项转换数据：
+
+```js
+// posts.data.js
+import { createContentLoader } from 'vitepress'
+
+export default createContentLoader('posts/*.md', {
+ includeSrc: true, // 包含原始 markdown 源?
+ render: true, // 包含渲染的整页 HTML?
+ excerpt: true, // 包含摘录?
+ transform(rawData) {
+ // 根据需要对原始数据进行 map、sort 或 filter
+ // 最终的结果是将发送给客户端的内容
+ return rawData.sort((a, b) => {
+ return +new Date(b.frontmatter.date) - +new Date(a.frontmatter.date)
+ }).map((page) => {
+ page.src // 原始 markdown 源
+ page.html // 渲染的整页 HTML
+ page.excerpt // 渲染的摘录 HTML（第一个 `---` 上面的内容）
+ return {/* ... */}
+ })
+ }
+})
+```
+
+查看它在 [Vue.js 博客](https://github.com/vuejs/blog/blob/main/.vitepress/theme/posts.data.ts)中是如何使用的。
+
+`createContentLoader` API 也可以在[构建钩子](/reference/site-config#build-hooks)中使用：
+
+```js
+// .vitepress/config.js
+export default {
+ async buildEnd() {
+ const posts = await createContentLoader('posts/*.md').load()
+ // 根据 posts 元数据生成文件，如 RSS 订阅源
+ }
+}
+```
+
+**类型**
+
+```ts
+interface ContentOptionsDemo
+
+
+
+
+
+```
+````
+
+**输出**
+
+```js
+export default {
+ name: 'MyComponent'
+ // ...
+}
+```
+
+```html
+
+
+```
+
+在 Shiki 的代码仓库中，可以找到[合法的编程语言列表](https://shiki.style/languages)。
+
+还可以全局配置中自定义语法高亮主题。有关详细信息，参见 [`markdown` 选项](../reference/site-config#markdown)得到更多信息。
+
+## 在代码块中实现行高亮 {#line-highlighting-in-code-blocks}
+
+**输入**
+
+````
+```js{4}
+export default {
+ data () {
+ return {
+ msg: 'Highlighted!'
+ }
+ }
+}
+```
+````
+
+**输出**
+
+```js{4}
+export default {
+ data () {
+ return {
+ msg: 'Highlighted!'
+ }
+ }
+}
+```
+
+除了单行之外，还可以指定多个单行、多行，或两者均指定：
+
+- 多行：例如 `{5-8}`、`{3-10}`、`{10-17}`
+- 多个单行：例如 `{4,7,9}`
+- 多行与单行：例如 `{4,7-13,16,23-27,40}`
+
+**输入**
+
+````
+```js{1,4,6-8}
+export default { // Highlighted
+ data () {
+ return {
+ msg: `Highlighted!
+ This line isn't highlighted,
+ but this and the next 2 are.`,
+ motd: 'VitePress is awesome',
+ lorem: 'ipsum'
+ }
+ }
+}
+```
+````
+
+**输出**
+
+```js{1,4,6-8}
+export default { // Highlighted
+ data () {
+ return {
+ msg: `Highlighted!
+ This line isn't highlighted,
+ but this and the next 2 are.`,
+ motd: 'VitePress is awesome',
+ lorem: 'ipsum',
+ }
+ }
+}
+```
+
+也可以使用 `// [!code highlight]` 注释实现行高亮。
+
+**输入**
+
+````
+```js
+export default {
+ data () {
+ return {
+ msg: 'Highlighted!' // [!!code highlight]
+ }
+ }
+}
+```
+````
+
+**输出**
+
+```js
+export default {
+ data() {
+ return {
+ msg: 'Highlighted!' // [!code highlight]
+ }
+ }
+}
+```
+
+## 代码块中聚焦 {#focus-in-code-blocks}
+
+在某一行上添加 `// [!code focus]` 注释将聚焦它并模糊代码的其他部分。
+
+此外，可以使用 `// [!code focus:
++ 
+```
+
+::: warning
+对于动态图像，仍然需要 `withBase`，如 [Base URL](./asset-handling#base-url) 中所示。
+:::
+
+使用 `
` 到 `
` 的所有标题。
+ *
+ * @default 2
+ */
+ level?: number | [number, number] | 'deep'
+
+ /**
+ * 显示在 outline 上的标题。
+ *
+ * @default 'On this page'
+ */
+ label?: string
+}
+```
+
+## socialLinks
+
+- 类型：`SocialLink[]`
+
+可以定义此选项以在导航栏中展示带有图标的社交帐户链接。
+
+```ts
+export default {
+ themeConfig: {
+ socialLinks: [
+ { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
+ { icon: 'twitter', link: '...' },
+ // 可以通过将 SVG 作为字符串传递来添加自定义图标：
+ {
+ icon: {
+ svg: ''
+ },
+ link: '...',
+ // 也可以为无障碍添加一个自定义标签 (可选但推荐):
+ ariaLabel: 'cool link'
+ }
+ ]
+ }
+}
+```
+
+```ts
+interface SocialLink {
+ icon: SocialLinkIcon
+ link: string
+ ariaLabel?: string
+}
+
+type SocialLinkIcon =
+ | 'discord'
+ | 'facebook'
+ | 'github'
+ | 'instagram'
+ | 'linkedin'
+ | 'mastodon'
+ | 'npm'
+ | 'slack'
+ | 'twitter'
+ | 'x'
+ | 'youtube'
+ | { svg: string }
+```
+
+## footer
+
+- 类型：`Footer`
+- 可以通过 [frontmatter](./frontmatter-config#footer) 进行覆盖。
+
+页脚配置。可以添加 message 和 copyright。由于设计原因，仅当页面不包含侧边栏时才会显示页脚。
+
+```ts
+export default {
+ themeConfig: {
+ footer: {
+ message: 'Released under the MIT License.',
+ copyright: 'Copyright © 2019-present Evan You'
+ }
+ }
+}
+```
+
+```ts
+export interface Footer {
+ message?: string
+ copyright?: string
+}
+```
+
+## editLink
+
+- 类型：`EditLink`
+- 每个页面可以通过 [frontmatter](./frontmatter-config#editlink) 覆盖
+
+编辑链接可让显示链接以编辑 Git 管理服务 (例如 GitHub 或 GitLab) 上的页面。有关详细信息，请参阅[默认主题：编辑链接](./default-theme-edit-link)。
+
+```ts
+export default {
+ themeConfig: {
+ editLink: {
+ pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
+ text: 'Edit this page on GitHub'
+ }
+ }
+}
+```
+
+```ts
+export interface EditLink {
+ pattern: string
+ text?: string
+}
+```
+
+## lastUpdated
+
+- 类型：`LastUpdatedOptions`
+
+允许自定义上次更新的文本和日期格式。
+
+```ts
+export default {
+ themeConfig: {
+ lastUpdated: {
+ text: 'Updated at',
+ formatOptions: {
+ dateStyle: 'full',
+ timeStyle: 'medium'
+ }
+ }
+ }
+}
+```
+
+```ts
+export interface LastUpdatedOptions {
+ /**
+ * @default 'Last updated'
+ */
+ text?: string
+
+ /**
+ * @default
+ * { dateStyle: 'short', timeStyle: 'short' }
+ */
+ formatOptions?: Intl.DateTimeFormatOptions & { forceLocale?: boolean }
+}
+```
+
+## algolia
+
+- 类型：`AlgoliaSearch`
+
+支持使用 [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch) 搜索站点文档。在[默认主题：搜索](./default-theme-search) 中了解更多信息。
+
+```ts
+export interface AlgoliaSearchOptions extends DocSearchProps {
+ locales?: Record
` 标题。使用 `#title` 和 `#lead` 插槽来介绍你的团队。
+
+`
{{ theme.footer.copyright }}
+
+```
+
+## `useRoute` Custom Layout!
+