Resaltado de sintaxis

Astro viene con soporte integrado para Shiki y Prism. Esto proporciona resaltado de sintaxis para:

todos los bloques de código (```) usados en un archivo Markdown o MDX.
el contenido dentro del componente integrado <Code /> (con tecnología de Shiki) en archivos .astro.
el contenido dentro del componente <Prism /> (con tecnología de Prism) en archivos .astro.

Añade integraciones de la comunidad como Expressive Code para aún más opciones de marcado de texto y anotaciones en tus bloques de código.

Bloques de código de Markdown

Un bloque de código de Markdown se indica con un bloque de tres backticks ``` al inicio y al final. Puedes indicar el lenguaje de programación usado después de los backticks de apertura para indicar cómo colorear y estilizar tu código para hacerlo más fácil de leer.

```js
// JavaScript code with syntax highlighting.
var fun = function lang(l) {
  dateformat.i18n = require('./lang/' + l);
  return true;
};
```

Los bloques de código de Markdown de Astro se estilizan con Shiki por defecto, preconfigurados con el tema github-dark. La salida compilada se limitará a styles inline sin ninguna clase CSS extraña, hojas de estilos, o JS del lado del cliente.

Puedes añadir una hoja de estilos de Prism y cambiar al resaltado de Prism, o deshabilitar el resaltado de sintaxis de Astro por completo, con la opción de configuración markdown.syntaxHighlight.

Consulta la referencia completa de markdown.shikiConfig para el conjunto completo de opciones de resaltado de sintaxis de Markdown disponibles al usar Shiki.

Establecer un tema de Shiki por defecto

Puedes configurar cualquier tema integrado de Shiki para tus bloques de código de Markdown en tu configuración de Astro:

import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    shikiConfig: {
      theme: 'dracula',
    },
  },
});

Consulta la referencia completa de configuración de Shiki para el conjunto completo de opciones de bloques de código de Markdown.

Establecer temas de modo claro y oscuro

Puedes especificar temas duales de Shiki para modo claro y oscuro en tu configuración de Astro:

import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    shikiConfig: {
      themes: {
        light: 'github-light',
        dark: 'github-dark',
      },
    },
  },
});

Luego, añade las variables CSS del modo oscuro de Shiki vía media query o clases para aplicarlas a todos tus bloques de código de Markdown por defecto. Reemplaza la clase .shiki en los ejemplos de la documentación de Shiki con .astro-code:

