@ -12,29 +12,33 @@ Todos los archivos Markdown son compilados en componentes Vue y procesados por [
```
Puede referenciar assets estáticos en sus archivos markdown, sus componentes `*.vue` en el tema, estilos y simples archivos `.css`, usando paths públicos absolutos (com base en la raiz del projeto) o paths relativos (con base en su sistema de arhivos). Este último es semejante al comportamiento que está acostumbrado se ya usó Vite, Vue CLI o el `file-loader` de webpack.
Puede referenciar assets estáticos en sus archivos markdown, sus componentes `*.vue` en el tema, estilos y simples archivos `.css`, usando rutas públicas absolutas (en base a la raíz del proyecto) o rutas relativos (en base en su sistema de archivos). Este último es semejante al comportamiento que está acostumbrado se ya usó Vite, Vue CLI o el `file-loader` de webpack.
Tipos comunes de archivos de imagen, media y fuente son detectados e incluidos automaticamente como assets.
Tipos comunes de archivos de imagen, media y fuente son detectados e incluidos automáticamente como assets.
Todos los assets referenciados, incluyendo aquellos usando paths absolutos, serán copiados al directorio de salida con un nombre de archivo hash en la compilación de producción. Assets nunca referenciados no serán copiados. Assets de imagen menores que 4KB serán incorporados en base64 - esto puede ser configurado por la opción [`vite`](../reference/site-config#vite) en configuración.
::: tip Los archivos vinculados no se tratan como recursos.
Los PDF u otros documentos a los que se hace referencia mediante enlaces dentro de archivos Markdown no se tratan automáticamente como recursos. Para que los archivos vinculados sean accesibles, debe colocarlos manualmente en el directorio [`public`](#the-public-directory) de su proyecto.
:::
Todas las referencias de path **estáticas**, incluyendo paths absolutos, deben ser basadas en la estructura de su directorio de trabajo.
Todos los assets referenciados, incluyendo aquellos usando rutas absolutas, serán copiados al directorio de salida con un nombre de archivo hash en la compilación de producción. Assets nunca referenciados no serán copiados. Assets de imagen menores que 4KB serán incorporados en base64 - esto puede ser configurado por la opción [`vite`](../reference/site-config#vite) en configuración.
## El directorio público {#the-public-directory}
Todas las referencias de rutas **estáticas**, incluyendo rutas absolutos, deben ser basadas en la estructura de su directorio de trabajo.
A veces, puede ser necesario proveer assets estáticos que no son referenciados directamente en ninguno de sus componentes del tema o Markdown, o usted puede querer servir ciertos archivos con el nombre del archivo original. Ejemplos de tales archivos incluyen `robots.txt`, favicons e iconos PWA.
## El Directorio Público {#the-public-directory}
Puede colocar esos archivos en el directorio `public` sobre el [directorio de origen](./routing#source-directory). Por ejemplo, se la raiz de su proyecto fuera `./docs` y estuviera usando localización por defecto del directorio fuente, entonces el directorio público será `./docs/public`.
A veces, puede ser necesario proveer assets estáticos que no son referenciados directamente en ningún Markdown o componentes del tema, o usted puede querer servir ciertos archivos con el nombre del archivo original. Ejemplos de tales archivos incluyen `robots.txt`, favicons e iconos PWA.
Los assets colocados en `public` serán copiados a la raiz del directorio de salida tal como son.
Puede colocar esos archivos en el directorio `public` sobre el [directorio de origen](./routing#source-directory). Por ejemplo, se la raíz de su proyecto fuera `./docs` y estuviera usando ubicación por defecto del directorio fuente, entonces el directorio público será `./docs/public`.
Observe que usted debe referenciar archivos colocados en `public` usando e path absoluto de la raiz - por ejemplo, `public/icon.png` debe siempre ser referenciado en el código fuente como `/icon.png`.
Los assets colocados en `public` serán copiados a la raíz del directorio de salida tal como son.
Observe que usted debe referenciar archivos colocados en `public` utilizando rutas absolutas de la raíz - por ejemplo, `public/icon.png` debe siempre ser referenciado en el código fuente como `/icon.png`.
## URL Base {#base-url}
Si su sitio estuviera implantado en una URL que no sea la raiz, será necesario definir la opción `base` en `.vitepress/config.js`. Por ejemplo, se planea implantar su sitio en `https://foo.github.io/bar/`, entonces `base` debe ser definido como `'/bar/'` (siempre debe comenzar y terminar con una barra).
Si su sitio estuviera implantado en una URL que no sea la raíz, será necesario definir la opción `base` en `.vitepress/config.js`. Por ejemplo, se planea implantar su sitio en `https://foo.github.io/bar/`, entonces `base` debe ser definido como `'/bar/'` (siempre debe comenzar y terminar con una barra).
Todos los paths de sus assets estáticos son procesados automáticamente para ajustarse a los diferentes valores de configuración `base`. Por ejemplo, se tuviera una referencia absoluta a un asset sobre `public` en su Markdown:
Todos las rutas de sus assets estáticos son procesados automáticamente para ajustarse a los diferentes valores de configuración `base`. Por ejemplo, se tuviera una referencia absoluta a un asset sobre `public` en su Markdown:
```md
@ -48,7 +52,7 @@ Sin embargo, se estuviera creando un componente de tema que vincula assets diná
<img:src="theme.logoPath"/>
```
En este caso, es recomendable complementar el path con el [`auxiliar withBase`](../reference/runtime-api#withbase) proporcionado por VitePress:
En este caso, es recomendable complementar la ruta con el [auxiliar `withBase`](../reference/runtime-api#withbase) proporcionado por VitePress:
Conectar VitePress a un CMS girará mayormente en torno a [Rutas dinámicas](./routing#dynamic-routes). Asegurese de entender cómo funcionan antes de proceder.
Conectar VitePress a un CMS girará mayormente en torno a [Rutas dinámicas](./routing#dynamic-routes). Asegúrese de entender cómo funcionan antes de proceder.
Como cada CMS funcionará de forma diferente, aqui podemos proveer apenas un flujo de trabajo genérico que requiere ser adaptado para cada escenario específico.
Como cada CMS funcionará de forma diferente, aquí podemos proveer apenas un flujo de trabajo genérico que requiere ser adaptado para cada escenario específico.
1. Si su CMS exige autenticación, cree un archivo `.env` para almacenar los tokens del API y cargarlos como:
@ -20,7 +20,7 @@ Como cada CMS funcionará de forma diferente, aqui podemos proveer apenas un flu
const env = loadEnv('', process.cwd())
```
2. Obtenga los datos necesarios del CMS y aplique formato en paths de datos apropiados:
2. Obtenga los datos necesarios del CMS y aplique formato en rutas de datos apropiados:
```js
export default {
@ -28,7 +28,7 @@ Como cada CMS funcionará de forma diferente, aqui podemos proveer apenas un flu
// use la biblioteca del cliente CMS respectiva si es necesario
const data = await (await fetch('https://my-cms-api', {
headers: {
// token caso necesario
// token si es necesario
}
})).json()
@ -42,7 +42,7 @@ Como cada CMS funcionará de forma diferente, aqui podemos proveer apenas un flu
}
```
3. Presente el contenido en la página:
3. Renderice el contenido en la página:
```md
# {{ $params.title }}
@ -52,6 +52,6 @@ Como cada CMS funcionará de forma diferente, aqui podemos proveer apenas un flu
<!-- @content -->
```
## Guias de Integración {#integration-guides}
## Guías de Integración {#integration-guides}
Se usted escribió una guía sobre cómo integrar VitePress con un CMS específico, por favor use el link "Edite esta página" abajo para enviarlo hacia aqui!
Se usted escribió una guía sobre cómo integrar VitePress con un CMS específico, por favor use el link "Edite esta página" abajo para enviarlo hacia aquí!
@ -10,7 +10,7 @@ Puede habilitar un tema personalizado creando un archivo `.vitepress/theme/index
```
.
├─ docs # raiz del proyecto
├─ docs # raíz del proyecto
│ ├─ .vitepress
│ │ ├─ theme
│ │ │ └─ index.js # entrada de tema
@ -19,16 +19,16 @@ Puede habilitar un tema personalizado creando un archivo `.vitepress/theme/index
└─ package.json
```
VitePress siempre usará el tema personalizado en vez del tema por defecto cuando detecte la precencia de un archivo de entrada de tema. Sin embargo, puede [extender el tema por defecto](./extending-default-theme) para realizar personalizaciones avanzadas sobre el.
VitePress siempre usará el tema personalizado en vez del tema por defecto cuando detecte la presencia de un archivo de entrada de tema. Sin embargo, puede [extender el tema por defecto](./extending-default-theme) para realizar personalizaciones avanzadas sobre el.
## Interfaz del Tema {#theme-interface}
Un tema personalizado de VitePress es definifo como un objeto con la siguiente interfaz:
Un tema personalizado de VitePress es definido como un objeto con la siguiente interfaz:
```ts
interface Theme {
/**
* Componente raiz de layout para todas las páginas
* Componente raíz de layout para cada página
* @required
*/
Layout: Component
@ -46,7 +46,7 @@ interface Theme {
interface EnhanceAppContext {
app: App // instancia de la aplicación Vue
router: Router // instancia del enrutador VitePress
router: Router // Enrutador VitePress
siteData: Ref<SiteData> // Metadata a nivel del sitio
}
```
@ -62,12 +62,33 @@ import Layout from './Layout.vue'
export default {
Layout,
enhanceApp({ app, router, siteData }) {
// ...
// app.component(...)
// app.use(...)
}
}
```
La exportación por defecto es el único contrato para un tema personalizado, y apenas la propiedad `Layout` es exigida. Tecnicamente, un tema de VitePress puede ser tan simple como un único componente Vue.
El hook `enhanceApp` permite acceder a la [instancia de la aplicación Vue](https://vuejs.org/api/application.html) y otros datos de tiempo de ejecución, que se pueden usar para [registrar componentes globales](./extending-default-theme.md#registering-global-components), integrarse con bibliotecas de Vue, etc.
El valor `router` es la misma instancia del enrutador VitePress que devuelve [`useRouter()`](../reference/runtime-api#userouter). Para escuchar los cambios de ruta, asigne manejadores al enrutador:
```ts [.vitepress/theme/index.ts]
export default {
enhanceApp({ router }) {
router.onBeforeRouteChange = (to) => {
console.log('navegando a', to)
}
router.onAfterRouteChange = (to) => {
console.log('navegando a', to)
}
}
}
```
Devuelve `false` desde `onBeforeRouteChange` o `onBeforePageLoad` para cancelar la navegación.
La exportación predeterminada es el único contrato para un tema personalizado, y solo se requiere la propiedad `Layout`. Por lo tanto, técnicamente, un tema de VitePress puede ser tan simple como un único componente de Vue.
Dentro de su componente de layout, el funciona como una aplicación Vite + Vue 3 normal. Note que el tema también necesita ser [compatible con SSR](./ssr-compat).
@ -77,9 +98,9 @@ El componente de layout más básico necesita un componente [`<Content />`](../r
```vue [.vitepress/theme/Layout.vue]
<template>
<h1>Layout Personalizado!</h1>
<h1>¡Layout Personalizado!</h1>
<!-- aqui es donde el contenido markdown será presentado -->
<!-- aquí es donde el contenido markdown será presentado -->
<Content/>
</template>
```
@ -93,16 +114,16 @@ const { page } = useData()
</script>
<template>
<h1>Layout Personalizado!</h1>
<h1>¡Layout Personalizado!</h1>
<divv-if="page.isNotFound">
Página 404 personalizada!
¡Página 404 personalizada!
</div>
<Contentv-else/>
</template>
```
El auxiliar [`useData()`](../reference/runtime-api#usedata) proporciona todos los datos en tiempo de ejecución que necesitamos para mostrar layouts diferentes. Uno de los otros datos que podemos accesar es el frontmatter de la página actual. Podemos aprovechar esto para permitir que el usuario final controle el layout en cada página. Por ejemplo, el usuario puede indicar que la página debe usar un layout especial de la pagina inicial con:
El auxiliar [`useData()`](../reference/runtime-api#usedata) proporciona todos los datos para condicionalmente en tiempo de ejecución mostrar layouts diferentes. Uno de los otros datos que podemos acceder es el frontmatter de la página actual. Podemos aprovechar esto para permitir que el usuario final controle el layout en cada página. Por ejemplo, el usuario puede indicar que la página debe usar un layout especial de la pagina inicial con:
@ -156,23 +177,23 @@ Consulte la [Referencia del API en tiempo de Ejecución](../reference/runtime-ap
## Distribuyendo un Tema Personalizado {#distributing-a-custom-theme}
La manera más facil de distribuir un tema personalizado es proporcionarlo como un [repositorio de template en GitHub](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository).
La manera más fácil de distribuir un tema personalizado es proporcionarlo como un [repositorio plantilla en GitHub](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository).
Si desea distribuir su tema como un paquete npm, siga estos pasos:
1. Exporte el objeto del tema como la exportación por defecto en su archivo de paquete.
1. Exporta el objeto de tema como exportación predeterminada en la entrada de tu paquete.
2. Si aplica, exporte la definición de configuración del tipo de tema como `ThemeConfig`.
2. Si aplica, exporte la definición del tipo de configuración de su tema como `ThemeConfig`.
3. Si su tema exige ajustes en la configuración de VitePress, exporte esa configuración en un subdirectorio del paquete (por ejemplo, `mi-tema/config`) para que el usuario pueda extenderlo.
3. Si su tema exige ajustes en la configuración de VitePress, exporte esa configuración en un sub-ruta del paquete (por ejemplo, `mi-tema/config`) para que el usuario pueda ampliarla.
4. Documente las opciones de configuración del tema (Ambos, via archivo y frontmatter).
5. Proporcione instrucciones claras sobre cómo consumir su tema(vea abajo).
5. Proporcione instrucciones claras sobre cómo consumir su tema(vea abajo).
## Consumiendo un Tema Personalizado {#consuming-a-custom-theme}
Para consumir un tema extereno, importelo e reexportelo a partir del archivo de entrada del tema personalizado:
Para consumir un tema externo, importelo y reexportelo a partir del archivo de entrada del tema:
```js [.vitepress/theme/index.js]
import Theme from 'awesome-vitepress-theme'
@ -195,8 +216,7 @@ export default {
Si el tema exige una configuración especial de VitePress, también necesitará extenderlo en su propia configuración:
```ts
// .vitepress/theme/config.ts
```ts [.vitepress/config.ts]
import baseConfig from 'awesome-vitepress-theme/config'
export default {
@ -207,13 +227,12 @@ export default {
Finalmente, si el tema proporciona tipos para la configuración del tema:
```ts
// .vitepress/theme/config.ts
```ts [.vitepress/config.ts]
import baseConfig from 'awesome-vitepress-theme/config'
import { defineConfigWithTheme } from 'vitepress'
import { defineConfig } from 'vitepress'
import type { ThemeConfig } from 'awesome-vitepress-theme'
description: Carga datos arbitrarios en tiempo de compilación usando cargadores de datos de VitePress e impórtalos desde páginas o componentes.
---
# Carga de Datos en Tiempo de Compilacion {#build-time-data-loading}
# Carga de Datos en Tiempo de Compilación {#build-time-data-loading}
VitePress proporciona un recurso llamado **cargadores de dato** que permite cargar datos arbitrarios e importarlos desde páginas o componentes. La carga de datos es ejecutada **apenas en el tiempo del build** los datos resultantes serán serializados como JSON en el paquete de JavaScript final.
VitePress proporciona un recurso llamado **cargadores de datos** que permite cargar datos arbitrarios e importarlos desde páginas o componentes. La carga de datos es ejecutada **solo en el tiempo del compilación** los datos resultantes serán serializados como JSON en el paquete de JavaScript final.
Los cargadores de datos pueden ser usados para buscar datos remotos o generar metadatos con base en archivos locales. Por ejemplo, puede usar cargadores de datos para procesar todas sus pagínas API locales y generar automáticamente un indice de todas las entradas del API.
Los cargadores de datos pueden ser usados para obtener datos remotos o generar metadatos a partir de archivos locales. Por ejemplo, puede usar cargadores de datos para analizar todas sus páginas de API locales y generar automáticamente un índice de todas las entradas de la API.
## Uso Básico {#basic-usage}
Un archivo de cargados de datos debe terminar con `.data.js` o `.data.ts`. El archivo debe proporcionar una exportación por defecto de un objeto con el método `load()`:
Un archivo de carga de datos debe terminar con `.data.js` o `.data.ts`. El archivo debe proporcionar una exportación predeterminada de un objeto con el método `load()`:
```js [example.data.js]
export default {
@ -22,8 +22,9 @@ export default {
}
```
El módulo del cargador es validado apenas en Node.js, entonces puede importar APIs Node y dependencias npm caso necesario.
Puede importar entonces datos de este archivo en páginas `.md` y componentes `.vue` usando la exportación llamada `data`:
El módulo de carga se evalúa únicamente en Node.js, por lo que puedes importar las API de Node y las dependencias de npm según sea necesario.
Luego puedes importar datos de este archivo en páginas `.md` y componentes `.vue` usando la exportación llamada `data`:
```vue
<scriptsetup>
@ -41,9 +42,9 @@ Salida:
}
```
Notará que el propio cargados de datos no exporta `data`. Es VitePress llamando el método `load()` entre bastidores y exponiendo implicitamente el resultado por medio de la exportación llamada `data`.
Notará que el cargador de datos en sí no exporta el `data`. Es VitePress llamando el método `load()` internamente y expone implícitamente el resultado a través de la exportación llamada `data`.
Esto funciona incluso si el cargador fuera asíncrono:
Esto funciona incluso si el cargador es asíncrono:
```js
export default {
@ -56,11 +57,11 @@ export default {
## Datos de Archivos Locales {#data-from-local-files}
Cuando necesita generar datos con base en archivos locales, debe usar la opción `watch` en el cargador de datos para que los cambios hechos en esos archivos puedan accionar actualizaciones rápidas.
Cuando necesita generar datos con base en archivos locales, debe usar la opción `watch` en el cargador de datos para que los cambios hechos en esos archivos puedan accionar actualizaciones en caliente.
La opción `watch` tabién es conveniente porque puede usar [patrones glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) para corresponder a vários archivos. Los patrones pueden ser relativos al propio archivo del cargador, y la función `load()` recibirá los archivos correspondientes como paths absolutos.
La opción `watch` también es conveniente porque puede usar [patrones glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) para corresponder a varios archivos. Los patrones pueden ser relativos al propio archivo del cargador, y la función `load()` recibirá los archivos correspondientes como rutas absolutas.
El siguiente ejemplo muestra el cargamento de archivos CSV y la transformación de estos en JSON usando [csv-parse](https://github.com/adaltas/node-csv/tree/master/packages/csv-parse/). Como este archivo solo es ejecutado en el tiempo del build, usted no enviará el procesador de CSV para el cliente!
El siguiente ejemplo muestra el cargamento de archivos CSV y la transformación de estos en JSON usando [csv-parse](https://github.com/adaltas/node-csv/tree/master/packages/csv-parse/). Como este archivo solo es ejecutado en el tiempo del compilación, usted no enviará el procesador de CSV para el cliente!
```js
import fs from 'node:fs'
@ -69,9 +70,9 @@ import { parse } from 'csv-parse/sync'
export default {
watch: ['./data/*.csv'],
load(watchedFiles) {
// watchedFiles será un array de paths absolutos de los archivos um array de caminhos absolutos dos arquivos correspondientes.
// generar un array de metadatos de post que puede ser usado para mostrar
// una lista en el layout del tema
// watchedFiles será un array con las rutas absolutas de los archivos coincidentes.
// Genera un array con los metadatos de las entradas del blog que se pueden usar para renderizar
// una lista en el diseño del tema.
return watchedFiles.map((file) => {
return parse(fs.readFileSync(file, 'utf-8'), {
columns: true,
@ -84,7 +85,7 @@ export default {
## `createContentLoader`
Al construir un sitio enfocado en contenido, frecuentemente necesitamos crear una página de "archivo" o "índice": una página donde listamos todas las entradas disponibles en nuestra colección de contenido, por ejemplo, articulos de blog o páginas de API. Nosotros **podemos** implementar esto directamente con el API de cargador de datos, pero como este es un caso de uso tan común, VitePress también proporciona un auxiliar `createContentLoader` para simplificar esto:
Al construir un sitio enfocado en contenido, frecuentemente necesitamos crear una página de "archivo" o "índice": una página donde listamos todas las entradas disponibles en nuestra colección de contenido, por ejemplo, artículos de blog o páginas de API. Nosotros **podemos** implementar esto directamente con el API de cargador de datos, pero como este es un caso de uso tan común, VitePress también proporciona un auxiliar `createContentLoader` para simplificar esto:
```js [posts.data.js]
import { createContentLoader } from 'vitepress'
@ -92,16 +93,16 @@ import { createContentLoader } from 'vitepress'
El auxiliar acepta un patrón glob relativo al [diretório fuente](./routing#source-directory) y retorna un objeto de cargador de datos `{ watch, load }` que puede ser usado como exportación por defecto en un archivo de cargador de datos. El también implementa cache con base en los sellos se datos del archivo para mejorar el desempeño en el desarrollo.
El auxiliar acepta un patrón glob relativo al [directorio fuente](./routing#source-directory) y retorna un objeto de cargador de datos `{ watch, load }` que puede ser usado como exportación por defecto en un archivo de cargador de datos. El también implementa cache con base en las marca de tiempo se datos del archivo para mejorar el desempeño en el desarrollo.
Note que el cargador solo funciona con archivos Markdown - archivos no Markdown encontrados serán ignorados.
Los datos cargados serán un _array_ con el tipo `ContentData[]`:
Los datos cargados serán un array con el tipo `ContentData[]`:
```ts
interface ContentData {
// URL mapeada para la página. Ex: /posts/hello.html (no incluye la base)
// itere manualmente o use `transform` personalizado para normalizar los paths
// URL mapeada para la página. p. ej.: /posts/hola.html (no incluye la base)
// itere manualmente o use `transform` personalizado para normalizar las rutas
url: string
// datos frontmatter de la página
frontmatter: Record<string,any>
@ -114,8 +115,7 @@ interface ContentData {
}
```
Por defecto, apenas `url` y `frontmatter` son proporcionados. Esto ocurre porque los datos cargados serán incorporados como JSON en el paquete del cliente, entonces necesitamos ser cautelosos con su tamaño. Aqui está un ejemplo de cómo usar los datos para construir una página de índice de blog mínima:
Por defecto, solo se proporcionan `url` y `frontmatter`. Esto se debe a que los datos cargados se insertarán como JSON en el paquete del cliente, por lo que debemos tener cuidado con su tamaño. Aquí hay un ejemplo que utiliza los datos para crear una página de índice de blog mínima:
```vue
<scriptsetup>
import { data as posts } from './posts.data.js'
@ -140,9 +140,9 @@ Los datos por defecto pueden no atender todas las necesidades - puede optar por
description: Despliega tu sitio VitePress en plataformas populares como Netlify, Vercel, GitHub Pages y más.
outline: deep
description: Despliega tu sitio VitePress en plataformas populares como Netlify, Vercel, GitHub Pages y más.
---
# Despliegue su Sitio VitePress {#deploy-your-vitepress-site}
@ -8,7 +8,7 @@ outline: deep
Las siguientes orientaciones están basadas en algunos supuestos:
- El sitio VitePress está dentro del directorio `docs` de su proyecto.
- Está usando la directorio por defecto para el build (`.vitepress/dist`).
- Está usando el directorio por defecto para la compilación (`.vitepress/dist`).
- VitePress está instalado como una dependencia local en su proyecto, y usted configuró los siguientes scripts en su `package.json`:
```json [package.json]
@ -46,27 +46,27 @@ Las siguientes orientaciones están basadas en algunos supuestos:
}
```
Ahora el método `docs:preview` implantará el servidor en `http://localhost:8080`.
Ahora, el método `docs:preview` iniciará el servidor en `http://localhost:8080`.
## Configurando un Path Base Publico {#setting-a-public-base-path}
## Configurando una Ruta Base Pública {#setting-a-public-base-path}
Por defecto, asumimos que el sitio será implantado en el path raiz de un dominio (`/`). Si su sitio fuera servido en un subpath, por ejemplo, `https://meusite.com/blog/`, necesitará entonces configurar la opción [`base`](../reference/site-config#base) para `'/blog/'` en la configuración VitePress.
Por defecto, asumimos que el sitio será implantado en la ruta raíz de un dominio (`/`). Si su sitio fuera servido en una sub-ruta, por ejemplo, `https://mipagina.com/blog/`, necesitará entonces configurar la opción [`base`](../reference/site-config#base) para `'/blog/'` en la configuración VitePress.
**Ejemplo:** Al usar GitHub Pages (ou GitLab Pages) e implantar en `user.github.io/repo/`, defina su `base` como`/repo/`.
**Ejemplo:** Si utilizas GitHub (o GitLab) Pages y realizas el despliegue en `user.github.io/repo/`, entonces establece tu `base` en`/repo/`.
## Headers de Cache HTTP {#http-cache-headers}
Si tiene control sobre los headers HTTP de su servidor en producción, se puede configurar headers `cache-control` para obtener mejor desempeño en vistar repetidas.
Si tiene control sobre los headers HTTP de su servidor en producción, se puede configurar headers `cache-control` para obtener mejor desempeño al visitar repetidas.
La compilación de producción usa nombres de archivos con hash para assets estáticos (JavaScript, CSS e otros assets que no están en `public`). Se inspecciona la previa de producción usando las herramientas de desarrollador de su navegador en la pestaña red, verá archivos como `app.4f283b18.js`.
Este hash `4f283b18`es generado a partir del contenido de este archivo. La misma URL con hash es garantizada para servir el mismo contenido del archivo - se el contenido cambia, las URLs también cambian. Esto significa que puede utilizar con seguridad los headers de cahe más fuertespara esos archivos. Todos esos archivos serán colocados en `assets/` en la directorio de salida, entonces puede configurar el siguiente header para ellos:
Este hash `4f283b18`se genera a partir del contenido de este archivo. Se garantiza que la misma URL con hash servirá el mismo contenido del archivo; si el contenido cambia, las URL también cambian. Esto significa que puede usar con seguridad los encabezados de caché más seguros para estos archivos. Todos estos archivos se colocarán en `assets/` en el directorio de salida, por lo que puede configurar el siguiente encabezado para ellos:
```
Cache-Control: max-age=31536000,immutable
```
::: details Ejemplo de archivo `_headers`do Netlify
Nota: el archivo `_headers` debe ser colocado en [diretório public](./asset-handling#the-public-directory) - en nuestro caso, `docs/public/_headers` - para que el sea copiado exactamente para la directorio de salida.
Nota: el archivo `_headers` debe colocarse en el [directorio público](./asset-handling#the-public-directory) - en nuestro caso, `docs/public/_headers` - para que se copie tal cual al directorio de salida.
[Documentación de headers personalizados de Netlify](https://docs.netlify.com/routing/headers/)
:::
::: details de Ejemplo de configuración Vercel em`vercel.json`
::: details de Ejemplo de configuración Vercel en`vercel.json`
```json
{
@ -98,13 +98,13 @@ Nota: el archivo `_headers` debe ser colocado en [diretório public](./asset-han
}
```
Nota: el archivo `vercel.json` debe ser colocado en la raiz de su **repositório**.
Nota: el archivo `vercel.json` debe ser colocado en la raíz de su **repositorio**.
[Documentación Vercel sobre configuración de headers](https://vercel.com/docs/concepts/projects/project-configuration#headers)
[Documentación Vercel sobre configuración de headers](https://vercel.com/docs/concepts/projects/project-configuration#headers)
@ -115,25 +115,25 @@ Configure un nuevo proyecto y altere estas configuraciones usando su panel:
- **Versión de Node:**`20` (o superior)
::: warning
No active opciones como _Auto Minify_ para código HTML. Eso removera comentarios de salida que tiene significado para Vue. Habrán errores de incompatibilidad de hidratación se fueran removidos.
No active opciones como _Auto Minify_ para código HTML. Eso removerá comentarios de salida que tiene significado para Vue. Habrán errores de incompatibilidad de hidratación si fueran removidos.
:::
### GitHub Pages
1. Cree un archivo llamado `deploy.yml` dentro del directorio `.github/workflows` do seu projeto com algum conteúdo como este:
1. Crea un archivo llamado `deploy.yml` dentro del directorio `.github/workflows` de tu proyecto con un contenido como este:
```yaml [.github/workflows/deploy.yml]
# Ejemplo de flujo de trabajo para compilar e implantar un sitio VitePress en GitHub Pages
#
name: Implante el sitio VitePress en Pages
name: Despliegue el sitio VitePress en Pages
on:
# Ejecute en push direccionados a la branch `main`.
# Cambie para `master` si estuviera usando la branch `master` por defecto.
# Se ejecuta en los pushes dirigidos a la rama `main`. Cámbialo a `master`
# si estás usando la rama `master` como rama predeterminada.
push:
branches: [main]
# Permite ejecutar manualmente este flujo de trabajo en la guia Actions
# Permite ejecutar este flujo de trabajo manualmente desde la pestaña Acciones
workflow_dispatch:
# Define permisos GITHUB_TOKEN para la implementación en GitHub Pages
@ -142,8 +142,9 @@ No active opciones como _Auto Minify_ para código HTML. Eso removera comentario
pages: write
id-token: write
# Permite apenas una implantación simultánea, omitiendo ejecuciones en fila entre la ejecución en progreso y la última de la fila.
# Sin embargo, NO cancela ejecuciones en progreso, pues queremos permitir que esas implantaciones de producción sean concuidas.
# Permitir solo una implementación simultánea, omitiendo las ejecuciones en cola entre la ejecución en curso y la última en cola.
# Sin embargo, NO cancelar las ejecuciones en curso, ya que queremos permitir que estas implementaciones de producción se completen.
concurrency:
group: pages
cancel-in-progress: false
@ -156,28 +157,35 @@ No active opciones como _Auto Minify_ para código HTML. Eso removera comentario
- name: Checkout
uses: actions/checkout@v5
with:
fetch-depth: 0 # No necesario se lastUpdated no estuviera habilitado
fetch-depth: 0 # No necesario si lastUpdated no estuviera habilitado
run: npm ci # o pnpm install / yarn install / bun install
- name: Build with VitePress
run: npm run docs:build # o pnpm docs:build / yarn docs:build / bun run docs:build
- name: Build with VitePress
run: npm run docs:build # o pnpm docs:build / yarn docs:build / bun run docs:build
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: docs/.vitepress/dist
# Trabajo de implantación
# Trabajo de despliegue
deploy:
environment:
name: github-pages
@ -192,18 +200,18 @@ No active opciones como _Auto Minify_ para código HTML. Eso removera comentario
```
::: warning
Asegurese de que la opción `base` en su VitePress esté configurada correctamentse. Vea [Configuranco un Path base Público](#setting-a-public-base-path) para más detalles.
Asegúrese de que la opción `base` en su VitePress esté configurada correctamente. Vea [Configurando una Ruta Base Pública](#setting-a-public-base-path) para más detalles.
:::
2. En las configuraciones de su repositorio sobre el item del menú "Pages", seleccione "GitHub Actions" en "Build and deployment > Source".
3. Envie sus modificaciones para el branch `main` y espere la conclusión del flujo de trabajo de GitHub Actions. Verá su sitio implantado en `https://<username>.github.io/[repository]/` o `https://<custom-domain>/` dependiendo de sus configuraciones. Su sitio será implantado automáticamente en cada push para la branch `main`.
3. Envie sus modificaciones para el branch `main` y espere la conclusión del flujo de trabajo de GitHub Actions. Verá su sitio implantado en `https://<usuario>.github.io/[repositorio]/` o `https://<dominio-personalizado>/` dependiendo de sus configuraciones. Su sitio será implantado automáticamente en cada push para la branch `main`.
### GitLab Pages
1. Defina `outDir` en la configuración VitePress como `../public`. Configure la opción `base` para `'/<repository>/'` se desea implantar en `https://<username>.gitlab.io/<repository>/`. No necesita `base` si está implementando en un dominio personalizado, páginas de usuario o grupo, o si la configuración "Use unique domain" está habilitada en GitLab.
1. Establezca `outDir` en la configuración de VitePress a `../public`. Configure la opción `base` a `'/<repositorio>/'` si desea implementar en `https://<usuario>.gitlab.io/<repositorio>/`. No necesita `base` si está implementando en un dominio personalizado, páginas de usuario o grupo, o si tiene habilitada la opción "Usar dominio único" en GitLab.
2. Cree un archivo llamado `.gitlab-ci.yml` en la raiz del proyecto con el contenido abajo. Esto construirá e implantará su sitio siempre que haga alteraciones en el contenido.
2. Cree un archivo llamado `.gitlab-ci.yml` en la raíz del proyecto con el contenido abajo. Esto construirá e implantará su sitio siempre que haga cambios en el contenido.
```yaml [.gitlab-ci.yml]
image: node:24
@ -212,7 +220,7 @@ No active opciones como _Auto Minify_ para código HTML. Eso removera comentario
paths:
- node_modules/
script:
# - apk add git # Desconecte eso se estuviera usando imagenes pequeñas de Docker como Alpine y tuviera lastUpdated habilitado
# - apk add git # Descomente esto si está utilizando imágenes de Docker pequeñas como alpine y tiene la última actualización habilitada.
- npm install
- npm run docs:build
artifacts:
@ -222,9 +230,11 @@ No active opciones como _Auto Minify_ para código HTML. Eso removera comentario
- main
```
<!-- Mantener los encabezados ordenados alfabéticamente, dejar nginx al final -->
### Azure
1. Siga la [documentación oficial](https://docs.microsoft.com/en-us/azure/static-web-apps/build-configuration).
1. Siga la [documentación oficial](https://learn.microsoft.com/es-es/azure/static-web-apps/build-configuration).
2. Configure esos valores en su archivo de configuración (y remueva aquellos que no necesita, como `api_location`):
@ -238,7 +248,7 @@ Puedes desplegar tu proyecto VitePress con [CloudRay](https://cloudray.io/) sigu
### Firebase
1. Cree `firebase.json` y `.firebaserc` en la raiz de su proyecto:
1. Cree `firebase.json` y `.firebaserc` en la raíz de su proyecto:
`firebase.json`:
@ -261,7 +271,7 @@ Puedes desplegar tu proyecto VitePress con [CloudRay](https://cloudray.io/) sigu
}
```
2. Después de ejecutar `npm run docs:build`, ejecute este comando para implantar:
2. Después de ejecutar `npm run docs:build`, ejecute este comando para desplegar:
```sh
firebase deploy
@ -269,9 +279,9 @@ Puedes desplegar tu proyecto VitePress con [CloudRay](https://cloudray.io/) sigu
### Heroku
1. Siga la documentación y el guia proporcionados por [`heroku-buildpack-static`](https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-static).
1. Siga la documentación y el guía proporcionados por [`heroku-buildpack-static`](https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-static).
2. Cree un archivo llamado `static.json` en la raiz de su proyecto con el contenido abajo:
2. Cree un archivo llamado `static.json` en la raíz de su proyecto con el siguiente contenido:
```json [static.json]
{
@ -283,10 +293,6 @@ Puedes desplegar tu proyecto VitePress con [CloudRay](https://cloudray.io/) sigu
Puedes desplegar tu proyecto VitePress con [Hostinger](https://www.hostinger.com/web-apps-hosting) siguiendo estas [instrucciones](https://www.hostinger.com/support/how-to-deploy-a-nodejs-website-in-hostinger/). Al configurar los ajustes de compilación, elige VitePress como framework y ajusta el directorio raíz a `./docs`.
### Kinsta
Puede implantar su sitio VitePress em [Kinsta](https://kinsta.com/static-site-hosting/) siguiendo estas [instrucciones](https://kinsta.com/docs/vitepress-static-site-example/).
### Stormkit
Puedes desplegar tu proyecto VitePress en [Stormkit](https://www.stormkit.io) siguiendo estas [instrucciones](https://stormkit.io/blog/how-to-deploy-vitepress).
@ -299,46 +305,57 @@ Puedes desplegar tu proyecto VitePress en [Stormkit](https://www.stormkit.io) si
npx surge docs/.vitepress/dist
```
### Nginx
### nginx
Aquí hay un ejemplo de configuración de bloque de servidor Nginx. Esta configuración incluye compresión gzip para recursos comunes basados en texto, reglas para servir los archivos estáticos de su sitio VitePress con encabezados de caché adecuados, así como el manejo de `cleanUrls: true`.
Aquí hay un ejemplo de configuración de bloque de servidor nginx. Esta configuración incluye compresión gzip para recursos comunes basados en texto, reglas para servir los archivos estáticos de su sitio VitePress con encabezados de caché adecuados, así como el manejo de `cleanUrls: true`.
# a folder without index.html raises 403 in this setup
error_page 403 /404.html;
location / {
try_files $uri $uri.html $uri/index.html =404;
}
# adjust caching headers
# files in the assets folder have hashes filenames
location ~* ^/assets/ {
expires 1y;
add_header Cache-Control "public, immutable";
location ~ ^(?<page>.+)/$ {
if (-f $document_root$page.html) {
return 301 $page$is_args$args;
}
try_files $page/index.html =404;
}
}
```
Esta configuración asume que su sitio VitePress compilado está ubicado en el directorio `/app` de su servidor. Ajuste la directiva `root` según corresponda si los archivos de su sitio se encuentran en otro lugar.
::: warning No predeterminar index.html
La resolución de try_files no debe predeterminar index.html como en otras aplicaciones Vue. Esto resultará en un estado de página inválido.
:::
Se puede encontrar más información en la [documentación oficial de nginx](https://nginx.org/en/docs/), en estos issues [#2837](https://github.com/vuejs/vitepress/discussions/2837), [#3235](https://github.com/vuejs/vitepress/issues/3235) así como en este [post del blog](https://blog.mehdi.cc/articles/vitepress-cleanurls-on-nginx-environment#readings) de Mehdi Merah.
description: Personaliza y extiende el tema predeterminado de VitePress con CSS personalizado, componentes, layouts y slots.
outline: deep
description: Personaliza y extiende el tema predeterminado de VitePress con CSS personalizado, componentes, layouts y slots.
---
# Extendiendo el Tema por defecto {#extending-the-default-theme}
# Extendiendo el Tema por Defecto {#extending-the-default-theme}
El tema por defecto de VitePress es optimizado para documentación y puede ser personalizado. Consulte la [Visión General de Configuración del Tema por Defecto](../reference/default-theme-config) para una lista completa de opciones.
@ -16,12 +16,12 @@ Sin embargo, hay casos en que apenas la configuración no será suficiente. Por
Esas personalizaciones avanzadas exigirán el uso de un tema personalizado que "extiende" el tema por defecto.
::: tip
Antes de seguir, asegurese de leer primero [Usando un Tema Personalizado](./custom-theme) para entender como funcionan los temas personalizados.
Antes de seguir, asegúrese de leer primero [Usando un Tema Personalizado](./custom-theme) para entender como funcionan los temas personalizados.
:::
## Personalizando el CSS {#customizing-css}
El CSS del tema por defecto puede ser personalizado substuyendo las variables CSS a nivel de la raiz:
El CSS del tema por defecto puede ser personalizado substituyendo las variables CSS a nivel de la raíz:
```js [.vitepress/theme/index.js]
import DefaultTheme from 'vitepress/theme'
@ -38,11 +38,11 @@ export default DefaultTheme
}
```
Vea las [variables CSS del tema por defecto](https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css) que pueden ser substituídas.
Vea las [variables CSS del tema por defecto](https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css) que pueden ser substituidas.
## Usando Fuentes Diferentes {#using-different-fonts}
VitePress usa [Inter](https://rsms.me/inter/) como fuente por defecto e incluirá las fuentes en la salida de compilación. La fuente también es pre-cargada automaticamente en producción. Sin embargo, eso puede no ser deseable se quiere usar una fuente principal diferente.
VitePress usa [Inter](https://rsms.me/inter/) como fuente por defecto e incluirá las fuentes en la salida de compilación. La fuente también es pre-cargada automáticamente en producción. Sin embargo, eso puede no ser deseable se quiere usar una fuente principal diferente.
Para evitar la inclusión de Inter en la salida de compilación, importe el tema de `vitepress/theme-without-fonts`:
@ -62,7 +62,7 @@ export default DefaultTheme
```
::: warning
Si está usando componentes opcionales como los componentes de la [Página del equipo](../reference/default-theme-team-page), asegurese de también importarlos de `vitepress/theme-without-fonts`!
Si está usando componentes opcionales como los componentes de la [Página del equipo](../reference/default-theme-team-page), asegúrese de también importarlos de `vitepress/theme-without-fonts`!
:::
Si su fuente es un archivo local referenciado via `@font-face`, ella será procesada como un asset e incluida en `.vitepress/dist/assets` con un nombre de archivo hash. Para pre-cargar ese archivo, use el hook de construcción [transformHead](../reference/site-config#transformhead):
@ -119,11 +119,11 @@ export default {
} satisfies Theme
```
Como estamos usando Vite, puede también aprovechar la [funcionalidad de importación glob](https://vite.dev/guide/features.html#glob-import) de Vite para registrar automaticamente un directorio de componetes.
Como estamos usando Vite, puede también aprovechar la [funcionalidad de importación glob](https://vite.dev/guide/features.html#glob-import) de Vite para registrar automáticamente un directorio de componentes.
## _Slots_ en el Layout {#layout-slots}
El componente `<Layout/>` del tema por defecto posee algunos _slots_ que pueden ser usados para inyectar contenido en lugares específicos de la página. Aqui un ejemplo de como inyectar un componente antes del esquema:
El componente `<Layout/>` del tema por defecto posee algunos _slots_ que pueden ser usados para inyectar contenido en lugares específicos de la página. Aquí un ejemplo de como inyectar un componente antes del esquema:
```js [.vitepress/theme/index.js]
import DefaultTheme from 'vitepress/theme'
@ -212,7 +212,7 @@ Lista completa de _slots_ disponibles en el layout del tema por defecto:
- `nav-screen-content-before`
- `nav-screen-content-after`
## Usando el API View Transitions
## Usando el API View Transitions {#using-view-transitions-api}
### En la Alternancia de Apariencia {#on-appearance-toggle}
Puede usar los [aliases](https://vite.dev/config/shared-options.html#resolve-alias) Vite para substituir los componentes del tema por defecto por los suyos personalizados:
Puede usar los [aliases](https://vite.dev/config/shared-options.html#resolve-alias) de Vite para substituir los componentes del tema por defecto por los suyos personalizados:
```ts
import { fileURLToPath, URL } from 'node:url'
@ -322,7 +322,7 @@ export default defineConfig({
{
find: /^.*\/VPNavBar\.vue$/,
replacement: fileURLToPath(
new URL('./components/CustomNavBar.vue', import.meta.url)
new URL('./theme/components/CustomNavBar.vue', import.meta.url)
@ -6,7 +6,7 @@ description: Aprende cómo usar frontmatter YAML en archivos Markdown de VitePre
## Uso {#usage}
VitePress soporta frontmatter YAML en todos los archivos Markdown, procesandolos con [gray-matter](https://github.com/jonschlinkert/gray-matter). El frontmatter debe estar en la parte superior del archivo Markdown (antes de cualquier elemento, incluyendo tags `<script>`), y debe tener la forma de un YAML válido entre lineas con trazos de triple guion. Ejemplo:
VitePress soporta frontmatter YAML en todos los archivos Markdown, procesándolos con [gray-matter](https://github.com/jonschlinkert/gray-matter). El frontmatter debe estar en la parte superior del archivo Markdown (antes de cualquier elemento, incluyendo tags `<script>`), y debe tener la forma de un YAML válido entre líneas con trazos de triple guion. Ejemplo:
```md
---
@ -23,7 +23,7 @@ Puede también definir datos propios del frontmatter personalizados, para ser us
Los datos del frontmatter pueden ser accedidos por medio de la variable global especial `$frontmatter`:
Aqui está un ejemplo de como podría usarlo en su archivo Markdown:
Aquí está un ejemplo de como podría usarlo en su archivo Markdown:
```md
---
@ -33,7 +33,7 @@ editLink: true
# {{ $frontmatter.title }}
Contenido de guia
Contenido de la guía
```
Puede acceder los datos del frontmatter de la página actual en `<script setup>` con el auxiliar [`useData()`](../reference/runtime-api#usedata).
@ -45,7 +45,7 @@ VitePress también soporta la sintaxis frontmatter JSON, comenzando y terminando
description: Comienza a trabajar con VitePress. Aprende cómo instalar, crear la estructura y comenzar a desarrollar tu sitio de documentación.
---
# Iniciando {#getting-started}
# Comenzar {#getting-started}
## Experimente Online {#try-it-online}
@ -13,7 +13,7 @@ Puede experimentar VitePress directamente en su navegador en [StackBlitz](https:
### Prerrequisitos {#prerequisites}
- [Node.js](https://nodejs.org/) versión 22 o superior.
- Terminal para acessar VitePress a través de su interfaz de linea de comando (CLI).
- Terminal para acceder VitePress a través de su interfaz de línea de comando (CLI).
- Editor de texto con soporte a sintaxis [Markdown](https://en.wikipedia.org/wiki/Markdown).
- [VSCode](https://code.visualstudio.com/) es recomendado, junto con la [extensión oficial Vue](https://marketplace.visualstudio.com/items?itemName=Vue.volar).
@ -30,24 +30,28 @@ $ pnpm add -D vitepress@next
```
```sh [yarn]
$ yarn add -D vitepress@next
$ yarn add -D vitepress@next vue
```
```sh [bun]
$ bun add -D vitepress@next
```
```sh [deno]
$ deno add -D vitepress@next
```
:::
::: tip NOTA
VitePress es un paquete apenas para ESM. No use `require()` para importarlo, y asegurese de que el `package.json` más cercano contiene `"type": "module"`, o cambie la extensión de archivo de sus archivos relevantes como `.vitepress/config.js` a `.mjs`/`.mts`. Consulte la [Guía de resolución de problemas Vite](http://vite.dev/guide/troubleshooting.html#this-package-is-esm-only) para más detalles. Además de eso, dentro de contextos de JavaScript asíncronos, puede usar `await import('vitepress')`.
VitePress es un paquete apenas para ESM. No use `require()` para importarlo, y asegúrese de que el `package.json` más cercano contiene `"type": "module"`, o cambie la extensión de archivo de sus archivos relevantes como `.vitepress/config.js` a `.mjs`/`.mts`. Consulte la [Guía de resolución de problemas Vite](http://vite.dev/guide/troubleshooting.html#this-package-is-esm-only) para más detalles. Además de eso, dentro de contextos de CJS asíncronos, puede usar `await import('vitepress')`.
:::
### Asistente de Instalación {#setup-wizard}
VitePress tiene embutido un asistente de instalación por linea de comando que ayudará a construir un proyecto básico. Después de la instalación, inicie el asistente ejecutando:
VitePress incluye un asistente de instalación por línea de comandos que le ayudará a crear un proyecto básico. Después de la instalación, inicie el asistente ejecutando:
::: code-group
@ -74,12 +78,12 @@ Será saludado con algunas preguntas simples:
<<<@/snippets/init.ansi
::: tip Vue como Dependencia Correspondiente
Si tiene la intención de realizar una personalización que usa componentes Vue o APIs, debe instalar explicitamente `vue` como una dependencia correspondiente.
Si tiene la intención de realizar una personalización que usa componentes Vue o APIs, debe instalar explícitamente `vue` como una dependencia correspondiente.
:::
## Estrutura de Archivos {#file-structure}
## Estructura de Archivos {#file-structure}
Se está construyendo un sitio VitePress individual, puede desarrollar su sitio en el directorio actual (`./`). Sin embargo, si está instalando VitePress en un proyecto existente junto con otro código fuente, es recomendado construir el sitio en un directorio anidado (e.g. `./docs`) para que esté separado del resto de su proyecto.
Si está construyendo un sitio web independiente con VitePress, puede generar la estructura básica del sitio en su directorio actual (`./`). Sin embargo, si está instalando VitePress en un proyecto existente junto con otro código fuente, se recomienda construir el sitio en un directorio anidado (por ejemplo, `./docs`) para que esté separado del resto del proyecto.
Asumiendo la opción de desarrollar el proyecto VitePress en `./docs`, la estructura de archivos generada debe parecerse a la siguiente:
@ -94,21 +98,21 @@ Asumiendo la opción de desarrollar el proyecto VitePress en `./docs`, la estruc
└─ package.json
```
El directorio `docs` es considerado la **raiz del proyecto** de su sitio VitePress. El directorio `.vitepress` es un lugar reservado para archivos de configuración VitePress, caché del servidor de desarrollo, resultado del build, y código de personalización de tema opcional.
El directorio `docs` es considerado la **raíz del proyecto** de su sitio VitePress. El directorio `.vitepress` es un lugar reservado para archivos de configuración VitePress, caché del servidor de desarrollo, resultado del compilación, y código de personalización de tema opcional.
::: tip
Por defecto, VitePress almacena el caché del servidor de desarrollo en `.vitepress/cache`, y el resultado del build de producción en `.vitepress/dist`. Se usa Git, debe adicionarlos a su archivo `.gitignore`. Estas ubicaciones también pueden ser [configuradas](../reference/site-config#outdir).
Por defecto, VitePress almacena el caché del servidor de desarrollo en `.vitepress/cache`, y el resultado del compilación de producción en `.vitepress/dist`. Se usa Git, debe adicionarlos a su archivo `.gitignore`. Estas ubicaciones también pueden ser [configuradas](../reference/site-config#outdir).
:::
### El archivo de configuración {#the-config-file}
El archivo de configuración (`.vitepress/config.js`) permite que personalice vários aspectos de su sitio VitePress, con las opciones más básicas siendo el titulo y la descripción del sitio:
El archivo de configuración (`.vitepress/config.js`) permite que personalice varios aspectos de su sitio VitePress, con las opciones más básicas siendo el título y la descripción del sitio:
```js [.vitepress/config.js]
export default {
// opciones a nivel del sitio
title: 'VitePress',
description: 'Solo una broma.',
description: 'Solo un juego.',
themeConfig: {
// opciones a nivel del tema
@ -116,15 +120,15 @@ export default {
}
```
Puede también configurar el comportamiento del tema a través de la opción `themeConfig`. Consulte la [Referencia de Configuración](../reference/site-config) para detaller completos sobre todas las opciones de configuración.
También puedes configurar el comportamiento del tema mediante la opción `themeConfig`. Consulta la [Referencia de Configuración](../reference/site-config) para obtener información detallada sobre todas las opciones de configuración.
### Archivos fuente {#source-files}
Archivos Markdown fuera del directorio `.vitepress` son considerados **archivos fuente**.
VitePress usa **enrutamiento basado en archivos**: cada archivo `.md` es compilado en un archivo `.html` correspondiente con el mismo path. Por ejemplo, `index.md` será compilado en `index.html`, y puede ser visitado en el path raiz `/` del sitio VitePress resultante.
VitePress usa **enrutamiento basado en archivos**: cada archivo `.md` es compilado en un archivo `.html` correspondiente con la misma ruta. Por ejemplo, `index.md` se compilará en `index.html` y se podrá acceder a él desde la ruta raíz `/` del sitio VitePress resultante.
VitePress también proporciona la habilidad de generar URLs limpias, retambém fornece a habilidade de gerar URLs limpas, reescribir paths, y generare páginas dinámicamente. Estos serán tratados en la [Guía de Enrutamiento](./routing).
VitePress también proporciona la habilidad de generar URLs limpias, reescribir rutas y generar páginas dinámicamente. Estos temas se tratarán en la [Guía de enrutamiento](./routing).
## Instalado y Funcionando {#up-and-running}
@ -142,7 +146,7 @@ La herramienta debe tener también inyectado los siguientes scripts npm en su `p
}
```
El script `docs:dev` iniciará un servidor de desarrollo local con actualizaciones instantáneas. Ejecutelo con el siguiente comando:
El script `docs:dev` iniciará un servidor de desarrollo local con actualizaciones instantáneas. Ejecútelo con el siguiente comando:
::: code-group
@ -186,9 +190,9 @@ $ bun vitepress dev docs
:::
Más usos de la linea de comandos están documaentados en la [Referencia CLI](../reference/cli).
Más usos de la línea de comandos están documentados en la [Referencia CLI](../reference/cli).
El servidor de desarrollo debe estar corriendo en `http://localhost:5173`. Visite la URL en su navegador para ver su nuevo sitio en acción!
El servidor de desarrollo debería estar corriendo en `http://localhost:5173`. ¡Visita la URL en tu navegador para ver tu nuevo sitio en acción!
## Qué viene después? {#what-s-next}
@ -200,4 +204,4 @@ El servidor de desarrollo debe estar corriendo en `http://localhost:5173`. Visit
- Se quiere profundizar la personalización de la apariencia de su sitio, explore tanto [Extienda el Tema por Defecto](./extending-default-theme) como [Construya un Tema Personalizado](./custom-theme).
- Una vez que su documentación tome forma, asegurese de leer la [Guia de Despliegue](./deploy).
- Una vez que su documentación tome forma, asegúrese de leer la [Guía de Despliegue](./deploy).
head?: HeadConfig[] // será mezclado con las entradas head existentes, las metatags duplicadas son removidas automáticamente
themeConfig?: ThemeConfig // será mezclado superficialmente, cosas comunes pueden ser colocadas en la entrada superios de themeConfig
head?: HeadConfig[] // se fusionará con las entradas de encabezado existentes, las etiquetas meta duplicadas se eliminan automáticamente
themeConfig?: ThemeConfig // Se fusionará superficialmente, los elementos comunes se pueden colocar en la entrada themeConfig de nivel superior.
}
```
Consulte la interfaz [`DefaultTheme.Config`](https://github.com/vuejs/vitepress/blob/main/types/default-theme.d.ts) para obtener detaller sobre la personalización de los textos marcadores del tema por defecto. No substituya `themeConfig.algolia` o `themeConfig.carbonAds` en el nivel de idioma. Consulte la [documentação Algolia](../reference/default-theme-search#i18n) para usar la busqueda multilenguaje.
Consulte la interfaz [`DefaultTheme.Config`](https://github.com/vuejs/vitepress/blob/main/types/default-theme.d.ts) para obtener detalles sobre cómo personalizar los textos de marcador de posición del tema predeterminado. No sobrescriba `themeConfig.algolia` ni `themeConfig.carbonAds` a nivel de configuración regional. Consulte la [documentación de Algolia](../reference/default-theme-search#i18n) para obtener información sobre cómo usar la búsqueda multilingüe.
**Consejo profesional:** El archivo de configuración puede ser almacenado en `docs/.vitepress/config/index.ts` también. Esto puede ayudar a organizar las cosas creando un archivo de configuración por idioma y entonces mezclarlos y exportarlos a partir de `index.ts`.
**Consejo profesional:** El archivo de configuración puede ser almacenado en `docs/.vitepress/config/index.ts` también. Esto puede ayudar a organizar las cosas creando un archivo de configuración por idioma y entonces fusionarlos y exportarlos a partir de `index.ts`.
## Cadenas de Markdown por configuración regional {#per-locale-markdown-strings}
Las cadenas integradas en las páginas por el renderizador de Markdown (los títulos predeterminados de los [contenedores personalizados](./markdown#custom-containers) y las [alertas al estilo de GitHub](./markdown#github-flavored-alerts), y las cadenas del botón de copiar código) se pueden sobrescribir por configuración regional con la clave `markdown` de una entrada de configuración regional:
```ts [docs/.vitepress/config.ts]
import { defineConfig } from 'vitepress'
export default defineConfig({
locales: {
root: { label: 'English', lang: 'en' },
zh: {
label: '简体中文',
lang: 'zh-Hans',
markdown: {
container: {
tipLabel: '提示',
warningLabel: '警告'
// ...las otras etiquetas y títulos de customContainers
},
codeCopyButton: {
tooltipText: '复制代码',
copiedText: '已复制'
}
}
}
}
})
```
Los valores recurren a las opciones `markdown` del nivel raíz cuando una configuración regional no los establece. Las entradas de configuración regional solo pueden sobrescribir los títulos de los contenedores registrados en el nivel raíz; no se admite el registro de nuevos contenedores por configuración regional. Tenga en cuenta también que, dado que el renderizador de Markdown se crea una sola vez para todo el sitio, estas opciones solo se pueden declarar en el archivo de configuración principal, no en configuraciones adicionales.
```
## Directorio separado para cada localización {#separate-directory-for-each-locale}
@ -4,13 +4,13 @@ description: Habilita el modo MPA (Aplicación de Múltiples Páginas) en VitePr
# Modo MPA <Badgetype="warning"text="experimental"/> {#mpa-mode}
El modo MPA (Aplicación de multiples páginas) puede ser habilitado por la linea de comandos con `vitepress build --mpa`, o a través de la configuración por la opción `mpa: true`.
El modo MPA (Aplicación de multiples páginas) puede ser habilitado por la línea de comandos con `vitepress build --mpa`, o a través de la configuración por la opción `mpa: true`.
En el modo MPA, todas las páginas son presentadas por defecto sin JavaScript incluído. Como resultado, el sitio en producción probablemente tendrá una marca de desempeño de visita inicial superior con herramientas de auditoría.
En el modo MPA, todas las páginas son presentadas por defecto sin JavaScript incluido. Como resultado, el sitio en producción probablemente tendrá una marca de desempeño de visita inicial superior con herramientas de auditoría.
Sin embargo, debido a la ausencia de navegación SPA, los links entre páginas resultan en recargas de página completos. Navegaciones después de la carga en el modo MPA no parecerán tan instantáneos en comparación con el modo SPA.
Sin embargo, debido a la ausencia de navegación SPA, los enlaces entre páginas resultan en recargas completas de la página. La navegación posterior a la carga en modo MPA no será tan instantánea como en modo SPA.
También note que no tener JavaScript por defecto significa que está esencialmente utilizando Vue como modelo de lenguaje en el lado del servidor. Nungun manipulador de eventos será embutido en el navegador, entonces no habrá interactividad. Para cargar JavaScript en el lado del cliente, necesitará usar el tag especial `<script client>`:
También note que `no-JS-by-default` significa que, esencialmente, está utilizando Vue únicamente como un lenguaje de plantillas del lado del servidor. No se adjuntarán controladores de eventos en el navegador, por lo que no habrá interactividad. Para cargar JavaScript del lado del cliente, deberá utilizar la etiqueta especial `<script client>`:
description: Comprende el enrutamiento basado en archivos de VitePress, rutas dinámicas, URLs limpias y reescritura de rutas.
outline: deep
description: Comprende el enrutamiento basado en archivos de VitePress, rutas dinámicas, URLs limpias y reescritura de rutas.
---
# Enrutamiento {#routing}
## Enrutamiento basasdo en Archivos {#file-based-routing}
## Enrutamiento basado en Archivos {#file-based-routing}
VitePress utiliza enrutamiento basado en archivos, esto significa que las páginas HTML generadas son mapeadas de la estructura de directorios de los archivos Markdown. Por ejemplo, dada la siguiente estructura de directorio:
```
.
├─ guide
│ ├─ getting-started.md
├─ guia
│ ├─ comenzar.md
│ └─ index.md
├─ index.md
└─ prologue.md
└─ prologo.md
```
Las páginas HTML generadas serán:
```
index.md --> /index.html (accesible por /)
prologue.md --> /prologue.html
guide/index.md --> /guide/index.html (accesible por /guide/)
guia/index.md --> /guia/index.html (accesible por /guia/)
guia/comenzar.md --> /guia/comenzar.html
```
El HTML resultante puede ser hospedado en cualquier servidor web que pueda servir archivos estáticos.
## Diretório Raiz y fuente {#root-and-source-directory}
## Directorio Raíz y fuente {#root-and-source-directory}
Existen dos conceptos importantes en la estructura de archivos de un proyecto VitePress: el **directorio raiz** y el **directorio fuente**.
Existen dos conceptos importantes en la estructura de archivos de un proyecto VitePress: el **directorio raíz** y el **directorio fuente**.
### Directorio Raiz {#project-root}
### Raíz del Proyecto {#project-root}
El directorio raiz es donde VitePress busca por el directorio especial `.vitepress`. El directorio `.vitepress` es un lugar reservado para el archivo de configuración de VitePress, el caché del servidor de desarrollo, el resultado de la compilación y el código de personalización del tema opcional.
La raíz del proyecto es donde VitePress intentará buscar el directorio especial `.vitepress`. El directorio `.vitepress` es una ubicación reservada para el archivo de configuración de VitePress, la caché del servidor de desarrollo, la salida de la compilación y el código de personalización de temas opcional.
Al ejecutar `vitepress dev` o `vitepress build` en el terminal, VitePress usará el directorio actual como directorio raiz del proyecto. Para especificar un subdirectorio como raiz, es necesario pasar el camino relativo para el comando. Por ejemplo, si el proyecto VitePress estuviera localizado en `./docs`, debe ejecutarse`vitepress dev docs`:
Cuando ejecute `vitepress dev` o `vitepress build` desde la línea de comandos, VitePress utilizará el directorio de trabajo actual como raíz del proyecto. Para especificar un subdirectorio como raíz, es necesario pasar la ruta relativa al comando. Por ejemplo, si su proyecto VitePress se encuentra en `./docs`, deberá ejecutar`vitepress dev docs`:
```
.
├─ docs # directorio raiz
├─ docs # raíz del proyecto
│ ├─ .vitepress # directorio de configuración
│ ├─ getting-started.md
│ ├─ comenzar.md
│ └─ index.md
└─ ...
```
@ -52,49 +52,49 @@ Al ejecutar `vitepress dev` o `vitepress build` en el terminal, VitePress usará
vitepress dev docs
```
Esto resultará en el siguiente mapeamento de fuente para HTML:
Esto resultará en el siguiente mapeo de fuente para HTML:
```
docs/index.md --> /index.html (accesible como /)
docs/getting-started.md --> /getting-started.html
docs/comenzar.md --> /comenzar.html
```
### Directorio Fuente {#source-directory}
El directorio fuente es donde sus archivos fuente en Markdown están. Por defecto, es el mismo que el directorio raiz. Sin embargo, puede configurarlo por medio de la opción de configuración [`srcDir`](../reference/site-config#srcdir).
El directorio fuente es donde se encuentran tus archivos fuente de Markdown. Por defecto, coincide con la raíz del proyecto. Sin embargo, puedes configurarlo mediante la opción de configuración [`srcDir`](../reference/site-config#srcdir).
La opción `srcDir`es resuelta en relación al directorio raiz del proyecto. Por ejemplo, con `srcDir: 'src'`, su estructura de archivos quedará así:
La opción `srcDir`se resuelve en relación con la raíz del proyecto. Por ejemplo, con `srcDir: 'src'`, la estructura de archivos será la siguiente:
```
. # directorio raiz
. # directorio raíz
├─ .vitepress # directorio de configuración
└─ src # directorio fuente
├─ getting-started.md
├─ comenzar.md
└─ index.md
```
El mapeamente resultante de la fuente para HTML:
El mapeo resultante de código fuente a HTML:
```
src/index.md --> /index.html (accesible como /)
src/getting-started.md --> /getting-started.html
src/comenzar.md --> /comenzar.html
```
## Links Entre Páginas {#linking-between-pages}
## Enlaces Entre Páginas {#linking-between-pages}
Puede usar tanto paths absolutos como relativos al vincular páginas. Note que, incluso si ambas extensiones `.md` y `.html` funcionan, funcionem, la práctica recomendada es omitir las extensiones de archivo para que VitePress pueda generar las URLs finales con base en su configuración.
Puedes usar rutas absolutas y relativas para enlazar páginas. Ten en cuenta que, si bien funcionan las extensiones `.md` y `.html`, lo recomendable es omitirlas para que VitePress genere las URL finales según tu configuración.
```md
<!-- Hacer -->
[Getting Started](./getting-started)
[Getting Started](../guide/getting-started)
[Comenzar](./comenzar)
[Comenzar](../guia/comenzar)
<!-- No hacer -->
[Getting Started](./getting-started.md)
[Getting Started](./getting-started.html)
[Comenzar](./comenzar.md)
[Comenzar](./comenzar.html)
```
Averigue más sobre la vinculación de assets, como imagenes, en [Manipulación de Assets](./asset-handling).
Obtenga más información sobre cómo vincular recursos como imágenes en [Manejo de Assets](./asset-handling).
### Vinculación de Páginas No VitePress {#linking-to-non-vitepress-pages}
@ -103,21 +103,21 @@ Si desea vincular a una página en su sitio que no es generada por VitePress, se
**Entrada**
```md
[Link para pure.html](/pure.html){target="_self"}
[Enlace para puro.html](/puro.html){target="_self"}
```
**Salida**
[Link para pure.html](/pure.html){target="_self"}
[Enlace para puro.html](/puro.html){target="_self"}
::: tip Nota
En los links Markdown, la `base` es automáticamente adicionada a la URL. Esto significa que, si desea vincular a una página fuera de su base, será necesario algo como `../../pure.html` en el link (resuelto en relación a la página actual por el navegador).
En los enlaces Markdown, la `base` es automáticamente adicionada a la URL. Esto significa que, si desea vincular a una página fuera de su base, será necesario algo como `../../puro.html` en el enlace (resuelto en relación a la página actual por el navegador).
Alternativamente, puede usarse directamente la sintaxis de tag anchor:
Alternativamente, puede utilizar directamente la sintaxis de la etiqueta de anclaje:
```md
<ahref="/pure.html" target="_self">Link para pure.html</a>
<ahref="/puro.html" target="_self">Enlace para puro.html</a>
```
:::
@ -128,7 +128,7 @@ Alternativamente, puede usarse directamente la sintaxis de tag anchor:
Para servir URLs limpias con VitePress, es necesario soporte en el lado del servidor.
:::
Por defecto, VitePress resuelve links de entrada para URLs que terminan con `.html`. Sin embargo, algunos usuarios pueden preferir "URLs limpias" sin la extensión `.html`, por ejemplo, `example.com/path` en vez de `example.com/path.html`.
Por defecto, VitePress resuelve los enlaces entrantes a URLs que terminan en `.html`. Sin embargo, algunos usuarios pueden preferir "URLs limpias" sin la extensión `.html`, por ejemplo, `ejemplo.com/ruta` en vez de `ejemplo.com/ruta.html`.
Algunos servidores o plataformas de hospedaje (por ejemplo, Netlify, Vercel, GitHub Pages) proporcionan la habilidad de mapear una URL como `/foo` para `/foo.html` si existir, sin redireccionamiento:
@ -137,41 +137,44 @@ Algunos servidores o plataformas de hospedaje (por ejemplo, Netlify, Vercel, Git
Si esa funcionalidad está disponible para usted, también se puede activar la propia opción de configuración [`cleanUrls`](../reference/site-config#cleanurls) de VitePress para que:
- Links de entrada entre páginas sean generados sin la extensión `.html`.
- Si el path actual termina con `.html`, el enrutador realizará un redireccionamiento en el lado del cliente para el path sin extensión.
- Los enlaces entrantes entre páginas se generan sin la extensión `.html`.
- Si la ruta actual termina en `.html`, el enrutador realizará una redirección del lado del cliente a la ruta sin extensión.
Sin embargo, si no puede configurar el servidor con ese soporte, será necesario recorrer manualmente la siguiente estructura de directorio:
```
.
├─ getting-started
├─ comenzar
│ └─ index.md
├─ installation
├─ instalacion
│ └─ index.md
└─ index.md
```
# Reescritura de Ruta {#route-rewrites}
Puede personalizar el mapeamento entre la estructura de directorios fuente y las páginas generadas. Esto es útil cuando tiene una estructura de proyecto compleja. Por ejemplo, digamos que tiene un monorepo con varios paquetes y le gustaría colocar la documentación junto con los archivos fuente de esta forma:
## Reescritura de Ruta {#route-rewrites}
Puedes personalizar la correspondencia entre la estructura del directorio de origen y las páginas generadas. Esto resulta útil cuando tienes una estructura de proyecto compleja. Por ejemplo, digamos que tienes un monorepo con varios paquetes y le gustaría colocar la documentación junto con los archivos fuente de esta forma:
```
.
├─ packages
│ ├─ pkg-a
│ │ └─ src
│ │ ├─ pkg-a-code.ts
│ │ └─ pkg-a-docs.md
│ └─ pkg-b
│ └─ src
│ ├─ pkg-b-code.ts
│ └─ pkg-b-docs.md
└─ packages
├─ pkg-a
│ └─ src
│ ├─ foo.md
│ └─ index.md
└─ pkg-b
└─ src
├─ bar.md
└─ index.md
```
Y desea que las páginas VitePress sean generadas así:
La opción `rewrites` también soporta parametros de ruta dinámicos. En el ejemplo arriba, sería tedioso listar todos los paths si tiene muchos paquetes. Dado que todos ellos tienen la misma estructura de archivo, puede simplificar la configuración así:
La opción `rewrites` también soporta parámetros de ruta dinámicos. En el ejemplo anterior, sería tedioso enumerar todas las rutas si tienes muchos paquetes. Dado que todos tienen la misma estructura de archivos, puedes simplificar la configuración de esta manera:
```ts
export default {
rewrites: {
'packages/:pkg/src/(.*)': ':pkg/index.md'
'packages/:pkg/src/:slug*': ':pkg/:slug*'
}
}
```
Los paths reesctritos son compilados usando el paquete `path-to-regexp` - consulte [su documentación](https://github.com/pillarjs/path-to-regexp#parameters) para una sintaxis más avanzada.
Las rutas de reescritura se compilan utilizando el paquete `path-to-regexp`. Consulte [su documentación](https://github.com/pillarjs/path-to-regexp/tree/6.x#parameters) para obtener una sintaxis más avanzada.
`rewrites` también puede ser una función que recibe la ruta original y devuelve la nueva ruta:
Cuando las reescrituras están habilitadas, **links relativos deben ser basados en los paths reescritos**. Por ejemplo, para crear un link relativo de `packages/pkg-a/src/pkg-a-code.md` para `packages/pkg-b/src/pkg-b-code.md`, debe usarse:
Cuando las reescrituras están habilitadas, **los enlaces relativos deben ser basados en las rutas reescritas**. Por ejemplo, para crear un enlace relativo de `packages/pkg-a/src/pkg-a-code.md` a `packages/pkg-b/src/pkg-b-code.md`, debe usar:
```md
[Link para PKG B](../pkg-b/pkg-b-code)
[Enlace para PKG B](../pkg-b/pkg-b-code)
```
:::
## Rutas Dinámicas {#dynamic-routes}
Puede generar muchas páginas usando un único archivo Markdown y datos dinámicos. Por ejemplo, puede crear un archivo `packages/[pkg].md` que genera una página correspondiente para cáda paquete en un proyecto. Aqui, el segmento `[pkg]` es un **parámetro** de ruta que diferencia cada página de las otras.
Puedes generar varias páginas usando un único archivo Markdown y datos dinámicos. Por ejemplo, puedes crear un archivo `packages/[pkg].md` que genere una página correspondiente para cada paquete de un proyecto. Aqui, el segmento `[pkg]` es un **parámetro** de ruta que diferencia cada página de las otras.
### Archivo de Carga de Paths {#paths-loader-file}
### Archivo de Carga de Rutas {#paths-loader-file}
Como VitePress es un generador de sitios estáticos, los paths posibles de las páginas deben ser determinados en el momento de la compilación. Por lo tanto, una página de ruta dinámica **debe** estar acompañada por un **archivo de carga de paths**. Para `packages/[pkg].md`, necesitaremos de`packages/[pkg].paths.js` (`.ts` también es soportado):
Como VitePress es un generador de sitios estáticos, las posibles rutas de página deben determinarse en tiempo de compilación. Por lo tanto, una página de ruta dinámica **debe** estar acompañada de un **archivo de carga de rutas**. Para `packages/[pkg].md`, necesitaremos `packages/[pkg].paths.js` (`.ts` también es soportado):
```
.
└─ packages
├─ [pkg].md # modelo de ruta
└─ [pkg].paths.js # cargador de paths de la ruta
├─ [pkg].md # plantilla de ruta
└─ [pkg].paths.js # cargador de rutas de ruta
```
El cargador de paths debe proporcionar un objeto con un método `paths` como su exportación por defecto. El método `paths` debe retornar un _array_ de objetos con una propiedad `params`. Cada uno de esos objetos generará una página correspondiente.
El cargador de rutas debe proporcionar un objeto con un método `paths` como su exportación por defecto. El método `paths` debe devolver un _array_ de objetos con una propiedad `params`. Cada uno de estos objetos generará una página correspondiente.
Dado el siguiente _array_`paths`:
@ -246,11 +261,35 @@ Las páginas HTML generadas serán:
└─ bar.html
```
### Cargador con tipado seguro mediante `defineRoutes` {#type-safe-loader-with-defineroutes}
Si utiliza TypeScript, puede envolver el cargador con `defineRoutes` de `vitepress` para obtener sugerencias de tipo para ganchos de ruta como `paths`, `watch` y `transformPageData`:
```ts
// packages/[pkg].paths.ts
import { defineRoutes } from 'vitepress'
export default defineRoutes({
watch: ['../data/**/*.json'],
async paths() {
return [
{ params: { pkg: 'foo' } },
{ params: { pkg: 'bar' } }
]
},
async transformPageData(pageData) {
pageData.title = `${pageData.title} · Packages`
}
})
```
`defineRoutes` es opcional, pero se recomienda al crear archivos `.paths.ts`.
### Múltiples Parámetros {#multiple-params}
Una ruta dinámica puede contener múltiples parámetros:
**Estrutura de Archivo**
**Estructura de Archivo**
```
.
@ -259,7 +298,7 @@ Una ruta dinámica puede contener múltiples parámetros:
El módulo de carga de paths es ejecutado en Node.js y apenas durante el momento de la compilación. Puede generar dinámicamente el _array_ de paths usando cualquier dato, sea local o remoto.
El módulo de carga de rutas se ejecuta en Node.js y solo durante el proceso de compilación. Puedes generar dinámicamente el _array_ de rutas utilizando cualquier dato, ya sea local o remoto.
Generando paths a partir de archivos locales:
Generación de rutas a partir de archivos locales:
```js
import fs from 'node:fs'
@ -303,7 +342,7 @@ export default {
}
```
Generando paths a partir de datos remotos:
Generación de rutas a partir de datos remotos:
```js
export default {
@ -322,17 +361,56 @@ export default {
}
```
### Visualización de plantillas y archivos de datos {#watching-template-and-data-files}
Al generar contenido de página a partir de plantillas o fuentes de datos externas, puede utilizar la opción de monitorización para reconstruir automáticamente las páginas cuando esos archivos cambien durante el desarrollo:
```js
// posts/[slug].paths.js
import fs from 'node:fs'
import { renderTemplate } from './templates/renderer.js'
export default {
// Esta atento a los cambios en los archivos de plantilla y las fuentes de datos.
watch: [
'./templates/**/*.njk', // Template files
'../data/**/*.json' // Data files
],
paths(watchedFiles) {
// watchedFiles será un array con las rutas absolutas de los archivos coincidentes.
const data = JSON.parse(fs.readFileSync(file, 'utf-8'))
return {
params: { slug: data.slug },
content: renderTemplate(data) // Utilice la plantilla para generar contenido.
}
})
}
}
```
La opción `watch` funciona de la misma manera que en [cargadores de datos](./data-loading#data-from-local-files):
- Acepta [patrones glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) para la coincidencia de archivos
- Los patrones son relativos al archivo `.paths.js`
- Los cambios en los archivos monitorizados activan la regeneración de la página y HMR durante el desarrollo.
- En las compilaciones de producción, todas las páginas se generan una sola vez, independientemente de la configuración de monitorización
### Accediendo Parámetros en la Página {#accessing-params-in-page}
Puede usar los parámetros para pasar datos adicionales para cada página. El archivo de ruta Markdown puede acceder a los parámetros de la página actual en expresiones Vue a través de la propiedad global `$params`:
Puedes usar los parámetros para pasar datos adicionales a cada página. El archivo de ruta Markdown puede acceder a los parámetros de la página actual en expresiones Vue a través de la propiedad global `$params`:
```md
- nombre del paquete: {{ $params.pkg }}
- versión: {{ $params.version }}
```
También puede acceder los parámetros de la página actual a través del API de tiempo de ejecución [`useData`](../reference/runtime-api#usedata). Esto está disponible tanto en archivos Markdown así como en componentes Vue:
También puedes acceder a los parámetros de la página actual a través de la API de tiempo de ejecución [`useData`](../reference/runtime-api#usedata). Esto está disponible tanto en archivos Markdown como en componentes Vue:
### Renderizado de contenido sin procesar {#rendering-raw-content}
Parámetros pasados para una página serán serializados en la carga JavaScript del cliente, por lo tanto, evite pasar datos pesados en los parámetros, como Markdown crudo o contenido HTML obtenido de un CSS remoto.
Los parámetros que se pasen a la página se serializarán en la carga útil de JavaScript del cliente, por lo que debe evitar pasar datos pesados en los parámetros, por ejemplo, contenido Markdown o HTML sin procesar obtenido de un CMS remoto.
En lugar de eso, puede pasar tal contenido para cada página usando la propiedad `content` en cada objeto de path:
En lugar de eso, puede pasar dicho contenido a cada página utilizando la propiedad `content` en cada objeto de ruta:
```js
export default {
@ -358,14 +436,14 @@ export default {
return posts.map((post) => {
return {
params: { id: post.id },
content: post.content // Markdown o HTML crudo
content: post.content // raw Markdown or HTML
}
})
}
}
```
En seguida, use la siguiente sintaxis especial para presentar el contenido como parte del propio archivo Markdown:
En seguida, use la siguiente sintaxis especial para mostrar el contenido como parte del propio archivo Markdown:
@ -4,47 +4,51 @@ description: Genera un archivo sitemap.xml para tu sitio VitePress para mejorar
# Generación de Sitemap {#sitemap-generation}
VitePress viene con soporte embutido para generar un archivo `sitemap.xml` para su sitio. Para habilitar, adicione lo siguiente a su`.vitepress/config.js`:
VitePress incluye soporte integrado para generar un archivo `sitemap.xml` para tu sitio. Para habilitarlo, agrega lo siguiente a tu archivo`.vitepress/config.js`:
```ts
import { defineConfig } from 'vitepress'
export default defineConfig({
export default {
sitemap: {
hostname: 'https://example.com'
hostname: 'https://ejemplo.com'
}
})
}
```
Para tener tags `<lastmod>` en su `sitemap.xml`, puede habilitar la opción [`lastUpdated`](../reference/default-theme-last-updated).
Para tener etiquetas `<lastmod>` en tu `sitemap.xml`, puedes habilitar la opción [`lastUpdated`](../reference/default-theme-last-updated).
## Opciones {#options}
El soporte de Sitemap es alimentado por el módulo [`sitemap`](https://www.npmjs.com/package/sitemap). Puede pasar cualquiera de las opciones soportadas por el en la opción `sitemap` de su archivo de configuración. Estos serán pasados directamente al constructor `SitemapStream`. Consulte la [documentación `sitemap`](https://www.npmjs.com/package/sitemap#options-you-can-pass) para más detalles. Ejemplo:
El soporte de Sitemap se basa en el módulo [`sitemap`](https://www.npmjs.com/package/sitemap). Puedes pasar cualquiera opciones soportadas con este módulo a la opción `sitemap` en tu archivo de configuración. Estas opciones se pasarán directamente al constructor de `SitemapStream`. Consulta la documentación de [`sitemap`](https://www.npmjs.com/package/sitemap#options-you-can-pass) para más detalles. Ejemplo:
```ts
import { defineConfig } from 'vitepress'
export default defineConfig({
export default {
sitemap: {
hostname: 'https://example.com',
hostname: 'https://ejemplo.com',
lastmodDateOnly: false
}
})
}
```
## Hook `transformItems`
Puede usar el hook `sitemap.transformItems` para modificar los items del sitemap antes de ser escritos en el archivo `sitemap.xml`. Este hook es llamado como un _array_ de items sitemap y espera un _array_ de items sitemap como retorno. Ejemplo:
Si estás usando `base` en tu configuración, debes agregarlo a la opción `hostname`:
```ts
import { defineConfig } from 'vitepress'
export default {
base: '/my-site/',
sitemap: {
hostname: 'https://ejemplo.com/mi-pagina/'
}
}
```
## Hook `transformItems` {#transformitems-hook}
export default defineConfig({
Puede usar el hook `sitemap.transformItems` para modificar los elementos del sitemap antes de que se escriban en el archivo `sitemap.xml`. Este hook se llama con un _array_ de elementos del mapa del sitio y espera que se devuelva un _array_ de elementos del sitemap. Ejemplo:
```ts
export default {
sitemap: {
hostname: 'https://example.com',
hostname: 'https://ejemplo.com',
transformItems: (items) => {
// adiciona nuevos items o modifica/filtra items existentes
// agregar nuevos elementos o modificar/filtrar elementos existentes
@ -4,9 +4,9 @@ description: Usa componentes Vue y funciones de plantillas dinámicas directamen
# Usando Vue en Markdown {#using-vue-in-markdown}
En VitePress, cada archivo Markdown es compilado para HTML y entonces procesado como un [Componente de Archivo Único de Vue](https://vuejs.org/guide/scaling-up/sfc.html). Esto significa que puede usar cualquier funcionalidad de Vue dentro del Markdown, incluyendo la interpolación dinámica, usar componentes Vue o lógica arbitrária de componentes Vue dentro de la página adicionando una tag`<script>`.
En VitePress, cada archivo Markdown es compilado en HTML y luego procesado como un [Componente de Archivo Único de Vue](https://vuejs.org/guide/scaling-up/sfc.html). Esto significa que puedes usar cualquier funcionalidad de Vue dentro del Markdown, incluyendo plantillas dinámicas, componentes de Vue o lógica arbitraria de componentes de Vue en la página, agregando una etiqueta`<script>`.
Vale resaltar que VitePress aprovecha el compilador Vue para detectar y optimizar automáticamente las partes puramente estáticas del contenido Markdown. Los contenidos estáticaos son optimizados en nodos de espacio reservado únicos y eliminados de la carga JavaScript de la página para visitas iniciales. Ellos también son ignorados durante la hidratación en el lado del cliente. En resumen, solo paga por las partes dinámicas en cualquier página específica.
Vale resaltar que VitePress aprovecha el compilador de Vue para detectar y optimizar automáticamente las partes puramente estáticas del contenido Markdown. El contenido estático se optimiza en nodos de marcador de posición individuales y se elimina del código JavaScript de la página en las visitas iniciales. También se omite durante la carga del lado del cliente. En resumen, solo se paga por las partes dinámicas de cada página.
::: tip Compatibilidad SSR
Todo uso de Vue necesita ser compatible con SSR. Consulte [Compatibilidad SSR](./ssr-compat) para detalles y soluciones comunes.
@ -16,7 +16,7 @@ Todo uso de Vue necesita ser compatible con SSR. Consulte [Compatibilidad SSR](.
### Interpolación {#interpolation}
Cada archivo Markdown es primero compilado para HTML y después pasado como un componente Vue para la canalización de procesos Vite. Esto significa que puede usar interpolación en el estilo Vue en el texto:
Cada archivo Markdown se compila primero a HTML y luego se pasa como un componente Vue al proceso de Vite. Esto significa que puedes usar la interpolación al estilo Vue en el texto:
**Entrada**
@ -30,7 +30,7 @@ Cada archivo Markdown es primero compilado para HTML y después pasado como un c
### Directivas {#directives}
Las Directivas también funcionan (observe que, por definición, HTML crudo también es válido en Markdown):
Las directivas también funcionan (observe que, por diseño, el HTML crudo también es válido en Markdown):
**Entrada**
@ -42,26 +42,26 @@ Las Directivas también funcionan (observe que, por definición, HTML crudo tamb
<divclass="language-text"><pre><code><spanv-for="i in 3">{{ i }} </span></code></pre></div>
## `<script>`e `<style>`
## `<script>`y `<style>` {#script-and-style}
las tags `<script>` e `<style>` en nivel raiz en los archivos Markdown funcionan igualmente como en los componentes de archivo único Vue, incluyendo `<script setup>`, `<style module>`, y etc. La principal diferencia aquí es que no hay una tag `<template>`: todo contenido en nivel raiz es Markdown. Además, observe que todas las tags deben ser colocadas**después** del frontmatter:
Las etiquetas `<script>` y `<style>` de nivel raíz en los archivos Markdown funcionan igual que en los SFC de Vue, incluyendo `<script setup>`, `<style module>`, etc. La principal diferencia es que no hay etiqueta `<template>`: todo el demás contenido de nivel raíz es Markdown. Además, tenga en cuenta que todas las etiquetas deben colocarse**después** del frontmatter:
Cuando es usado en Markdown, `<style scoped>`exige la adición de atributos especiales a cada elemento en la página actual, lo que aumentará significativamente el tamaño de la página. `<style module>` es preferido cuando es necesaria una estilización localizada en una página.
Cuando es usado en Markdown, `<style scoped>`requiere agregar atributos especiales a cada elemento de la página actual, lo que aumenta significativamente el tamaño de la página. Se prefiere `<style module>` cuando se necesita un estilo con ámbito local en una página.
:::
También tiene acceso a los APIs de tiempo de ejecución VitePress, como el [auxiliar `useData`](../reference/runtime-api#usedata), que proporciona acceso a los metadados de la página actual:
También tienes acceso a las API de tiempo de ejecución de VitePress, como el [auxiliar `useData`](../reference/runtime-api#usedata), que proporciona acceso a los metadatos de la página actual:
**Entrada**
@ -106,7 +106,7 @@ Puede importar y usar componentes Vue directamente en los archivos Markdown.
### Importando en el Markdown {#importing-in-markdown}
Si un componente es usado apenas por algunas páginas, es recomendable importarlos explicitamente donde son usados. Esto permite que ellos sean divididos adecuadamente y cargados apenas cuando las páginas relevantes son mostradas.
Si un componente es usado apenas por algunas páginas, es recomendable importarlos explícitamente donde son usados. Esto permite que ellos sean divididos adecuadamente y cargados apenas cuando las páginas relevantes son mostradas.
```md
<scriptsetup>
@ -128,8 +128,8 @@ Este es un archivo .md usando un componente personalizado
Si un componente fuera usado en la mayoría de las páginas, ellos pueden ser registrados globalmente personalizando la instancia de la aplicación Vue. Consulte la sección relevante en [Extendiendo el Tema por Defecto](./extending-default-theme#registering-global-components) para un ejemplo.
::: warning IMPORTANT
Asegurese de que el nombre de un componente personalizado contenga un hífen o esté en PascalCase. Caso contrario, el será tratado como un elemento alineado y envuelto dentro de una tag `<p>`, lo que llevará a una incompatibilidad de hidratación pues `<p>` no permite que elementos de bloque sean colocados dentro de el.
::: warning IMPORTANTE
Asegúrese de que el nombre de un componente personalizado contenga un guion o esté en formato PascalCase. De lo contrario, se tratará como un elemento en línea y se envolverá dentro de una etiqueta `<p>`, lo que provocará un error de compatibilidad, ya que `<p>` no permite colocar elementos de bloque en su interior.
:::
### Usando Componentes En Headers <ComponentInHeader/> {#using-components-in-headers}
@ -144,46 +144,46 @@ Puede usar componentes Vue en los headers, pero observe la diferencia entre las
El HTML envuelto por `<code>` será mostrado como es, solamente el HTML que **no** estuviera envuelto será analizado por Vue.
::: tip
EL HTML de salida es realizado por [Markdown-it](https://github.com/Markdown-it/Markdown-it), en cuanto los headers procesados son manipulados por VitePress (y usados tanto en la barra lateral como dentro del título del video).
La generación del HTML de salida se realiza mediante [Markdown-it](https://github.com/Markdown-it/Markdown-it), mientras que los encabezados analizados son gestionados por VitePress (y se utilizan tanto para la barra lateral como para el título del documento).
:::
## Escapes {#escaping}
Puede escapar de interpolaciones Vue envolvientdolas en un `<span>` u otros elementos con la directiva `v-pre`:
Puede escapar de interpolaciones de Vue envolviéndolas en un `<span>` u otros elementos con la directiva `v-pre`:
**Entrada**
```md
Esto <spanv-pre>{{ será exibido como es }}</span>
Esto <spanv-pre>{{ se mostrará como es }}</span>
```
**Salida**
<divclass="escape-demo">
<p>Esto <spanv-pre>{{ será exibido como es }}</span></p>
<p>Esto <spanv-pre>{{ se mostrará como es }}</span></p>
</div>
Alternativamente, puede envolver todo el paragrafo en un contenedor personalizadon`v-pre`:
Alternativamente, puede envolver todo el párrafo en un contenedor personalizado`v-pre`:
```md
::: v-pre
{{ Esto será exibido como es }}
{{ se mostrará como es }}
:::
```
**Output**
**Salida**
<divclass="escape-demo">
::: v-pre
{{ Esto será exibido como es }}
{{ se mostrará como es }}
:::
</div>
## "Desescape" en bloques de Código {#unescape-in-code-blocks}
Por defecto, todos los bloques de código cercados son automáticamente envueltos con `v-pre`, entonces ninguna sintaxis Vue será procesada dentro de ellos. Para permitir la interpolación en el estilo Vue dentro de la valla, puede adicionar el lenguaje con el sufijo `-vue`, por ejemplo, `js-vue`:
Por defecto, todos los bloques de código delimitados se envuelven automáticamente con `v-pre`, por lo que no se procesará ninguna sintaxis de Vue en su interior. Para habilitar la interpolación al estilo Vue dentro de las delimitaciones, puede agregar el sufijo `-vue` al lenguaje, por ejemplo, `js-vue`:
**Entrada**
@ -199,21 +199,20 @@ Hola {{ 1 + 1 }}
Hola {{ 1 + 1 }}
```
Observe que esto puede impedir que ciertos tokens sean realzados correctamente.
Observe que esto puede impedir que ciertos tokens se resalte la sintaxis correctamente.
VitePress poseé [soporte embutido](https://vite.dev/guide/features.html#css-pre-processors) para preprocesadores CSS: archivos `.scss`, `.sass`, `.less`, `.styl`e `.stylus`. No es necesario instalar plugins específicos de Vite para ellos, pero el propio preprocesados correspondiente debe ser instalado:
VitePress tiene [soporte integrado](https://vite.dev/guide/features.html#css-pre-processors) para preprocesadores CSS: archivos `.scss`, `.sass`, `.less`, `.styl`y `.stylus`. No es necesario instalar complementos específicos de Vite para ellos, pero sí debe instalarse el preprocesador correspondiente.
```
# .scss e .sass
# .scss y .sass
npm install -D sass
# .less
npm install -D less
# .styl e .stylus
# .styl y .stylus
npm install -D stylus
```
@ -228,7 +227,7 @@ Entonces puede usar lo siguiente en Markdown y en los componentes del tema:
## Usando _Teleports_ {#using-teleports}
VitePress actualmente ofrece soporte a SSG para _teleports_ apenas para el cuerpo. Para otros objetivos, puede envolverlos dentro del componente embutido `<ClientOnly>` o inyectar la marcación de _teleport_ en la localización correcta en su página final HTML por medio del [hook `postRender`](../reference/site-config#postrender).
VitePress actualmente ofrece soporte a SSG para _teleports_ al cuerpo del documento. Para otros objetivos, puede envolverlos dentro del componente `<ClientOnly>` integrado o inyectar el marcado de _teleport_ en la ubicación correcta del HTML de su página final mediante el hook [`postRender`](../reference/site-config#postrender).
<ModalDemo/>
@ -259,7 +258,7 @@ import ComponentInHeader from '../../components/ComponentInHeader.vue'
}
</style>
## Soporte de IntelliSense en VS Code
## Soporte de IntelliSense en VS Code {#vs-code-intellisense-support}
<!-- Based on https://github.com/vuejs/language-tools/pull/4321 -->
@ -4,7 +4,7 @@ description: VitePress es un generador de sitios estáticos diseñado para crear
# ¿Qué es VitePress? {#what-is-vitepress}
VitePress es un [Generador de Sitios Estáticos](https://en.wikipedia.org/wiki/Static_site_generator) (SSG) diseñado para construir sitios web rápidos y enfocados en el contenido. En pocas palabras, VitePress toma tu contenido fuente escrito en [Markdown](https://en.wikipedia.org/wiki/Markdown), le aplica un tema y genera páginas HTML estáticas que se pueden desplegar fácilmente en cualquier lugar.
VitePress es un [Generador de Sitios Estáticos](https://es.wikipedia.org/wiki/Generador_de_sitios_est%C3%A1ticos) (SSG) diseñado para construir sitios web rápidos y enfocados en el contenido. En pocas palabras, VitePress toma tu contenido fuente escrito en [Markdown](https://es.wikipedia.org/wiki/Markdown), le aplica un tema y genera páginas HTML estáticas que se pueden desplegar fácilmente en cualquier lugar.
::: tip {no-title}
¿Quieres probarlo? Ve directo al [Inicio Rápido](./getting-started).
@ -14,13 +14,13 @@ VitePress es un [Generador de Sitios Estáticos](https://en.wikipedia.org/wiki/S
- **Documentación**
VitePress incluye un tema por defecto diseñado para documentación técnica. Este tema es el que se utiliza en la página que estás leyendo ahora, así como en la documentación de [Vite](https://vite.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/) y [muchos otros](https://github.com/search?q=/%22vitepress%22:+/+path:/(?:package%7Cdeno)%5C.jsonc?$/+NOT+is:fork+NOT+is:archived&type=code).
VitePress incluye un tema por defecto diseñado para documentación técnica. Este tema impulsa esta página que está leyendo ahora mismo, junto con la documentación para [Vite](https://vite.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/) y [muchos otros](https://github.com/search?q=/%22vitepress%22:+/+path:/(?:package%7Cdeno)%5C.jsonc?$/+NOT+is:fork+NOT+is:archived&type=code).
La [documentación oficial Vue.js](https://vuejs.org/) también está basada en VitePress, pero utiliza un tema personalizado compartido entre varias traducciones.
- **Blogs, Portfolios y sitios de Marketing**
VitePress soporta [temas completamente personalizables](./custom-theme), con la experiencia de desarrollo de una aplicación estándar de Vite + Vue. Al estar construido sobre Vite, también puedes aprovechar directamente los plugins de su rico ecosistema. Adicionalmente, VitePress proporciona APIs flexibles para [cargar datos](./data-loading) (locales o remotos) y [generar rutas dinámicamente](./routing#dynamic-routes). Puedes usarlo para construir prácticamente cualquier cosa, siempre y cuando los datos puedan ser determinados en el momento de la construcción.
VitePress soporta [temas completamente personalizables](./custom-theme), con la experiencia de desarrollo de una aplicación estándar de Vite + Vue. Al estar construido sobre Vite, también permite aprovechar directamente los plugins de su rico ecosistema. Además, VitePress proporciona API flexibles para [cargar datos](./data-loading) (locales o remotos) y [generar rutas dinámicamente](./routing#dynamic-routes). Puedes usarlo para construir prácticamente cualquier cosa, siempre que los datos se puedan determinar durante la compilación.
El [blog oficial Vue.js](https://blog.vuejs.org/) es un blog simple que genera su página de inicio basándose en contenido local.
@ -30,17 +30,17 @@ VitePress busca ofrecer una excelente Experiencia de Desarrollador (DX) al traba
- **[Con tecnología Vite:](https://vite.dev/)** inicio instantáneo del servidor, con los cambios reflejados al instante (<100ms)sinrecargarlapágina.
- **[Extensiones Markdown Integradas:](./markdown)** Frontmatter, tablas, destaque de sintaxis... tú decides. Específicamente, VitePress proporciona muchos recursos para trabajar con bloques de código, tornándolo ideal para documentación altamente técnica.
- **[Extensiones Markdown integradas:](./markdown)** Frontmatter, tablas, resaltado de sintaxis... tú decides. Específicamente, VitePress ofrece muchas funciones avanzadas para trabajar con bloques de código, tornándolo ideal para documentación altamente técnica.
- **[Markdown Mejorado con Vue:](./using-vue)** cada página Markdown es también un [Componente de Archivo único](https://vuejs.org/guide/scaling-up/sfc.html) de Vue, gracias a la compatibilidad del 100% de la sintaxis de las plantillas de Vue con HTML. Puedes incrustar interactividad en tu contenido estático usando las funciones de plantillas de Vue o componentes de Vue importados.
- **[Markdown mejorado con Vue:](./using-vue)** cada página Markdown también es un [Componente de Archivo Único](https://vuejs.org/guide/scaling-up/sfc.html) de Vue, gracias a la compatibilidad del 100% de la sintaxis de las plantillas de Vue con HTML. Puedes incrustar interactividad en tu contenido estático usando las funciones de plantillas de Vue o componentes de Vue importados.
## Desempeño {#performance}
## Rendimiento {#performance}
A diferencia de muchos SSG tradicionales donde cada navegación resulta en una recarga completa de la página, un sitio web generado por VitePress sirve HTML estático en la visita inicial, pero se convierte en una [Single Page Application](https://en.wikipedia.org/wiki/Single-page_application) (SPA) para las navegaciones posteriores dentro del sitio. Este modelo, en nuestra opinión, ofrece un equilibrio óptimo para el rendimiento:
- **Carga Inicial Rápida**
La visita inicial a cualquier página será servida con el HTML estático pre-renderizado para una velocidad de carga rápida y SEO óptimo. La página entonces carga un paquete JavaScript que transforma la página en una SPA de Vue (a este proceso se le llama "hidratación"). A diferencia de la creencia popular de que la hidratación de una SPA es lenta, este proceso es de hecho extremadamente rápido gracias al rendimiento nativo y a las optimizaciones del compilador de Vue 3. En [PageSpeed Insights](https://pagespeed.web.dev/report?url=https%3A%2F%2Fvitepress.dev%2F), los sitios típicos VitePress alcanzan puntuaciones de desempeño casi perfectas, incluso en dispositivos móbiles de gama baja con una red lenta.
La visita inicial a cualquier página será servida con el HTML estático pre-renderizado para una velocidad de carga rápida y SEO óptimo. La página entonces carga un paquete JavaScript que transforma la página en una SPA de Vue (a este proceso se le llama "hidratación"). A diferencia de la creencia popular de que la hidratación de una SPA es lenta, este proceso es de hecho extremadamente rápido gracias al rendimiento nativo y a las optimizaciones del compilador de Vue 3. En [PageSpeed Insights](https://pagespeed.web.dev/report?url=https%3A%2F%2Fvitepress.dev%2F), los sitios típicos VitePress alcanzan puntuaciones de desempeño casi perfectas, incluso en dispositivos móviles de gama baja con una red lenta.
- **Navegación Rápida pos-carga**
@ -52,8 +52,8 @@ A diferencia de muchos SSG tradicionales donde cada navegación resulta en una r
## ¿Y VuePress? {#what-about-vuepress}
VitePress es el sucesor espiritual de VuePress. El VuePress original se basó en Vue 2 y webpack. Con Vue 3 y Vite como base, VitePress ofrece una Experiencia de Desarrollador (DX) significativamente mejor, un mejor rendimiento en producción, un tema por defecto más pulido y una API de personalización más flexible.
VitePress es el sucesor espiritual de VuePress 1. El VuePress 1 original se basó en Vue 2 y webpack. Con Vue 3 y Vite como base, VitePress ofrece una Experiencia de Desarrollador (DX) significativamente mejor, un mejor rendimiento en producción, un tema por defecto más pulido y una API de personalización más flexible.
La diferencia entre la API de VitePress y VuePress radica principalmente en los temas y la personalización. Si estás usando VuePress 1 con el tema por defecto, debería ser relativamente sencillo migrar a VitePress.
La diferencia entre la API de VitePress y VuePress 1 radica en los temas y la personalización. Si estás usando VuePress 1 con el tema por defecto, debería ser relativamente sencillo migrar a VitePress.
También se ha invertido esfuerzo en VuePress 2, que también es compatible con Vue 3 y Vite, y tiene mayor compatibilidad con VuePress 1. Sin embargo, mantener dos SSG en paralelo no es sostenible, por lo que el equipo de Vue ha decidido centrarse en VitePress como el principal SSG recomendado a largo plazo.
Mantener dos generadores de sitios estáticos (SSG) en paralelo no es sostenible, por lo que el equipo de Vue ha decidido centrarse en VitePress como el principal SSG recomendado a largo plazo. Ahora VuePress 1 está obsoleto y VuePress 2 se ha entregado al equipo de la comunidad de VuePress para su desarrollo y mantenimiento.
description: Referencia de los comandos CLI de VitePress, incluyendo dev, build, preview e init.
---
# Intefaz de Linea de Comando {#command-line-interface}
# Interfaz de Línea de Comando {#command-line-interface}
## `vitepress dev`
Inicia el servidor de desarrollo VitePress con el directorio designado como raíz. Por defecto, utiliza el director actual. el comando `dev` también se puede omitir cuando se ejecuta el directorio actual.
### Uso
### Uso {#usage}
```sh
# Comienza en el directorio actual, omite el `dev`
@ -8,9 +8,9 @@ La configuración del tema te permite personalizar tu tema. puedes definir la co
```ts
export default {
lang: 'pt-BR',
lang: 'es-ES',
title: 'VitePress',
description: 'Generador de site estático Vite & Vue.',
description: 'Generador de sitios estáticos desarrollado con Vite y Vue.',
// Configuraciones relacionadas con el tema.
themeConfig: {
@ -21,19 +21,37 @@ export default {
}
```
**Las opciones documentadas de esta página se aplican unicamente al tema por defecto.** Diferentes temas esperan configuraciones diferentes de tema. Cuando se utiliza un tema personalizado, el objeto de configuración del tema se pasará al tema para que se puedan definir comportamientos condicionales.
**Las opciones documentadas en esta página se aplican unicamente al tema por defecto.** Diferentes temas esperan configuraciones distintas. Al usar un tema personalizado, el objeto de configuración del tema se le pasará al tema para que este pueda definir un comportamiento condicional basado en él.
Cambiar la configuración regional a `zh` modificará la URL de `/foo` (o `/en/foo/`) a `/zh/foo`. Puedes desactivar este comportamiento estableciendo `themeConfig.i18nRouting` en `false`.
Establezca `themeConfig.i18nRouting` en una función para personalizar el enlace de configuración regional. La función recibe los datos actuales de VitePress, la ruta actual y la clave de configuración regional de destino, y devuelve el enlace de destino.
Cambie la configuración a, por ejemplo, `zh` será alterado para URL `/foo` (ou `/en/foo/`) para `/zh/foo`. Puedes desactivar este comportamiento configurado `themeConfig.i18nRouting` como `false`.
Archivo de logotipo que se mostrará en la barra de navegación, justo antes del título del sitio. Acepta una ruta de cadena o un objeto para definir un logotipo diferente para los modos claro/oscuro.
Archivo de logotipo para mostrar en la barra de navegación, justo antes del título del sitio. Acepta una ruta de archivo (string) o un objeto para configurar un logotipo diferente para el modo claro/oscuro.
```ts
export default {
@ -54,7 +72,7 @@ type ThemeableImage =
- Tipo: `string | false`
Puedes personalizar este elemento para reemplazar el título del sitio predeterminado (`title` en configuración de la aplicación) en navegación. Cuando se establece como `false`, el título en la navegación quedará deshabilitado. Útil cuando tienes un `logo` que ya contiene el título del sitio.
Puedes personalizar este elemento para reemplazar el título del sitio predeterminado (`title` en la configuración de la aplicación) en la navegación. Cuando se establece como `false`, el título en la navegación quedará deshabilitado. Útil cuando tienes un `logo` que ya contiene el texto del título del sitio.
```ts
export default {
@ -74,9 +92,9 @@ La configuración del elemento del menú de navegación. Más detalles en [Tema
- Se puede superponer por página mediante [frontmatter](./frontmatter-config#footer)
- Se puede sobrescribir por página mediante [frontmatter](./frontmatter-config#footer)
Configuración de pie de página. Puede agregar un mensaje o texto de derechos de autor en el pie de página; sin embargo, solo se mostrará cuando la página no contenga una barra lateral. Esto se debe a preocupaciones de diseño.
Configuración de pie de página. Puede agregar un mensaje o texto de derechos de autor en el pie de página; sin embargo, solo se mostrará cuando la página no contenga una barra lateral. Esto se debe a consideraciones de diseño.
```ts
export default {
@ -271,7 +305,7 @@ export interface Footer {
## editLink
- Tipo: `EditLink`
- Se puede superponer por página mediante [frontmatter](./frontmatter-config#editlink)
- Se puede sobrescribir por página mediante [frontmatter](./frontmatter-config#editlink)
_EditLink_ le permite mostrar un enlace para editar la página en los servicios de administración Git, como GitHub o GitLab. Consulte [Tema por defecto: Editar Link](./default-theme-edit-link) para más detalles.
@ -303,7 +337,7 @@ Permite la personalización del formato de fecha y texto actualizado por ultima
export default {
themeConfig: {
lastUpdated: {
text: 'Actualizado en',
text: 'Actualizado el',
formatOptions: {
dateStyle: 'full',
timeStyle: 'medium'
@ -352,16 +386,14 @@ Una opción para mostrar [Carbon Ads](https://www.carbonads.net/).
export default {
themeConfig: {
carbonAds: {
code: 'su-código-carbon',
placement: 'su-colocación-carbon',
code: 'tu-código-carbon',
placement: 'tu-vinculación-carbon',
format: 'classic'
}
}
}
```
La opción `format` admite `classic`, `responsive` y `cover`.
```ts
export interface CarbonAdsOptions {
code: string
@ -382,8 +414,8 @@ Se puede utilizar para personalizar el texto que aparece encima de los enlaces a
export default {
themeConfig: {
docFooter: {
prev: 'Página anterior',
next: 'Próxima página'
prev: 'Anterior',
next: 'Siguiente'
}
}
}
@ -399,48 +431,97 @@ export interface DocFooter {
## darkModeSwitchLabel
- Tipo: `string`
- Estandar: `Appearance`
- Predeterminado: `Appearance`
Se puede utilizar para personalizar la etiqueta del botón del modo oscuro. Esta etiqueta solo se muestra en la vista móvil.
## lightModeSwitchTitle
- Tipo: `string`
- Estandar: `Switch to light theme`
- Predeterminado: `Switch to light theme`
Se puede utilizar para personalizar el título del botón borrar que aparece al pasar el mouse.
Se puede utilizar para personalizar el título del interruptor de modo de claro que aparece al pasar el cursor por encima.
## darkModeSwitchTitle
- Tipo: `string`
- Estandar: `Switch to dark theme`
- Predeterminado: `Switch to dark theme`
Se puede utilizar para personalizar el título del botón del modo oscuro que aparece al pasar el mouse.
Se puede utilizar para personalizar el título del interruptor del modo oscuro que aparece al pasar el cursor por encima.
## sidebarMenuLabel
- Tipo: `string`
- Estandar: `Menu`
- Predeterminado: `Menu`
Se puede utilizar para personalizar la etiqueta del menú de la barra lateral. Esta etiqueta solo se muestra en la vista móvil.
## returnToTopLabel
- Tipo: `string`
- Estandar: `Return to top`
- Predeterminado: `Return to top`
Se puede utilizar para personalizar la etiqueta del botón Volver al principio. Esta etiqueta solo se muestra en la vista móvil.
Se puede usar para personalizar la etiqueta del botón "Volver al inicio". Esta etiqueta solo se muestra en la vista móvil.
## langMenuLabel
- Tipo: `string`
- Estandar: `Change language`
- Predeterminado: `Change language`
Se puede utilizar para personalizar la etiqueta aria del botón de idioma en la barra de navegación. Esto sólo se usa si estás usando [i18n](../guide/i18n).
Se puede usar para personalizar la etiqueta aria del botón de cambio de idioma en la barra de navegación. Esto solo se usa si estás usando [i18n](../guide/i18n).
## skipToContentLabel
- Tipo: `string`
- Predeterminado: `Skip to content`
Se puede usar para personalizar la etiqueta del enlace "Saltar al contenido". Este enlace se muestra cuando el usuario navega por el sitio web mediante el teclado.
## externalLinkIcon
- Tipo: `boolean`
- Estandar: `false`
- Predeterminado: `false`
Indica si se debe mostrar un icono de enlace externo junto a los enlaces externos en Markdown.
## Contenedores graduados
Se debe mostrar um ícono de link externo junto a los enlaces externos en markdown.
- Tipo: `booleano`
- Predeterminado: `false`
Indica si se deben colorear los [contenedores personalizados](../guide/markdown#custom-containers), las [alertas al estilo de GitHub] (../guide/markdown#github-flavored-alerts) y las insignias según una escala de gravedad graduada: peligro rojo, advertencia naranja, precaución amarillo. Por defecto, los colores coinciden con las alertas de GitHub, donde la precaución comparte el rojo con peligro y la advertencia es amarilla.
Esto no debería generar efectos secundarios ni acceder a nada fuera de su alcance, ya que será serializado y ejecutado en el navegador.
De forma predeterminada, esto agregará el enlace con el texto 'Editar esta página' al final de la página de documentación. Puedes personalizar este texto configurando la opción `text`.
De forma predeterminada, esto agregará el enlace con el texto "Edit this page" al final de la página de documentación. Puedes personalizar este texto configurando la opción `text`.
La configuración anterior también admite cadenas HTML. Entonces, por ejemplo, si desea configurar el texto de su pie de página para que tenga algunos enlaces, puede ajustar la configuración de la siguiente manera:
La configuración anterior también admite cadenas HTML. Entonces, por ejemplo, si desea configurar el texto del pie de página para que contenga algunos enlaces, puede ajustar la configuración de la siguiente manera:
```ts
export default {
themeConfig: {
footer: {
message: 'Publicado bajo <ahref="https://github.com/vuejs/vitepress/blob/main/LICENSE">Licencia MIT</a>.',
Solo se utilizan elementos _inline_ será utilizado en `message` y `copyright` tal como se presenta dentro del elemento `<p>`. Si desea agregar elementos de tipo_block_, considere usar un _slot_ [`layout-bottom`](../guide/extending-default-theme#layout-slots).
Solo se pueden usar elementos _inline_ en `message` y `copyright`, ya que se renderizan dentro de un elemento `<p>`. Si desea agregar elementos_block_, considere usar un _slot_ [`layout-bottom`](../guide/extending-default-theme#layout-slots).
:::
Tenga en cuenta que el pie de página no se mostrará cuando la [Barra Lateral](./default-theme-sidebar) es visible.
text: Generador de sitios web estáticos con Vite & Vue.
text: Generador de sitios estáticos desarrollado con Vite y Vue.
tagline: Lorem ipsum...
image:
src: /logo.png
alt: VitePress
actions:
- theme: brand
text: Iniciar
text: Comenzar
link: /guide/what-is-vitepress
- theme: alt
text: Ver en GitHub
@ -52,10 +52,10 @@ interface Hero {
// Eslogan que se muestra abajo del `text`.
tagline?: string
// La imagen se muestra junto al área de texto y eslogan.
// La imagen se muestra junto al texto y el eslogan.
image?: ThemeableImage
// Botones accionables para mostrar en la sección principal de la página de inicio.
// Botones de acción que se mostrarán en la sección principal.
actions?: HeroAction[]
}
@ -74,17 +74,17 @@ interface HeroAction {
// Destino del enlace del botón.
link: string
// Atributo target del link.
// Atributo target del enlace.
target?: string
// Atributo rel del link.
// Atributo rel del enlace.
rel?: string
}
```
### Personalizando el color del nombre {#customizing-the-name-color}
VitePress usa el color de la marca (`--vp-c-brand-1`) para `name`. Sin embargo, puedes personalizar este color anulando la variable `--vp-home-hero-name-color`.
VitePress usa el color de la marca (`--vp-c-brand-1`) para `name`. Sin embargo, puedes personalizar este color sobrescribiendo la variable `--vp-home-hero-name-color`.
```css
:root {
@ -101,11 +101,11 @@ También puedes personalizarlo aún más combinando `--vp-home-hero-name-backgr
}
```
## Sección de caracteristicas {#features-section}
## Sección de características {#features-section}
En la sección de funciones, puede enumerar cualquier cantidad de funciones que desee mostrar inmediatamente después de la sección. _Hero_. Para configurarlo seleccione la opción `features` para el frontmatter.
En la sección de características, puede enumerar cualquier cantidad de características que desee mostrar inmediatamente después de la sección. _Hero_. Para configurarlo seleccione la opción `features` para el frontmatter.
Puede proporcionar un icono para cada función, que puede ser un emoji o cualquier tipo de imagen. Cuando el icono configurado es una imagen (svg, png, jpeg...), debes proporcionar al ícono el ancho y alto apropiados; También puedes proporcionar la descripción, su tamaño intrínseco y sus variantes para temas oscuros y claros cuando sea necesario.
Puedes asignar un icono a cada característica, que puede ser un emoji o cualquier tipo de imagen. Si el icono configurado es una imagen (svg, png, jpeg, etc.), debes especificar el ancho y la altura correctos; también puedes incluir la descripción, su tamaño intrínseco y sus variantes para temas claros y oscuros, si fuera necesario.
```yaml
---
@ -116,35 +116,35 @@ features:
title: Sencillo y minimalista, siempre
details: Lorem ipsum...
- icon:
src: /cool-feature-icon.svg
title: Otra caracteristica interesante
src: /icono-de-caracteristica-genial.svg
title: Otra característica interesante
details: Lorem ipsum...
- icon:
dark: /dark-feature-icon.svg
light: /light-feature-icon.svg
title: Otra caracteristica interesante
dark: /icono-de-caracteristica-oscuro.svg
light: /icono-de-caracteristica-claro.svg
title: Otra característica interesante
details: Lorem ipsum...
---
```
```ts
interface Feature {
// Muestra el icono en cada cuadro de función.
// Muestra el icono en cada cuadro de característica.
icon?: FeatureIcon
// Título de la caracteristica.
// Título de la característica.
title: string
// Detalles de la caracteristicas.
// Detalles de la características.
details: string
// Enlace al hacer clic en el componente de funcionalidad
// El vínculo puede ser interno o externo.
// Enlace que aparece al hacer clic en el componente de la característica.
// ej. `guide/reference/default-theme-home-page` o `https://example.com`
link?: string
// Texto del enlace que se mostrará dentro del componente de funcionalidad.
// Texto del enlace que se mostrará dentro del componente de característica.
// Mejor usado con opción `link`.
//
// ej. `Sepa más`, `Visitar página`, etc.
@ -170,3 +170,30 @@ type FeatureIcon =
height: string
}
```
## Contenido Markdown {#markdown-content}
Puedes agregar contenido adicional a la página de inicio de tu sitio simplemente agregando Markdown debajo del divisor del frontmatter `---`.
````md
---
layout: home
hero:
name: VitePress
text: Generador de sitios estáticos desarrollado con Vite y Vue.
---
# Comenzar
¡Puedes empezar a usar VitePress inmediatamente usando `npx`!
```sh
npm init
npx vitepress init
```
````
::: info
VitePress no siempre aplicaba estilos automáticamente al contenido adicional de la página `layout: home`. Para volver al comportamiento anterior, puedes agregar `markdownStyles: false` al encabezado.
@ -4,10 +4,29 @@ description: Muestra la marca de tiempo de la última actualización en las pág
# Última Actualización {#last-updated}
La hora en que se actualizó el contenido por última vez se mostrará en la esquina inferior derecha de la página. Para habilitar, agregue la opción `lastUpdated`en su confirguración.
La hora de la última actualización del contenido se mostrará en la esquina inferior derecha de la página. Para habilitar, agregue la opción `lastUpdated`a su archivo de configuración.
::: tip
Necesitas hacer un _commit_ en el archivo markdown para ver el clima actualizado.
::: info
VitePress muestra la hora de la última actualización utilizando la marca de tiempo del commit de Git más reciente para cada archivo. Para habilitar esta función, el archivo Markdown debe estar suscrito a Git.
Internamente, VitePress ejecuta `git log -1 --pretty="%ai"` en cada archivo para obtener su marca de tiempo. Si todas las páginas muestran la misma hora de actualización, probablemente se deba a una clonación superficial (común en entornos de CI), lo que limita el historial de Git.
Para solucionar esto en **GitHub Actions**, utilice lo siguiente en su flujo de trabajo:
```yaml{4}
- name: Checkout
uses: actions/checkout@v5
with:
fetch-depth: 0
```
Otras plataformas de CI/CD tienen configuraciones similares.
Si dichas opciones no están disponibles, puede ejecutar un fetch manual antes, configurándolo en el comando `docs:build` de su `package.json` de la siguiente forma:
## Configuración a nivel de sitio {#site-level-config}
@ -28,4 +47,4 @@ lastUpdated: false
---
```
Consulte [Tema Personalizado: Última Actualización](./default-theme-config#lastupdated) para obtener más. Cualquier valor positivo a nivel de tema también habilitará la funcionalidad a menos que esté explícitamente deshabilitado a nivel de página o sitio.
Consulte también [Tema predeterminado: Última actualización](./default-theme-config#lastupdated) para obtener más detalles. Cualquier valor verdadero a nivel de tema también habilitará la función, a menos que se deshabilite explícitamente a nivel de sitio o página.
description: Elige entre los layouts doc, page y home en el tema predeterminado de VitePress.
---
# Layout {#layout}
# Layout
Puedes elegir el layout de la página definiendo una opción de `layout` para el [frontmatter](./frontmatter-config) De la página. Hay tres opciones de layout: `doc`, `page` y `home`. Si no se especifica nada, la página será tratada como una página. `doc`.
@ -20,8 +20,8 @@ Casi todos los elementos genéricos como `p` o `h2`, recibirá un estilo especia
También proporciona recursos de documentación específicos que se enumeran a continuación. Estas funciones solo están habilitadas en este layout.
- Editar link
- Links Anterior y próximo.
- Editar enlace
- Enlace Anterior y Siguiente.
- _Outline_
- [Carbon Ads](./default-theme-carbon-ads)
@ -35,11 +35,11 @@ Tenga en cuenta que incluso en este mismo layout, la barra lateral seguirá apar
## Layout de Home {#home-layout}
La opción `home` gerará un modelo de _"Homepage"_. En este layout podrás definir opciones extras, como `hero` y `features`, para personalizar todavá más el contenido. Visite [Tema predeterminado: Página Inicial](./default-theme-home-page) para obter más detalles.
La opción `home` generará un modelo de _"Homepage"_. En este layout podrás definir opciones extras, como `hero` y `features`, para personalizar todavía más el contenido. Visite [Tema predeterminado: Página Inicial](./default-theme-home-page) para obtener más detalles.
## Sin Layout {#no-layout}
Si no quieres ningún diseño, puedes pasar `layout: false` a través del frontmatter. Esta opción es útil si deseas una página de destino completamente personalizable (sin barra lateral, barra de navegacón o pie de página por defecto).
Si no quieres ningún diseño, puedes pasar `layout: false` a través del frontmatter. Esta opción es útil si deseas una página de destino completamente personalizable (sin barra lateral, barra de navegación o pie de página por defecto).
@ -4,7 +4,7 @@ description: Configura la barra de navegación en el tema predeterminado de Vite
# Navegación {#nav}
Refiriéndose a la barra de navegación que se muestra en la parte superior de la página. Contiene el título del sitio, enlaces del menú global, etc.
La barra de navegación (Nav) se muestra en la parte superior de la página. Contiene el título del sitio, enlaces del menú global, etc.
## Título y logotipo del sitio {#site-title-and-logo}
@ -33,7 +33,7 @@ Cuando agrega un logotipo, se muestra junto con el título del sitio. Si su logo
```js
export default {
themeConfig: {
logo: '/my-logo.svg',
logo: '/mi-logo.svg',
siteTitle: false
}
}
@ -41,7 +41,7 @@ export default {
También puedes pasar un objeto como logotipo si quieres agregar un atributo. `alt` o personalizarlo según el modo claro/oscuro. Consultar [`themeConfig.logo`](./default-theme-config#logo) para obtener más detalles.
## Links de Navegación {#navigation-links}
## Enlace de Navegación {#navigation-links}
Puedes configurar la opción `themeConfig.nav` para añadir enlaces a tu navegación.
@ -49,7 +49,7 @@ Puedes configurar la opción `themeConfig.nav` para añadir enlaces a tu navegac
export default {
themeConfig: {
nav: [
{ text: 'Guia', link: '/guide' },
{ text: 'Guía', link: '/guide' },
{ text: 'Configuración', link: '/config' },
{ text: 'Registro de Cambios', link: 'https://github.com/...' }
]
@ -57,17 +57,17 @@ export default {
}
```
`text` es el texto que se muestra en la navegación, y el `link` es el link al que será navegando cuando se hace click en el texto. Para el enlace, establezca la ruta al archivo sin el prefijo `.md` y siempre comenzar por `/`.
`text` es el texto que se muestra en la navegación, y el `link` es el enlace al que será navegando cuando se hace click en el texto. Para el enlace, establezca la ruta al archivo sin el prefijo `.md` y siempre comenzar por `/`.
El `link` también puede ser una función que acepte [`PageData`](./runtime-api#usedata) como argumento y devuelva la ruta.
Links de navegación también pueden ser menus _dropdown_. Para hacer eso, establezca la clave de `items` en la opción del link.
Los Enlaces de navegación también pueden ser menus _dropdown_. Para hacer eso, establezca la clave de `items` en la opción del enlace.
```js
export default {
themeConfig: {
nav: [
{ text: 'Guia', link: '/guide' },
{ text: 'Guía', link: '/guide' },
{
text: 'Menú Dropdown',
items: [
@ -89,12 +89,12 @@ También puedes agregar "secciones" a los elementos del menú _dropdown_ pasando
export default {
themeConfig: {
nav: [
{ text: 'Guia', link: '/guia' },
{ text: 'Guía', link: '/guia' },
{
text: 'Menú Dropdown',
text: 'Dropdown Menu',
items: [
{
// Título da seção.
// Título de la sección.
text: 'Título de la sección A',
items: [
{ text: 'Item A de la sección A', link: '...' },
@ -109,8 +109,8 @@ export default {
{
// También puedes omitir el título
items: [
{ text: 'Item A da Seção A', link: '...' },
{ text: 'Item B da Seção B', link: '...' }
{ text: 'Item A de la sección A', link: '...' },
{ text: 'Item B de la sección B', link: '...' }
]
}
]
@ -120,19 +120,19 @@ export default {
}
```
### Personaliza el estado "activo" del link {#customize-link-s-active-state}
### Personaliza el estado "activo" del enlace {#customize-link-s-active-state}
Los elementos del menú de navegación se resaltarán cuando la página actual esté en la ruta correspondiente. Si desea personalizar la ruta que debe coincidir, establezca la propiedad `activeMatch` el regex como um valor en string.
Los elementos del menú de navegación se resaltarán cuando la página actual esté en la ruta correspondiente. Si desea personalizar la ruta que debe coincidir, establezca la propiedad `activeMatch` el regex como un valor en string.
```js
export default {
themeConfig: {
nav: [
// Este link esta en estado activo cuando
// el usuario esta en el camino`/config/`.
// Este enlace se activa cuando el usuario está
// en la ruta`/config/`.
{
text: 'Guia',
link: '/guide',
text: 'Guía',
link: '/guia',
activeMatch: '/config/'
}
]
@ -141,10 +141,10 @@ export default {
```
::: warning
`activeMatch` Debería ser un string regex, pero deberías definirla como un string. No podemos usar un objeto RegExp real aquí porque no es serializable durante el tiempo de construcción.
`activeMatch` Debería ser un string regex, pero deberías definirla como un string. No podemos usar un objeto RegExp real aquí porque no es serializable durante el tiempo de compilación.
:::
### Personalizar los atributos "target" y "rel" de links {#customize-link-s-target-and-rel-attributes}
### Personaliza los atributos "target" y "rel" del enlace. {#customize-link-s-target-and-rel-attributes}
Por defecto, VitePress determina automáticamente lod atributos `target` y `rel` en función de si existe un enlace externo o no. Pero si quieres, también puedes personalizarlos.
Puedes incluir componentes personalizados en la barra de navegación usando la opción `component`. La clave `component` debe ser el nombre del componente Vue y debe registrarse globalmente usando [Theme.enhanceApp](../guide/custom-theme#theme-interface).
```js [.vitepress/config.js]
export default {
themeConfig: {
nav: [
{
text: 'Mi Menu',
items: [
{
component: 'MiComponentePersonalizado',
// Optional props to pass to the component
props: {
title: 'Mi Componente Personalizado'
}
}
]
},
{
component: 'OtroComponentePersonalizado'
}
]
}
}
```
Luego, debes registrar el componente globalmente:
```js [.vitepress/theme/index.js]
import DefaultTheme from 'vitepress/theme'
import MiComponentePersonalizado from './components/MiComponentePersonalizado.vue'
import OtroComponentePersonalizado from './components/OtroComponentePersonalizado.vue'
description: Personaliza los enlaces de página anterior y siguiente que se muestran en la parte inferior de las páginas de documentación en VitePress.
---
# Links Anterior y Próximo {#prev-next-links}
# Enlaces Anterior y Siguiente {#prev-next-links}
Puede personalizar el texto y el enlace de los botones Anterior y Siguiente que se muestran en la parte inferior de la página. Esto es útil cuando desea mostrar un texto diferente al que tiene en la barra lateral. Además, puede resultarle útil desactivar el pie de página o el enlace a la página para que no se incluya en la barra lateral.
Puede personalizar el texto y el enlace para las páginas anterior y siguiente (mostrados en el pie de página de la documentación). Esto es útil si desea tener allí un texto diferente al que tiene en su barra lateral. Además, puede resultarle útil desactivar el pie de página o el enlace a una página que no esté incluida en su barra lateral.
## prev
@ -12,29 +12,29 @@ Puede personalizar el texto y el enlace de los botones Anterior y Siguiente que
- Detalles:
Especifica el text/enlace que se mostrará en el enlace a la página anterior. Si no ve esto al principio, el text/enlace se deducirá de la configuración de la barra lateral.
Especifica el texto/enlace a mostrar en el enlace a la página anterior. Si no configura esto en el `frontmatter`, el texto/enlace se inferirá de la configuración de la barra lateral.
- Ejemplos:
- Para personalizar solo texto:
- Para personalizar solo el texto:
```yaml
---
prev: 'Iniciar | Markdown'
prev: 'Comenzar | Markdown'
---
```
- Para personalizar ambos texto y link:
- Para personalizar ambos texto y enlace:
```yaml
---
prev:
text: 'Markdown'
link: '/guide/markdown'
link: '/guia/markdown'
---
```
- Para esconder la página anterior:
- Para ocultar la página anterior:
```yaml
---
@ -44,4 +44,4 @@ Puede personalizar el texto y el enlace de los botones Anterior y Siguiente que
## next
Igual que el `prev` pero para la página siguiente.
description: Configura la búsqueda local o con Algolia para tu sitio VitePress.
outline: deep
description: Configura la búsqueda local o impulsada por Algolia para tu sitio VitePress.
---
# Buscar {#search}
# Búsqueda {#search}
## Busqueda local {#local-search}
## Búsqueda Local {#local-search}
VitePress admite la búsqueda de texto completo utilizando un índice en el navegador gracias a [minisearch](https://github.com/lucaong/minisearch/). Para habilitar esta función, simplemente configure la opción `themeConfig.search.provider` como `'local'` en el archivo `.vitepress/config.ts`:
VitePress admite la búsqueda de texto completo difusa utilizando un índice en el navegador gracias a [minisearch](https://github.com/lucaong/minisearch/). Para habilitar esta característica, simplemente configure la opción `themeConfig.search.provider` como `'local'` en su archivo `.vitepress/config.ts`:
```ts
import { defineConfig } from 'vitepress'
@ -23,13 +23,18 @@ export default defineConfig({
Resultado de ejemplo:
Alternativamente, puedes usar [Algolia DocSearch](#algolia-search) o algunos complementos comunitarios como <https://www.npmjs.com/package/vitepress-plugin-search> o <https://www.npmjs.com/package/vitepress-plugin-pagefind>.
Alternativamente, puede usar [Algolia DocSearch](#algolia-search) o algunos complementos de la comunidad como:
Esta función se eliminará de los datos del sitio web en el lado del cliente, por lo que podrá utilizar las API de Node.js en ella.
Esta función se eliminará de los datos del sitio en el lado del cliente, por lo que puede utilizar las API de Node.js en ella.
#### Ejemplo: Excluir páginas de la busqueda {#example-excluding-pages-from-search}
#### Ejemplo: Excluir páginas de la búsqueda {#example-excluding-pages-from-search}
Puedes excluir páginas de la busqueda adicionando `search: false` al principio de la página. Alternativamente:
Puede excluir páginas de la búsqueda añadiendo `search: false` en el `frontmatter` de la página. Alternativamente:
```ts
import { defineConfig } from 'vitepress'
@ -149,7 +154,7 @@ export default defineConfig({
async _render(src, env, md) {
const html = await md.renderAsync(src, env)
if (env.frontmatter?.search === false) return ''
if (env.relativePath.startsWith('some/path')) return ''
if (env.relativePath.startsWith('alguna/ruta')) return ''
return html
}
}
@ -159,7 +164,7 @@ export default defineConfig({
```
::: warning Nota
En este caso, una función `_render` se proporciona, es necesario manipular el `search: false` desde el frente por su cuenta. Además, el objeto `env` no estará completamente poblado antes que `md.renderAsync` se llama, luego verifica las propiedades opcionales `env`, como `frontmatter`, debe hacerse después de eso.
En caso de que se proporcione una función `_render` personalizada, deberá gestionar el `frontmatter``search: false` por su cuenta. Además, el objeto `env` no estará completamente poblado antes de que se llame a `md.renderAsync`, por lo que cualquier comprobación de las propiedades opcionales de `env`, como `frontmatter`, debe realizarse después de eso.
VitePress admite la búsqueda en su sitio de documentación utilizando [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Consulte su guía de introducción. en tu archivo `.vitepress/config.ts`, Deberá proporcionar al menos lo siguiente para que funcione:
VitePress admite la búsqueda en su sitio de documentación utilizando [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Consulte su guía para comenzar. En su archivo `.vitepress/config.ts`, deberá proporcionar al menos lo siguiente para que funcione:
Puedes utilizar una configuración como esta para utilizar la búsqueda multilingüe:
Puede usar una configuración como esta para utilizar la búsqueda multilingüe:
<details>
<summary>Haz clic para expandir</summary>
<summary>Ver ejemplo completo</summary>
<<<@/snippets/algolia-i18n.ts
</details>
Consulta la [documentación oficial de Algolia](https://docsearch.algolia.com/docs/api#translations) para conocer más detalles. Para empezar rápidamente, también puedes copiar las traducciones usadas por este sitio desde [nuestro repositorio de GitHub](https://github.com/search?q=repo:vuejs/vitepress+%22function+searchOptions%22&type=code).
Consulte la [documentación oficial de Algolia](https://docsearch.algolia.com/docs/api#translations) para obtener más información al respecto. Para comenzar rápidamente, también puede copiar las traducciones utilizadas por este sitio desde [nuestro repositorio de GitHub](https://github.com/search?q=repo:vuejs/vitepress+%22function+searchOptions%22&type=code).
### Algolia Ask AI Support {#ask-ai}
### Soporte de Ask AI de Algolia {#ask-ai}
Si deseas incluir **Ask AI**, pasa la opción `askAi` (o alguno de sus campos parciales) dentro de `options`:
Si desea incluir **Ask AI**, pase la opción `askAi` (o cualquiera de los campos parciales) dentro de `options`:
Si prefieres solo la búsqueda por palabra clave y no la Ask AI, simplemente omite`askAi`.
Si desea utilizar la búsqueda por palabras clave de forma predeterminada y no desea utilizar Ask AI, omita la propiedad`askAi`.
:::
### Panel lateral de Ask AI {#ask-ai-side-panel}
DocSearch v4.5+ admite un **panel lateral de Ask AI** opcional. Cuando está habilitado, se puede abrir con **Ctrl/Cmd+I**por defecto. La [Referencia de API del Panel Lateral](https://docsearch.algolia.com/docs/sidepanel/api-reference) contiene la lista completa de opciones.
DocSearch v4.5+ admite un **panel lateral de Ask AI** opcional. Cuando está habilitado, se puede abrir con **Ctrl/Cmd+I**de forma predeterminada. La [Referencia de la API del Panel Lateral](https://docsearch.algolia.com/docs/sidepanel/api-reference) contiene la lista completa de opciones.
```ts
import { defineConfig } from 'vitepress'
@ -271,7 +276,6 @@ export default defineConfig({
askAi: {
assistantId: 'XXXYYY',
sidePanel: {
// Refleja la API de @docsearch/sidepanel-js SidepanelProps
panel: {
variant: 'floating', // o 'inline'
side: 'right',
@ -287,7 +291,9 @@ export default defineConfig({
})
```
Si necesitas deshabilitar el atajo de teclado, usa la opción `keyboardShortcuts` del panel lateral:
Utilice `askAi.sidePanel.panel.suggestedQuestions` para las preguntas sugeridas del panel lateral. Los ejemplos independientes de Ask AI de Algolia también mencionan `askAi.suggestedQuestions`, pero esa opción de nivel superior no es suficiente para el modo de panel lateral de VitePress y no hace que el modal integrado de búsqueda por palabras clave muestre las preguntas sugeridas al abrirse por primera vez.
Si necesita deshabilitar el atajo de teclado, use la opción `keyboardShortcuts` en el nivel raíz del panel lateral:
#### Modo (auto / sidePanel / hybrid / modal) {#ask-ai-mode}
Puedes controlar opcionalmente cómo VitePress integra la búsqueda por palabra clave y Ask AI:
Opcionalmente puede controlar cómo VitePress integra la búsqueda por palabras clave y Ask AI:
- `mode: 'auto'` (por defecto): infiere `hybrid` cuando la búsqueda por palabra clave está configurada, de lo contrario `sidePanel` cuando el panel lateral de Ask AI está configurado.
- `mode: 'sidePanel'`: fuerza solo el panel lateral (oculta el botón de búsqueda por palabra clave).
- `mode: 'hybrid'`: habilita el modal de búsqueda por palabra clave + panel lateral de Ask AI (requiere configuración de búsqueda por palabra clave).
- `mode: 'modal'`: mantiene Ask AI dentro del modal de DocSearch (incluso si configuraste el panel lateral).
- `mode: 'auto'` (predeterminado): infiere `hybrid` cuando la búsqueda por palabras clave está configurada, de lo contrario `sidePanel` cuando el panel lateral de Ask AI está configurado.
- `mode: 'sidePanel'`: fuerza solo el panel lateral (oculta el botón de búsqueda por palabras clave).
- `mode: 'hybrid'`: habilita el modal de búsqueda por palabras clave + panel lateral de Ask AI (requiere configuración de búsqueda por palabras clave).
- `mode: 'modal'`: mantiene Ask AI dentro del modal de DocSearch (incluso si configuró el panel lateral).
#### Solo Ask AI (sin búsqueda por palabra clave) {#ask-ai-only}
#### Solo Ask AI (sin búsqueda por palabras clave) {#ask-ai-only}
Si quieres usar **solo el panel lateral de Ask AI**, puedes omitir la configuración de búsqueda por palabra clave de nivel superior y proporcionar las credenciales bajo `askAi`:
Si desea usar **solo el panel lateral de Ask AI**, puede omitir la configuración de búsqueda por palabras clave de nivel superior y proporcionar las credenciales bajo `askAi`:
```ts
import { defineConfig } from 'vitepress'
@ -349,8 +355,8 @@ export default defineConfig({
})
```
### Configuración _Crawler_ {#crawler-config}
### Configuración de _Crawler_ {#crawler-config}
A continuación se muestra un ejemplo de la configuración que utiliza este sitio:
A continuación se muestra un ejemplo de configuración basado en lo que usa este sitio:
description: Configura la navegación de la barra lateral en el tema predeterminado de VitePress con grupos, secciones colapsables y múltiples barras laterales.
description: Configura la navegación de la barra lateral en el tema predeterminado de VitePress con grupos, secciones plegables y múltiples barras laterales.
---
# Barra Lateral {#sidebar}
@ -11,10 +11,10 @@ export default {
themeConfig: {
sidebar: [
{
text: 'Guia',
text: 'Guía',
items: [
{ text: 'Introducción', link: '/introduction' },
{ text: 'Iniciando', link: '/getting-started' },
{ text: 'Introducción', link: '/introduccion' },
{ text: 'Comenzar', link: '/comenzar' },
...
]
}
@ -25,7 +25,7 @@ export default {
## Conceptos básicos {#the-basics}
La forma más sencilla del menú de la barra lateral es pasar una único _array_ de links. El elemento de primer nivel define la "sección" de la barra latera. debe contener `text`, cuál es el título de la sección, y `items` que son los propios enlaces de navegación.
La forma más sencilla del menú de la barra lateral es pasar un único _array_ de enlaces. El elemento de primer nivel define la "sección" para la barra lateral. Debe contener `text`, que es el título de la sección, e `items`, que son los enlaces de navegación reales.
```js
export default {
@ -52,18 +52,17 @@ export default {
}
```
Cada `link` debe especificar la ruta al archivo en sí comenzando con `/`.
Si agrega una barra al final del enlace, mostrará el `index.md` del directorio correspondiente.
Cada `link` debe especificar la ruta al archivo real comenzando con `/`. Si agrega una barra al final del enlace, se mostrará el `index.md` del directorio correspondiente.
```js
export default {
themeConfig: {
sidebar: [
{
text: 'Guia',
text: 'Guía',
items: [
// Esto muestra la página `/guide/index.md`.
{ text: 'Introducción', link: '/guide/' }
// Esto muestra la página `/guia/index.md`.
{ text: 'Introducción', link: '/guia/' }
]
}
]
@ -71,7 +70,7 @@ export default {
}
```
Puede anidar aún más elementos de la barra lateral hasta 6 niveles de profundidad contando desde el nivel raíz. Tenga en cuenta que los niveles superiores a 6 se ignorarán y no se mostrarán en la barra lateral.
Puede anidar aún más los _items_ (elementos) de la barra lateral hasta 6 niveles de profundidad contando desde el nivel raíz. Tenga en cuenta que los niveles de elementos anidados superiores a 6 se ignorarán y no se mostrarán en la barra lateral.
Puedes mostrar una barra lateral diferente según la ruta de la página. Por ejemplo, como se muestra en este sitio, es posible que desee crear secciones separadas de contenido en su documentación, como la página "Guía" y la página "Configuración".
Puede mostrar una barra lateral diferente dependiendo de la ruta de la página. Por ejemplo, como se muestra en este sitio, es posible que desee crear secciones de contenido separadas en su documentación, como la página "Guía" y la página "Configuración".
Para hacer esto, primero organice sus páginas en directorios para cada sección deseada:
Para hacerlo, primero organice sus páginas en directorios para cada sección deseada:
```
.
├─ guide/
├─ guia/
│ ├─ index.md
│ ├─ one.md
│ └─ two.md
└─ config/
│ ├─ uno.md
│ └─ dos.md
└─ configuracion/
├─ index.md
├─ three.md
└─ four.md
├─ tres.md
└─ cuatro.md
```
Luego actualice su configuración para definir su barra lateral para cada sección. Esta vez debes pasar un objeto en lugar de un array.
Luego, actualice su configuración para definir su barra lateral para cada sección. Esta vez, debe pasar un objeto en lugar de un `array`.
```js
export default {
themeConfig: {
sidebar: {
// Esta barra lateral se muestra cuando un usuario
// está en el directorio `guide`.
'/guide/': [
// está en el directorio `guia`.
'/guia/': [
{
text: 'Guia',
text: 'Guía',
items: [
{ text: 'Índice', link: '/guide/' },
{ text: 'Um', link: '/guide/one' },
{ text: 'Dois', link: '/guide/two' }
{ text: 'Índice', link: '/guia/' },
{ text: 'Uno', link: '/guia/uno' },
{ text: 'Dos', link: '/guia/dos' }
]
}
],
// Esta barra lateral se muestra cuando un usuario
// está en el directorio `config`.
'/config/': [
// está en el directorio `configuracion`.
'/configuracion/': [
{
text: 'Configuración',
items: [
{ text: 'Índice', link: '/config/' },
{ text: 'Tres', link: '/config/three' },
{ text: 'Cuatro', link: '/config/four' }
{ text: 'Índice', link: '/configuracion/' },
{ text: 'Tres', link: '/configuracion/tres' },
{ text: 'Cuatro', link: '/configuracion/cuatro' }
]
}
]
@ -152,9 +151,9 @@ export default {
}
```
## Grupos Retráctiles en la Barra Lateral {#collapsible-sidebar-groups}
## Grupos de barra lateral plegables {#collapsible-sidebar-groups}
Adicionando una opción `collapsed` al grupo de la barra lateral, muestra un botón para ocultar/mostrar cada sección
Al agregar la opción `collapsed` al grupo de la barra lateral, se muestra un botón de alternancia para ocultar/mostrar cada sección.
```js
export default {
@ -170,7 +169,7 @@ export default {
}
```
Todas las secciones están 'abiertas' de forma predeterminada. Si desea que estén 'cerrados' al cargar la página inicial, configure la opción `collapsed` como`true`.
Todas las secciones están "abiertas" de forma predeterminada. Si desea que estén "cerradas" en la carga inicial de la página, configure la opción `collapsed` en`true`.
```js
export default {
@ -185,3 +184,63 @@ export default {
}
}
```
## Prefijo de Ruta {#path-prefix}
Cuando la estructura de su documentación tiene directorios profundos o grupos ubicados bajo el mismo subdirectorio, puede usar la opción `base` para anteponer automáticamente un prefijo de ruta a todos los `items` anidados dentro de ese grupo. Esto evita repetir el mismo prefijo de ruta para cada `link`.
La opción `base` es compatible tanto en configuraciones de múltiples barras laterales como en grupos de barras laterales anidados.
### En Múltiples Barras Laterales {#in-multiple-sidebars}
Puede definir `base` en la raíz de la configuración de una sección de la barra lateral:
```js {5}
export default {
themeConfig: {
sidebar: {
'/guia/': {
base: '/guia/',
items: [
// Este enlace se resuelve como `/guia/introduccion`
{ text: 'Introducción', link: 'introduccion' },
// Este enlace se resuelve como `/guia/comenzar`
{ text: 'Comenzar', link: 'comenzar' }
]
}
}
}
}
```
### En Grupos Anidados {#in-nested-groups}
También puede usar `base` dentro de grupos de barras laterales anidados. Se aplicará a los hijos inmediatos de ese grupo:
```js{6,13}
export default {
themeConfig: {
sidebar: [
{
text: 'Referencia',
base: '/referencia/',
items: [
// Este enlace se resuelve como `/referencia/configuracion-del-sitio`
{ text: 'Configuración del sitio', link: 'configuracion-del-sitio' },
{
text: 'Tema predeterminado',
// La base anidada sobrescribe el prefijo de ruta principal
base: '/referencia/tema-predeterminado-',
items: [
// Este enlace se resuelve como `/referencia/tema-predeterminado-nav`
{ text: 'Nav', link: 'nav' },
// Este enlace se resuelve como `/referencia/tema-predeterminado-sidebar`
Si deseas presentar a tu equipo, puedes utilizar componentes del equipo para crear la página del equipo. Hay dos formas de utilizar estos componentes. Una es incrustarlo en la página del documento y otra es crear una página de equipo completa.
Si desea presentar a su equipo, puede utilizar los componentes de equipo para crear la página de equipo. Hay dos formas de utilizar estos componentes. Una es incrustarlo en una página de documento, y otra es crear una página de equipo completa.
## Mostrar miembros del equipo en una página {#show-team-members-in-a-page}
Puedes usar el componente `<VPTeamMembers>` expuesto en`vitepress/theme` para mostrar una lista de los miembros del equipo en cualquier página.
Puede usar el componente `<VPTeamMembers>` expuesto desde`vitepress/theme` para mostrar una lista de los miembros del equipo en cualquier página.
```html
<scriptsetup>
@ -55,26 +55,26 @@ const members = [
# Nuestro equipo
Saluda a nuestro increible equipo.
Salude a nuestro increíble equipo.
<VPTeamMemberssize="small":members/>
```
El código anterior mostrará a un miembro del equipo en un elemento similar a una tarjeta. Debería mostrar algo similar a lo siguiente.
El código anterior mostrará a un miembro del equipo en un elemento con apariencia de tarjeta. Debería mostrar algo similar a lo siguiente.
<VPTeamMemberssize="small":members/>
El componente `<VPTeamMembers>` viene en dos tamaños diferentes, pequeño `small` y médio `medium`. Si bien es una cuestión de preferencia, generalmente el tamaño `small` debería encajar mejor cuando se use en la página del documento. Además, puede agregar más propiedades a cada miembro, como agregar el botón "descripción" o "patrocinador". Obtenga más información sobre en [`<VPTeamMembers>`](#vpteammembers).
El componente `<VPTeamMembers>` viene en dos tamaños diferentes, `small` y `medium`. Si bien depende de su preferencia, generalmente el tamaño `small` debería encajar mejor cuando se usa en una página de documento. Además, puede agregar más propiedades a cada miembro, como agregar un botón de "descripción" o "patrocinador". Obtenga más información al respecto en [`<VPTeamMembers>`](#vpteammembers).
Incrustar miembros del equipo en la página del documento es bueno para equipos pequeños donde tener una página de equipo dedicada completa puede ser demasiado, o introducir miembros parciales como referencia al contexto de la documentación.
Incrustar miembros del equipo en la página de documento es bueno para equipos pequeños donde tener una página de equipo dedicada completa puede ser demasiado, o para presentar miembros parciales como referencia al contexto de la documentación.
Si tienes una gran cantidad de miembros o simplemente deseas más espacio para exhibir a los miembros del equipo, considere [crear una página de equipo completa.](#create-a-full-team-page)
Si tiene una gran cantidad de miembros, o simplemente desea tener más espacio para mostrar a los miembros del equipo, considere [crear una página de equipo completa](#create-a-full-team-page).
## Creando una página de equipo completa {#create-a-full-team-page}
## Crear una página de equipo completa {#create-a-full-team-page}
En lugar de agregar miembros del equipo a la página del documento, también puede crear una página de equipo completa, del mismo modo que puede crear una [Página Inicial](./default-theme-home-page) personalizada.
En lugar de agregar miembros del equipo a la página de documento, también puede crear una página de equipo completa, de manera similar a cómo puede crear una [Página de Inicio](./default-theme-home-page) personalizada.
Para crear una página de equipo, primero cree un nuevo md. El nombre del archivo no importa, pero aquí lo llamaremos `team.md`. En este archivo, configure la opción `layout: page` desde frontmatter, y luego puedes componer la estructura de tu página usando componentes `TeamPage`.
Para crear una página de equipo, primero, cree un nuevo archivo md. El nombre del archivo no importa, pero aquí lo llamaremos `team.md`. En este archivo, configure la opción del `frontmatter``layout: page`, y luego podrá componer la estructura de su página usando los componentes `TeamPage`.
```html
---
@ -108,24 +108,24 @@ const members = [
</template>
<template#lead>
El desarrollo de VitePress está guiado por un equipo internacional,
Algunos de los miembros han elegido aparecer a continuación.
algunos de los cuales han elegido aparecer a continuación.
</template>
</VPTeamPageTitle>
<VPTeamMembers:members/>
</VPTeamPage>
```
Al crear una página de equipo completa, recuerde agrupar todos los componentes con el componente `<VPTeamPage>`. Este componente garantizará que todos los componentes anidados relacionados con el equipo obtengan la estructura de diseño adecuada, como los espacios.
Al crear una página de equipo completa, recuerde agrupar todos los componentes con el componente `<VPTeamPage>`. Este componente garantizará que todos los componentes anidados relacionados con el equipo obtengan la estructura de `layout` adecuada, como los espaciados.
El componente `<VPPageTitle>` adiciona la sección de título de la página. El título es `<h1>`. Use los _slots_`#title` y `#lead` para poder documentar sobre su equipo.
El componente `<VPPageTitle>` agrega la sección del título de la página. El título es un encabezado `<h1>`. Use los `slots``#title` y `#lead` para documentar sobre su equipo.
`<VPMembers>` funciona igual que cuando se usa en una página de documento. Mostrará la lista de miembros.
`<VPMembers>` funciona igual que cuando se usa en una página de documento. Mostrará una lista de miembros.
### Agregar secciones para dividir a los miembros del equipo {#add-sections-to-divide-team-members}
Puede agregar "secciones" a la página de su equipo. Por ejemplo, puede tener diferentes tipos de miembros del equipo, como miembros del equipo central y socios de la comunidad. Puede dividir a estos miembros en secciones para explicar mejor las funciones de cada grupo.
Puede agregar "secciones" a la página de equipo. Por ejemplo, puede tener diferentes tipos de miembros en el equipo, como miembros del equipo central y socios de la comunidad. Puede dividir a estos miembros en secciones para explicar mejor los roles de cada grupo.
Para poder hacerlo, agregue al componente `<VPTeamPageSection>` al archivo `team.md` que creamos anteriormente.
Para hacerlo, agregue el componente `<VPTeamPageSection>` al archivo `team.md` que creamos anteriormente.
El componente `<VPTeamPageSection>`Puede tener los _slots_`#title` y `#lead` similares al componente `VPTeamPageTitle`, y también al _slot_`#members` para mostrar a los miembros del equipo.
El componente `<VPTeamPageSection>`puede tener los `slots``#title` y `#lead` similares al componente `VPTeamPageTitle`, y también un `slot``#members` para mostrar a los miembros del equipo.
Recuerde colocar el componente `<VPTeamMembers>` dentro del _slot_`#members`.
Recuerde colocar el componente `<VPTeamMembers>` dentro del `slot``#members`.
## `<VPTeamMembers>`
El componente `<VPTeamMembers>` muestra una determinada lista de miembros.
El componente `<VPTeamMembers>` muestra una lista determinada de miembros.
```html
<VPTeamMembers
@ -183,22 +183,22 @@ interface Props {
// Tamaño de cada miembro. El valor predeterminado es `medium`.
size?: 'small' | 'medium'
// Lista de miembros que se mostrará.
// Lista de miembros a mostrar.
members: TeamMember[]
}
interface TeamMember {
// Imagen de avatar de miembro.
// Imagen de avatar del miembro.
avatar: string
// Nombre del miembro.
name: string
// Título a ser mostrado a bajo del nombre del miembro.
// Ej.: Desarrollador, Ingeniero de Software, etc.
// Título a mostrar debajo del nombre del miembro.
// Ej. Desarrollador, Ingeniero de Software, etc.
title?: string
// Organización a la que pertenece al miembro.
// Organización a la que pertenece el miembro.
org?: string
// URL de la organización.
@ -207,26 +207,26 @@ interface TeamMember {
// Descripción del miembro.
desc?: string
// Links sociales, por ejemplo, GitHub, Twitter, etc.
// Puedes pasar un objeto de Links Sociales aquí.
// Enlaces sociales. Ej. GitHub, Twitter, etc. Puede pasar
// el objeto de Enlaces Sociales (Social Links) aquí.
// Texto para enlace del patrocinador. El valor predeterminado es 'Sponsor'.
// Texto para el enlace del patrocinador. El valor predeterminado es 'Sponsor'.
actionText?: string
}
```
## `<VPTeamPage>`
El componente raíz al crear una página de equipo completa. Sólo acepta una_slot_. Aplicará estilo a todos los componentes anteriores relacionados con el equipo.
El componente raíz al crear una página de equipo completa. Solo acepta un único_slot_. Aplicará estilo a todos los componentes relacionados con el equipo que se le pasen.
## `<VPTeamPageTitle>`
Agrega la sección "título" a la página. Es mejor usarlo desde el principio debajo `<VPTeamPage>`. Acepta los _slots_`#title` y `#lead`.
Agrega la sección del "título" de la página. Es mejor usarlo al principio debajo de `<VPTeamPage>`. Acepta los `slots``#title` y `#lead`.
```html
<VPTeamPage>
@ -236,7 +236,7 @@ Agrega la sección "título" a la página. Es mejor usarlo desde el principio de
</template>
<template#lead>
El desarrollo de VitePress está guiado por un equipo internacional,
Algunos de los miembros han elegido aparecer a continuación.
algunos de los cuales han elegido aparecer a continuación.
</template>
</VPTeamPageTitle>
</VPTeamPage>
@ -244,17 +244,17 @@ Agrega la sección "título" a la página. Es mejor usarlo desde el principio de
## `<VPTeamPageSection>`
Crea una 'sección' en la página del equipo. Aceptar los _slots_`#title`, `#lead` y `#members`. Puedes agregar tantas secciones como quieras dentro`<VPTeamPage>`.
Crea una "sección" dentro de la página de equipo. Acepta los `slots``#title`, `#lead` y `#members`. Puede agregar tantas secciones como desee dentro de`<VPTeamPage>`.
description: Referencia de todas las opciones de configuración de frontmatter disponibles para páginas Markdown de VitePress.
outline: deep
description: Referencia de todas las opciones de configuración de frontmatter disponibles para las páginas Markdown de VitePress.
---
# Configuración Frontmatter {#frontmatter-config}
# Configuración de frontmatter {#frontmatter-config}
Frontmatter permite la configuración basada en páginas. En cada archivo markdown, puede utilizar la configuración de frontmatter para anular las opciones de configuración a nivel de sitio o tema. Además, hay opciones de configuración que sólo se pueden establecer en frontmatter.
El `frontmatter` permite la configuración basada en la página. En cada archivo Markdown, puede utilizar la configuración del `frontmatter` para sobrescribir las opciones de configuración a nivel del sitio o a nivel del tema. Además, hay opciones de configuración que solo se pueden definir en el `frontmatter`.
Ejemplo de uso:
@ -26,7 +26,7 @@ Puede acceder a los datos del frontmatter a través de la variable global `$fron
- Tipo: `string`
Título de la página. Es lo mismo que [config.title](./site-config#title), y anula la configuración a nivel de sitio.
Título de la página. Es igual a [config.title](./site-config#title) y sobrescribe la configuración a nivel del sitio.
```yaml
---
@ -38,20 +38,20 @@ title: VitePress
- Tipo: `string | boolean`
El sufijo del título. Es lo mismo que [config.titleTemplate](./site-config#titletemplate), y anula la configuración a nivel de sitio.
El sufijo del título. Es igual a [config.titleTemplate](./site-config#titletemplate) y sobrescribe la configuración a nivel del sitio.
```yaml
---
title: VitePress
titleTemplate: Generador de sitios web estáticos con Vite & Vue
titleTemplate: Generador de Sitios Estáticos desarrollado con Vite y Vue.
---
```
## descripción
## description
- Tipo: `string`
Descripción de la página. Es lo mismo que [config.description](./site-config#description), y anula la configuración a nivel de sitio.
Descripción de la página. Es igual a [config.description](./site-config#description) y sobrescribe la configuración a nivel del sitio.
```yaml
---
@ -63,17 +63,17 @@ description: VitePress
- Tipo: `HeadConfig[]`
Especifica etiquetas de encabezado adicionales que se inyectarán en la página actual. Se agregarán después de las etiquetas principales inyectadas por la configuración a nivel de sitio.
Especifica las etiquetas `head` adicionales que se inyectarán para la página actual. Se agregarán después de las etiquetas `head` inyectadas por la configuración a nivel del sitio.
```yaml
---
head:
- - meta
- name: description
content: hello
content: hola
- - meta
- name: keywords
content: super duper SEO
content: super increíble SEO
---
```
@ -85,18 +85,18 @@ type HeadConfig =
## Solo Tema Predeterminado {#default-theme-only}
Las siguientes opciones de frontmatter solo se aplican cuando se usa el tema predeterminado.
Las siguientes opciones de frontmatter solo son aplicables cuando se utiliza el tema predeterminado.
### layout
- Tipo: `doc | home | page`
- Predeterminado: `doc`
Determina el layout de la página.
Determina el `layout` de la página.
- `doc` - Aplica estilos de documentación por defecto al contenido markdown.
- `home` - Layout especial para la "Página Inicial". Puedes agregar opciones extras como `hero` y `features` para crear rapidamente una hermosa página inicial.
- `page` - Se comporta de manera similar a `doc`, pero no aplica estilos al contenido. Útil cuando desea crear una página totalmente personalizada.
- `doc` - Aplica los estilos de documentación predeterminados al contenido Markdown.
- `home` - `layout` especial para la "Página de inicio". Puede agregar opciones adicionales como `hero` y `features` para crear rápidamente una hermosa página de inicio.
- `page` - Se comporta de manera similar a `doc`, pero no aplica estilos al contenido. Es útil cuando desea crear una página totalmente personalizada.
```yaml
---
@ -104,20 +104,20 @@ layout: doc
---
```
### hero <Badgetype="info"text="apenas para página inicial" />
### hero <Badgetype="info"text="solo página de inicio" />
Define el contenido de la sección _hero_ en la página inicial cuando `layout` está definido como `home`. Más detalles en [Tema Predeterminado: Página Inicial](./default-theme-home-page).
Define los contenidos de la sección _hero_ de la página de inicio cuando `layout` está establecido en `home`. Más detalles en [Tema predeterminado: Página de inicio](./default-theme-home-page).
### features <Badgetype="info"text="apenas para página inicial" />
### features <Badgetype="info"text="solo página de inicio" />
Define los elementos que se mostrarán en la sección de características cuando `layout` está definido como `home`. Más detalles en [Tema Predeterminado: Página Inicial](./default-theme-home-page).
Define los elementos que se mostrarán en la sección de características cuando `layout` está establecido en `home`. Más detalles en [Tema predeterminado: Página de inicio](./default-theme-home-page).
### navbar
- Tipo: `boolean`
- Predeterminado: `true`
Se debe mostrar una [barra de navegación](./default-theme-nav).
Indica si se debe mostrar la [barra de navegación](./default-theme-nav).
```yaml
---
@ -130,7 +130,7 @@ navbar: false
- Tipo: `boolean`
- Predeterminado: `true`
Se debe mostrar una [barra lateral](./default-theme-sidebar).
Indica si se debe mostrar la [barra lateral](./default-theme-sidebar).
```yaml
---
@ -143,11 +143,11 @@ sidebar: false
- Tipo: `boolean | 'left'`
- Predeterminado: `true`
Define la localización del componente aside en el layout`doc`.
Define la ubicación del componente lateral en el `layout``doc`.
Configurar este valor como `false` evita que se muestre el elemento lateral.\
Configurar este valor como `true` presenta el lado de la derecha.\
Configurar este valor como `'left'` presenta el lado de la izquierda.
Establecer este valor en `false` evita renderizar el contenedor lateral.\
Establecer este valor en `true` renderiza el contenedor lateral a la derecha.\
Establecer este valor en `'left'` renderiza el contenedor lateral a la izquierda.
Los niveles del encabezado en _outline_ que se mostrará para la página. Es lo mismo que [config.themeConfig.outline.level](./default-theme-config#outline), y anula el valor establecido en la configuración a nivel de sitio.
Los niveles de encabezado en el esquema (_outline_) que se mostrarán para la página. Es igual a [config.themeConfig.outline.level](./default-theme-config#outline) y sobrescribe el valor establecido en la configuración a nivel del sitio.
```yaml
---
outline: [2, 4]
---
```
### lastUpdated
- Tipo: `boolean | Date`
- Predeterminado: `true`
Se debe mostrar el texto de [última actualización](./default-theme-last-updated) en el pie de página de la página actual. Si se especifica una fecha y hora específicas, se mostrarán en lugar de la hora de la última modificación de git.
Indica si se debe mostrar el texto de [última actualización](./default-theme-last-updated) en el pie de página de la página actual. Si se especifica una fecha y hora, se mostrará en lugar de la marca de tiempo de la última modificación de git.
```yaml
---
@ -180,7 +186,7 @@ lastUpdated: false
- Tipo: `boolean`
- Predeterminado: `true`
Se debe mostrar el [link de edición](./default-theme-edit-link) en el pie de página de la página actual.
Indica si se debe mostrar el [enlace de edición](./default-theme-edit-link) en el pie de página de la página actual.
```yaml
---
@ -193,7 +199,7 @@ editLink: false
- Tipo: `boolean`
- Predeterminado: `true`
Se debe mostrar el [pie de página](./default-theme-footer).
Indica si se debe mostrar el [pie de página](./default-theme-footer).
```yaml
---
@ -209,14 +215,27 @@ Agrega un nombre de clase adicional a una página específica.
```yaml
---
pageClass: custom-page-class
pageClass: clase-de-pagina-personalizada
---
```
Luego puede personalizar los estilos para esta página específica en el archivo.`.vitepress/theme/custom.css`:
Luego puede personalizar los estilos de esta página específica en el archivo`.vitepress/theme/custom.css`:
```css
.custom-page-class {
/* estilos especificos de la página */
.clase-de-pagina-personalizada {
/* estilos específicos de la página */
}
```
### isHome
- Tipo: `boolean`
El tema predeterminado se basa en comprobaciones como `frontmatter.layout === 'home'` para determinar si la página actual es la página de inicio.\
Esto es útil cuando desea forzar la visualización de los elementos de la página de inicio en un `layout` personalizado.
description: Referencia de las APIs en tiempo de ejecución de VitePress, incluyendo composables, funciones auxiliares y componentes integrados.
description: Referencia de las API en tiempo de ejecución de VitePress, incluyendo composables, funciones auxiliares y componentes integrados.
---
# API en Tiempo de Ejecución {#runtime-api}
VitePress ofrece varias API integradas para permitir el acceso a los datos de la aplicación. VitePress también viene con algunos componentes integrados que se pueden utilizar globalmente.
Los métodos auxiliares son importaciones globales de `vitepress` y se utilizan a menudo en componentes Vue de temas personalizados. Sin embargo, también se pueden utilizar dentro de páginas `.md` porque los archivos de rebajas se compilan en [Componentes de Archivo Único Vue (SFC)](https://vuejs.org/guide/scaling-up/sfc.html).
Los métodos auxiliares se pueden importar globalmente desde `vitepress` y normalmente se utilizan en componentes de Vue de temas personalizados. Sin embargo, también se pueden utilizar dentro de páginas `.md` porque los archivos Markdown se compilan en [Componentes de un solo archivo de Vue (SFC)](https://vuejs.org/guide/scaling-up/sfc.html).
Métodos que comienzan con `use*` indican que es una función de [API de Composición Vue 3](https://vuejs.org/guide/introduction.html#composition-api) ("Composable") que solo puede ser utilizada dentro de `setup()` o `<script setup>`.
Los métodos que comienzan con `use*` indican que se trata de una función de la [API de Composición de Vue 3](https://vuejs.org/guide/introduction.html#composition-api) ("Composable") que solo se puede utilizar dentro de `setup()` o `<script setup>`.
## `useData`<Badgetype="info"text="composable"/>
@ -17,15 +17,15 @@ Retorna datos específicos de la página. El objeto devuelto tiene el siguiente
`page.headers` se rellena solo cuando [`markdown.headers`](./site-config#markdown) está habilitado. Sin esa opción, permanece como un `array` vacío. El esquema del tema predeterminado lee los encabezados renderizados del contenido de la página, por lo que aún puede aparecer cuando `page.headers` está vacío.
El componente `<ClientOnly />`muestra tu _slot_ solo del lado del cliente.
El componente `<ClientOnly />`renderiza su `slot` solo en el lado del cliente.
Debido a que las aplicaciones VitePress se interpretan en el lado del servidor en Node.js cuando generan compilaciones estáticas, cualquier uso de Vue debe seguir los requisitos del código universal. En resumen, asegúrese de acceder solo a las API del navegador/DOM en ganchos`beforeMount` o `mounted`.
Debido a que las aplicaciones de VitePress se renderizan en el lado del servidor en Node.js al generar compilaciones estáticas, cualquier uso de Vue debe cumplir con los requisitos del código universal. En resumen, asegúrese de acceder a las API del navegador/DOM solo en los *hooks*`beforeMount` o `mounted`.
Si está utilizando o demostrando componentes que no son compatibles con SSR (por ejemplo, contienen directivas personalizadas), puede incluirlos dentro del componente.`ClientOnly`.
Si está utilizando o demostrando componentes que no son compatibles con SSR (por ejemplo, que contienen directivas personalizadas), puede envolverlos dentro del componente`ClientOnly`.
```vue-html
<ClientOnly>
@ -145,15 +167,15 @@ Si está utilizando o demostrando componentes que no son compatibles con SSR (po
description: Referencia completa de las opciones de configuración del sitio VitePress, incluyendo ajustes a nivel de aplicación, temas y opciones de compilación.
outline: deep
description: Referencia completa de las opciones de configuración del sitio VitePress, incluyendo los ajustes a nivel de aplicación, tematización y opciones de compilación.
---
# Configuración de site {#site-config}
# Configuración del sitio {#site-config}
La configuración del site es donde puede configurar los ajustes globales del site. Las opciones de configuración de la aplicación definen las configuraciones que se aplican a todos los sites de VitePress, independientemente del tema que estén utilizando. Por ejemplo, el directorio base o el título del site.
La configuración del sitio es donde puede definir los ajustes globales del sitio. Las opciones de configuración a nivel de aplicación definen los ajustes que se aplican a todos los sitios de VitePress, independientemente del tema que estén utilizando. Por ejemplo, el directorio base o el título del sitio.
## Vista general {#overview}
## Descripción general {#overview}
### Resolución de configuración {#config-resolution}
### Resolución de la configuración {#config-resolution}
El archivo de configuración siempre se resuelve desde `<root>/.vitepress/config.[ext]`, donde `<root>` es la [raiz del proyecto](../guide/routing#root-and-source-directory) VitePress y `[ext]` es una de las extensiones de archivo compatibles. TypeScript es compatible desde el primer momento. Las extensiones compatibles incluyen `.js`, `.ts`, `.mjs` y `.mts`.
El archivo de configuración siempre se resuelve desde `<root>/.vitepress/config.[ext]`, donde `<root>` es la [raíz de su proyecto](../guide/routing#root-and-source-directory) de VitePress, y `[ext]` es una de las extensiones de archivo compatibles. TypeScript es compatible de forma predeterminada. Las extensiones compatibles incluyen `.js`, `.ts`, `.mjs` y `.mts`.
Recuerde usar la sintaxis de módulos ES en los archivos de configuración. El archivo de configuración debe exportar por defecto un objeto:
Se recomienda usar la sintaxis de módulos ES en los archivos de configuración. El archivo de configuración debe exportar por defecto un objeto:
```ts
export default {
// opciones de configuración a nivel de aplicación
lang: 'pt-BR',
lang: 'es-ES',
title: 'VitePress',
description: 'Generador de site estático Vite & Vue.',
description: 'Generador de sitios estáticos desarrollado con Vite y Vue.',
...
}
```
::: details Configuración dinámica (Assíncrona)
::: details Configuración dinámica (asíncrona)
Si necesitas generar dinamicamente la configuración, también puedes exportar por defecto una función. Por ejemplo:
Si necesita generar dinámicamente la configuración, también puede exportar por defecto una función. Por ejemplo:
Usar el auxiliar `defineConfig` proporcionará Intellisense con tecnología TypeScript para las opciones de configuración. Suponiendo que su IDE lo admita, esto debería funcionar tanto en JavaScript como en TypeScript.
El uso del asistente `defineConfig` proporcionará Intellisense impulsado por TypeScript para las opciones de configuración. Suponiendo que su IDE lo admita, esto debería funcionar tanto en JavaScript como en TypeScript.
```js
import { defineConfig } from 'vitepress'
@ -93,9 +93,9 @@ export default defineConfig({
})
```
### Configuración de Tema Escrito {#typed-theme-config}
### Configuración de Tema Tipada {#typed-theme-config}
Por defecto, el auxiliar `defineConfig` espera el tipo de configuración del tema por defecto:
De forma predeterminada, el asistente `defineConfig` espera el tipo de configuración de tema desde el tema predeterminado:
```ts
import { defineConfig } from 'vitepress'
@ -107,7 +107,7 @@ export default defineConfig({
})
```
Si usa un tema personalizado y desea realizar comprobaciones de tipo para la configuración del tema, deberá usar `defineConfigWithTheme` en su lugar, y pase el tipo de configuración para su tema personalizado a través de un argumento genérico:
Si usa un tema personalizado y desea realizar comprobaciones de tipo para la configuración del tema, deberá usar `defineConfigWithTheme` en su lugar, y pasar el tipo de configuración de su tema personalizado a través de un argumento genérico:
### Configuración de Vite, Vue y Markdown {#vite-vue-markdown-config}
- **Vite**
Puede configurar la instancia de Vite subyacente usando la opción [vite](#vite) en su configuración de VitePress. No es necesario crear un archivo de configuración de Vite por separado.
Puede configurar la instancia de Vite subyacente utilizando la opción [vite](#vite) en su configuración de VitePress. No es necesario crear un archivo de configuración de Vite por separado.
- **Vue**
VitePress ya incluye el plugin oficial de Vue para Vite ([@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue)). Puede configurar sus opciones usando la opción [vue](#vue) en su configuración VitePress.
VitePress ya incluye el complemento oficial de Vue para Vite ([@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue)). Puede configurar sus opciones utilizando la opción [vue](#vue) en su configuración de VitePress.
- **Markdown**
Puede configurar la instancia subyacente de [Markdown-It](https://github.com/markdown-it/markdown-it) usando la opción [markdown](#markdown) en su configuración VitePress.
Puede configurar la instancia subyacente de [Markdown-It](https://github.com/markdown-it/markdown-it) utilizando la opción [markdown](#markdown) en su configuración de VitePress.
### Sobrescrituras a nivel de página {#page-level-overrides}
Algunos ajustes se pueden sobrescribir para páginas específicas utilizando el `frontmatter`.
Consulte la [Configuración de frontmatter](./frontmatter-config) para obtener más detalles.
### Sobrescrituras a nivel de directorio {#directory-level-overrides}
Algunos ajustes de configuración se pueden sobrescribir a nivel de directorio, lo que permite que todas las páginas en ese directorio compartan la configuración sin necesidad de repetirla en el `frontmatter` de cada página.
Esto se logra agregando un archivo llamado `config.ts` (o `.js`, `.mjs`, o `.mts`) en el directorio correspondiente. Este archivo debe exportar un objeto de configuración utilizando `export default`, de manera similar al archivo de configuración principal.
Los directorios anidados heredan la configuración de su directorio principal, y las sobrescrituras de configuración se fusionan en consecuencia.
El asistente `defineAdditionalConfig` se puede utilizar para obtener Intellisense impulsado por TypeScript para las opciones disponibles, aunque al igual que con `defineConfig`, su uso es opcional.
## Metadatos de Site {#site-metadata}
Por ejemplo, para un sitio con varios idiomas, es posible que queramos una `description` diferente para cada idioma. Podríamos agregar `es/config.ts` con el siguiente contenido:
```ts
import { defineAdditionalConfig } from 'vitepress'
export default defineAdditionalConfig({
description: 'Generador de sitios estáticos desarrollado con Vite y Vue.'
})
```
Esta `description` se usaría entonces para todas las páginas en el directorio `es`.
Como alternativa, al usar las características integradas de i18n, los ajustes para un directorio de configuración regional (locale) se pueden sobrescribir a través de la opción `locales` en el archivo de configuración principal. Consulte la [Internacionalización](../guide/i18n) para obtener más detalles.
## Metadatos del sitio {#site-metadata}
### title
- Tipo: `string`
- Predeterminado: `VitePress`
- Puede ser reemplazado por página a través de [frontmatter](./frontmatter-config#title)
- Puede sobrescribirse por página a través del [`frontmatter`](./frontmatter-config#title) o a [nivel de directorio](#directory-level-overrides)
Título de site. Al usar el tema por defecto, este será mostrado en la barra de navegación.
Título para el sitio. Cuando se utiliza el tema predeterminado, este se mostrará en la barra de navegación.
También se utilizará como sufijo predeterminado para todos los títulos de páginas individuales a menos que [`titleTemplate`](#titletemplate) definirse. El título final de una página individual será el contenido textual de su primer encabezado. `<h1>`, combinado con el título global como sufijo. Por ejemplo, con la siguiente configuración y contenido de página:
También se utilizará como el sufijo predeterminado para todos los títulos de páginas individuales, a menos que se defina [`titleTemplate`](#titletemplate). El título final de una página individual será el contenido de texto de su primer encabezado `<h1>`, combinado con el `title` global como sufijo. Por ejemplo, con la siguiente configuración y contenido de página:
```ts
export default {
title: 'Mi increible sitio web'
title: 'Mi sitio increíble'
}
```
@ -156,19 +186,19 @@ export default {
# Hola
```
El título de la página será `Hola | Mi increible sitio web`.
El título de la página será `Hola | Mi sitio increíble`.
### titleTemplate
- Tipo: `string | boolean`
- Puede ser reemplazado por página a través de [frontmatter](./frontmatter-config#titletemplate)
- Puede sobrescribirse por página a través del [`frontmatter`](./frontmatter-config#titletemplate) o a [nivel de directorio](#directory-level-overrides)
Le permite personalizar el sufijo del título de cada página o el título completo. Por ejemplo:
Permite personalizar el sufijo del título de cada página o el título completo. Por ejemplo:
```ts
export default {
title: 'Mi increible sitio web',
titleTemplate: 'Sufijo Personalizado'
title: 'Mi sitio increíble',
titleTemplate: 'Sufijo personalizado'
}
```
@ -176,31 +206,31 @@ export default {
# Hola
```
El título de la página será `Hola | Sufijo Personalizado`.
El título de la página será `Hola | Sufijo personalizado`.
Para personalizar completamente cómo se debe representar el título, puedes usar el símbolo `:title` en `titleTemplate`:
Para personalizar completamente cómo se debe renderizar el título, puede usar el símbolo `:title` en `titleTemplate`:
```ts
export default {
titleTemplate: ':title - Sufijo Personalizado'
titleTemplate: ':title - Sufijo personalizado'
}
```
Aqui, `:title` será reemplazado por el texto que se deduce del primer título `<h1>` de la página. El título del ejemplo de la página anterior será `Hola - Sufijo Personalizado`.
Aquí `:title` será reemplazado con el texto inferido del primer encabezado `<h1>` de la página. El título de la página del ejemplo anterior sería `Hola - Sufijo personalizado`.
Una opción puede ser definida como `false` para desactivar sufijos del título.
La opción se puede establecer en `false` para desactivar los sufijos de los títulos.
### description
- Tipo: `string`
- Predeterminado: `Um site VitePress`
- Puede ser sustituído por página a través de [frontmatter](./frontmatter-config#descrição)
- Predeterminado: `A VitePress site`
- Puede sobrescribirse por página a través del [`frontmatter`](./frontmatter-config#description) o a [nivel de directorio](#directory-level-overrides)
Descripción del sitio web. Esto se presentará como una etiqueta. `<meta>` en la página HTML.
Descripción para el sitio. Esto se renderizará como una etiqueta `<meta>` en el HTML de la página.
```ts
export default {
descripción: 'Un site VitePress'
description: 'Un sitio de VitePress'
}
```
@ -208,9 +238,9 @@ export default {
- Tipo: `HeadConfig[]`
- Predeterminado: `[]`
- Se puede agregar por página a través de [frontmatter](./frontmatter-config#head)
- Se puede agregar por página a través del [`frontmatter`](./frontmatter-config#head) o a [nivel de directorio](#directory-level-overrides)
Elementos adicionales para agregar a la etiqueta `<head>` de la página HTML. Las etiquetas agregadas por los usuarios son mostradas antes de la etiqueta `head` de cierre, despues de las etiquetas VitePress.
Elementos adicionales para renderizar en la etiqueta `<head>` en el HTML de la página. Las etiquetas añadidas por el usuario se renderizan antes de la etiqueta `head` de cierre, después de las etiquetas de VitePress.
```ts
type HeadConfig =
@ -218,19 +248,19 @@ type HeadConfig =
| [string, Record<string,string>, string]
```
#### Ejemplo: Agregando un favicon {#example-adding-a-favicon}
#### Ejemplo: Agregar un favicon {#example-adding-a-favicon}
- Puede sobrescribirse a [nivel de directorio](#directory-level-overrides)
El atributo de idioma del sitio. Esto se mostrará como una etiqueta. `<html lang="en-US">` en la página HTML.
El atributo `lang` para el sitio. Esto se renderizará como una etiqueta `<html lang="en-US">` en el HTML de la página.
```ts
export default {
@ -334,9 +365,9 @@ export default {
- Tipo: `string`
- Predeterminado: `/`
La URL base donde se implementará el sitio. Deberá configurar esto si planea implementar su sitio en un subdirectorio, por ejemplo, en páginas de GitHub. Si planea implementar su sitio web en `https://foo.github.io/bar/` entonces deberías definir la base como`'/bar/'`. Siempre debe comenzar y terminar con una barra.
La URL base en la que se desplegará el sitio. Tendrá que configurar esto si planea desplegar su sitio en una subruta, por ejemplo, en GitHub Pages. Si planea desplegar su sitio en `https://foo.github.io/bar/`, entonces debe establecer la `base` en`'/bar/'`. Siempre debe comenzar y terminar con una barra. No se admiten bases relativas.
La base se agrega automáticamente a todas las URL que comienzan con / en otras opciones, por lo que solo necesitas especificarla una vez.
La base se antepone automáticamente a todas las URL que comienzan con `/` en otras opciones, por lo que solo necesita especificarla una vez.
```ts
export default {
@ -344,24 +375,24 @@ export default {
}
```
## Roteamento {#routing}
## Enrutamiento {#routing}
### cleanUrls
- Tipo: `boolean`
- Predeterminado: `false`
Cuando se establece en `true`, VitePress eliminará el `.html`al final de las URLs. Consulte también [Generación de URLs Limpias](../guide/routing#generating-clean-urls).
Cuando se establece en `true`, VitePress eliminará el `.html`final de las URLs. Consulte también [Generar URLs limpias](../guide/routing#generating-clean-urls).
::: warning Soporte de Servidor Requerido
Habilitar esto puede requerir configurar adicional en su plataforma de alojamiento. Para funcionar, su servidor debe poder servir `/foo.html` cuando visite `/foo`**sin redirección**.
::: warning Se requiere soporte del servidor
Habilitar esto puede requerir configuración adicional en su plataforma de alojamiento. Para que funcione, su servidor debe poder servir `/foo.html` al visitar `/foo`**sin una redirección**.
:::
### rewrites
- Tipo: `Record<string, string>`
Define asignaciones de directorios personalizados <-> URL. Visite [Rutas: Reescribir Rutas](../guide/routing#route-rewrites) para obtener más detalles.
Define mapeos personalizados de directorio <-> URL. Consulte [Enrutamiento: Reescribir rutas](../guide/routing#route-rewrites) para obtener más detalles.
```ts
export default {
@ -371,14 +402,14 @@ export default {
}
```
## Construcción {#build}
## Compilación {#build}
### srcDir
- Tipo: `string`
- Predeterminado: `.`
El directorio donde se almacenan tus páginas de rebajas, en relación con la raíz del proyecto. vea también [Directorio Raiz y de origen](../guide/routing#root-and-source-directory).
El directorio donde se almacenan sus páginas Markdown, relativo a la raíz del proyecto. Consulte también [Raíz y directorio fuente](../guide/routing#root-and-source-directory).
```ts
export default {
@ -388,10 +419,10 @@ export default {
### srcExclude
- Tipo: `string`
- Tipo: `string[]`
- Predeterminado: `undefined`
Un [patrón glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) para hacer coincidir los archivos de rebajas que deben exluirse como contenido de origen.
Un [patrón glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) para hacer coincidir los archivos Markdown que deben excluirse del contenido fuente.
```ts
export default {
@ -404,7 +435,7 @@ export default {
- Tipo: `string`
- Predeterminado: `./.vitepress/dist`
La ubicación de la salida de compilación para el sitio, en relación con el [raiz del proyecto](../guide/routing#root-and-source-directory).
La ubicación de salida de la compilación para el sitio, relativa a la [raíz del proyecto](../guide/routing#root-and-source-directory).
```ts
export default {
@ -417,7 +448,7 @@ export default {
- Tipo: `string`
- Predeterminado: `assets`
Especifica el directorio para anidar los activos generados. El camino debe estar dentro [`outDir`](#outdir) y se resuelve en relación con el mismo.
Especifica el directorio para anidar los recursos generados. La ruta debe estar dentro de [`outDir`](#outdir) y se resuelve de forma relativa a este.
```ts
export default {
@ -430,7 +461,7 @@ export default {
- Tipo: `string`
- Predeterminado: `./.vitepress/cache`
El directorio para los archivos de caché, en relación con el [raiz del proyecto](../guide/routing#root-and-source-directory). Vea también: [cacheDir](https://vite.dev/config/shared-options.html#cachedir).
El directorio para los archivos de caché, relativo a la [raíz del proyecto](../guide/routing#root-and-source-directory). Consulte también: [cacheDir](https://vite.dev/config/shared-options.html#cachedir).
Cuando se establece en `true`, VitePress no dejará de compilarse debido a links rotos.
Cuando se establece en `true`, VitePress no fallará las compilaciones debido a enlaces rotos.
Cuando se establece en `'localhostLinks'`, la compilación fallará en links rotos, per no verificará los links`localhost`.
Cuando se establece en `'localhostLinks'`, la compilación fallará en los enlaces rotos, pero no comprobará los enlaces a`localhost`.
```ts
export default {
@ -453,18 +484,18 @@ export default {
}
```
También puede ser un _array_ de una exacta URL en string, patrones regex, o funciones de filtro personalizadas.
También puede ser un _array_ de cadenas de URL exactas, patrones de expresiones regulares (regex) o funciones de filtro personalizadas.
```ts
export default {
ignoreDeadLinks: [
// ignora URL exacta "/playground"
// ignora la URL exacta "/playground"
'/playground',
// ignora todos los links localhost
// ignora todos los enlaces a localhost
/^https?:\/\/localhost/,
// ignora todos los links incluyendo "/repl/""
// ignora todos los enlaces que incluyan "/repl/"
/\/repl\//,
// función personalizada, ignora todos los links incluyendo "ignore"
// función personalizada, ignora todos los enlaces que incluyan "ignore"
(url) => {
return url.toLowerCase().includes('ignore')
}
@ -477,33 +508,35 @@ export default {
- Tipo: `boolean`
- Predeterminado: `false`
Cuando se define como`true`, la aplicación de producción se compilará en [Modo MPA](../guide/mpa-mode). El modo MPA envía 0 kb de JavaScript de forma predeterminada, a expensas de deshabilitar la navegación del lado del cliente y requerir permiso explícito para la interactividad.
Cuando se establece en`true`, la aplicación de producción se compilará en [Modo MPA](../guide/mpa-mode). El modo MPA envía 0 kb de JavaScript de forma predeterminada, a expensas de deshabilitar la navegación en el lado del cliente y requiere habilitación explícita (opt-in) para la interactividad.
Se habilitará el modo oscuro (agregando una classe `.dark` al elemento `<html>`).
Indica si se debe habilitar el modo oscuro (añadiendo la clase `.dark` al elemento `<html>`).
- Si la opción está configurada en `true` El tema predeterminado está determinado por la combinación de colores preferida del usuario.
- Si la opción está configurada en `dark` El tema es oscuro de forma predeterminada a menos que el usuario lo cambie manualmente.
- Si la opción está configurada en `false` los usuarios no podrán cambiar el tema.
- Si la opción está establecida en `true`, el tema predeterminado se determinará por la preferencia de color del usuario.
- Si la opción está establecida en `dark`, el tema será oscuro de forma predeterminada, a menos que el usuario lo cambie manualmente.
- Si la opción está establecida en `false`, los usuarios no podrán cambiar el tema.
- Si la opción está establecida en `'force-dark'`, el tema siempre será oscuro y los usuarios no podrán cambiarlo.
- Si la opción está establecida en `'force-auto'`, el tema siempre se determinará por la preferencia de color del usuario y los usuarios no podrán cambiarlo.
Esta opción inyecta un script en línea que restaura la configuración de los usuarios desde el almacenamiento local. (_local storage_) usando una llave `vitepress-theme-appearance`. Eso asegurará que la clase `.dark` se aplicará antes de que se muestre la página para evitar el parpadeo.
Esta opción inyecta un script en línea que restaura la configuración del usuario desde el almacenamiento local utilizando la clave `vitepress-theme-appearance`. Esto asegura que la clase `.dark` se aplique antes de que la página se renderice para evitar parpadeos.
`appearance.initialValue`puede ser `'dark' | undefined`. Refs o getters no son soportados.
`appearance.initialValue`solo puede ser `'dark' | undefined`. No se admiten referencias (`refs`) o `getters`.
### lastUpdated
- Tipo: `boolean`
- Predeterminado: `false`
Para obtener la marca de tiempo de la última actualización para cada página usando Git. El sello de fecha se incluirá en los datos de cada página, accesible a través de [`useData`](./runtime-api#usedata).
Indica si se debe obtener la marca de tiempo de la última actualización para cada página utilizando Git. La marca de tiempo se incluirá en los datos de página de cada página, accesible a través de [`useData`](./runtime-api#usedata).
Cuando se utiliza el tema predeterminado, al habilitar esta opción se mostrará la última hora de actualización de cada página. Puedes personalizar el texto mediante la opción [`themeConfig.lastUpdated.text`](./default-theme-config#lastupdated).
Al usar el tema predeterminado, habilitar esta opción mostrará la hora de última actualización de cada página. Puede personalizar el texto a través de la opción [`themeConfig.lastUpdated.text`](./default-theme-config#lastupdated).
## Personalización {#customization}
@ -511,7 +544,7 @@ Cuando se utiliza el tema predeterminado, al habilitar esta opción se mostrará
- Tipo: `MarkdownOption`
Configure las opciones de procesador Markdown. VitePress usa [Markdown-it](https://github.com/markdown-it/markdown-it) como procesador y [Shiki](https://github.com/shikijs/shiki) para resaltar la sintaxis del idioma. Dentro de esta opción, puede pasar varias opciones de Markdown relacionadas para satisfacer sus necesidades.
Configura las opciones del analizador Markdown. VitePress usa [Markdown-it](https://github.com/markdown-it/markdown-it) como analizador y [Shiki](https://github.com/shikijs/shiki) para el resaltado de la sintaxis del lenguaje. Dentro de esta opción, puede pasar varias opciones relacionadas con Markdown para adaptarse a sus necesidades.
```js
export default {
@ -521,16 +554,18 @@ export default {
Consulte la [declaración de tipo y jsdocs](https://github.com/vuejs/vitepress/blob/main/src/node/markdown/markdown.ts) para conocer todas las opciones disponibles.
Establezca `markdown.headers` en `true` o pase las opciones de [`@mdit-vue/plugin-headers`](https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-headers) para recopilar los encabezados en [`useData().page.headers`](./runtime-api#usedata). Esta opción está deshabilitada de forma predeterminada.
### vite
- Tipo: `import('vite').UserConfig`
Pase la [Configuración Vite](https://vite.dev/config/) sin procesar al servidor interno / empaquetador Vite.
Pase la [configuración de Vite](https://vite.dev/config/) sin procesar al servidor de desarrollo / empaquetador de Vite interno.
```js
export default {
vite: {
// Opciones de configuración Vite
// Opciones de configuración de Vite
}
}
```
@ -539,28 +574,30 @@ export default {
- Tipo: `import('@vitejs/plugin-vue').Options`
Pase las opciones [`@vitejs/plugin-vue`](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue#options) sin formato a la instancia del complemento interno.
Pase las opciones de [`@vitejs/plugin-vue`](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue#options) sin procesar a la instancia del complemento interno.
```js
export default {
vue: {
// Opciones @vitejs/plugin-vue
// Opciones de @vitejs/plugin-vue
}
}
```
## Construir Ganchos {#build-hooks}
## Hooks de compilación {#build-hooks}
Los enlaces de compilación VitePress permiten agregar nuevas funciones al su sitio web:
Los hooks de compilación de VitePress le permiten agregar nueva funcionalidad y comportamientos a su sitio web:
`buildEnd` es un enlace de compilación CLI (Interfaz de línea de comando), se ejecutará después de que se complete la compilación (SSG) pero antes de que finalice el proceso CLI de VitePress.
`buildEnd` es un hook de la CLI de compilación, se ejecutará después de que finalice la compilación (SSG) pero antes de que termine el proceso de la CLI de VitePress.
- `postRender` es un gancho de compilación, llamado cuando se completa la interpretación de SSG. Le permitirá manipular el contenido de los _teleports_ durante la generación de sitios estáticos.
```ts
export default {
async postRender(context) {
// ...
}
}
```
`postRender` es un hook de compilación, llamado cuando se completa el renderizado de SSG. Le permitirá manejar el contenido de los `teleports` durante la generación estática (SSG).
`transformHead` es un enlace de compilación para transformar el encabezado antes de generar cada página. Esto le permite agregar entradas de encabezado que no se pueden agregar estáticamente a la configuración de VitePress. Sólo necesita devolver entradas adicionales, que se fusionarán automáticamente con las existentes.
`transformHead` es un hook de compilación para agregar etiquetas adicionales al `<head>` de cada página. Le permite añadir entradas de encabezado que no se pueden agregar estáticamente a su configuración de VitePress. Solo necesita devolver entradas adicionales, que se fusionarán automáticamente con las existentes.
::: warning
No mutes ningún elemento dentro `context`.
No mute nada dentro del`context`.
:::
```ts
@ -609,8 +649,8 @@ export default {
```ts
interface TransformContext {
page: string // e.g. index.md (relativo a srcDir)
assets: string[] // todos los activos no-js/css con URL pública completamente resuelta
page: string // ej. index.md (relativo a srcDir)
assets: string[] // todos los recursos no js/css como una URL pública completamente resuelta
siteConfig: SiteConfig
siteData: SiteData
pageData: PageData
@ -621,50 +661,46 @@ interface TransformContext {
}
```
Tenga en cuenta que este enlace solo se llama cuando se genera el sitio de forma estática. No se llama durante el desarrollo. Si necesita agregar entradas de encabezado dinámicas durante el desarrollo, puede usar el enlace [`transformPageData`](#transformpagedata) en su lugar.
Este hook solo se llama al realizar una compilación, no se llama durante el desarrollo.
```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`
}
])
}
}
```
Las etiquetas adicionales se añadirán a los archivos HTML estáticos generados por la compilación. No se actualizarán durante la navegación en el lado del cliente.
#### Ejemplo: Agregando una URL canónica `<link>` {#example-adding-a-canonical-url-link}
En muchos casos, el uso del hook [`transformPageData`](#transformpagedata) es una solución más limpia. Ese hook también se aplicará tanto a la navegación en el lado del cliente como durante el desarrollo. Pero si la generación de las etiquetas de encabezado es computacionalmente costosa, entonces `transformHead` evitará esa sobrecarga durante el desarrollo.
#### Ejemplo: Agregar meta `og:image` {#example-adding-og-image-meta}
// Los detalles de implementación de generatePageImage dependerán
// de sus requerimientos. Aquí asumimos que genera una imagen adecuada
// para cada página y devuelve la URL de la imagen.
const imageUrl = await generatePageImage(context)
return [[
'meta',
{ name: 'og:image', content: imageUrl }
]]
}
}
```
Aquí asumimos que la URL de la imagen es dinámica y su generación lleva mucho tiempo. El uso de `transformHead` evita esa sobrecarga durante el desarrollo.
Para casos más simples, es posible que pueda usar la configuración [`head`](./frontmatter-config#head) en el `frontmatter`, o [`transformPageData`](#transformpagedata).
`transformPageData` es un gancho para transformar los datos de cada página. Puedes hacer mutaciones directamente en `pageData` o devolver valores modificados que se fusionarán con los datos de la página.
`transformPageData` es un hook para transformar el `pageData` de cada página. Puede mutar directamente `pageData` o devolver valores modificados que se fusionarán en los datos de la página.
::: warning
No mute ningún elemento dentro del `context` y tenga cuidado ya que esto puede afectar el rendimiento del servidor de desarrollo, especialmente si tiene algunas solicitudes de red o cálculos pesados (como generar imágenes) en el gancho. Puede consultar `process.env.NODE_ENV === 'production'` para ver la lógica condicional.
No mute nada dentro del `context` y tenga cuidado de que esto podría afectar el rendimiento del servidor de desarrollo, especialmente si tiene algunas solicitudes de red o cálculos pesados (como generar imágenes) en el hook. Puede comprobar si `process.env.NODE_ENV === 'production'` para utilizar lógica condicional.
Jackestar
23 hours ago
committed by
GitHub