Navegación

Boltdocs trae un sistema de navegación de cuatro capas. Entender las capas — y qué clave de configuración controla cada una — es la diferencia entre un sitio que los lectores recorren con fluidez y uno en el que se pierden.

┌───────────────────────────────────────────────────────────┐
│ Navbar (theme.navbar)          enlaces principales + dropdowns │
├──────────┬────────────────────────────────────────────────┤
│ Tabs     │                                                │
│ (theme.  │  Breadcrumbs (automáticos, desde la ruta)      │
│  tabs)   │                                                │
├──────────┤────────────────────────────────────────────────┤
│ Sidebar  │  Contenido de la página                        │
│ (auto o  │                    OnThisPage (rail derecho)   │
│  theme.  │                    — headings de la página     │
│  sidebar)│                                                │
│          │  PageNav (página anterior / siguiente)         │
└──────────┴────────────────────────────────────────────────┘

Las tres últimas las renderiza automáticamente el layout por defecto a partir de los datos de ruta — solo configuras las dos primeras y, opcionalmente, tomas control del sidebar.

Navbar — theme.navbar

El navbar es el header global. Muestra tu logo, título y enlaces principales. Los enlaces pueden ser entradas simples o dropdowns anidados:

export default defineConfig({
  theme: {
    navbar: [
      { label: 'Docs', href: '/docs' },
      { label: 'Blog', href: '/blog' },
      {
        label: 'Recursos',
        href: '/recursos',
        items: [
          { label: 'Changelog', href: '/changelog' },
          { label: 'Showcase', href: '/showcase' },
        ],
      },
    ],
  },
})

Referencia del item de navbar

Opciones de display relacionadas: theme.githubRepo añade automáticamente el icono de GitHub, y theme.socialLinks añade iconos de Discord/X/Bluesky.

Tabs — theme.tabs

Los tabs dividen tu documentación en secciones horizontales. Cada tab mapea a una carpeta entre paréntesis en docs/:

docs/
├── (guides)/        → tab "guides"
├── (api)/           → tab "api"
└── (blog)/          → tab "blog"

export default defineConfig({
  theme: {
    tabs: [
      { id: 'guides', text: 'Guías', icon: 'BookOpen' },
      { id: 'api', text: 'API', icon: 'Code2' },
      { id: 'blog', text: 'Blog', icon: 'History' },
    ],
  },
})

Referencia de tab

Los paréntesis se eliminan de las URLs: docs/(guides)/getting-started se sirve en /docs/guides/getting-started. Los tabs funcionan con i18n anidando carpetas de locale dentro de ellos. Consulta File-System Routing para las convenciones completas de carpetas.

Sidebar — auto o manual

El sidebar se genera automáticamente desde tu árbol de docs/ por defecto: cada carpeta se convierte en un grupo, cada archivo en un item hijo. Es la forma más rápida de tener un sidebar completo — nunca escribes config de navegación para ello.

Sidebar automático (por defecto)

• Las carpetas se convierten en grupos colapsables; los títulos de grupo por defecto son el nombre de la carpeta capitalizado.
• El orden viene de prefijos numéricos de archivo (01-intro.md) o del frontmatter sidebarPosition.
• El meta.json de una carpeta controla su título, icono, orden y estado de colapso.

Sobrescribir títulos de grupo — theme.sidebarGroups

Ajusta títulos e iconos de grupo sin reconstruir todo el sidebar:

export default defineConfig({
  theme: {
    sidebarGroups: {
      'getting-started': { title: 'Quick Start', icon: 'Rocket' },
    },
  },
})

Sidebar manual — theme.sidebar

Toma control total de la estructura de un prefijo:

export default defineConfig({
  theme: {
    sidebar: {
      '/docs/guides': [
        { text: 'Introduction', link: '/docs/guides/introduction' },
        { text: 'Installation', link: '/docs/guides/installation' },
      ],
    },
  },
})

Frontmatter de sidebar por página

Consulta la guía de Routing para las reglas de orden y la guía de Metadatos para meta.json en profundidad.

Breadcrumbs, OnThisPage y PageNav

Estos tres son automáticos — el layout por defecto los deriva de los metadatos de ruta. No los configuras, pero debes saber qué hacen y cómo sustituirlos:

