- Add missing documentation sections for `defineRoutes` type-safe loaders and watching template/data files.
- Update file names in code block examples to match the Spanish translation (e.g., `getting-started.md` to `comenzar.md` and `guide/` to `guia/`).
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](../guide/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 pure.html](/pure.html){target="_self"}
```
**Salida**
[Link para pure.html](/pure.html){target="_self"}
[Enlace para pure.html](/pure.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 `../../pure.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="/pure.html"target="_self">Link to pure.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:
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:
::: warning Enlaces Relativos con Reescrituras
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)
@ -208,20 +223,20 @@ Cuando las reescrituras están habilitadas, **links relativos deben ser basados
## 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:
jackestar
3 weeks ago