Navegación

Tu barra lateral y barra superior se definen completamente en docs.json. La jerarquía de navegación tiene tres niveles: pestañas para las secciones principales, grupos para carpetas contraíbles y páginas para entradas individuales, además de anclas para enlaces externos que aparecen en todas las páginas.

Las capturas de pantalla muestran la interfaz en inglés.

Descripción general de la estructura

docs.json

{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "icon": "book-open",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["introduction", "quickstart"]
          }
        ]
      }
    ]
  }
}

Conceptos

Pestañas

Secciones de navegación de nivel superior. Controla su posición con el ajuste tabsPosition:

Valor	Posición
`"top"`	En la barra de pestañas del encabezado
`"left"`	En la parte superior de la barra lateral

La posición predeterminada depende del tema:

Tema	Predeterminado
jam	`"left"`
nebula	`"left"`
pulsar	`"top"`

{
  "tabsPosition": "left",
  "navigation": {
    "tabs": [
      { "tab": "Guides", "icon": "book", "groups": [...] },
      { "tab": "API", "icon": "code", "groups": [...] }
    ]
  }
}

Los iconos utilizan la variante Light de Font Awesome para mantener una apariencia limpia y coherente.

Enlaces externos (anclas)

Añade enlaces externos que aparecen en la parte superior de la barra lateral en todas las páginas:

{
  "anchors": [
    { "name": "Blog", "href": "https://blog.example.com", "icon": "newspaper" },
    { "name": "Status", "href": "https://status.example.com", "icon": "signal" }
  ]
}

Campo	Tipo	Requerido	Descripción
`name`	string	Sí	Texto visible del enlace
`href`	string	Sí	URL (se abre en una pestaña nueva)
`icon`	string	No	Nombre del icono de Font Awesome

Grupos

Un grupo es un conjunto etiquetado de entradas de la barra lateral dentro de una pestaña. Los grupos dan a tu barra lateral un ritmo de dos niveles y te permiten ocultar secciones más profundas detrás de carpetas estilo acordeón.

{
  "group": "Authentication",
  "pages": ["auth/overview", "auth/tokens"]
}

Dos niveles de renderizado

La barra lateral muestra los grupos de nivel superior y los grupos anidados de forma diferente:

Nivel	Dónde aparece	Comportamiento
Grupo de nivel superior	Directamente bajo una pestaña en `docs.json`	Actúa como encabezado de sección persistente. Siempre muestra sus páginas. Al hacer clic en el encabezado se salta a la primera página del grupo.
Grupo anidado	Dentro del array `pages` de otro grupo	Se renderiza como una carpeta estilo acordeón con un botón de alternancia. Haz clic para expandir o contraer.

El nivel de un grupo es posicional: los grupos más externos bajo una pestaña se renderizan como nivel superior, y cualquier grupo colocado dentro del array pages de otro grupo se renderiza como carpeta anidada. No existe un indicador topLevel.

Usa grupos de nivel superior para las secciones principales de tu barra lateral (Get Started, Reference, Guides) y grupos anidados cuando una sección de nivel superior tenga suficientes páginas como para que un segundo nivel de jerarquía ayude al lector a explorar. Consulta Grupos anidados para ver la estructura JSON.

Comportamiento de los grupos anidados

Sidebar with the 'Privacy & Access' nested group collapsed: chevron points right, child pages hidden — Un grupo anidado en su estado contraído. El chevron apunta a la derecha y las páginas hijas están ocultas.

Se expanden automáticamente a la página actual. El grupo que contiene la página que estás viendo se abre automáticamente, de modo que el enlace activo siempre es visible.
Haz clic para alternar. Hacer clic en el encabezado de un grupo anidado lo expande (y navega a su primera página) o lo contrae si ya está abierto.
El estado persiste durante la navegación en la aplicación. Los grupos que abres manualmente permanecen abiertos mientras te mueves entre páginas. Una recarga completa de la página restablece el estado abierto/cerrado.