@media (prefers-color-scheme: dark) {
  .shiki,
  .shiki span {
  .astro-code,
  .astro-code span {
    color: var(--shiki-dark) !important;
    background-color: var(--shiki-dark-bg) !important;
    /* Optional, if you also want font styles */
    font-style: var(--shiki-dark-font-style) !important;
    font-weight: var(--shiki-dark-font-weight) !important;
    text-decoration: var(--shiki-dark-text-decoration) !important;
  }
}

Consulta la referencia completa de configuración de Shiki para el conjunto completo de opciones de bloques de código de Markdown.

Añadir tu propio tema de Shiki

En lugar de usar uno de los temas predefinidos de Shiki, puedes importar un tema personalizado de Shiki desde un archivo local.

import { defineConfig } from 'astro/config';
import customTheme from './my-shiki-theme.json';

export default defineConfig({
  markdown: {
    shikiConfig: {
      theme: customTheme,
    },
  },
});

Personalizar temas de Shiki

Puedes seguir la documentación de temas de Shiki para más opciones de personalización de temas, alternar entre modo claro y oscuro, o estilizar vía variables CSS.

Necesitarás ajustar los ejemplos de la documentación de Shiki para tu proyecto de Astro haciendo las siguientes sustituciones:

Los bloques de código se estilizan usando la clase .astro-code en lugar de .shiki
Cuando se usa el tema css-variables, las propiedades personalizadas se prefijan con --astro-code- en lugar de --shiki-

Componentes para bloques de código

Hay dos componentes de Astro disponibles para archivos .astro y .mdx para renderizar bloques de código: <Code /> y <Prism />.

Puedes referenciar las Props de estos componentes usando la utilidad de tipo ComponentProps.

`<Code />`

Este componente está impulsado internamente por Shiki. Soporta todos los temas y lenguajes populares de Shiki así como varias otras opciones de Shiki como temas personalizados, lenguajes, transformers, y colores por defecto.

Estos valores se pasan al componente <Code /> usando los atributos theme, lang, embeddedLangs, transformers, y defaultColor respectivamente como props. El componente <Code /> no heredará tus ajustes de shikiConfig para bloques de código de Markdown.

---
import { Code } from 'astro:components';
---
<!-- Syntax highlight some JavaScript code. -->
<Code code={`const foo = 'bar';`} lang="js" />
<!-- Optional: Customize your theme. -->
<Code code={`const foo = 'bar';`} lang="js" theme="dark-plus" />
<!-- Optional: Enable word wrapping. -->
<Code code={`const foo = 'bar';`} lang="js" wrap />
<!-- Optional: Output inline code. -->
<p>
  <Code code={`const foo = 'bar';`} lang="js" inline />
  will be rendered inline.
</p>
<!-- Optional: defaultColor -->
<Code code={`const foo = 'bar';`} lang="js" defaultColor={false} />

`embeddedLangs`

Type: string[] | undefined

Añadido en: astro@6.0.0

Cualquier lenguaje adicional a incluir para el resaltado de sintaxis por Shiki.

Un valor de lang puede incluir soporte para resaltar algunos lenguajes adicionales por defecto (p. ej. lang="svelte" también proporcionará resaltado para ts).

Usa embeddedLangs para incluir soporte para combinaciones de lenguajes adicionales no estándar (p. ej. soporte para jsx cuando lang="vue").

---
import { Code } from 'astro:components'

const code = `<script setup lang="tsx">
const Text = ({ text }: { text: string }) => <div>{text}</div>;
</script>

<template>
  <Text text="Hello world" />
</template>
`
---
<Code
  lang="vue"
  embeddedLangs={["tsx"]}
  code={code}
/>

`transformers`

Type: ShikiTransformer[] | undefined

Añadido en: astro@4.11.0

Un array de transformers de Shiki para aplicar a tu code. Desde Astro v4.14.0, también puedes proporcionar un string para el atributo meta de Shiki para pasar opciones a los transformers.

Ten en cuenta que transformers solo aplica clases y debes proporcionar tus propias reglas CSS para apuntar a los elementos de tu bloque de código.

---
import { transformerNotationFocus, transformerMetaHighlight } from '@shikijs/transformers'
import { Code } from 'astro:components'
const code = `const foo = 'hello'
const bar = ' world'
console.log(foo + bar) // [!code focus]
`
---
<Code
  code={code}
  lang="js"
  transformers={[transformerMetaHighlight()]}
  meta="{1,3}"
/>

<style is:global>
  pre.has-focused .line:not(.focused) {
    filter: blur(1px);
  }
</style>

`<Prism />`

Este componente proporciona resaltado de sintaxis específico del lenguaje para bloques de código aplicando las clases CSS de Prism. Ten en cuenta que debes proporcionar una hoja de estilos CSS de Prism (o traer la tuya propia) para estilizar las clases.

Para usar el componente de resaltado Prism, debes instalar el paquete @astrojs/prism:

npm install @astrojs/prism

pnpm add @astrojs/prism

yarn add @astrojs/prism

Luego, puedes importar y usar el componente <Prism /> como cualquier otro componente de Astro, pasando un lenguaje y el código a renderizar.

---
import { Prism } from '@astrojs/prism';
---
<Prism lang="js" code={`const foo = 'bar';`} />

Además de la lista de lenguajes soportados por Prism, también puedes usar lang="astro" para mostrar bloques de código de Astro.

Añadir una hoja de estilos de Prism

Si optas por usar Prism (ya sea configurando markdown.syntaxHighlight: 'prism' o con el componente <Prism />), Astro aplicará las clases CSS de Prism en lugar de las de Shiki a tu código. Necesitarás traer tu propia hoja de estilos CSS para que el resaltado de sintaxis aparezca.

Elige una hoja de estilos prefabricada de los Prism Themes disponibles.
Añade esta hoja de estilos al directorio public/ de tu proyecto.
Cárgala en el <head> de tu página en un componente layout vía una etiqueta <link>. (Consulta uso básico de Prism.)

También puedes visitar la lista de lenguajes soportados por Prism para opciones y uso.

Contribuir Comunidad Patrocinar