Riferimento docs.json

Il file docs.json è la configurazione centrale del sito di documentazione Jamdesk.

Campi obbligatori

name

Tipo: string (obbligatorio)

Il nome del sito di documentazione. Viene visualizzato nell'intestazione e nella scheda del browser.

{ "name": "Acme API Docs" }

theme

Tipo: "jam" | "nebula" | "pulsar" | "halo" (obbligatorio)

colors

Tipo: object (obbligatorio)

{
  "colors": {
    "primary": "#635BFF",
    "light": "#7C75FF",
    "dark": "#4F46E5"
  }
}

Branding

favicon

Tipo: string oppure object

Percorso del file favicon (SVG consigliato). Fornisci un'unica immagine per entrambe le modalità oppure varianti separate light / dark.

{ "favicon": "/images/favicon.svg" }

{
  "favicon": {
    "light": "/images/favicon.svg",
    "dark": "/images/favicon-dark.svg"
  }
}

logo

Tipo: object

{
  "logo": {
    "light": "/images/logo-light.webp",
    "dark": "/images/logo-dark.webp",
    "href": "https://yoursite.com"
  }
}

Tipografia

fonts

Tipo: object (facoltativo)

Sostituisci il font predefinito del tema per il testo del corpo e le intestazioni. Ogni tema include un font predefinito ottimizzato. Imposta fonts solo quando vuoi un aspetto diverso.

Usa lo stesso font ovunque:

{
  "fonts": {
    "family": "Lora"
  }
}

Separa intestazioni e corpo:

{
  "fonts": {
    "heading": { "family": "Space Grotesk" },
    "body": { "family": "Inter" }
  }
}

Sia heading sia body accettano gli stessi campi. Consulta Temi → Tipografia per indicazioni sulla scelta dei font.

Aspetto

appearance

Tipo: object (facoltativo)

Controlla il comportamento predefinito della modalità scura del sito.

{
  "appearance": {
    "default": "dark",
    "strict": true
  }
}

Consulta Temi → Modalità scura per sapere come si comporta il selettore.

Metadati delle pagine

metadata

Tipo: object (facoltativo)

Controlla i metadati mostrati su ogni pagina della documentazione.

{
  "metadata": {
    "timestamp": true
  }
}

La data viene visualizzata sul sito pubblicato e in jamdesk dev. Riflette il commit più recente che ha modificato il file di ogni pagina, quindi le pagine che non hai modificato conservano la data originale.

Localizzazione

localization

Tipo: object (facoltativo)

Controlla come i visitatori raggiungono la versione tradotta della documentazione.

{
  "localization": {
    "autoRedirect": true
  }
}

Vengono reindirizzate solo le radici. Un link profondo come /guides/authentication serve sempre la pagina che indica, quindi un link che incolli in un ticket apre la stessa pagina per tutti. I crawler dei motori di ricerca non vengono mai reindirizzati, quindi i tag hreflang continuano a decidere cosa viene indicizzato.

La lingua del visitatore viene ricordata per un anno. Scegliere una lingua dal selettore sostituisce da quel momento l'abbinamento automatico.

Consulta Supporto multilingue → Routing automatico della lingua per il comportamento completo.

Banner

banner

Mostra una barra di annuncio valida per l'intero sito, fissata nella parte superiore di ogni pagina, sopra l'intestazione, a larghezza completa e nel colore in evidenza del tema. Usala per lanci, migrazioni, finestre di manutenzione o qualsiasi messaggio che ogni visitatore debba vedere.

{
  "banner": {
    "content": "🎉 Version 2.0 is live! Read the [changelog](/changelog).",
    "dismissible": true
  }
}