Sidebar with the 'Privacy & Access' nested group expanded: chevron rotated down, three child pages visible below — El mismo grupo tras navegar a una de sus páginas hijas. El chevron rota y las páginas hijas aparecen debajo.

Campos de grupo

Campo	Tipo	Requerido	Descripción
`group`	string	Sí	Etiqueta visible en la barra lateral.
`pages`	array	Sí	Lista de rutas de páginas y/o objetos de grupo anidado (consulta Grupos anidados para la estructura anidada).
`icon`	string	No	Nombre del icono de Font Awesome que aparece junto a la etiqueta del grupo.
`tag`	string	No	Pequeña insignia junto a la etiqueta (p. ej., `"New"`, `"Beta"`).
`root`	string	No	Ruta de página a la que enlaza el grupo al hacer clic en la etiqueta (en lugar de saltar a la primera página hija).
`hidden`	boolean	No	Oculta el grupo de la barra lateral de forma predeterminada. Las páginas siguen siendo accesibles mediante enlace directo.
`public`	boolean	No	Marca el grupo como accesible públicamente. Por defecto usa el ajuste de la pestaña padre.
`expanded`	boolean	No	Abre el grupo de forma predeterminada en la primera carga de la página. Solo tiene efecto en grupos anidados (los grupos de nivel superior siempre muestran sus páginas).

Páginas

Páginas individuales de documentación, referenciadas por su ruta de archivo (sin .mdx):

"pages": ["introduction", "guides/quickstart", "api/endpoints"]

De forma predeterminada, el título de la barra lateral se genera a partir del nombre del archivo: los guiones se convierten en espacios y cada palabra se escribe con mayúscula inicial. Por ejemplo, "api/getting-started" se muestra como "Getting Started".

Para definir un título personalizado en la barra lateral, usa un objeto en lugar de una cadena:

"pages": [
  "guides/quickstart",
  { "page": "deploy/aws", "title": "AWS Route 53 & CloudFront" },
  { "page": "content/seo", "title": "SEO" },
  { "page": "api/users", "title": "List Users", "method": "GET" }
]

Esto es útil para acrónimos, nombres propios e insignias de endpoints de API.

Campo	Tipo	Requerido	Descripción
`page`	string	Sí	Ruta del archivo sin `.mdx`
`title`	string	No	Título personalizado en la barra lateral
`icon`	string	No	Nombre del icono de Font Awesome
`tag`	string	No	Pequeña insignia junto al título (p. ej., "New", "Beta")
`method`	string	No	Insignia de método HTTP: GET, POST, PUT, PATCH o DELETE

Múltiples pestañas

Crea secciones separadas para distintos tipos de usuarios:

{
  "navigation": {
    "tabs": [
      {
        "tab": "Guides",
        "icon": "book",
        "groups": [
          { "group": "Getting Started", "pages": ["intro", "quickstart"] }
        ]
      },
      {
        "tab": "API Reference",
        "icon": "code",
        "groups": [{ "group": "Endpoints", "pages": ["api/auth", "api/users"] }]
      }
    ]
  }
}

Enlaces de pestaña externos

Enlaza a documentación o recursos externos directamente desde las pestañas:

{
  "navigation": {
    "tabs": [
      { "tab": "Docs", "icon": "book", "groups": [...] },
      { "tab": "GitHub", "icon": "github", "href": "https://github.com/example/repo" }
    ]
  }
}

Las pestañas externas se abren en una nueva pestaña del navegador.

Grupos anidados

Organiza documentación compleja con estructuras anidadas:

{
  "group": "SDKs",
  "pages": [
    "sdks/overview",
    {
      "group": "JavaScript",
      "pages": ["sdks/js/install", "sdks/js/usage"]
    },
    {
      "group": "Python",
      "pages": ["sdks/python/install", "sdks/python/usage"]
    }
  ]
}

¿Qué sigue?

Conectar GitHub

Vincula tu repositorio para builds automáticos

Estructura de directorios

Organiza tu documentación para escalar