diff --git a/docs/es/guide/markdown.md b/docs/es/guide/markdown.md new file mode 100644 index 00000000..a48fc50b --- /dev/null +++ b/docs/es/guide/markdown.md @@ -0,0 +1,930 @@ +# Extensiones Markdown {#markdown-extensions} + +VitePress viene con Extensiones embutidas. + +## Anchors de Header {#header-anchors} + +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 {#custom-anchors} + +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 {#links} + +Ambos links internos y externos reciben tratamiento especial. + +### Links Internos {#internal-links} + +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`: + +```md +[Página Inicial](/) +[foo](/foo/) +[foo heading](./#heading) +[bar - three](../bar/three) +[bar - three](../bar/three.md) +[bar - four](../bar/four.html) +``` + +### Sufijo de Página {#page-suffix} + +Páginas y links internos son generados con el sufijo `.html` por defecto. + +### Links Externos {#external-links} + +Links externos reciben automáticamente `target="_blank" rel="noreferrer"`: + +- [vuejs.org](https://vuejs.org) +- [VitePress no GitHub](https://github.com/vuejs/vitepress) + +## Frontmatter {#frontmatter} + +[YAML frontmatter](https://jekyllrb.com/docs/front-matter/) es soportado por defecto: + +```yaml +--- +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](../reference/frontmatter-config). + +## Tablas al Estilo GitHub {#github-style-tables} + +**Entrada** + +```md +| 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 :tada: + +**Entrada** + +``` +:tada: :100: +``` + +**Salida** + +:tada: :100: + +Una [lista de todos los emojis](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/full.mjs) está disponible. + +## Tabla de Contenido (TOC) + +**Entrada** + +``` +[[toc]] +``` + +**Salida** + +[[toc]] + +La presentación de TOC (Table of Contents) puede ser configurada usando la opción `markdown.toc`. + +## Contenedores Personalizados {#custom-containers} + +Contenedores personalizados pueden ser definidos por sus tipos, títulos y contenidos. + +### Título por Defecto {#default-title} + +**Entrada** + +```md +::: 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 {#custom-title} + +Puede definir un título personalizado adicionando el texto inmediatamente después del "tipo" del recipiente. + +**Entrada** + +```md +::: danger STOP +Zona de peligro, no siga +::: + +::: details Click para ver el código +```js +console.log('Hola, VitePress!') +``` +::: +``` +``` + +**Salida** + +::: danger STOP +Zona de peligro, no siga +::: + +::: details Click para ver el código +```js +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: + +```ts +// 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](https://whyframe.dev/docs/integrations/vitepress) para mejor aislamiento. + +**Sintaxis** + +```md +::: raw +Envuelve en un
+::: +``` + +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: + + ```sh + $ npm add -D postcss + ``` + +- Cree un archivo llamado `docs/postcss.config.mjs` y adicione lo siguiente: + + ```js + import { postcssIsolateStyles } from 'vitepress' + + export default { + plugins: [postcssIsolateStyles()] + } + ``` + + El utiliza [`postcss-prefix-selector`](https://github.com/postcss/postcss-load-config) internamente. Puede pasar opciones así: + + ```js + postcssIsolateStyles({ + includeFiles: [/vp-doc\.css/] // o padrão é /base\.css/ + }) + ``` + +## Alertas en estilo GitHub {#github-flavored-alerts} + +VitePress también soporta [alertas en estilo GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) para presentar como un bloque de llamada. Ellos serán presentados de la misma forma que [elementos personalizados](#custom-containers). + +```md +> [!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 {#syntax-highlighting-in-code-blocks} + +VitePress utiliza [Shiki](https://github.com/shikijs/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 + +``` +```` + +**Salida** + +```js +export default { + name: 'MyComponent' + // ... +} +``` + +```html + +``` + +Una [lista de lenguajes válidas](https://shiki.style/languages) 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`](../reference/site-config#markdown) para más detalles. + +## Destaque de Linea en Bloques de Código {#line-highlighting-in-code-blocks} + +**Entrada** + +```` +```js{4} +export default { + data () { + return { + msg: 'Destacado!' + } + } +} +``` +```` + +**Salida** + +```js{4} +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** + +```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', + } + } +} +``` + +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** + +```js +export default { + data() { + return { + msg: 'Destacado!' // [!code highlight] + } + } +} +``` + +## Enfoque en Bloques de Código {#focus-in-code-blocks} + +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:]`. + +**Entrada** + +```` +```js +export default { + data () { + return { + msg: 'Enfocado!' // [!!code focus] + } + } +} +``` +```` + +**Salida** + +```js +export default { + data() { + return { + msg: 'Enfocado!' // [!code focus] + } + } +} +``` + +## Diferencias Coloreadas en Bloques de Código {#colored-diffs-in-code-blocks} + +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** + +```js +export default { + data () { + return { + msg: 'Borrado' // [!code --] + msg: 'Adicionado' // [!code ++] + } + } +} +``` + +## Errores y Avisos en Bloques de Código {#errors-and-warnings-in-code-blocks} + +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** + +```js +export default { + data() { + return { + msg: 'Error', // [!code error] + msg: 'Aviso' // [!code warning] + } + } +} +``` + +## Números de Linea {#line-numbers} + +Puede habilitar números de linea para cada bloque de código a través del archivo de configuración: + +```js +export default { + markdown: { + lineNumbers: true + } +} +``` + +Consulte las [opciones markdown](../reference/site-config#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** + +````md +```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** + +```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' +``` + +## Importar _Snippets_ de Código {#import-code-snippets} + +Puede importar pedazos de código de archivos existentes usando la siguiente sintaxis: + +```md +<<< @/filepath +``` + +También soporta [destaque de linea](#line-highlighting-in-code-blocks): + +```md +<<< @/filepath{highlightLines} +``` + +**Entrada** + +```md +<<< @/snippets/snippet.js{2} +``` + +**Archivo de Código** + +<<< @/snippets/snippet.js + +**Salida** + +<<< @/snippets/snippet.js{2} + +::: 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: + +```md +<<< ../snippets/snippet.js +``` + +::: + +También puede usar una [región VS Code](https://code.visualstudio.com/docs/editor/codebasics#_folding) 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** + +```md +<<< @/snippets/snippet-with-region.js#snippet{1} +``` + +**Archivo de Código** + +<<< @/snippets/snippet-with-region.js + +**Salida** + +<<< @/snippets/snippet-with-region.js#snippet{1} + +También puede especificar el idioma dentro de llaves (`{}`), así: + +```md +<<< @/snippets/snippet.cs{c#} + + + +<<< @/snippets/snippet.cs{1,2,4-6 c#} + + + +<<< @/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 {#code-groups} + +Puede agrupar varios bloques de código así: + +**Entrada** + +````md +::: code-group + +```js [config.js] +/** + * @type {import('vitepress').UserConfig} + */ +const config = { + // ... +} + +export default config +``` + +```ts [config.ts] +import type { UserConfig } from 'vitepress' + +const config: UserConfig = { + // ... +} + +export default config +``` + +::: +```` + +**Salída** + +::: 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 +``` + +::: + +También puede [importar _snippets_ de código](#import-code-snippets) en grupos de código: + +**Entrada** + +```md +::: code-group + + + +<<< @/snippets/snippet.js + + + +<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region] + +::: +``` + +**Output** + +::: code-group + +<<< @/snippets/snippet.js + +<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region] + +::: + +## Inclusión de Archivo Markdown {#markdown-file-inclusion} + +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** + +```md +# Documentación + +## Conceptos Básicos + + +``` + +**Archivo de Parte** (`parts/basics.md`) + +```md +Algunas cosas básicas. + +### Configuración + +Puede ser creada usando `.foorc.json`. +``` + +**Código Equivalente** + +```md +# 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** + +```md +# Documentación + +## Conceptos Básicos + + +``` + +**Archivo de Parte** (`parts/basics.md`) + +```md +Algunas cosas básicas. + +### Configuración + +Puede ser creada usando `.foorc.json`. +``` + +**Código Equivalente** + +```md +# 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 {#math-equations} + +Esto es actualmente opcional. Para activarlo, necesita instalar `markdown-it-mathjax3` y definir `markdown.math` como `true` en su archivo de configuración: + +```sh +npm add -D markdown-it-mathjax3 +``` + +```ts +// .vitepress/config.ts +export default { + markdown: { + math: true + } +} +``` + +**Entrada** + +```md +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 {#advanced-configuration} + +VitePress usa [markdown-it](https://github.com/markdown-it/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`: + +```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](../reference/site-config#markdown). \ No newline at end of file