Navegación

Tu barra lateral y tu barra superior se definen completamente en docs.json. La jerarquía de navegación tiene tres niveles: pestañas para las secciones de nivel superior, grupos para carpetas plegables y páginas para entradas individuales. Las anclas añaden 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 la configuración 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 de tu 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 de la barra lateral se muestran en la variante Font Awesome Solid de forma predeterminada. Anula el grosor de cualquier icono con un prefijo de estilo (light/book) o el formato de objeto de icono.

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	Obligatorio	Descripción
`name`	string	Sí	Texto que se muestra para el 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 añaden un segundo nivel de jerarquía a tu barra lateral y te permiten ocultar secciones más profundas detrás de carpetas con estilo de acordeón.

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

Comportamiento de secciones y acordeones

Los grupos de nivel superior son secciones permanentes: el título y sus páginas siempre están visibles, y al hacer clic en el título se salta a la primera página del grupo. Los grupos anidados con nombre son acordeones plegables. Un grupo anidado empieza cerrado a menos que contenga la página actual o tenga expanded: true. En la carga inicial y en los cambios de ruta, toda la cadena de ancestros de la página actual se abre automáticamente para revelar el enlace activo; los visitantes aún pueden colapsar manualmente el grupo anidado activo.

Tipo de grupo	Comportamiento predeterminado
Grupo de nivel superior	Siempre abierto, sin chevron. Al hacer clic en el título se navega a la primera página del grupo.
Grupo anidado con nombre	Colapsado hasta que está activo, se abre manualmente o se configura con `expanded: true`. Al hacer clic en un grupo cerrado se abre, y al hacer clic en un grupo abierto se cierra; la navegación solo ocurre al hacer clic en una página.
Contenedor sin nombre	Siempre muestra sus páginas porque no tiene etiqueta ni control de alternancia.

Usa grupos de nivel superior para las secciones principales de tu barra lateral y grupos anidados para mantener las secciones más largas fáciles de explorar. El estado de expansión persiste durante la navegación dentro de la aplicación y se restablece al actualizar la página por completo.

Barra lateral con el grupo 'Privacidad y acceso' colapsado: el chevron apunta hacia la derecha, las páginas hijas están ocultas — Un grupo anidado en su estado colapsado. El chevron apunta hacia la derecha y las páginas hijas están ocultas.

Barra lateral con el grupo 'Privacidad y acceso' expandido: el chevron rotado hacia abajo, tres páginas hijas visibles debajo — El mismo grupo después de navegar a una de sus páginas hijas. El chevron rota y las páginas hijas aparecen debajo.

Campos de grupo

Campo	Tipo	Obligatorio	Descripción
`group`	string	Sí	Etiqueta que se muestra en la barra lateral.
`pages`	array	Sí	Lista de rutas de página y/o objetos de grupo anidados (consulta Grupos anidados para conocer la forma anidada).
`icon`	string	No	Nombre del icono de Font Awesome que se muestra junto a la etiqueta del grupo.
`tag`	string	No	Pequeña insignia junto a la etiqueta (por ejemplo, `"New"`, `"Beta"`).
`root`	string	No	Ruta de página a la que enlaza el grupo cuando se hace 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. Usa la configuración de la pestaña principal de forma predeterminada.
`expanded`	boolean	No	Abre un grupo anidado con nombre de forma predeterminada al cargar la página por primera vez. Los grupos de nivel superior siempre están abiertos, por lo que la marca no tiene ningún efecto visible ahí. Los grupos ancestros de la página actual se abren automáticamente en la carga inicial y en los cambios de ruta.

Páginas

Páginas de documentación individuales, 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 establecer 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 siglas, nombres propios e insignias de endpoints de API.

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

Varias pestañas

Crea secciones independientes para diferentes públicos:

{
  "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 externos en pestañas

Enlaza directamente a documentación o recursos externos 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 tus documentos para escalar