Markdown y MDX
El Markdown se usa comúnmente para crear contenido con mucho texto, como artículos de blog y documentación. Astro incluye soporte integrado para archivos estándar de Markdown, que también pueden incluir frontmatter YAML para definir metadatos personalizados como un título, descripción y etiquetas.
Con la integración @astrojs/mdx instalada, Astro también soporta archivos MDX (.mdx
) los cuales poseen algunas características adicionales como soporte para expresiones JavaScript y componentes en un contenido Markdown.
¡Utiliza cualquiera de ambos (o ambos) para escribir tu contenido Markdown!
Páginas de Markdown y MDX
Sección titulada Páginas de Markdown y MDXColecciones de contenido
Sección titulada Colecciones de contenidoPuedes gestionar tus archivos Markdown y MDX en Astro en una carpeta especial src/content/
. Las colecciones de contenido te ayudan a organizar tu contenido, validar tu frontmatter y proporcionar seguridad de tipo TypeScript automática mientras trabajas con tu contenido.
Directorysrc/content/
Directorynewsletter/
- week-1.md
- week-2.md
Directoryauthors/
- grace-hopper.md
- alan-turing.md
Ver más sobre el uso de colecciones de contenido en Astro.
Enrutamiento basado en archivos
Sección titulada Enrutamiento basado en archivosAstro trata cualquier archivo .md
(u otra extensión alternativa soportada) o .mdx
dentro de la carpeta /src/pages
como una página.
Al colocar un archivo en esta carpeta, o en cualquier subcarpeta, se creará automáticamente una ruta de página utilizando la ruta del archivo.
Características de Markdown
Sección titulada Características de MarkdownAstro provee algunas características adicionales incorporadas disponibles a la hora de usar Markdown y archivos MDX.
layout
en el Frontmatter
Sección titulada layout en el FrontmatterAstro provee a las páginas de Markdown y MDX (localizadas en src/pages/
) una propiedad especial en el frontmatter para layout
que define la ruta relativa (o un alias) a un componente plantilla de Astro.
Luego las propiedades especificas están disponibles para el componente plantilla a través de Astro.props
. Por ejemplo, puedes acceder a las propiedades del frontmatter a través de Astro.props.frontmatter
:
Puedes también aplicar estilos al Markdown en tu componente plantilla.
IDs de Encabezado
Sección titulada IDs de EncabezadoUsar títulos en Markdown y MDX generará automáticamente los hipervínculos anchor para vincular directamente a diferentes secciones de tu página.
Astro genera id
s de encabezado basados en github-slugger
. Puedes encontrar más ejemplos en la documentación de github-slugger.
Escapando caracteres especiales
Sección titulada Escapando caracteres especialesCiertos caracteres tienen un significado especial en Markdown y MDX. Puedes necesitar usar una sintaxis diferente si deseas mostrarlos. Para hacer esto, puedes usar entidades HTML para esos caracteres en su lugar.
Por ejemplo, para prevenir que <
sea interpretado como el inicio de un elemento HTML, escribe <
. O, para prevenir que {
sea interpretado como el inicio de una expesión de JavaScript en MDX, escribe {
.
Características de MDX únicamente
Sección titulada Características de MDX únicamenteAñadiendo la integración de MDX de Astro vas a potenciar tu autoría de Markdown con variables JSX, expresiones y componentes.
También añade características extra al MDX estándar, incluyendo soporte para frontmatter del estilo Markdown en MDX. Esto te permite usar la mayoría de las características incorporadas en Astro de Markdown como la propiedad layout
en el frontmatter.
Los archivos .mdx
deben ser escritos usando sintaxis de MDX en vez de la sintaxis de tipo HTML de Astro.
Usando Variables Exportadas en MDX
Sección titulada Usando Variables Exportadas en MDXMDX admite usar declaraciones export
para añadir variables a tu contenido MDX. Estas variables son accesibles tanto en el template como propiedades nombradas al momento de importar el archivo en algún otro lugar.
Por ejemplo, puedes exportar un campo title
desde una página o componente MDX para usar como título usando {expresiones JSX}
:
Usando Variables de Frontmatter en MDX
Sección titulada Usando Variables de Frontmatter en MDXLa integración con MDX de Astro incluye soporte para utilizar frontmatter en MDX de manera predeterminada. Puedes agregar propiedades de frontmatter de la misma manera que lo harías en archivos Markdown y esas variables son accesibles para usar en el template, en su componente layout
y como propiedades nombradas al momento de importar el archivo en algún otro lugar.
Usando Componentes en MDX
Sección titulada Usando Componentes en MDXLuego de instalar la integración con MDX, puedes importar y utilizar ambos componentes de Astro components y componentes de frameworks UI en archivos MDX (.mdx
) de la misma manera que los usarías en cualquier otro componente de Astro.
¡No olvides agregar una directiva client:
en tus componentes de frameworks UI si es necesario!
Puedes ver más ejemplos de declaraciones de import y export en la documentación de MDX.
Asignando Componentes Personalizados a elementos HTML
Sección titulada Asignando Componentes Personalizados a elementos HTMLCon MDX, puedes mapear sintaxis de Markdown a componentes personalizados en vez de sus elementos HTML estándar. Esto te permite escribir usando sintaxis común de Markdown pero aplicando estilo de componentes especiales a los elementos seleccionados.
Importa tus componentes personalizados en tu archivo .mdx
, luego exporta un objeto components
que mapee el elemento HTML estándar a tu componente personalizado:
Puedes visitar el sitio de MDX para ver la lista completa de elementos HTML que pueden ser sobreescritos con componentes personalizados.
Importando Markdown
Sección titulada Importando MarkdownPuedes importar archivos Markdown y MDX directamente en tus archivos Astro. Esto te da acceso a su contenido Markdown como así también otras propiedades como valores de frontmatter, que puedes utilizar en expresiones JSX-like de Astro.
Puedes importar una página específica con una declaración import
, o varias con Astro.glob()
.
Cuando importas archivos Markdown y MDX en un componente Astro, puedes acceder a un objeto conteniendo sus propiedades exportadas.
En archivos MDX, puedes acceder a propiedades tanto del frontmatter como de las declaraciones export
:
Opcionalmente, puedes proporcionar un tipo para la variable frontmatter
usando un genérico de TypeScript:
Propiedades exportadas
Sección titulada Propiedades exportadasPuedes ver las propiedades exportadas a un componente de plantilla de Astro cuando usas el layout en el Frontmatter especial de Astro
Estas propiedades están disponibles en un componente .astro
cuando usas una declaración import
o Astro.glob()
:
file
- La ruta absoluta de este archivo (por ejemplo,/home/user/projects/.../file.md
).url
- Si es una página, su URL (por ejemplo,/en/guides/markdown-content
).frontmatter
- Contiene la data especificada en el YAML del frontmatter del archivo.getHeadings
- Una función asincrónica que devuelte un array de todos los encabezados (h1 -> h6
) en el archivo. Cadaslug
del encabezado corresponde al ID generado para cada encabezado y puede usarse para hipervínculos anchor. Esta lista tiene la siguiente forma de datos:{ depth: number; slug: string; text: string }[]
.content
- Un componente que devuelve el contenido completo y renderizado del archivo.- (Solamente Markdown)
rawContent()
- Una función que devuelve el documento Markdown como string. - (Solamente Markdown)
compiledContent()
- Una función que devuelve el documento Markdown compilado a un string HTML. ¡Ten en cuenta que esto no incluye plantillas configuradas en tu frontmatter! Solamente el documento markdown va a ser devuelto como HTML. - (Solamente MDX) - Los archivos MDX también pueden exportar data con una declaración
export
.
El componente Content
Sección titulada El componente ContentImporta Content
para renderizar un componente que devuelve el contenido completo de un archivo Markdown o MDX:
Ejemplo: Enrutamiento de página dinámico
Sección titulada Ejemplo: Enrutamiento de página dinámicoSi no deseas poner tus archivos Markdown/MDX en la carpeta src/pages
para crear rutas de página, puedes generar páginas dinámicamente.
Para acceder al contenido Markdown, puedes pasar el componente <Content/>
a través de las props
de la página Astro. Luego, puedes obtener el componente desde Astro.props
y renderizarlo en tu plantilla.
Exportación en MDX únicamente
Sección titulada Exportación en MDX únicamenteLos archivos MDX también pueden exportar data declarando un export
.
Por ejemplo, puedes exportar un campo title
desde un componente o página MDX.
Este title
será accesible desde una declaración import
y Astro.glob():
Componentes personalizados con MDX importado
Sección titulada Componentes personalizados con MDX importadoA la hora de renderizar contenido MDX importado, es posible pasar componentes personalizados por medio de la propiedad components
.
Los componentes personalizados definidos y exportados en un archivo MDX deben ser importados y pasados de vuelta al componente <Content />
por medio de la propiedad components
.
Configuración de Markdown y MDX
Sección titulada Configuración de Markdown y MDXEl soporte de Markdown en Astro está basado en remark, una potente herramienta de análisis sintáctico y procesamiento con un ecosistema activo. Otros analizadores de Markdown como Pandoc y markdown-it no están soportados actualmente.
De forma predeterminada, Astro aplica los plugins GitHub-flavored Markdown y SmartyPants. Esto trae algunas características útiles como la generación de links cliqueables desde el texto y formato para citas y guiones largos.
Puedes personalizar cómo remark analiza tu Markdown en astro.config.mjs
. Puedes ver la lista completa de opciones de configuración de Markdown.
Plugins de Markdown
Sección titulada Plugins de MarkdownAstro es compatible con plugins externos de remark y rehype para Markdown y MDX. Estos plugins te permiten extender tu Markdown con nuevas características, como generación automática de tabla de contenidos, aplicar etiquetas accesibles a emojis y aplicar estilos al Markdown.
¡Te invitamos a darle un vistazo a las listas awesome-remark y awesome-rehype para ver más plugins populares! Puedes leer sus README para seguir las instrucciones de instalación de cada uno.
Este ejemplo aplica remark-toc
y rehype-accesible-emojis
a ambos archivos Markdown y MDX:
IDs de encabezados y plugins
Sección titulada IDs de encabezados y pluginsAstro inyecta un atributo id
en todos los elementos de encabezado (<h1>
a <h6>
) en archivos Markdown y MDX y proporciona una utilidad getHeadings()
para recuperar estos IDs en propiedades exportadas de Markdown.
Puedes personalizar estos IDs de encabezado agregando un plugin de rehype que inyecte atributos id
(por ejemplo, rehype-slug
). Tus IDs personalizados, en lugar de los predeterminados de Astro, se reflejarán en la salida HTML y los elementos devueltos por getHeadings()
.
Por defecto, Astro inyecta atributos id
después de que se ejecutan tus complementos de rehype. Si uno de tus complementos de rehype personalizados necesita acceder a los IDs inyectados por Astro, puedes importar y usar el complemento rehypeHeadingIds
de Astro directamente. Asegúrate de agregar rehypeHeadingIds
antes de cualquier complemento que lo requiera:
getHeadings()
solo devuelve los encabezados escritos directamente en un archivo Markdown o MDX. Si un archivo MDX importa componentes que contienen sus propios encabezados, estos no serán devueltos por getHeadings()
.
Personalizando un plugin
Sección titulada Personalizando un pluginPara personalizar un plugin, proporciona un objeto de opciones después de él en un array anidado.
En el ejemplo de abajo se agrega la opción de encabezado al plugin remarkToc
para cambiar dónde es colocada la tabla de contenidos y la opción behavior
al plugin rehype-autolink-headings
para agregar una etiqueta de ancla después del texto del encabezado.
Modificación programática del frontmatter
Sección titulada Modificación programática del frontmatterSi estás usando colecciones de contenido, por favor ve “Modificando el Frontmatter con Remark”.
Puedes agregar propiedades al frontmatter de todos tus archivos Markdown o MDX utilizando un plugin de remark o rehype.
-
Agrega una
customProperty
a la propiedaddata.astro.frontmatter
del argumentofile
de tu plugin:Agregado en: astro@2.0.0
data.astro.frontmatter
contiene todas las propiedades de un documento Markdown o MDX. Esto te permite modificar propiedades existentes del frontmatter, o calcular nuevas propiedades a partir de este frontmatter existente. -
Aplica este plugin a tu configuración de integración
markdown
omdx
:o bien
Ahora, cada archivo Markdown o MDX tendrá customProperty
en su frontmatter, la cual estará disponible al importar markdown y en la propiedad Astro.props.frontmatter
en tus plantillas.
Extendiendo la configuración de Markdown desde MDX
Sección titulada Extendiendo la configuración de Markdown desde MDXLa integración MDX de Astro extenderá la configuración de Markdown existente de tu proyecto por defecto. Para sobrescribir opciones individuales, puedes especificar su equivalente en tu configuración MDX.
El siguiente ejemplo deshabilita el GitHub-Flavored Markdown y aplica un conjunto diferente de complementos remark para archivos MDX:
Para evitar extender la configuración de Markdown desde MDX, establece la opción extendMarkdownConfig
(habilitada por defecto) a false
:
Resaltado de sintaxis
Sección titulada Resaltado de sintaxisAstro viene con soporte integrado para Shiki y Prism. Esto proporciona un resaltado de sintaxis instantáneo para:
- todas las vallas de código (```) usadas en Markdown o archivos MDX.
- el contenido dentro del componente incorporado
<Code />
(con la tecnología de Shiki) - el contenido dentro del componente
<Prism />
(con la tecnología de Prism).
Shiki está habilitado de forma predeterminada, preconfigurado con el tema github-dark
. La salida compilada se limitará a estilos en línea sin clases CSS externas, hojas de estilo o JS del lado del cliente.
Configuración de Shiki
Sección titulada Configuración de ShikiShiki es nuestro resaltador de sintaxis predeterminado. Puedes configurar todas las opciones a través del objeto shikiConfig
así:
Los bloques de código de Astro están estilizados usando la clase .astro-code
. Al seguir la documentación de Shiki (por ejemplo, para personalizar temas duales o múltiples claros/oscuros), asegúrate de reemplazar la clase .shiki
en los ejemplos con .astro-code
.
Añadiendo tu propio tema
Sección titulada Añadiendo tu propio temaEn lugar de usar alguno de los temas predefinidos de Shiki, puedes importar un tema personalizado desde un archivo local.
También sugerimos leer la documentación de Shiki sobre sus temas para explorar la carga de temas personalizados, alternar entre modo claro y oscuro, o estilar utilizando variables de CSS.
Cambia el resaltador de sintaxis predeterminado
Sección titulada Cambia el resaltador de sintaxis predeterminadoSi deseas cambiar a 'prism'
o deshabilitar el resaltado de sintaxis por completo, puedes usar el objeto de configuración markdown.syntaxHighlight
:
Configuración de Prism
Sección titulada Configuración de PrismSi optas por usar Prism, se aplicarán las clases CSS de Prism en su lugar. ¡Ten en cuenta que necesitas aportar tu propia hoja de estilo CSS para que aparezca el resaltado de sintaxis!
- Escoge una hoja de estilos prediseñada de los Temas de Prism disponibles.
- Agrega esta hoja de estilos a la carpeta
public/
de tu proyecto. - Agrega esto en el
<head>
de tu página en un componente de plantilla a través de una etiqueta<link>
. (Lee sobre el uso básico de Prism.)
También puedes visitar la lista de lenguajes soportados por Prism para ver las opciones y su uso.
Fetching de Markdown Remoto
Sección titulada Fetching de Markdown RemotoAstro fue diseñado principalmente para archivos Markdown locales que podrían ser guardados dentro del directorio del proyecto. Sin embargo, pueden ocurrir casos donde necesites obtener Markdown de una fuente remota. Por ejemplo, puedes necesitar hacer fetching y renderizar Markdown de una API remota al estar construyendo un sitio web (o cuando el usuario ejecute una request a su página, al usar SSR).
¡Astro no incluye soporte para Markdown remoto!. Para hacer fetching de Markdown remoto y renderizarlo a HTML, necesitarás instalar y configurar tu propio parser de Markdown desde npm. Este no heredará ajustes que hayas configurado del Markdown y MDX de Astro. Asegúrate de comprender estas limitaciones antes de implementar esto en tu proyecto.
Learn