Navigazione

La barra laterale e la barra superiore sono definite interamente in docs.json. La gerarchia di navigazione ha tre livelli: schede per le sezioni di primo livello, gruppi per le cartelle comprimibili e pagine per le singole voci. Le ancore aggiungono link esterni visualizzati in ogni pagina.

Gli screenshot mostrano l'interfaccia in inglese.

Panoramica della struttura

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

Concetti

Schede

Sezioni di navigazione di primo livello. Controlla la loro posizione con l'impostazione tabsPosition:

La posizione predefinita dipende dal tema:

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

Quando le schede si trovano nell'intestazione, tabsAlignment stabilisce dove sta la riga di schede:

{
  "tabsPosition": "top",
  "tabsAlignment": "center"
}

tabsAlignment non ha effetto quando le schede sono nella barra laterale, né nel tema Pulsar, che colloca le schede superiori sul lato destro dell'intestazione.

Link esterni (ancore)

Aggiungi link esterni visualizzati in cima alla barra laterale in tutte le pagine:

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

Gruppi

Un gruppo è un insieme denominato di voci della barra laterale all'interno di una scheda. I gruppi aggiungono un secondo livello alla gerarchia della barra laterale e consentono di nascondere le sezioni più profonde dietro cartelle in stile fisarmonica.

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

Comportamento di sezioni e fisarmoniche

I gruppi di primo livello sono sezioni permanenti: il titolo e le relative pagine sono sempre visibili e facendo clic sul titolo si passa alla prima pagina del gruppo. I gruppi denominati annidati sono fisarmoniche comprimibili. Un gruppo annidato è chiuso per impostazione predefinita, a meno che non contenga la pagina corrente o non imposti expanded: true. Al caricamento iniziale e quando cambia il percorso, l'intera catena di antenati della pagina corrente si apre automaticamente, mostrando il link attivo; i visitatori possono comunque comprimere manualmente il gruppo annidato attivo.

Usa i gruppi di primo livello per le sezioni principali della barra laterale e i gruppi annidati per mantenere consultabili le sezioni più lunghe. Lo stato di apertura persiste durante la navigazione nell'app e viene reimpostato dopo un aggiornamento completo della pagina.

Campi dei gruppi

Pagine

Singole pagine della documentazione, identificate dal percorso del file (senza .mdx):

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

Per impostazione predefinita, il titolo della barra laterale viene generato dal nome del file: i trattini diventano spazi e ogni parola viene scritta con l'iniziale maiuscola. Ad esempio, "api/getting-started" viene visualizzato come "Getting Started".

Per impostare un titolo personalizzato nella barra laterale, usa un oggetto invece di una stringa:

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

Questa opzione è utile per acronimi, nomi propri e badge degli endpoint API.

Più schede

Crea sezioni separate per destinatari diversi:

{
  "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"] }]
      }
    ]
  }
}

Link esterni nelle schede

Collega direttamente dalle schede documentazione o risorse esterne:

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

Le schede esterne si aprono in una nuova scheda del browser.

Gruppi annidati

Organizza la documentazione complessa con strutture annidate:

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

Cosa fare ora?