mintlify__docs/es/guides/linking.mdx

---
title: "Cómo enlazar páginas de documentación de manera efectiva"
sidebarTitle: "Enlaces"
description: "Crea enlaces internos, anclas y enlaces profundos en tu documentación, y mantén su integridad con redirecciones y verificaciones de enlaces rotos."
keywords: ["enlaces de documentación", "enlaces internos", "enlaces de anclaje", "enlaces rotos", "enlaces profundos", "referencias cruzadas"]
---

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.

<div id="internal-links">
## Enlaces internos
</div>

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.

```mdx
- [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>`.

```mdx
- [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.

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

<Tip>
  Las rutas relativas a la raíz (que comienzan con `/`) funcionan mejor para los enlaces internos porque siguen siendo correctas si mueves la página que enlaza a un directorio diferente.
</Tip>

<div id="anchor-links">
## Enlaces de anclaje
</div>

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.

<div id="link-to-headers-on-the-same-page">
### Enlazar a encabezados en la misma página
</div>

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

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

<div id="link-to-headers-on-other-pages">
### Enlazar a encabezados en otras páginas
</div>

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

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

<div id="how-mintlify-generates-anchors">
### Cómo Mintlify genera anclajes
</div>

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

| Texto del encabezado | Anclaje generado |
|---|---|
| `## Getting Started` | `#getting-started` |
| `### API Authentication` | `#api-authentication` |
| `#### Step 1: Install` | `#step-1-install` |

<Note>
  Los encabezados con la prop `noAnchor` no generan enlaces de anclaje. Consulta [Formatear texto](/es/create/text#disabling-anchor-links) para más detalles.
</Note>

<div id="custom-anchor-ids">
### IDs de anclaje personalizados
</div>

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

```mdx
## 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](/es/create/text#custom-heading-ids) para más detalles.

<div id="deep-links">
## Enlaces profundos
</div>

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

<div id="accordion-deep-links">
### Enlaces profundos de acordeón
</div>

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:

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

Este acordeón es accesible en `#install` en lugar del `#installation-steps` generado automáticamente. Consulta [Acordeones](/es/components/accordions) para más información.

<div id="api-playground-deep-links">
### Enlaces profundos del API playground
</div>

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

```text
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](/es/api-playground/overview#parameter-anchor-links) para información sobre enlaces de anclaje de parámetros.

<div id="external-links">
## Enlaces externos
</div>

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

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

<div id="best-practices">
## Mejores prácticas
</div>

<div id="write-descriptive-anchor-text">
### Escribe texto de anclaje descriptivo
</div>

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.

<CodeGroup>

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

```mdx Avoid
[Click here](/api-playground/overview)
[Read more](/deploy/deployments)
[See this page](/customize/custom-domain)
```

</CodeGroup>

<div id="link-prerequisites-explicitly">
### Enlaza los prerrequisitos explícitamente
</div>

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

```mdx
## 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
```

<div id="build-topic-clusters">
### Construye clústeres de temas
</div>

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

```mdx
## Related topics

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

<div id="check-for-broken-links">
### Verifica los enlaces rotos
</div>

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

```bash
mint broken-links
```

<div id="update-links-when-reorganizing">
### Actualiza los enlaces al reorganizar
</div>

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.

<div id="use-redirects-for-moved-content">
### Usa redirecciones para contenido movido
</div>

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

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

Consulta [Redirecciones](/es/create/redirects) para más información.

<div id="frequently-asked-questions">
## Preguntas frecuentes
</div>

<AccordionGroup>
<Accordion title="¿Debo usar rutas relativas a la raíz o URLs absolutas para enlaces internos?">
Las rutas relativas a la raíz (que comienzan con `/`) son la opción más común para enlaces internos en Mintlify. Funcionan de manera consistente sin importar dónde se encuentre la página que enlaza en tu directorio, y no se rompen si tu dominio de documentación cambia. Las URLs absolutas para enlaces internos crean una fragilidad innecesaria.

Puedes usar rutas relativas (`./` y `../`), pero debido a que se resuelven según la ubicación del archivo fuente, pueden romperse con mayor frecuencia.
</Accordion>

<Accordion title="¿Cómo mantengo estables los enlaces de anclaje cuando actualizo los encabezados?">
Usa IDs de anclaje personalizados para los encabezados a los que enlazas frecuentemente. Añadir `{#custom-id}` a un encabezado desacopla el anclaje del texto del encabezado, para que puedas actualizar el texto del encabezado sin romper ningún enlace que apunte a él. Esto es especialmente útil para encabezados en secciones de referencia de alto tráfico donde el texto puede necesitar refinamiento con el tiempo.
</Accordion>

<Accordion title="¿Qué pasa con los enlaces marcados cuando reorganizo mi documentación?">
Los enlaces marcados y compartidos se convierten en errores 404 sin redirecciones. Configura redirecciones en tu `docs.json` cada vez que muevas o renombres una página. Las redirecciones son económicas de añadir y evitan una mala experiencia de usuario para cualquiera que haya enlazado a tu documentación desde una fuente externa—publicaciones de blog, respuestas de Stack Overflow, wikis internas.
</Accordion>

<Accordion title="¿Cuántos enlaces internos debe tener una página?">
Enlaza cuando un concepto relacionado sea genuinamente útil para el usuario en ese momento—no para cumplir una cuota. Muy pocos enlaces dejan a los usuarios sin contexto o próximos pasos. Demasiados enlaces convierten la página en un ejercicio de navegación que aleja a los usuarios de lo que están tratando de hacer. Como heurística general, enlaza la primera mención de un concepto o herramienta, y no repitas el mismo enlace varias veces en una sola página.
</Accordion>
</AccordionGroup>

<div id="related-resources">
## Recursos relacionados
</div>

- [Formatear texto](/es/create/text): Opciones de formato Markdown incluyendo IDs de encabezados y comportamiento de anclajes.
- [Navegación](/es/organize/navigation): Configura la estructura de tu documentación.
- [Redirecciones](/es/create/redirects): Configura redirecciones para contenido movido.