Cómo enlazar páginas de documentación de manera efectiva

Los enlaces conectan tu documentación en un sistema coherente. Ayudan a los usuarios a descubrir contenido relacionado, navegar eficientemente y seguir un camino lógico a través de temas complejos. Los enlaces deficientes—texto de anclaje vago, referencias cruzadas faltantes, URLs rotas—hacen que la documentación sea más difícil de usar y perjudican el SEO.

Esta guía cubre cómo crear diferentes tipos de enlaces en Mintlify y cómo mantener la integridad de los enlaces a medida que tu documentación crece.

Enlaza a otras páginas de tu documentación usando rutas relativas a la raíz. Las rutas relativas a la raíz comienzan desde la raíz de tu directorio de documentación y funcionan de manera consistente sin importar dónde se encuentre la página que enlaza en tu estructura de directorios.

- [Quickstart guide](/quickstart)
- [API overview](/api-playground/overview)
- [Custom components](/customize/react-components)

Mintlify resuelve las rutas relativas (./ y ../) según la ubicación del archivo fuente en el directorio de tu proyecto. Esto funciona para enlaces, imágenes y elementos JSX como las etiquetas <Card> y <a>.

- [Página hermana](./sibling-page)
- [Página de la sección superior](../other-page)

Para los archivos index.mdx, las rutas relativas se resuelven desde el directorio que contiene el archivo de índice. Por ejemplo, un enlace ./setup en guides/getting-started/index.mdx se resuelve a /guides/getting-started/setup.

Los enlaces conservan los fragmentos y las cadenas de consulta.

[Instrucciones de configuración](./setup#step-1)

Los enlaces de anclaje apuntan a secciones específicas dentro de una página. Cada encabezado genera automáticamente un anclaje basado en su texto.

Referencia encabezados en la página actual usando el símbolo de hash:

[Jump to best practices](#best-practices)

Combina la ruta de la página con el anclaje:

- [Customize your playground](/api-playground/overview#customize-your-playground)
- [Cards properties](/components/cards#properties)

Mintlify crea automáticamente anclajes a partir del texto de los encabezados convirtiendo a minúsculas, reemplazando espacios con guiones y eliminando caracteres especiales.

Sobrescribe el anclaje generado automáticamente para cualquier encabezado añadiendo {#custom-id} al texto del encabezado:

## Configuration options [#config]

Este encabezado es accesible en #config en lugar de #configuration-options. Los IDs personalizados mantienen los enlaces de anclaje estables cuando actualizas el texto del encabezado—útil para encabezados a los que enlazas frecuentemente. Consulta Formatear texto para más detalles.

Los enlaces profundos apuntan a estados o ubicaciones específicas dentro de una página, no solo a la página en sí.

Cuando un usuario abre un acordeón, el hash de la URL se actualiza para reflejar el estado abierto. Visitar una URL con ese hash abre automáticamente y desplaza hasta el acordeón.

Por defecto, el hash se deriva del title del acordeón. Usa la propiedad id para establecer un hash personalizado:

<Accordion title="Installation steps" id="install">
  ...
</Accordion>

Este acordeón es accesible en #install en lugar del #installation-steps generado automáticamente. Consulta Acordeones para más información.

Para abrir el API playground en un enlace, añade ?playground=open a cualquier URL de página de endpoint:

https://your-docs-url/endpoint-path?playground=open

La URL se actualiza cuando los usuarios abren o cierran el playground. Usa los enlaces profundos del playground en conversaciones de soporte o flujos de incorporación para enviar a los usuarios directamente al playground interactivo de un endpoint. Consulta API playground para información sobre enlaces de anclaje de parámetros.

Al enlazar a recursos externos, escribe texto de anclaje que deje claro el destino:

See the [OpenAPI specification](https://swagger.io/specification/) in the Swagger documentation for details.

El texto de anclaje debe indicar a los usuarios a dónde van antes de hacer clic. Frases vagas como “haz clic aquí” o “leer más” también son señales SEO más débiles que el texto descriptivo.

See [Hidden pages](/organize/hidden-pages) for more information.
[Configure custom domains](/customize/custom-domain)

Cuando una página asume pasos previos, enlázalos en la parte superior en lugar de asumir que los usuarios los encuentran:

## Prerequisites

Before deploying your documentation, ensure you have:

- Completed the [quickstart guide](/quickstart)
- Configured your [custom domain](/customize/custom-domain)
- Set up [authentication](/deploy/authentication-setup) if needed

Enlaza contenido relacionado para ayudar a los usuarios—y a los motores de búsqueda—a entender cómo organizas tu documentación:

## Related topics

- [API authentication](/api-playground/overview#authentication)
- [Adding SDK examples](/api-playground/adding-sdk-examples)
- [Managing page visibility](/api-playground/managing-page-visibility)

Ejecuta el CLI de Mintlify antes de publicar para detectar enlaces internos y externos rotos:

mint broken-links

Al mover o renombrar páginas:

1. Actualiza la ruta de la página en tu configuración de navegación.
2. Configura redirecciones de la ruta antigua a la nueva ruta.
3. Busca en tu documentación referencias a la ruta antigua.
4. Actualiza todos los enlaces internos para usar la nueva ruta.
5. Ejecuta mint broken-links para verificar.

Al mover contenido permanentemente, añade redirecciones para evitar enlaces rotos para los usuarios que han marcado o compartido URLs antiguas.

{
  "redirects": [
    {
      "source": "/old-path",
      "destination": "/new-path"
    }
  ]
}

Consulta Redirecciones para más información.

• Formatear texto: Opciones de formato Markdown incluyendo IDs de encabezados y comportamiento de anclajes.
• Navegación: Configura la estructura de tu documentación.
• Redirecciones: Configura redirecciones para contenido movido.