Riferimento docs.json

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

Campi obbligatori

name

Tipo: string (obbligatorio)

Il nome del tuo 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 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 funziona l'interruttore.

Metadati delle pagine

metadata

Tipo: object (facoltativo)

Controlla i metadati visualizzati su ogni pagina di 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 ciascuna pagina, quindi le pagine che non hai modificato conservano la data originale.

Banner

banner

Mostra una barra di annuncio a livello di sito, fissata nella parte superiore di ogni pagina, sopra l'intestazione, a larghezza intera e con il colore di accento del tema. Usala per lanci, migrazioni, finestre di manutenzione o qualsiasi messaggio che tutti i visitatori devono 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 solo banner per l'intero sito); i banner specifici per scheda e lingua non sono attualmente supportati.

OpenAPI

api.openapi

Tipo: string | string[]

Elenca i file di specifica OpenAPI 3.x che vuoi che Jamdesk convalidi e utilizzi per le pagine degli endpoint. Usa percorsi relativi a 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 delle directory per il posizionamento dei file.

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

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 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, un pulsante "Try it" appare in ogni pagina openapi: e api:.

{
  "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 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 (structure)

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 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 blocchi.

{
  "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 integrato per la chat AI. 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 AI Actions 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 AI Actions 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 all'elenco di esclusione parole specifiche del progetto.

{
  "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 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 solitamente più piccoli del 60-80% rispetto agli originali, senza perdita visibile di qualità. I riferimenti nel tuo MDX, nel CSS personalizzato, nel JS 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 e i client email eseguono il rendering di WebP in modo affidabile; un'anteprima non funzionante è 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 utilizzare l'indicatore di avanzamento della build.

Controllo degli accessi

auth.password

Tipo: object (facoltativo)

Attiva la protezione del sito con una password condivisa. La configurazione è solo dichiarativa. Devi comunque impostare la passphrase effettiva nel 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 modalità attivano la stessa richiesta di password del dashboard nella build successiva.

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

Consulta Protezione con password per la procedura completa, inclusi il flusso del dashboard e il modo in cui public: true / private: true nel frontmatter interagiscono con 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"]
          }
        ]
      }
    ]
  }
}

Cosa fare dopo?