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 o object

Percorso del file favicon (SVG consigliato). Fornisci una singola 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 desideri 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 informazioni sul comportamento del selettore.

Metadati della pagina

metadata

Tipo: object (facoltativo)

Controlla i metadati visualizzati in ogni pagina della documentazione.

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

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

Banner

banner

Mostra una barra di annuncio del sito fissata nella parte superiore di ogni pagina, sopra l'intestazione, a larghezza completa e nel colore d'accento 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 nel sito pubblicato e in jamdesk dev. È configurato globalmente (un solo banner per l'intero sito); i banner per singola tab e per lingua non sono attualmente supportati.

OpenAPI

api.openapi

Tipo: string | string[]

Elenca i file di specifica OpenAPI 3.x che vuoi far convalidare 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 di endpoint aggiungendo un campo openapi nel 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 di endpoint attiva e Struttura directory per la posizione dei file.

Se il sito è multilingue, inserisci un file <spec>.<lang>.<ext> accanto a ogni specifica sorgente (ad esempio openapi/api.fr.yaml) e Jamdesk lo servirà negli URL di quella lingua. Consulta Traduzione delle specifiche OpenAPI.

navigation openapi (pagine generate)

Tipo: object

Inserisci un oggetto openapi in una tab di navigazione e imposta generate: true: Jamdesk genera in fase di build una pagina di endpoint per ogni operazione della specifica, oltre ai gruppi della barra laterale che le contengono. Non devi creare né salvare alcun file.

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

Le pagine generate si trovano sotto il nome della tab, convertito in slug, con uno slug creato dal metodo e dal percorso: la tab precedente inserisce POST /tickets in /api-reference/post-tickets. Le operazioni vengono raggruppate in base al primo tag; per le specifiche senza tag viene usato il primo segmento significativo del percorso, quindi /api/v1/auctions/{auctionId} finisce 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 riceve un titolo al singolare (GET /users/{id} → "Get User").

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

Se in seguito rinomini un percorso nella specifica, lo slug generato si sposta con 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 ingresso 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 tab annidate in languages o versions, e produce pagine solo per la lingua predefinita. Una 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 create con MDX, non le pagine openapi:, che usano i server della 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 nelle pagine openapi:. L'ordine dell'array determina l'ordine di visualizzazione delle tab; 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, in 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'header di autenticazione appropriato.

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

api.mdx.auth.name

Tipo: string

Nome dell'header personalizzato per l'autenticazione basata su chiave. Viene 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 tab di navigazione.

Il valore predefinito dipende dal tema:

{ "tabsPosition": "left" }

anchors

Tipo: array

Link esterni visualizzati nella parte superiore della barra laterale in 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 (con 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 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 personalizzato 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 in popularPages accetta:

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

Chat

chat

Tipo: object (facoltativo)

Configura l'assistente integrato di chat AI. La chat è abilitata per impostazione predefinita in 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 informazioni 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 in 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 ecc.) e ignora automaticamente il nome del progetto presente nel campo name. Aggiungi solo parole specifiche del tuo 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 in genere più piccoli del 60-80% rispetto agli originali, senza perdita visibile di qualità. I riferimenti in MDX, CSS personalizzato, JavaScript personalizzato e 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 cache e come usare l'indicatore 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 della password nella dashboard durante la 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 l'interazione tra public: true / private: true nel frontmatter e questi array.

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

Prossimi passaggi