12 KiB

Raw Blame History

outline
deep

Enrutamiento

Enrutamiento basasdo en Archivos

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
│  └─ index.md
├─ index.md
└─ prologue.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/)
guide/getting-started.md  -->  /guide/getting-started.html

El HTML resultante puede ser hospedado en cualquier servidor web que pueda servir archivos estáticos.

Diretório Raiz y fuente

Existen dos conceptos importantes en la estructura de archivos de un proyecto VitePress: el directorio raiz y el directorio fuente.

Directorio Raiz

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.

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:

.
├─ docs                    # directorio raiz
│  ├─ .vitepress           # directorio de configuración
│  ├─ getting-started.md
│  └─ index.md
└─ ...

vitepress dev docs

Esto resultará en el siguiente mapeamento de fuente para HTML:

docs/index.md            -->  /index.html (accesible como /)
docs/getting-started.md  -->  /getting-started.html

Directorio Fuente

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.

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í:

.                          # directorio raiz
├─ .vitepress              # directorio de configuración
└─ src                     # directorio fuente
   ├─ getting-started.md
   └─ index.md

El mapeamente resultante de la fuente para HTML:

src/index.md            -->  /index.html (accesible como /)
src/getting-started.md  -->  /getting-started.html

Links Entre Páginas

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.

<!-- Hacer -->
[Getting Started](./getting-started)
[Getting Started](../guide/getting-started)

<!-- No hacer -->
[Getting Started](./getting-started.md)
[Getting Started](./getting-started.html)

Averigue más sobre la vinculación de assets, como imagenes, en Manipulación de Assets.

Vinculación de Páginas No VitePress

Si desea vincular a una página en su sitio que no es generada por VitePress, será necesario usar la URL completa (abre en una nueva pestaña) o especificar explícitamente el destino:

Entrada

[Link para pure.html](/pure.html){target="_self"}

Salida

Link para 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).

Alternativamente, puede usarse directamente la sintaxis de tag anchor:

<a href="/pure.html" target="_self">Link para pure.html</a>

:::

Generación de URL Limpia

::: warning Soporte del Servidor Necesario 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.

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:

Netlify y GitHub Pages soportan esto por defecto.
Vercel requiere activación de la opción cleanUrls en vercel.json.

Si esa funcionalidad está disponible para usted, también se puede activar la propia opción de configuración 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.

Sin embargo, si no puede configurar el servidor con ese soporte, será necesario recorrer manualmente la siguiente estructura de directorio:

.
├─ getting-started
│  └─ index.md
├─ installation
│  └─ index.md
└─ index.md

Reescritura de Ruta

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:

.
├─ packages
│  ├─ pkg-a
│  │  └─ src
│  │      ├─ pkg-a-code.ts
│  │      └─ pkg-a-docs.md
│  └─ pkg-b
│     └─ src
│         ├─ pkg-b-code.ts
│         └─ pkg-b-docs.md

Y desea que las páginas VitePress sean generadas así:

packages/pkg-a/src/pkg-a-docs.md  -->  /pkg-a/index.html
packages/pkg-b/src/pkg-b-docs.md  -->  /pkg-b/index.html

Puede realizar esto configurando la opción rewrites así:

// .vitepress/config.js
export default {
  rewrites: {
    'packages/pkg-a/src/pkg-a-docs.md': 'pkg-a/index.md',
    'packages/pkg-b/src/pkg-b-docs.md': 'pkg-b/index.md'
  }
}

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í:

export default {
  rewrites: {
    'packages/:pkg/src/(.*)': ':pkg/index.md'
  }
}

Los paths reesctritos son compilados usando el paquete path-to-regexp - consulte su documentación para una sintaxis más avanzada.

::: warning Links Relativos con Reescrituras

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:

[Link para PKG B](../pkg-b/pkg-b-code)

:::

Rutas Dinámicas

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.

Archivo de Carga de Paths

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):

.
└─ packages
   ├─ [pkg].md         # modelo de ruta
   └─ [pkg].paths.js   # cargador de paths de la 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.

Dado el siguiente array paths:

// packages/[pkg].paths.js
export default {
  paths() {
    return [
      { params: { pkg: 'foo' }},
      { params: { pkg: 'bar' }}
    ]
  }
}

Las páginas HTML generadas serán:

.
└─ packages
   ├─ foo.html
   └─ bar.html

Múltiples Parámetros

Una ruta dinámica puede contener múltiples parámetros:

Estrutura de Archivo

.
└─ packages
   ├─ [pkg]-[version].md
   └─ [pkg]-[version].paths.js

Cargador de Paths

export default {
  paths: () => [
    { params: { pkg: 'foo', version: '1.0.0' }},
    { params: { pkg: 'foo', version: '2.0.0' }},
    { params: { pkg: 'bar', version: '1.0.0' }},
    { params: { pkg: 'bar', version: '2.0.0' }}
  ]
}

Salida

.
└─ packages
   ├─ foo-1.0.0.html
   ├─ foo-2.0.0.html
   ├─ bar-1.0.0.html
   └─ bar-2.0.0.html

Generando Paths Dinámicamente

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.

Generando paths a partir de archivos locales:

import fs from 'fs'

export default {
  paths() {
    return fs
      .readdirSync('packages')
      .map((pkg) => {
        return { params: { pkg }}
      })
  }
}

Generando paths a partir de datos remotos:

export default {
  async paths() {
    const pkgs = await (await fetch('https://my-api.com/packages')).json()

    return pkgs.map((pkg) => {
      return {
        params: {
          pkg: pkg.name,
          version: pkg.version
        }
      }
    })
  }
}

Accediendo Parámetros en la Página

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:

- 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. Esto está disponible tanto en archivos Markdown así como en componentes Vue:

<script setup>
import { useData } from 'vitepress'

// params es una ref Vue
const { params } = useData()

console.log(params.value)
</script>

Presentando Contenido Crudo

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.

En lugar de eso, puede pasar tal contenido para cada página usando la propiedad content en cada objeto de path:

export default {
  async paths() {
    const posts = await (await fetch('https://my-cms.com/blog-posts')).json()

    return posts.map((post) => {
      return {
        params: { id: post.id },
        content: post.content // Markdown o HTML crudo
      }
    })
  }
}

En seguida, use la siguiente sintaxis especial para presentar el contenido como parte del propio archivo Markdown:

<!-- @content -->

12 KiB Raw Blame History