Saltearse al contenido

@astrojs/markdoc

Esta integración de Astro permite el uso de Markdoc para crear componentes, páginas y entradas de colecciones de contenido.

Markdoc te permite mejorar tu Markdown con componentes de Astro. Si tienes contenido existente escrito en Markdoc, esta integración te permite traer esos archivos a tu proyecto de Astro usando colecciones de contenido.

La herramienta de línea de comandos astro add automatiza la instalación por ti. Ejecuta uno de los siguientes comandos en una nueva ventana de terminal. (Si no estás seguro de qué gestor de paquetes estás usando, ejecuta el primer comando.) Luego, sigue las indicaciones y escribe “y” en la terminal (que significa “sí”) para cada una.

Terminal window
# Usando NPM
npx astro add markdoc
# Usando Yarn
yarn astro add markdoc
# Usando PNPM
pnpm astro add markdoc

Si tienes algún problema, no dudes en reportarlo en GitHub e intenta los pasos de instalación manual a continuación.

Primero, instala el paquete @astrojs/markdoc usando tu gestor de paquetes. Si estás usando npm o no estás seguro, ejecuta esto en la terminal:

Terminal window
npm install @astrojs/markdoc

Luego, aplica esta integración a tu archivo astro.config.* usando la propiedad integrations:

astro.config.mjs

astro.config.mjs
import { defineConfig } from 'astro/config';
import markdoc from '@astrojs/markdoc';
export default defineConfig({
// ...
integrations: [markdoc()],
// ^^^^^^^^^
});

VS Code admite Markdown de forma predeterminada. Sin embargo, para el soporte del editor Markdoc, es posible que desees agregar la siguiente configuración en tu configuración de VSCode. Esto garantiza que la creación de archivos Markdoc proporcione una experiencia de edición similar a Markdown.

.vscode/settings.json
{
"files.associations": {
"*.mdoc": "markdown"
}
}

Los archivos Markdoc solo se pueden usar dentro de las colecciones de contenido. Agrega entradas a cualquier colección de contenido usando la extensión .mdoc:

Terminal window
src/content/docs/
why-markdoc.mdoc
quick-start.mdoc

Luego, consulta tu colección usando las APIs de colecciones de contenido:

---
import { getEntryBySlug } from 'astro:content';
const entry = await getEntryBySlug('docs', 'why-markdoc');
const { Content } = await entry.render();
---
<!--Accede a las propiedades del frontmatter con `data`-->
<h1>{entry.data.title}</h1>
<!--Renderiza el contenido Markdoc con el componente de contenido-->
<Content />

📚 Consulta la documentación de Astro sobre Colecciones de Contenido para más información.

@astrojs/markdoc ofrece opciones de configuración para usar todas las características de Markdoc y conectar componentes de interfaz de usuario a tu contenido.

Usa componentes Astro como etiquetas Markdoc

Sección titulada Usa componentes Astro como etiquetas Markdoc

Puedes configurar etiquetas Markdoc que se asignan a componentes .astro. Puedes agregar una nueva etiqueta creando un archivo markdoc.config.mjs|ts en la raíz de tu proyecto y configurando el atributo tag.

Este ejemplo renderiza un componente Aside, y permite que se pase una prop type como un string:

markdoc.config.mjs
import { defineMarkdocConfig, component } from '@astrojs/markdoc/config';
export default defineMarkdocConfig({
tags: {
aside: {
render: component('./src/components/Aside.astro'),
attributes: {
// Markdoc requiere definiciones de tipo para cada atributo.
// Estas deben reflejar el tipo `Props` del componente
// que vas a renderizar.
// Consulta la documetación de Markdoc sobre definir atributos
// https://markdoc.dev/docs/attributes#defining-attributes
type: { type: String },
},
},
},
});

Este componente ahora se puede usar en tus archivos Markdoc con la etiqueta {% aside %}. Los elementos hijos serán enviados al espacio por defecto de tu componente:

# Bienvenido a Markdoc 👋
{% aside type="tip" %}
Usa etiquetas como esta elegante "aside" para agregar un poco de _estilo_ a tus documentos.
{% /aside %}

Usa componentes de Astro desde paquetes npm y archivos TypeScript