Il banner viene visualizzato sul sito pubblicato e in jamdesk dev. È configurato globalmente (un banner per l'intero sito); al momento i banner per singola scheda o lingua non sono supportati.

OpenAPI

api.openapi

Tipo: string | string[]

Elenca i file di specifica OpenAPI 3.x che vuoi far validare e utilizzare da Jamdesk per le pagine degli endpoint. Usa percorsi relativi al tuo docs.json.

{
  "api": {
    "openapi": ["/openapi/api.yaml"]
  }
}

Dopo la configurazione, puoi generare pagine degli endpoint aggiungendo un campo openapi al frontmatter di una pagina:

---
title: Create Ticket
openapi: /openapi/api.yaml POST /tickets
---

Se hai una sola specifica elencata, puoi usare anche il formato breve:

---
title: Create Ticket
openapi: POST /tickets
---

Consulta Esempio OpenAPI per una pagina endpoint funzionante e Struttura delle directory per la posizione dei file.

Se il sito è multilingue, aggiungi un file <spec>.<lang>.<ext> accanto a ogni specifica di origine (ad esempio openapi/api.fr.yaml): Jamdesk lo servirà sugli URL della lingua corrispondente. Consulta Traduzione delle specifiche OpenAPI.

navigation openapi (pagine generate)

Tipo: object

Inserisci un oggetto openapi in una scheda di navigazione e imposta generate: true: Jamdesk crea in fase di build una pagina endpoint per ogni operazione della specifica e i gruppi della barra laterale che le conterranno. Nessun contenuto da scrivere e nessun commit da effettuare.

{
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "openapi": { "source": "/openapi/api.yaml", "generate": true }
      }
    ]
  }
}

Le pagine generate si trovano sotto il nome della scheda, convertito in slug, con uno slug creato dal metodo e dal percorso: la scheda precedente posiziona POST /tickets in /api-reference/post-tickets. Le operazioni vengono raggruppate in base al primo tag; le specifiche senza tag usano il primo segmento significativo del percorso. Di conseguenza, /api/v1/auctions/{auctionId} viene inserito sotto Auctions. I titoli provengono da summary dell'operazione quando presente nella specifica; in caso contrario, dal metodo e dal percorso. Un'operazione relativa a una singola risorsa usa il titolo al singolare (GET /users/{id} → "Get User").

Un file .mdx sottoposto a commit ha sempre la precedenza in caso di conflitto tra slug, quindi puoi adottare la generazione gradualmente: attivala, poi elimina una alla volta le pagine endpoint scritte manualmente quando sei pronto.

Se in seguito rinomini un percorso nella specifica, lo slug generato cambia insieme a esso. Jamdesk conserva una cronologia degli slug per operazione e, a ogni build, emette un redirect da ogni URL precedente a quello attuale, così i link in entrata e i segnalibri continuano a funzionare dopo la ridenominazione. I tuoi redirect e qualsiasi pagina attiva hanno comunque la precedenza.

Limiti attuali. La generazione viene eseguita solo su navigation.tabs di primo livello, non su gruppi, ancore o schede annidate sotto languages o versions, e produce pagine solo per la lingua predefinita. La chiave directory è accettata dallo schema, ma non influisce sulla posizione delle pagine.

api.mdx.server

Tipo: string

URL di base usato negli esempi di codice nelle pagine con frontmatter api: (quelle scritte in MDX, non le pagine openapi:, che ricavano i server dalla specifica).

{
  "api": {
    "mdx": {
      "server": "https://api.example.com"
    }
  }
}

api.examples.languages

Tipo: string[] Predefinito: ["curl", "python", "javascript"]

Scegli quali linguaggi di programmazione visualizzare negli esempi di codice API generati automaticamente sulle pagine openapi:. L'ordine dell'array determina l'ordine di visualizzazione delle schede e il primo linguaggio viene selezionato per impostazione predefinita.

Valori supportati: curl, bash, python, javascript, go, ruby, csharp, java, rust, php

{
  "api": {
    "examples": {
      "languages": ["curl", "python", "javascript", "go", "ruby", "csharp", "java", "rust", "php"]
    }
  }
}

