Componentes

Los componentes te permiten reutilizar fácilmente una parte de la interfaz de usuario o un estilo de manera consistente. Ejemplos podrían incluir una tarjeta de enlace o un incrustado de YouTube. Starlight admite el uso de componentes en archivos MDX y proporciona algunos componentes comunes para que los utilices.

Aprende más sobre la construcción de componentes en los docs de Astro.

Usando un componente

Puedes utilizar un componente importándolo en tu archivo MDX y luego renderizándolo como una etiqueta JSX. Estas etiquetas se ven como etiquetas HTML, pero comienzan con una letra mayúscula que coincide con el nombre en tu declaración de import:

src/content/docs/example.mdx

---
title: Bienvenido a mis docs
---

import UnComponente from '../../componentes/UnComponente.astro';
import OtroComponente from '../../componentes/OtroComponente.astro';

<UnComponente prop="algo" />

<OtroComponente>
  Los componentes también pueden contener **contenido anidado**.
</OtroComponente>

Debido a que Starlight está impulsado por Astro, puedes agregar soporte para componentes construidos con cualquier framework UI compatible (React, Preact, Svelte, Vue, Solid, Lit y Alpine) en tus archivos MDX.

Compatibilidad con los estilos de Starlight

Starlight aplica estilos predeterminados a tu contenido en Markdown, por ejemplo, añadiendo margen entre elementos. Si estos estilos entran en conflicto con la apariencia de tu componente, establece la clase not-content en tu componente para deshabilitarlos.

src/components/Ejemplo.astro

<div class="not-content">
  <p>
    No se ve afectado por el estilo de contenido predeterminado de Starlight.
  </p>
</div>

Componentes integrados

Starlight proporciona algunos componentes integrados para casos de uso comunes en la documentación. Estos componentes están disponibles en el paquete @astrojs/starlight/components.

Pestañas

Puedes mostrar una interfaz con pestañas utilizando los componentes <Tabs> y <TabItem>. Cada <TabItem> debe tener una label que se mostrará a los usuarios.

src/content/docs/example.mdx

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

<Tabs>
  <TabItem label="Estrellas">Sirius, Vega, Betelgeuse</TabItem>
  <TabItem label="Lunas">Io, Europa, Ganymede</TabItem>
</Tabs>

El código anterior genera las siguientes pestañas en la página:

Estrellas

Sirius, Vega, Betelgeuse

Lunas

Io, Europa, Ganymede

Tarjetas

Puedes mostrar contenido en una caja que coincida con los estilos de Starlight utilizando el componente <Card>. Envuelve varias tarjetas en el componente <CardGrid> para mostrar las tarjetas una al lado de la otra cuando hay suficiente espacio.

El componente <Card> requiere un title y opcionalmente puede incluir un atributo icon establecido con el nombre de uno de los iconos integrados de Starlight.

src/content/docs/example.mdx

import { Card, CardGrid } from '@astrojs/starlight/components';

<Card title="¡Echa un vistazo a esto!">
  Contenido interesante que quieres resaltar.
</Card>

<CardGrid>
  <Card title="Estrellas" icon="star">
    Sirius, Vega, Betelgeuse
  </Card>
  <Card title="Lunas" icon="moon">
    Io, Europa, Ganymede
  </Card>
</CardGrid>

El código anterior genera lo siguiente en la página:

¡Echa un vistazo a esto!

Contenido interesante que quieres resaltar.

Estrellas

Sirius, Vega, Betelgeuse

Lunas

Io, Europa, Ganymede

Consejo

Utiliza una cuadrícula de tarjetas en tu página de inicio para mostrar las características clave de tu proyecto. Agrega el atributo stagger para desplazar verticalmente la segunda columna de tarjetas y agregar interés visual:

<CardGrid stagger>
  <!-- tarjetas -->
</CardGrid>

Tarjetas de enlace

Usa el componente <LinkCard> para vincular de forma prominente a diferentes páginas.

Un <LinkCard> requiere un title y un atributo href. Opcionalmente puedes incluir una breve description u otros atributos de enlace como target.

Agrupa varios componentes <LinkCard> en <CardGrid> para mostrar las tarjetas una al lado de la otra cuando hay suficiente espacio.

src/content/docs/example.mdx

import { LinkCard, CardGrid } from '@astrojs/starlight/components';

<LinkCard
  title="Personalizando Starlight"
  description="Aprende a hacer que tu sitio Starlight sea único con estilos personalizados, fuentes y más."
  href="/es/guides/customization/"
/>

<CardGrid>
  <LinkCard
    title="Creación de contenido en Markdown"
    href="/es/guides/authoring-content/"
  />
  <LinkCard title="Componentes" href="/es/guides/components/" />
</CardGrid>

El código anterior genera lo siguiente en la página:

Personalizando Starlight Aprende a hacer que tu sitio Starlight sea único con estilos personalizados, fuentes y más.

Creación de contenido en Markdown

Componentes

Iconos

Starlight proporciona un conjunto de iconos comunes que puedes mostrar en tu contenido utilizando el componente <Icon>.

Cada <Icon> requiere un atributo name que se puede encontrar en la lista de todos los iconos, y opcionalmente puede incluir atributos como label, size y color.

src/content/docs/example.mdx

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

<Icon name="star" color="goldenrod" size="2rem" />

El código anterior genera lo siguiente en la página:

Todos los iconos

A continuación se muestra una lista de todos los iconos disponibles con sus nombres asociados. Haz clic en un ícono para copiar el código del componente correspondiente.

up-caret down-caret right-caret right-arrow left-arrow bars translate pencil pen document add-document setting external moon sun laptop open-book information magnifier forward-slash close error warning approve-check-circle approve-check rocket star puzzle list-format random github gitlab bitbucket codePen discord gitter twitter x.com mastodon codeberg youtube threads linkedin twitch microsoftTeams instagram stackOverflow telegram rss facebook email reddit patreon slack matrix openCollective

Código

Usa el componente <Code> para renderizar código con resaltado de sintaxis cuando no sea posible usar un bloque de código Markdown, por ejemplo, para renderizar datos provenientes de fuentes externas como archivos, bases de datos o APIs.

Consulta el componente de código de Expressive Code para obtener detalles completos de las props que admite <Code>.

src/content/docs/example.mdx

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

export const exampleCode = `console.log('¡Esto podría venir de un archivo o CMS!');`;
export const fileName = 'example.js';
export const highlights = ['file', 'CMS'];

<Code code={exampleCode} lang="js" title={fileName} mark={highlights} />

El código anterior genera lo siguiente en la página:

example.js

console.log('¡Esto podría venir de un archivo o CMS!');

Código importado

Usa el sufijo de importación ?raw de Vite para importar cualquier archivo de código como un string. Puedes pasar luego este string importado al componente <Code> para incluirlo en tu página.

src/content/docs/example.mdx

import { Code } from '@astrojs/starlight/components';
import importedCode from '/src/env.d.ts?raw';

<Code code={importedCode} lang="ts" title="src/env.d.ts" />

El código anterior genera lo siguiente en la página:

src/env.d.ts

/// <reference path="../.astro/types.d.ts" />
/// <reference types="astro/client" />