Sección titulada Usa componentes de Astro desde paquetes npm y archivos TypeScript

Es posible que necesites usar componentes de Astro expuestos como exportaciones nombradas desde archivos de TypeScript o JavaScript. Esto es común cuando se usan paquetes npm y sistemas de diseño.

Puedes pasar el nombre de importación como segundo argumento a la función component():

markdoc.config.mjs
import { defineMarkdocConfig, component } from '@astrojs/markdoc/config';
export default defineMarkdocConfig({
tags: {
tabs: {
render: component('@astrojs/starlight/components', 'Tabs'),
},
},
});

Esto genera la siguiente declaración de importación internamente:

import { Tabs } from '@astrojs/starlight/components';

Utiliza los componentes de Astro desde paquetes npm y archivos TypeScript

Sección titulada Utiliza los componentes de Astro desde paquetes npm y archivos TypeScript

Es posible que necesites utilizar los componentes de Astro expuestos como exportaciones nombradas desde archivos TypeScript o JavaScript. Esto es común cuando se utilizan paquetes npm y sistemas de diseño.

Puedes pasar el nombre de importación como segundo argumento a la función component():

markdoc.config.mjs
import { defineMarkdocConfig, component } from '@astrojs/markdoc/config';
export default defineMarkdocConfig({
tags: {
tabs: {
render: component('@astrojs/starlight/components', 'Tabs'),
},
},
});

Esto genera la siguiente declaración de importación internamente:

import { Tabs } from '@astrojs/starlight/components';

@astrojs/markdoc automaticamente agrega enlaces a tus encabezados, y genera una lista de headings a través de la API de colecciones de contenido. Para personalizar aún más cómo se renderizan los encabezados, puedes aplicar un componente de Astro como un nodo Markdoc.

Este ejemplo renderiza un componente Heading.astro usando la propiedad render:

markdoc.config.mjs
import { defineMarkdocConfig, nodes, component } from '@astrojs/markdoc/config';
export default defineMarkdocConfig({
nodes: {
heading: {
...nodes.heading, // Preserva la generación predeterminada de enlaces
render: component('./src/components/Heading.astro'),
},
},
});

Todos los encabezados Markdown renderizarán el componente Heading.astro y pasarán los siguientes attributes como props del componente:

  • level: number El nivel de encabezado 1 - 6
  • id: string Un id generado a partir del contenido de texto del encabezado. Esto corresponde al slug generado por la función render() de contenido.

Por ejemplo, el encabezado ### Level 3 heading! pasará level: 3 e id: 'level-3-heading' como props del componente.

@astrojs/markdoc proporciona extensiones de Shiki y Prism para resaltar tus bloques de código.

Aplica la extensión shiki() a tu configuración Markdoc usando la propiedad extends. Opcionalmente puedes pasar un objeto de configuración de shiki:

markdoc.config.mjs
import { defineMarkdocConfig } from '@astrojs/markdoc/config';
import shiki from '@astrojs/markdoc/shiki';
export default defineMarkdocConfig({
extends: [
shiki({
// Escoge de los temas integrados de Shiki (o agrega el tuyo)
// Por defecto: 'github-dark'
// https://github.com/shikijs/shiki/blob/main/docs/themes.md
theme: 'dracula',
// Habilita el ajuste de palabras para evitar el desplazamiento horizontal
// Por defecto: false
wrap: true,
// Pasa lenguajes personalizados
// Nota: Shiki tiene innumerables lenguajes integrados, ¡incluyendo `.astro`!
// https://github.com/shikijs/shiki/blob/main/docs/languages.md
langs: [],
}),
],
});

Aplica la extensión prism() a tu configuración Markdoc usando la propiedad extends.

markdoc.config.mjs
import { defineMarkdocConfig } from '@astrojs/markdoc/config';
import prism from '@astrojs/markdoc/prism';
export default defineMarkdocConfig({
extends: [prism()],
});

📚 Para aprender acerca de como configurar las hojas de estilo de Prism, consulta nuestra guía de resaltado de sintaxis.

Markdoc envuelve los documentos con una etiqueta <article> de forma predeterminada. Esto se puede cambiar desde el nodo document de Markdoc. Esto acepta un nombre de elemento HTML o null si prefieres eliminar el elemento de envoltura:

