Extensiones Markdown

VitePress viene con Extensiones embutidas.

Anchors de Header

Los Header reciben la aplicación automáticamente de links anchor. La presentación de los anchor puede ser configurada usando la opción markdown.anchor.

Anchor personalizados

Para especificar un tag anchor personalizado para um header en vex de usar la generada automáticamente, adicione un sufijo al header:

# Usando anchors personalizados {#mi-anchor}

Esto permite que tenga un link del header como #mi-anchor en vez del default #usando-anchors-personalizados.

Links

Ambos links internos y externos reciben tratamiento especial.

Links Internos

Los links internos son convertidos en links de enrutador para navegación SPA. Además de eso , todo archivo index.md contenido en cada subdirectorio será automáticamente convertido en index.html, con la URL correspondiente /.

Por ejemplo, dada la siguiente estructura de directorios:

.
├─ index.md
├─ foo
│  ├─ index.md
│  ├─ one.md
│  └─ two.md
└─ bar
   ├─ index.md
   ├─ three.md
   └─ four.md

Y suponiendo que está en foo/one.md:

[Página Inicial](/) <!-- lleva al usuario al index.md raiz -->
[foo](/foo/) <!-- lleva al usuario al index.html del directorio foo -->
[foo heading](./#heading) <!-- ancla al usuario a un header del archivo índice foo -->
[bar - three](../bar/three) <!-- puede omitir la extensión -->
[bar - three](../bar/three.md) <!-- puede adicionar .md -->
[bar - four](../bar/four.html) <!-- o puede adicionar .html -->

Sufijo de Página

Páginas y links internos son generados con el sufijo .html por defecto.

Links Externos

Links externos reciben automáticamente target="_blank" rel="noreferrer":

• vuejs.org
• VitePress no GitHub

Frontmatter

YAML frontmatter es soportado por defecto:

---
título: Escribiendo como un Hacker
idioma: es-CO
---

Esos datos estarán disponibles para el resto de la página, junto con todos los componentes personalizados y de temas.

Para más detalles, vea Frontmatter.

Tablas al Estilo GitHub

Entrada

| Tablas        |    Son        | Geniales|
| ------------- | :-----------: |   ----: |
| col 3 está    | à direita     |   $1600 |
| col 2 está    | centralizada  |     $12 |
| listras       |   são legais  |      $1 |

Salida

Tablas	Son	Geniales
col 3 está	à direita	$1600
col 2 está	centralizada	$12
listras	são legais	$1

Emoji 🎉

Entrada

:tada: :100:

Salida

🎉 💯

Una lista de todos los emojis está disponible.

Tabla de Contenido (TOC)

Entrada

[[toc]]

Salida

• Anchors de Header
  • Anchor personalizados
• Links
  • Links Internos
  • Sufijo de Página
  • Links Externos
• Frontmatter
• Tablas al Estilo GitHub
• Emoji 🎉
• Tabla de Contenido (TOC)
• Contenedores Personalizados
  • Título por Defecto
  • Título Personalizado
  • raw
• Alertas en estilo GitHub
• Destaque de Sintaxis en Bloques de Código
• Destaque de Linea en Bloques de Código
• Enfoque en Bloques de Código
• Diferencias Coloreadas en Bloques de Código
• Errores y Avisos en Bloques de Código
• Números de Linea
• Importar Snippets de Código
• Grupos de Código
• Inclusión de Archivo Markdown

La presentación de TOC (Table of Contents) puede ser configurada usando la opción markdown.toc.

Contenedores Personalizados

Contenedores personalizados pueden ser definidos por sus tipos, títulos y contenidos.

Título por Defecto

Entrada

::: info
Este es un bloque de información.
:::

::: tip
Este es un aviso.
:::

::: warning
Esto es una advertencia.
:::

::: danger
Este es un aviso de peligro.
:::

::: details
Este es un bloque de detalles.
:::

Salida

INFO

Este es un bloque de información.

TIP

Este es un aviso.

WARNING

Esto es una advertencia.

DANGER

Este es un aviso de peligro.

Details

Este es un bloque de detalles.

Título Personalizado

Puede definir un título personalizado adicionando el texto inmediatamente después del "tipo" del recipiente.

Entrada

::: danger STOP
Zona de peligro, no siga
:::

::: details Click para ver el código
```js
console.log('Hola, VitePress!')

:::

Salida

STOP

Zona de peligro, no siga

Click para ver el código

console.log('Hola, VitePress!')

Además de eso, puede definir títulos personalizados globalmente adicionando el siguiente contenifo en el archivo de configuración del sitio, útil si no estuviera escribiendo en ingles:

// config.ts
export default defineConfig({
  // ...
  markdown: {
    container: {
      tipLabel: '提示',
      warningLabel: '警告',
      dangerLabel: '危险',
      infoLabel: '信息',
      detailsLabel: '详细信息'
    }
  }
  // ...
})

raw

Este es un recipiente especial que puee ser usado para evitar conflictos de estilo y enrutador con VitePress. Esto es especialmente útil al documentar bibliotecas de componentes. Puede tambien verificar whyframe para mejor aislamiento.

Sintaxis

::: raw
Envuelve en un `<div class="vp-raw">`
:::

La clase vp-raw también puede ser usada directamente en elementos. El aislamiento de estilo es actualmente opcional:

• Instale postcss con su gestor de paquetes preferido:

  $ npm add -D postcss

• Cree un archivo llamado docs/postcss.config.mjs y adicione lo siguiente:

  import { postcssIsolateStyles } from 'vitepress'
  
  export default {
    plugins: [postcssIsolateStyles()]
  }

  El utiliza postcss-prefix-selector internamente. Puede pasar opciones así:

  postcssIsolateStyles({
    includeFiles: [/vp-doc\.css/] // o padrão é /base\.css/
  })

Alertas en estilo GitHub

VitePress también soporta alertas en estilo GitHub para presentar como un bloque de llamada. Ellos serán presentados de la misma forma que elementos personalizados.

> [!NOTE]
> Destaca informaciones que los usuarios deben tener en consideración, incluso leyendo rapidamente.

> [!TIP]
> Informaciones opcionales para ayudar al usuario a tener más éxito.

> [!IMPORTANT]
> Informaciones cruciales necesarias par que los usuarios tengan éxito.

> [!WARNING]
> Contenido critico exigiendo atención inmediata del usuario debido a riesgos potenciales.

> [!CAUTION]
> Potenciales consecuencias negativas de una acción.

NOTE

Destaca informaciones que los usuarios deben tener en consideración, incluso leyendo rapidamente.

TIP

Informaciones opcionales para ayudar al usuario a tener más éxito.

IMPORTANT

Informaciones cruciales necesarias par que los usuarios tengan éxito.

WARNING

Contenido critico exigiendo atención inmediata del usuario debido a riesgos potenciales.

CAUTION

Potenciales consecuencias negativas de una acción.

Destaque de Sintaxis en Bloques de Código

VitePress utiliza Shiki para destacar la sintaxis del lenguaje en bloques de código Markdown, usando texto coloreado. Shiki soporta una amplia variedad de lenguajes de programación. Todo lo que necesita es adicionar un alias de lenguaje válido después de los backticks iniciales del bloque de código:

Entrada

```js
export default {
  name: 'MyComponent',
  // ...
}
```

```html
<ul>
  <li v-for="todo in todos" :key="todo.id">
    {{ todo.text }}
  </li>
</ul>
```

Salida

export default {
  name: 'MyComponent'
  // ...
}

<ul>
  <li v-for="todo in todos" :key="todo.id">
    {{ todo.text }}
  </li>
</ul>

Una lista de lenguajes válidas está disponible en el repositório Shiki.

También puede personalizar el tema de destaque de sintaxis en la configuración de la aplicación. Consulte las opciones markdown para más detalles.

Destaque de Linea en Bloques de Código

Entrada

```js{4}
export default {
  data () {
    return {
      msg: 'Destacado!'
    }
  }
}
```

Salida

export default {
  data () {
    return {
      msg: 'Destacado!'
    }
  }
}

Además de una única linea, puede también especificar múltiples lineas únicas, intervalos, o ambos:

• Intervalos de linea: por ejemplo, {5-8}, {3-10}, {10-17}
• Múltiples lineas únicas: por ejemplo, {4,7,9}
• Intervalos de linea y lineas únicas: por ejemplo, {4,7-13,16,23-27,40}

Entrada

```js{1,4,6-8}
export default { // Destacado
  data () {
    return {
      msg: `Destacado!
      Esta linea no está destacada,
      pero esta y las próximas están.`,
      motd: 'VitePress es increible',
      lorem: 'ipsum'
    }
  }
}
```

Salida

export default { // Destacado
  data () {
    return {
      msg: `Destacado!
      Esta linea no está destacada,
      pero esta y las próximas están.`,
      motd: 'VitePress es increible',
      lorem: 'ipsum',
    }
  }
}

Alternativamente, es posible destacar directamente en la linea usando el comentario // [!code highlight].

Entrada

```js
export default {
  data () {
    return {
      msg: 'Destacado!' // [!code highlight]
    }
  }
}
```

Saída

export default {
  data() {
    return {
      msg: 'Destacado!'
    }
  }
}

Enfoque en Bloques de Código

Adicionando el comentario // [!code focus] en una linea, esta será destacada y desenfocará las otras partes del código.

Además, puede definir el número de lineas para enfocar usando // [!code focus:<lineas>].

Entrada

```js
export default {
  data () {
    return {
      msg: 'Enfocado!' // [!code focus]
    }
  }
}
```

Salida

export default {
  data() {
    return {
      msg: 'Enfocado!'
    }
  }
}

Diferencias Coloreadas en Bloques de Código

Adicionar los comentarios // [!code --] o // [!code ++] en una linea creará una diferencia en esa linea, manteniendo los colores del bloque de código.

Entrada

```js
export default {
  data () {
    return {
      msg: 'Borrado' // [!code --]
      msg: 'Adicionado' // [!code ++]
    }
  }
}
```

Salida

export default {
  data () {
    return {
      msg: 'Borrado'
      msg: 'Adicionado'
    }
  }
}

Errores y Avisos en Bloques de Código

Adicionar los comentarios // [!code warning] o // [!code error] en una linea coloreará los bloques conforme necesário.

Entrada

```js
export default {
  data () {
    return {
      msg: 'Error', // [!code error]
      msg: 'Aviso' // [!code warning]
    }
  }
}
```

Salida

export default {
  data() {
    return {
      msg: 'Error', 
      msg: 'Aviso'
    }
  }
}

Números de Linea

Puede habilitar números de linea para cada bloque de código a través del archivo de configuración:

export default {
  markdown: {
    lineNumbers: true
  }
}

Consulte las opciones markdown para más detalles.

Puede adicionar la marca :line-numbers / :no-line-numbers en sus bloques de código para substituir el valor definido en la configuración.

También puede personalizar el número inicial de linea adicionando = después :line-numbers. Por ejemplo, :line-numbers=2 significa que los números de las lineas en los bloques de código comenzarán a partir de 2.

Entrada

```ts {1}
// números de linea desactivados por defecto
const line2 = 'Esta es la linea 2'
const line3 = 'Esta es la linea 3'
```

```ts:line-numbers {1}
// números de linea activados
const line2 = 'Esta es la linea 2'
const line3 = 'Esta es la linea 3'
```

```ts:line-numbers=2 {1}
// números de linea activados y comienzan en 2
const line3 = 'Esta es la linea 3'
const line4 = 'Esta es la linea 4'
```

Salida

// números de linea desactivados por defecto
const line2 = 'Esta es la linea 2'
const line3 = 'Esta es la linea 3'

// números de linea activados
const line2 = 'Esta es la linea 2'
const line3 = 'Esta es la linea 3'

// números de linea activados y comienzan en 2
const line3 = 'Esta es la linea 3'
const line4 = 'Esta es la linea 4'

Importar Snippets de Código

Puede importar pedazos de código de archivos existentes usando la siguiente sintaxis:

<<< @/filepath

También soporta destaque de linea:

<<< @/filepath{highlightLines}

Entrada

<<< @/snippets/snippet.js{2}

Archivo de Código

export default function () {
  // ..
}

Salida

export default function () {
  // ..
}

TIP

El valor de @ corresponde a la raiz del código fuente. Por defecto, es la raiz del proyecto VitePress, a menos que srcDir sea configurado. Alternativamente, puede también importar de paths relativos:

<<< ../snippets/snippet.js

También puede usar una región VS Code para incluir apenas la parte correspondiente del archivo de código. Puede proporcionar un nombre de región personalizado después de # siguiendo el path del archivo:

Entrada

<<< @/snippets/snippet-with-region.js#snippet{1}

Archivo de Código

// #region snippet
function foo() {
  // ..
}
// #endregion snippet

export default foo

Salida

function foo() {
  // ..
}

También puede especificar el idioma dentro de llaves ({}), así:

<<< @/snippets/snippet.cs{c#}

<!-- con destaque de linea: -->

<<< @/snippets/snippet.cs{1,2,4-6 c#}

<!-- con números de linea: -->

<<< @/snippets/snippet.cs{1,2,4-6 c#:line-numbers}

Esto es útil si el lenguaje original no puede ser inferida por la extensión de archivo.

Grupos de Código

Puede agrupar varios bloques de código así:

Entrada

::: code-group

```js [config.js]
/**
 * @type {import('vitepress').UserConfig}
 */
const config = {
  // ...
}

export default config
```

```ts [config.ts]
import type { UserConfig } from 'vitepress'

const config: UserConfig = {
  // ...
}

export default config
```

:::

Salída

config.js

/**
 * @type {import('vitepress').UserConfig}
 */
const config = {
  // ...
}

export default config

config.ts

import type { UserConfig } from 'vitepress'

const config: UserConfig = {
  // ...
}

export default config

También puede importar snippets de código en grupos de código:

Entrada

::: code-group

<!-- nombre de archivo usado como título por defecto -->

<<< @/snippets/snippet.js

<!-- puede proporcionar uno personalizado también -->

<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region]

:::

Output

snippet.js

export default function () {
  // ..
}

snippet with region

function foo() {
  // ..
}

Inclusión de Archivo Markdown

Puede incluir un archivo markdown en otro archvo markdown, incluso anidado.

TIP

Puede prefijar el path del markdown con @, el actuará como la raiz de origen. Por defecto, es la raiz del projecto VitePress, a menos que srcDir sea configurado.

Por ejemplo, puede incluir un archivo markdown relativo usando esto:

Entrada

# Documentación

## Conceptos Básicos

<!--@include: ./parts/basics.md-->

Archivo de Parte (parts/basics.md)

Algunas cosas básicas.

### Configuración

Puede ser creada usando `.foorc.json`.

Código Equivalente

# Documentación

## Conceptos básicos

Algunas cosas básicas

### Configuración

Puede ser creada usando `.foorc.json`.

También soporta la selección de un intervalo de lineas:

Entrada

# Documentación

## Conceptos Básicos

<!--@include: ./parts/basics.md{3,}-->

Archivo de Parte (parts/basics.md)

Algunas cosas básicas.

### Configuración

Puede ser creada usando `.foorc.json`.

Código Equivalente

# Documentación

## Conceptos Básicos

### Configuración

Puede ser creada usando `.foorc.json`.

El formato del intervalo de lineas seleccionado puede ser: {3,}, {,10}, {1,10}

WARNING

Observe que esto no genera errores si el archivo no está presente. Por lo tanto, al usar este recurso, asegurese de que el contenido está siendo mostrado como se espera.:::

Ecuaciones Matemáticas

Esto es actualmente opcional. Para activarlo, necesita instalar markdown-it-mathjax3 y definir markdown.math como true en su archivo de configuración:

npm add -D markdown-it-mathjax3

.vitepress/config.ts

export default {
  markdown: {
    math: true
  }
}

Entrada

Cuando $a \ne 0$, existen dos soluciones para $(ax^2 + bx + c = 0)$ y ellas son
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$

**Ecuaciones de Maxwell:**

| ecuación                                                                                                                                                                  | descripción                                                                                |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| $\nabla \cdot \vec{\mathbf{B}}  = 0$                                                                                                                                      | la divergencia de $\vec{\mathbf{B}}$ es cero                                               |
| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t}  = \vec{\mathbf{0}}$                                                          | la rotacional de $\vec{\mathbf{E}}$ es proporcional a la tasa de variación de $\vec{\mathbf{B}}$ |
| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}}    \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _hã?_                                                                                     |

**Salída**

Cuando $a \ne 0$, existen dos soluciones para $(ax^2 + bx + c = 0)$ y ellas son
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$

**Ecuaciones de Maxwell:**

| ecuación                                                                                                                                                                  | descripción                                                                                |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| $\nabla \cdot \vec{\mathbf{B}}  = 0$                                                                                                                                      | la divergencia de $\vec{\mathbf{B}}$ es cero                                               |
| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t}  = \vec{\mathbf{0}}$                                                          | la rotacional de $\vec{\mathbf{E}}$ es proporcional a la tasa de variación de $\vec{\mathbf{B}}$ |
| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}}    \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _hã?_                                                                                     |

## _Lazy Loading_ de Imagenes {#image-lazy-loading}

Puede activar la "carga perezosa" para cada imagen adicionada via markdown definiendo `lazyLoading` como `true` en su archivo de configuración:

```js
export default {
  markdown: {
    image: {
      // la carga perezosa de imagenes está desactivada por defecto
      lazyLoading: true
    }
  }
}

Configuración Avanzada

VitePress usa markdown-it como interprete Markdown. Muchas de las extensiones arriba son implementadas por medio de plugins personalizados. Puede personalizar más la instancia markdown-it usando la opción markdown en .vitepress/config.js:

import { defineConfig } from 'vitepress'
import markdownItAnchor from 'markdown-it-anchor'
import markdownItFoo from 'markdown-it-foo'

export default defineConfig({
  markdown: {
    // opciones para markdown-it-anchor
    // https://github.com/valeriangalliat/markdown-it-anchor#usage
    anchor: {
      permalink: markdownItAnchor.permalink.headerLink()
    },

    // opciones para @mdit-vue/plugin-toc
    // https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
    toc: { level: [1, 2] },

    config: (md) => {
      // use más plugins markdown-it!
      md.use(markdownItFoo)
    }
  }
})

Consulte la lista completa de propiedades configurables en Referencia de Configuración: Configuración de la Aplicación.