{
  "api": {
    "examples": {
      "languages": ["python", "javascript", "go"]
    }
  }
}

api.examples.defaults

Tipo: "required" | "all" Predefinito: "all"

Controlla quali parametri vengono visualizzati negli esempi di codice generati automaticamente.

{
  "api": {
    "examples": {
      "defaults": "required"
    }
  }
}

api.examples.prefill

Tipo: boolean Predefinito: false

Quando è true, API Playground precompila i campi dei parametri con i valori example della specifica OpenAPI.

{
  "api": {
    "examples": {
      "prefill": true
    }
  }
}

api.playground.display

Tipo: "interactive" | "simple" | "none" Predefinito: "interactive"

Controlla API Playground nelle pagine degli endpoint. Per impostazione predefinita, su ogni pagina openapi: e api: viene visualizzato un pulsante "Try it".

{
  "api": {
    "playground": {
      "display": "interactive"
    }
  }
}

Consulta API Playground per i dettagli sull'utilizzo e sulle sostituzioni per singola pagina.

api.mdx.auth.method

Tipo: "bearer" | "basic" | "key" | "cobo"

Metodo di autenticazione utilizzato negli esempi di codice generati automaticamente. Quando è impostato, gli esempi includono l'intestazione di autenticazione appropriata.

{
  "api": {
    "mdx": {
      "auth": {
        "method": "bearer"
      }
    }
  }
}

api.mdx.auth.name

Tipo: string

Nome dell'intestazione personalizzata per l'autenticazione basata su chiave. Utilizzato solo quando api.mdx.auth.method è "key".

{
  "api": {
    "mdx": {
      "auth": {
        "method": "key",
        "name": "X-API-Key"
      }
    }
  }
}

Navigazione

tabsPosition

Tipo: "top" | "left"

Controlla dove vengono visualizzate le schede di navigazione.

Il valore predefinito dipende dal tema:

{ "tabsPosition": "left" }

anchors

Tipo: array

Link esterni visualizzati nella parte superiore della barra laterale su tutte le pagine.

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

navigation (struttura)

Tipo: object

La struttura di navigazione della documentazione. Consulta Navigazione per la documentazione dettagliata.

Le pagine possono essere stringhe (titolo generato automaticamente dal nome del file) oppure oggetti con un titolo personalizzato:

"pages": [
  "introduction",
  { "page": "content/mdx-basics", "title": "MDX Basics" }
]

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

Barra di navigazione e piè di pagina

navbar

Tipo: object

{
  "navbar": {
    "links": [
      {
        "label": "Blog",
        "labels": { "fr": "Blog", "es": "Blog" },
        "href": "/blog"
      },
      {
        "label": "Pricing",
        "labels": { "fr": "Tarifs", "es": "Precios" },
        "href": "/pricing"
      }
    ],
    "primary": {
      "type": "button",
      "label": "Dashboard",
      "labels": { "fr": "Tableau de bord", "es": "Panel" },
      "href": "https://app.example.com"
    }
  }
}

footer

Tipo: object

Configura il piè di pagina con link ai social e colonne di link personalizzate.

{
  "footer": {
    "socials": {
      "github": "https://github.com/yourorg",
      "x": "https://x.com/yourhandle",
      "discord": "https://discord.gg/yourserver"
    },
    "links": [
      {
        "header": "Resources",
        "items": [
          { "label": "Blog", "href": "https://example.com/blog" },
          { "label": "Changelog", "href": "/changelog" }
        ]
      }
    ]
  }
}

Piattaforme social supportate: github, x, twitter, linkedin, discord, slack, youtube, instagram, facebook, reddit, telegram, bluesky, threads, medium, hacker-news, website

Stile

styling.latex

Tipo: boolean

Abilita il rendering della matematica LaTeX con KaTeX. Quando è abilitato, puoi usare $...$ per la matematica inline e $$...$$ per le equazioni a blocco.

{
  "styling": {
    "latex": true
  }
}