markdoc.config.mjs
import { defineMarkdocConfig, nodes } from '@astrojs/markdoc/config';
export default defineMarkdocConfig({
nodes: {
document: {
...nodes.document, // Aplica los valores predeterminados para otras opciones
render: null, // por defecto 'article'
},
},
});

Nodos personalizados de Markdoc / elementos

Sección titulada Nodos personalizados de Markdoc / elementos

Es posible que desees renderizar elementos Markdown estándar, como párrafos y texto en negrita, como componentes Astro. Para esto, puedes configurar un nodo Markdoc. Si un nodo determinado recibe atributos, estarán disponibles como props del componente.

Este ejemplo renderiza bloques de citas con un componente Quote.astro personalizado:

markdoc.config.mjs
import { defineMarkdocConfig, nodes, component } from '@astrojs/markdoc/config';
export default defineMarkdocConfig({
nodes: {
blockquote: {
...nodes.blockquote, // Aplica los valores predeterminados de Markdoc para otras opciones
render: component('./src/components/Quote.astro'),
},
},
});

📚 Encuentra todos los nodos integrados de Markdoc y los atributos de nodo en su documentación.

Usa componentes de UI del lado del cliente

Sección titulada Usa componentes de UI del lado del cliente

Las etiquetas y nodos están restringidos a archivos .astro. Para incrustar componentes de interfaz de usuario del lado del cliente en Markdoc, usa un componente .astro de envoltura que renderice un componente de framework con tu directiva client: deseada.

Este ejemplo envuelve un componente React Aside.tsx con un componente ClientAside.astro:

src/components/ClientAside.astro
---
import Aside from './Aside';
---
<Aside {...Astro.props} client:load />

El componente Astro ahora puede ser pasado a la propiedad render para cualquier tag o node en tu configuración:

markdoc.config.mjs
import { defineMarkdocConfig, component } from '@astrojs/markdoc/config';
export default defineMarkdocConfig({
tags: {
aside: {
render: component('./src/components/ClientAside.astro'),
attributes: {
type: { type: String },
},
},
},
});

El archivo markdoc.config.mjs|ts acepta todas las opciones de configuración de Markdoc, incluyendo etiquetas y funciones.

Puedes pasar estas opciones desde la exportación predeterminada en tu archivo markdoc.config.mjs|ts:

markdoc.config.mjs
import { defineMarkdocConfig } from '@astrojs/markdoc/config';
export default defineMarkdocConfig({
functions: {
getCountryEmoji: {
transform(parameters) {
const [country] = Object.values(parameters);
const countryToEmojiMap = {
japan: '🇯🇵',
spain: '🇪🇸',
france: '🇫🇷',
};
return countryToEmojiMap[country] ?? '🏳';
},
},
},
});

Ahora, puedes llamar a esta función desde cualquier entrada de contenido de Markdoc:

¡Hola {% getCountryEmoji("spain") %}!

📚 Consulta la documentación de Markdoc para más información sobre el uso de variables o funciones en tu contenido.

Si estás usando VS Code, hay una extensión de lenguaje Markdoc que incluye resaltado de sintaxis y autocompletado para etiquetas configuradas. Consulta el servidor de lenguaje en GitHub para más información.

Para configurar la extensión, crea un archivo markdoc.config.json en la raíz del proyecto con el siguiente contenido:

[
{
"id": "my-site",
"path": "src/content",
"schema": {
"path": "markdoc.config.mjs",
"type": "esm",
"property": "default",
"watch": true
}
}
]

La propiedad schema contiene toda la información para configurar el servidor de lenguaje para las colecciones de contenido de Astro. Acepta las siguientes propiedades:

  • path: La ruta al archivo de configuración.
  • type: El tipo de módulo que usa tu archivo de configuración (esm permite la sintaxis import).
  • property: La propiedad exportada que contiene el objeto de configuración.
  • watch: Indica al servidor que observe los cambios en la configuración.

La propiedad path de nivel superior le indica al servidor dónde se encuentra el contenido. Dado que Markdoc es específico para las colecciones de contenido, puedes usar src/content.

Es posible que necesites pasar variables a tu contenido. Esto es útil cuando pasas parámetros SSR como pruebas A/B.

