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 ---:

---
title: Mi título de página
---

El contenido de la página sigue luego de los `---`.

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~~.

El texto puede estar **en negrita**, _en cursiva_, o ~~tachado~~.

Puedes enlazar a otra página.

Puedes [enlazar a otra página](/es/getting-started/).

Puedes resaltar código en línea con comillas invertidas.

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.

Una ilustración de planetas y estrellas con la palabra “astro”

![Una ilustración de planetas y estrellas con la palabra “astro”](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png)

También se admiten rutas de imágenes relativas para imágenes almacenadas localmente en tu proyecto.

![Una nave espacial en el espacio](../../assets/images/rocket.svg)

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:

---
title: Guía de Markdown
description: Cómo utilizar Markdown en Starlight
---

Esta página describe cómo utilizar Markdown en Starlight.

## Estilos en línea

## Encabezados

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:

---
title: Mi página de contenido
description: Cómo utilizar los enlaces de anclaje integrados de Starlight.
---

## Introducción

Puedo enlazar a [mi conclusión](#conclusión) más abajo en la misma página.

## Conclusión

`https://mi-sitio.com/page1/#introduction` navega directamente a mi Introducción.

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 ids 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

Starlight es un conjunto de herramientas para crear sitios web de documentación construido con Astro. Puedes comenzar con este comando:

npm run create astro@latest --template starlight

:::note
Starlight es un conjunto de herramientas para sitios de documentación construido con [Astro](https://astro.build/). Puedes comenzar con este comando:

```sh
npm run create astro@latest --template starlight
```

:::

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?].

:::tip[¿Sabías esto?]
Astro te ayuda a construir sitios web más rápidos con la[“Arquitectura de Islas”](https://docs.astro.build/es/concepts/islands/).
:::

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.

:::caution
Si no estás seguro de si deseas un sitio de documentación increíble, piénsalo dos veces antes de usar [Starlight](/es/).
:::

:::danger
Tus usuarios pueden ser más productivos y encontrar más fácil de usar tu producto gracias a las útiles características de Starlight.

- Navegación clara
- Tema de color configurable por el usuario
- [Soporte de i18n](/es/guides/i18n/)

:::

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.

> 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.

// Código JavaScript con resaltado de sintaxis.
var fun = function lang(l) {
  dateformat.i18n = require('./lang/' + l);
  return true;
};

```js
// Código JavaScript con resaltado de sintaxis.
var fun = function lang(l) {
  dateformat.i18n = require('./lang/' + l);
  return true;
};
```

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 { }:

function demo() {
  // Esta línea (#2) y la siguiente están resaltadas
  retrun 'Esta es la línea #3 de este fragmento'
}

```js {2-3}
function demo() {
  // Esta línea (#2) y la siguiente están resaltadas
  return 'Esta es la línea #3 de este fragmento';
}
```

Marca selecciones de texto usando el marcador " " o expresiones regulares:

// Términos individuales también pueden ser resaltados
function demo() {
  return 'También las expresiones regulares son compatibles';
}

```js "Términos individuales" /También.*compatibles/
// Términos individuales también pueden ser resaltados
function demo() {
  return 'También las expresiones regulares son compatibles';
}
```

Marca texto o líneas como insertadas o eliminadas con ins o del:

function demo() {
  console.log('Estos son tipos de marcadores insertados y eliminados');
  // La declaración de retorno utiliza el tipo de marcador predeterminado
  return true;
}

```js "return true;" ins="insertados" del="eliminados"
function demo() {
  console.log('Estos son tipos de marcadores insertados y eliminados');
  // La declaración de retorno utiliza el tipo de marcador predeterminado
  return true;
}
```

Combina el resaltado de sintaxis con la sintaxis similar a diff:

function thisIsJavaScript() {
  // ¡El bloque completo se resalta como JavaScript,
  // y aún podemos añadir marcadores de diferencias a él!
  console.log('Código antiguo a eliminar')
  console.log('¡Nuevo y brillante código!')
}

```diff lang="js"
  function thisIsJavaScript() {
    // ¡El bloque completo se resalta como JavaScript,
    // y aún podemos añadir marcadores de diferencias a él!
-   console.log('Código antiguo a eliminar')
+   console.log('¡Nuevo y brillante código!')
  }
```

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, basho 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.

Añade una pestaña con el nombre del archivo con un comentario

console.log('¡Hola mundo!');

```js
// mi-archivo-de-prueba.js
console.log('¡Hola mundo!');
```

Agrega un título a la ventana Terminal

npm install

```bash title="Instalando dependencias…"
npm install
```

Desactiva los marcos de ventana con frame="none"

echo "Esto no se renderiza como una terminal a pesar de usar el lenguaje bash"

```bash frame="none"
echo "Esto no se renderiza como una terminal a pesar de usar el lenguaje bash"
```

Details

Los details (también conocidos como “revelaciones” o “acordeones”) son útiles para ocultar contenido que no es inmediatamente relevante. Los usuarios pueden hacer clic en un breve resumen para expandir y ver el contenido completo.

Usa el elemento HTML estándar <details> y <summary> en tu contenido Markdown para crear un widget de revelación.

Puedes anidar cualquier otra sintaxis de Markdown dentro de un elemento <details>.

¿Dónde y cuándo es más visible la constelación de Andrómeda?

La constelación de Andrómeda es más visible en el cielo nocturno durante el mes de noviembre en latitudes entre +90° y −40°.

<details>
<summary>¿Dónde y cuándo es más visible la constelación de Andrómeda?</summary>

La [constelación de Andrómeda](<https://es.wikipedia.org/wiki/Andr%C3%B3meda_(constelaci%C3%B3n)>) es más visible en el cielo nocturno durante el mes de noviembre en latitudes entre `+90°` y `−40°`.

</details>

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 “Plugins de Markdown” en la documentación de Astro para obtener más información.

Markdoc

Starlight admite la creación de contenido en Markdoc utilizando la integración experimental de Astro Markdoc y el preset de Starlight Markdoc.

Crea un nuevo proyecto con Markdoc

Empieza un nuevo proyecto en Starlight con Markdoc preconfigurado usando create astro:

npm create astro@latest -- --template starlight/markdoc

pnpm create astro --template starlight/markdoc

yarn create astro --template starlight/markdoc

Agrega Markdoc a un proyecto existente

Si ya tienes un sitio Starlight y quieres agregar Markdoc, sigue estos pasos.

Agrega la integración de Markdoc de Astro:
- npm
- pnpm
- Yarn
Ventana de terminal
npx astro add markdoc
Ventana de terminal
pnpm astro add markdoc
Ventana de terminal
yarn astro add markdoc

Instala el preajuste de Starlight Markdoc:

npm install @astrojs/starlight-markdoc

pnpm add @astrojs/starlight-markdoc

yarn add @astrojs/starlight-markdoc

Crea un archivo de configuración de Markdoc en markdoc.config.mjs y utiliza el preset de Starlight Markdoc:

import { defineMarkdocConfig } from '@astrojs/markdoc/config';
import starlightMarkdoc from '@astrojs/starlight-markdoc';

export default defineMarkdocConfig({
  extends: [starlightMarkdoc()],
});

Para obtener más información sobre la sintaxis y las características de Markdoc, consulta la documentación de Markdoc o la guía de integración de Astro Markdoc.