• Breadcrumbs — una ruta de migas sobre el título (p. ej. Guías → Navegación), construida desde la cadena de grupos de la ruta y localizada automáticamente. Referencia: Breadcrumbs.
• OnThisPage — el TOC del rail derecho que lista los headings h2–h4 de la página. Referencia: OnThisPage.
• PageNav — enlaces "Anterior / Siguiente" al final, siguiendo el orden del sidebar. Referencia: PageNav.

Usarlos en un layout personalizado

Se exportan como primitivas, así que un layout personalizado puede colocarlas donde quieras:

import { Breadcrumbs, OnThisPage, PageNav } from 'boltdocs/primitives'

export function MyLayout() {
  return (
    <>
      <Breadcrumbs />
      <main>{/* contenido de la página */}</main>
      <OnThisPage />
      <PageNav />
    </>
  )
}

Links y hrefs — cómo funciona la resolución

Todos los enlaces de Boltdocs — entradas del navbar, entradas del sidebar, cards y enlaces MDX — pasan por el mismo resolvedor de rutas (useLocalizedTo). Calcula la URL final a partir de una ruta canónica sin localizar más el contexto del visitante (locale, versión y base de docs). Escribes hrefs canónicos; el framework los localiza. El resolvedor nunca reescribe URLs externas.

Orden de resolución

Cuando el resolvedor ve un href, aplica estas reglas en orden:

1. Las URLs externas pasan intactas — https://…, http://…, relativas de protocolo //…, otros esquemas URI (mailto:, tel:, data:), anclas internas (#section) y strings solo de query (?q=term).
2. El prefijo site: fuerza la resolución contra la raíz del sitio — el destino se resuelve contra la raíz del sitio, fuera de la base de docs.
3. Las rutas conocidas ganan — si la ruta coincide con una ruta del índice de rutas (incluidas las páginas de pages-external/ y las rutas de colección), se respeta su propio tipo: las páginas externas se quedan en la raíz, las colecciones se quedan bajo la base.
4. Las rutas desconocidas con / se tratan como rutas de docs — se aplica la base configurada y se añaden los prefijos de locale/versión activos.

Tabla de decisión de hrefs

El protocolo site:

site: es un prefijo tipo URI que le dice al resolvedor que deje de tratar el destino como una ruta de docs. Es la vía de escape para enlaces que deben resolverse contra la raíz del sitio en lugar de la base de docs. En prosa a menudo lo verás escrito como site:// — la forma soportada es el prefijo site: seguido de la ruta absoluta (site:/ruta).

¿Cuándo se necesita?

• Enlazar a páginas de nivel superior del sitio — la home, pricing, roadmap o una landing que vive fuera de docs/. Si la ruta no está en el índice del resolvedor, un /roadmap simple se trataría como ruta de docs y se convertiría en /docs/roadmap. site:/roadmap siempre resuelve a /roadmap.
• Enlazar desde superficies que se renderizan pronto — banners, heroes y páginas externas que se renderizan antes de la hidratación pueden tener un índice de rutas vacío. site: mantiene esos enlaces correctos.
• Enlazar a entradas de colección desde cualquier lugar — site:/blog/mi-post resuelve a /docs/blog/mi-post (la base se aplica a colecciones conocidas), así los enlaces de colección funcionan aunque el índice no esté cargado.

- [Home](site:/)
- [Roadmap](site:/roadmap)
- [Último release](site:/blog/boltdocs-3.3.0)

export default defineConfig({
  theme: {
    navbar: [
      { label: 'Home', href: 'site:/' },
      { label: 'Docs', href: '/docs/guides' },
      { label: 'Showcase', href: '/showcase' },
    ],
  },
})

Cómo funciona la inferencia de locale

El i18n se basa en convenciones de carpetas, y el resolvedor refleja esa convención en las URLs:

• Las rutas canónicas nunca contienen un locale. Escribes /docs/guides/getting-started, no /es/docs/guides/getting-started.
• El locale activo viene del contexto del visitante (la URL en la que está más su preferencia guardada).
• Cuando el locale activo no es el predeterminado, el resolvedor lo antepone: /docs/guides/getting-started → /docs/es/guides/getting-started.
• El locale predeterminado nunca recibe prefijo — vive en la raíz de la base.
• El parsing también es consciente del locale: un primer segmento que coincida con un locale configurado (p. ej. /docs/es/...) se reconoce y se elimina antes de clasificar, así los enlaces mixtos también resuelven.