Las variables pueden pasarse como props a través del componente Content:

---
import { getEntryBySlug } from 'astro:content';
const entry = await getEntryBySlug('docs', 'why-markdoc');
const { Content } = await entry.render();
---
<!--Pasa el parámetro `abTest` como una variable-->
<Content abTestGroup={Astro.params.abTestGroup} />

Ahora, abTestGroup esta disponible como una variable en docs/why-markdoc.mdoc:

{% if $abTestGroup === 'image-optimization-lover' %}
Déjame contarte sobre la optimización de imágenes...
{% /if %}

Para hacer una variable global para todos los archivos Markdoc, puedes usar el atributo variables de tu markdoc.config.mjs|ts:

import { defineMarkdocConfig } from '@astrojs/markdoc/config';
export default defineMarkdocConfig({
variables: {
environment: process.env.IS_PROD ? 'prod' : 'dev',
},
});

Accede al frontmatter desde tu contenido Markdoc

Sección titulada Accede al frontmatter desde tu contenido Markdoc

Para acceder al frontmatter, puedes pasar la propiedad de entrada data como una variable donde renderizas tu contenido:

---
import { getEntry } from 'astro:content';
const entry = await getEntry('docs', 'why-markdoc');
const { Content } = await entry.render();
---
<Content frontmatter={entry.data} />

Esto ahora puede ser accedido como $frontmatter en tu Markdoc.

Opciones de configuración de integración

Sección titulada Opciones de configuración de integración

La integración de Astro con Markdoc se encarga de configurar opciones y capacidades de Markdoc que no están disponibles a través del archivo markdoc.config.js.

Permite escribir marcas HTML junto con etiquetas y nodos de Markdoc. Por defecto, Markdoc no reconocerá las marcas HTML como contenido semántico. Para lograr una experiencia más similar a Markdown, donde los elementos HTML pueden incluirse junto con tu contenido, establece allowHTML:true como opción de integración de markdoc. Esto habilitará el análisis de HTML en las marcas de Markdoc.

astro.config.mjs
import { defineConfig } from 'astro/config';
import markdoc from '@astrojs/markdoc';
export default defineConfig({
// ...
integrations: [markdoc({ allowHTML: true })],
// ^^^^^^^^^^^^^^^
});

Por defecto, cualquier contenido que esté indentado por cuatro espacios se tratará como un bloque de código. Desafortunadamente, este comportamiento hace que sea difícil usar niveles arbitrarios de indentación para mejorar la legibilidad de los documentos con estructura compleja.

Cuando uses etiquetas anidadas en Markdoc, puede ser útil indentar el contenido dentro de las etiquetas para que el nivel de profundidad sea claro. Para admitir la indentación arbitraria, tenemos que deshabilitar los bloques de código basados en la indentación y modificar varias otras reglas de análisis de markdown-it que tienen en cuenta los bloques de código basados en la indentación. Estos cambios se pueden aplicar habilitando la opción ignoreIndentation.

astro.config.mjs
import { defineConfig } from 'astro/config';
import markdoc from '@astrojs/markdoc';
export default defineConfig({
// ...
integrations: [markdoc({ ignoreIndentation: true })],
// ^^^^^^^^^^^^^^^^^^^^^^^
});
# Bienvenido a Markdoc con etiquetas indentadas 👋
# Nota: Puedes usar tanto espacios como tabulaciones para la identación
{% custom-tag %}
{% custom-tag %} ### Las etiquetas pueden ser indentadas para una mejor legibilidad
{% another-custom-tag %}
Esto es más fácil de seguir cuando hay mucho anidamiento
{% /another-custom-tag %}
{% /custom-tag %}
{% /custom-tag %}

Para obtener ayuda, revisa el canal #support en Discord. ¡Los miembros de nuestro amigable equipo de soporte están aquí para ayudarte!

También puedes revisar nuestra Documentación de integración de Astro para más información sobre integraciones.

Este paquete es mantenido por el equipo central de Astro. ¡Eres bienvenido a enviar un issue o PR!

Consulta el CHANGELOG.md para ver el historial de cambios de esta integración.

Otros

Frameworks UI

Adaptadores SSR

Otros