Creación de contenido en Markdown
Starlight admite la gama completa de la sintaxis Markdown en archivos .md
, así como el frontmatter en YAML para definir metadatos como el título y la descripción.
Por favor, asegúrate de consultar la documentación de MDX o Markdoc si estás utilizando esos formatos de archivo, ya que el soporte y el uso de Markdown pueden variar.
Frontmatter
Puedes personalizar individualmente las páginas en Starlight estableciendo valores en el frontmatter.
El frontmatter se establece en la parte superior de tus archivos entre separadores ---
:
Cada página debe incluir al menos un title
.
Consulta la referencia de frontmatter para ver todos los campos disponibles y cómo añadir campos personalizados.
Estilos en línea
El texto puede estar en negrita, en cursiva, o tachado.
Puedes enlazar a otra página.
Puedes resaltar código en línea
con comillas invertidas.
Imágenes
Las imágenes en Starlight utilizan el soporte de assets optimizados incorporado en Astro.
Markdown y MDX admiten la sintaxis Markdown para mostrar imágenes, que incluye alt-text para lectores de pantalla y tecnología de asistencia.
También se admiten rutas de imágenes relativas para imágenes almacenadas localmente en tu proyecto.
Encabezados
Puedes estructurar el contenido utilizando encabezados. Los encabezados en Markdown se indican con uno o más #
al comienzo de la línea.
Cómo estructurar el contenido de la página en Starlight
Starlight está configurado para utilizar automáticamente el título de tu página como un encabezado de nivel superior y se incluirá un encabezado “Visión general” en la parte superior de la tabla de contenido de cada página. Recomendamos comenzar cada página con contenido de texto de párrafo regular y utilizar encabezados dentro de la página a partir de <h2>
en adelante:
Enlaces de anclaje automáticos para encabezados.
Al utilizar encabezados en Markdown, se generan automáticamente enlaces de anclaje para que puedas vincular directamente a ciertas secciones de tu página:
Los encabezados de nivel 2 (<h2>
) y nivel 3 (<h3>
) aparecerán automáticamente en la tabla de contenido de la página.
Aprende más sobre cómo Astro procesa los id
s de los encabezados en la documentación de Astro
Apartados
Los apartados (también conocidos como “apartados” o ”contenido destacado”) son útiles para mostrar información secundaria junto al contenido principal de una página.
Starlight proporciona una sintaxis personalizada de Markdown para renderizar apartados. Los bloques de apartados se indican utilizando un par de triples dos puntos :::
para envolver tu contenido, y pueden ser de tipo note
, tip
, caution
o danger
.
Puedes anidar cualquier otro tipo de contenido Markdown dentro de un apartado, pero los apartados son más adecuados para fragmentos de contenido cortos y concisos.
Nota de apartados
Títulos personalizados para los apartados
Puedes especificar un título personalizado para el apartado utilizando corchetes cuadrados después del tipo del apartado, por ejemplo, :::tip[¿Sabías esto?]
.
Más tipos de apartados
Los apartados de caution y danger son útiles para llamar la atención del usuario sobre detalles que podrían generar problemas. Si te encuentras utilizando estos tipos de apartados con frecuencia, también puede ser una señal de que lo que estás documentando podría beneficiarse de una reestructuración o rediseño.
Citas en bloque
Esto es una cita en bloque, que se utiliza comúnmente para citar a otra persona o documento.
Las citas en bloque se indican con un
>
al inicio de cada línea.
Bloques de código
Un bloque de código se indica con un bloque de tres comillas invertidas ```
al inicio y al final. Puedes indicar el lenguaje de programación que se está utilizando después de las comillas invertidas de apertura.
Características de Expressive Code
Starlight usa Expressive Code para ampliar las posibilidades de formato de los bloques de código.
Los marcadores de texto de Expressive Code y los plugins de marcos de ventana están habilitados de forma predeterminada.
El renderizado de los bloques de código se puede configurar utilizando la opción de configuración expressiveCode
de Starlight.
Marcadores de texto
Puedes resaltar líneas específicas o partes de tus bloques de código utilizando los marcadores de texto de Expressive Code en la línea de apertura de tu bloque de código.
Usa llaves ({ }
) para resaltar líneas enteras, y comillas para resaltar cadenas de texto.
Hay tres estilos de resaltado: neutral para llamar la atención sobre el código, verde para indicar código insertado y rojo para indicar código eliminado.
Tanto el texto como las líneas enteras pueden marcarse con el marcador predeterminado, o en combinación con ins=
y del=
para producir el resaltado deseado.
Expressive Code proporciona varias opciones para personalizar la apariencia visual de tus ejemplos de código. Muchas de estas opciones se pueden combinar, para obtener ejemplos de código altamente ilustrativos. Por favor, explora la documentación de Expressive Code para ver las extensas opciones disponibles. Algunos de los ejemplos más comunes se muestran a continuación:
-
Marca líneas enteras y rangos de líneas usando el marcador
{ }
: -
Marca selecciones de texto usando el marcador
" "
o expresiones regulares: -
Marca texto o líneas como insertadas o eliminadas con
ins
odel
: -
Combina el resaltado de sintaxis con la sintaxis similar a
diff
:
Marcos y títulos
Los bloques de código se pueden representar dentro de un marco similar a una ventana.
Un marco que se parece a una ventana de código se utilizará para todos los demás lenguajes de programación (por ejemplo, bash
o sh
).
Otros lenguajes se muestran dentro de un marco de estilo de editor de código si incluyen un título.
Un título opcional del bloque de código se puede establecer con un atributo title="..."
después de las comillas invertidas de apertura del bloque de código y el identificador del lenguaje, o con un comentario del nombre del archivo en las primeras líneas del código.
Otras características comunes de Markdown
Starlight admite todas las demás sintaxis de autoría de Markdown, como listas y tablas. Puedes consultar la Guía de referencia de Markdown para obtener una descripción general rápida de todos los elementos de sintaxis de Markdown.
Configuración avanzada de Markdown y MDX
Starlight utiliza el motor de renderizado de Markdown y MDX de Astro, construido sobre remark y rehype. Puedes añadir soporte para sintaxis y comportamientos personalizados añadiendo remarkPlugins
o rehypePlugins
en tu archivo de configuración de Astro. Consulta la sección “Configuración de Markdown y MDX” en la documentación de Astro para obtener más información.