Locale activo: es (predeterminado: en)
  /docs/guides/getting-started  →  /docs/es/guides/getting-started
  site:/                        →  /es
  /docs/es/guides/getting-started  →  /docs/es/guides/getting-started (se mantiene)

Locale activo: en (predeterminado: en)
  /docs/guides/getting-started  →  /docs/guides/getting-started (sin prefijo)

Consulta Internacionalización para el layout de carpetas y el comportamiento de respaldo.

Cómo funciona la inferencia de versión

El versionado sigue el mismo patrón que el locale:

• Las rutas canónicas no contienen segmento de versión. Escribes /docs/guides/getting-started.
• La versión activa viene del contexto del visitante. Cuando no es la versión predeterminada, el resolvedor antepone el/los segmento(s) de versión construidos desde versions.prefix + la ruta de la versión.
• Una versión explícita en el destino gana sobre la preferencia activa: /docs/v2/guides/getting-started resuelve exactamente a eso, aunque el visitante esté leyendo v1.
• Si el versionado está desactivado (o la versión es desconocida), nunca se añade un segmento de versión — una preferencia obsoleta no puede corromper las URLs.

Config: versions: { prefix: 'v', defaultVersion: 'v1', versions: [{ path: 'v1' }, { path: 'v2' }] }

Versión activa: v1 (predeterminada)
  /docs/guides/getting-started  →  /docs/guides/getting-started (sin prefijo)

Versión activa: v2, locale: es
  /docs/guides/getting-started  →  /docs/v2/es/guides/getting-started

Consulta Versionado para el layout de carpetas y la estructura de URLs.

Buenas prácticas para navegar desde MDX

1. Escribe siempre hrefs canónicos. Hardcodear prefijos de locale o versión rompe la localización — el resolvedor espera rutas canónicas sin localizar y añade los prefijos él mismo.

<!-- ✅ Canónico — se localiza automáticamente -->
- [Primeros pasos](/docs/guides/getting-started)

<!-- ❌ Nunca escribas prefijos de locale/versión a mano -->
- [Primeros pasos](/es/docs/guides/getting-started)
- [Primeros pasos](/v2/docs/guides/getting-started)

2. Usa rutas absolutas canónicas para enlaces entre páginas. Son inequívocas sin importar dónde viva la página actual:

- [Routing](/docs/guides/getting-started/routing)
- [Instalación](/docs/guides/getting-started/installation)

3. Usa enlaces relativos para saltos dentro de la misma carpeta y ../ para carpetas hermanas:

[Siguiente: metadatos](../content/metadata)

4. Usa site: para todo lo que deba vivir en la raíz del sitio — home, páginas de marketing o entradas de colección referenciadas desde fuera del tab de docs:

[Home](site:/)
[Blog](/docs/blog)
[Showcase](/showcase)

5. Mantén las anclas y queries locales. #section y ?q=term se conservan y se unen a la página actual:

[Saltar a la sección site:](#el-protocolo-site)

6. Prefiere <Link> sobre <a> en componentes. La primitiva Link de boltdocs/primitives pasa cada href por el resolvedor y mantiene la navegación client-side rápida. Llama a useLocalizedTo() directamente solo cuando necesites el string resuelto (estados activos, analytics, menús):

import { Link } from 'boltdocs/primitives'
import { useLocalizedTo } from 'boltdocs/client'

const resolved = useLocalizedTo('/docs/guides')

<Link href="/docs/guides">Guías</Link>

Cómo navegan los lectores (referencia rápida)

1. Arriba — los enlaces del navbar cambian de área principal; los tabs cambian de sección de documentación.
2. Izquierda — el sidebar muestra la estructura completa de la sección actual; la página activa está resaltada.
3. Derecha — OnThisPage salta dentro de la página actual.
4. Abajo — PageNav mueve a la página anterior/siguiente en orden de lectura.
5. En todas partes — los breadcrumbs muestran dónde está la página en la jerarquía; la búsqueda (⌘K) encuentra páginas en todos los tabs.

Dónde seguir

• File-System Routing — convenciones de carpetas, orden y tabs en profundidad.
• Metadatos — meta.json y _meta.json para grupos del sidebar.
• Internacionalización — carpetas de locale y rutas de respaldo.
• Versionado — prefijos de versión y estructura de URLs.
• Layout personalizado — compón el shell completo de la página tú mismo.
• Referencia de DocsLayout — cada región que el layout por defecto conecta.

Jesús Alcalá

Last updated on October 18, 2026