Il file docs.json consente di trasformare una raccolta di file Markdown in un sito di documentazione navigabile e personalizzato. Questo file di configurazione obbligatorio controlla stile, navigazione, integrazioni e altro ancora. Consideralo come il blueprint della tua documentazione. Le impostazioni in docs.json si applicano globalmente a tutte le pagine.

​
Configurazione del file docs.json

Per iniziare, è sufficiente specificare theme, name, colors.primary e navigation. Gli altri campi sono facoltativi e puoi aggiungerli man mano che aumentano le esigenze della tua documentazione. Per la migliore esperienza di editing, includi il riferimento allo schema all’inizio del file docs.json. Questo abilita il completamento automatico, la validazione e utili suggerimenti contestuali nella maggior parte degli editor di codice: 
{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Your Docs",
  "colors": {
    "primary": "#ff0000"
  },
  "navigation": {
    // Struttura di navigazione
  }
  // Resto della configurazione
}

​
Riferimento

Questa sezione contiene la reference completa del file docs.json.

​
Personalizzazione

​
theme
required
Il tema del layout del tuo sito.Una delle seguenti opzioni: mint, maple, palm, willow, linden, almond, aspen.Consulta Temi per ulteriori informazioni.
​
name
string
required
Il nome del tuo progetto, organizzazione o prodotto.
​
colors
object
required
I colori utilizzati nella documentazione. L’applicazione dei colori varia a seconda del tema. Se fornisci solo un colore primario, verrà usato per tutti gli elementi cromatici.
​
description
string
Descrizione del sito per SEO e indicizzazione AI.
Il logo per le modalità chiara e scura.
​
favicon
string or object
Percorso del file favicon, inclusa l’estensione. Ridimensionata automaticamente alle dimensioni appropriate. Può essere un singolo file o file separati per le modalità chiara e scura. Esempio: /favicon.png
​
thumbnails
object
Personalizzazione delle miniature per i social media e le anteprime delle pagine.
​
styling
object
Configurazioni di stile visivo.
​
icons
object
Impostazioni della libreria di icone.
​
fonts
object
Configurazione dei font per la documentazione. Il font predefinito è Inter.
​
appearance
object
Impostazioni dell’interruttore modalità chiara/scura.
​
background
object
Impostazioni del colore e delle decorazioni dello sfondo.

​
Struttura

​
navbar
object
Elementi della barra di navigazione.
​
navigation
object
required
La struttura di navigazione dei contenuti.
​
interaction
object
Impostazioni di interazione utente per gli elementi di navigazione.
​
footer
object
Contenuto del footer e link ai social.
​
banner
object
Banner a livello di sito visualizzato in cima alle pagine.
​
redirects
array of object
Reindirizzamenti per pagine spostate, rinominate o eliminate.
​
contextual
object
Menu contestuale per contenuti e integrazioni ottimizzati con l’IA.

​
Configurazioni API

​
api
object
Impostazioni per la documentazione API e per l’API playground interattivo.
​
seo
object
Configurazioni di indicizzazione SEO.
​
search
object
Impostazioni di visualizzazione della ricerca.

​
Integrazioni

​
integrations
object
Integrazioni di terze parti.

​
Errori

​
errors
object
Impostazioni per la gestione degli errori.

​
Esempi

docs.json
{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "maple",
  "name": "Example Co.",
  "description": "Example Co. è un'azienda che fornisce contenuti di esempio e testo segnaposto.",
  "colors": {
    "primary": "#3B82F6",
    "light": "#F8FAFC",
    "dark": "#0F172A"
  },
  "navigation": {
    "dropdowns": [
      {
        "dropdown": "Documentazione",
        "icon": "book",
        "description": "Guida all'uso del prodotto Example Co.",
        "groups": [
          {
            "group": "Per iniziare",
            "pages": [
              "index",
              "quickstart"
            ]
          },
          {
            "group": "Personalizzazione",
            "pages": [
              "settings",
              "users",
              "features"
            ]
          },
          {
            "group": "Fatturazione",
            "pages": [
              "billing/overview",
              "billing/payments",
              "billing/subscriptions"
            ]
          }
        ]
      },
      {
        "dropdown": "Changelog",
        "icon": "history",
        "description": "Aggiornamenti e modifiche",
        "pages": [
          "changelog"
        ]
      }
    ]
  },
  "logo": {
    "light": "/logo-light.svg",
    "dark": "/logo-dark.svg",
    "href": "https://example.com"
  },
  "navbar": {
    "links": [
      {
        "label": "Community",
        "href": "https://example.com/community"
      }
    ],
    "primary": {
      "type": "button",
      "label": "Inizia",
      "href": "https://example.com/start"
    }
  },
  "footer": {
    "socials": {
      "x": "https://x.com/example",
      "linkedin": "https://www.linkedin.com/company/example",
      "github": "https://github.com/example",
      "slack": "https://example.com/community"
    },
    "links": [
      {
        "header": "Risorse",
        "items": [
          {
            "label": "Clienti",
            "href": "https://example.com/customers"
          },
          {
            "label": "Enterprise",
            "href": "https://example.com/enterprise"
          },
          {
            "label": "Richiedi anteprima",
            "href": "https://example.com/preview"
          }
        ]
      },
      {
        "header": "Azienda",
        "items": [
          {
            "label": "Posizioni aperte",
            "href": "https://example.com/careers"
          },
          {
            "label": "Blog",
            "href": "https://example.com/blog"
          },
          {
            "label": "Informativa sulla privacy",
            "href": "https://example.com/legal/privacy"
          }
        ]
      }
    ]
  },
  "integrations": {
    "ga4": {
      "measurementId": "G-XXXXXXXXXX"
    },
    "koala": {
      "publicApiKey": "pk_example_key_123"
    },
    "telemetry": {
      "enabled": true
    },
    "cookies": {
      "key": "example_cookie_key",
      "value": "example_cookie_value"
    }
  },
  "contextual": {
    "options": [
      "copy",
      "view",
      "chatgpt",
      "claude"
    ]
  },
  "errors": {
    "404": {
      "redirect": false,
      "title": "Impossibile trovare la pagina",
      "description": "Che fine ha **fatto** questa _pagina_?"
    }
  }
}

​
Aggiornamento da mint.json

Se il tuo progetto di documentazione utilizza il file deprecato mint.json, segui questi passaggi per passare a docs.json.
1

Installa o aggiorna la CLI

Se non hai ancora installato la CLI, installala ora:
npm i -g mint
Se la CLI è già installata, assicurati che sia aggiornata:
mint update
2

Crea il file docs.json

Nel repository della tua documentazione, esegui:
mint upgrade
Questo comando creerà un file docs.json a partire dal mint.json esistente. Controlla il file generato per assicurarti che tutte le impostazioni siano corrette.
3

Elimina il file mint.json

Dopo aver verificato che docs.json è configurato correttamente, puoi eliminare in sicurezza il vecchio file mint.json.