Consulta Matematica e LaTeX per i dettagli sull'utilizzo.

styling.js

Tipo: string | string[]

File JavaScript personalizzati da includere in ogni pagina. I percorsi sono relativi alla directory della documentazione e devono iniziare con /.

{
  "styling": {
    "js": "/script.js"
  }
}

Passa un array per più file:

{
  "styling": {
    "js": ["/chat.js", "/analytics.js"]
  }
}

Senza questo campo, Jamdesk rileva automaticamente i file `.js nella radice del progetto. Consulta JavaScript personalizzato per i dettagli.

Ricerca

search

Tipo: object (facoltativo)

Personalizza la barra di ricerca della documentazione. La ricerca funziona immediatamente; ti serve questo campo solo per modificare il testo segnaposto o mostrare pagine popolari nello stato vuoto.

{
  "search": {
    "prompt": "Ask me anything…",
    "popularPages": [
      { "title": "Quick Start", "slug": "quickstart", "icon": "rocket" },
      { "title": "Authentication", "slug": "guides/authentication", "icon": "key" }
    ]
  }
}

Pagine popolari

Ogni voce di popularPages accetta:

Il campo icon accetta anche l'oggetto completo { "name", "style", "library" }. Consulta Forma oggetto dell'icona. Quando popularPages viene omesso, Jamdesk mostra Quick Start e Introduction per impostazione predefinita.

Chat

chat

Tipo: object (facoltativo)

Configura l'assistente di chat AI integrato. La chat è abilitata per impostazione predefinita su tutti i siti; ti serve questo campo solo per personalizzare le domande iniziali o disabilitarla.

{
  "chat": {
    "starterQuestions": [
      "How do I get started?",
      "What API endpoints are available?"
    ]
  }
}

Consulta Chat AI per i dettagli sul funzionamento della chat e su ciò che vedono i visitatori.

Menu Azioni AI

contextual

Tipo: object (facoltativo)

Configura il menu a discesa Azioni AI visualizzato su ogni pagina. È abilitato per impostazione predefinita con tutte le opzioni; ti serve questo campo solo per personalizzare le opzioni visualizzate o disabilitarlo.

Chiavi delle opzioni integrate: copy, view, chatgpt, claude, perplexity, gemini, mcp, cursor, vscode

{
  "contextual": {
    "options": ["copy", "claude", "mcp", "cursor"]
  }
}

Aggiungi opzioni personalizzate insieme a quelle integrate:

{
  "contextual": {
    "options": [
      "copy",
      "claude",
      {
        "title": "Ask on Discord",
        "description": "Get help from the community",
        "icon": "discord",
        "href": "https://discord.gg/your-server"
      }
    ]
  }
}

Consulta Menu Azioni AI per l'elenco completo delle opzioni e il formato delle opzioni personalizzate.

Controllo ortografico

spellcheck

Tipo: object (facoltativo)

Configura il comando CLI jamdesk spellcheck. Ti serve questo campo solo per aggiungere parole specifiche del progetto all'elenco di esclusione.

{
  "spellcheck": {
    "ignore": ["Acme", "kubectl", "Terraform"]
  }
}

La CLI include oltre 180 termini tecnici integrati (API, GraphQL, Kubernetes, React e così via) e ignora automaticamente il nome del progetto indicato nel campo name. Aggiungi solo parole specifiche del progetto.

Consulta Panoramica CLI: controllo ortografico per i dettagli sull'utilizzo e sulla modalità interattiva di correzione.

Immagini

images.convertToWebp

Tipo: boolean (facoltativo, predefinito false)

Abilita la conversione automatica in WebP degli asset PNG e JPG durante le build. I file convertiti sono generalmente più piccoli del 60-80% rispetto agli originali, senza perdita visibile di qualità. I riferimenti nel tuo MDX, nel CSS personalizzato, nel JavaScript personalizzato e in docs.json vengono riscritti automaticamente, quindi non devi modificare alcun percorso.

Favicon, og:image e twitter:image mantengono il formato originale. Non tutti i crawler social o i client email eseguono il rendering di WebP in modo affidabile e una scheda di anteprima danneggiata è peggiore di un JPG leggermente più grande.

{
  "images": {
    "convertToWebp": true
  }
}

Consulta Conversione automatica delle immagini per sapere cosa viene convertito, come funziona la memorizzazione nella cache e come viene indicato lo stato di avanzamento della build.

Controllo degli accessi

auth.password

Tipo: object (facoltativo)

Attiva la protezione del sito tramite password condivisa. Si tratta esclusivamente di una configurazione dichiarativa. Devi comunque impostare la passphrase effettiva nella dashboard dopo l'esecuzione della build successiva.

Imposta auth.password.enabled: true per bloccare l'intero sito oppure elenca i percorsi in auth.password.private[] per proteggere solo determinate pagine. Entrambe le opzioni attivano la stessa richiesta di password nella dashboard alla build successiva.

{
  "auth": {
    "password": {
      "enabled": true,
      "hint": "Ask your account manager",
      "public": ["/marketing/**", "/changelog"]
    }
  }
}

Consulta Protezione tramite password per la procedura completa, inclusi il flusso della dashboard e il modo in cui public: true / private: true nel frontmatter interagiscono con questi array.

auth.jwt

Tipo: object (facoltativo)

Proteggi l'intero sito con il tuo sistema di accesso. Il backend firma un token a breve durata per ogni utente autenticato e Jamdesk lo scambia con un cookie di sessione. La chiave di firma viene generata nella dashboard, non in questo file. auth.jwt e auth.password non possono essere abilitati contemporaneamente; una build con entrambe le opzioni attive non va a buon fine con un config_error.

{
  "auth": {
    "jwt": {
      "enabled": true,
      "loginUrl": "https://app.example.com/docs-login",
      "public": ["/changelog/**", "/status"]
    }
  }
}

Il controllo degli accessi per singola pagina, oltre a questo, deriva da groups nel frontmatter della pagina. Consulta Autenticazione JWT per il formato del token, il flusso di reindirizzamento e il funzionamento dei gruppi.

Esempio completo

{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "Acme Documentation",
  "description": "Learn how to use Acme",
  "theme": "jam",
  "colors": {
    "primary": "#635BFF"
  },
  "favicon": "/images/favicon.svg",
  "logo": {
    "light": "/images/logo-light.webp",
    "dark": "/images/logo-dark.webp"
  },
  "api": {
    "openapi": ["/openapi/api.yaml"],
    "playground": {
      "display": "interactive"
    },
    "examples": {
      "languages": ["curl", "python", "javascript"],
      "prefill": true
    }
  },
  "styling": {
    "latex": true,
    "js": "/script.js"
  },
  "chat": {
    "starterQuestions": ["How do I get started?", "What endpoints are available?"]
  },
  "contextual": {
    "options": ["copy", "claude", "chatgpt", "mcp", "cursor"]
  },
  "spellcheck": {
    "ignore": ["Acme"]
  },
  "anchors": [
    { "name": "Blog", "href": "https://blog.acme.com", "icon": "newspaper" }
  ],
  "navbar": {
    "links": [
      { "label": "Support", "href": "/support" }
    ],
    "primary": {
      "type": "button",
      "label": "Dashboard",
      "href": "https://app.acme.com"
    }
  },
  "navigation": {
    "tabs": [
      {
        "tab": "Docs",
        "icon": "book-open",
        "groups": [
          {
            "group": "Get Started",
            "pages": ["introduction", "quickstart"]
          }
        ]
      },
      {
        "tab": "API Reference",
        "icon": "code",
        "groups": [
          {
            "group": "Endpoints",
            "pages": ["api/users", "api/posts"]
          }
        ]
      }
    ]
  }
}

E adesso?