Immagini
Dimensiona le immagini, aggiungi didascalie, alterna varianti chiare/scure e scegli un formato supportato per visual di documentazione nitidi e accessibili.
Jamdesk visualizza le immagini con angoli arrotondati e spaziatura uniforme. Inserisci i file nella tua cartella /images e fai riferimento ad essi con la sintassi markdown standard.
Gli screenshot mostrano l'interfaccia in inglese.
Markdown standard
Usa la sintassi :
I percorsi partono dalla radice del progetto. Un'immagine in your-docs/images/screenshot.webp si referenzia come /images/screenshot.webp.
Dimensioni delle immagini
Aggiungi =WIDTHxHEIGHT dopo l'URL dell'immagine (separato da uno spazio) per controllarne le dimensioni:
Se imposti solo una dimensione, l'altra viene scalata proporzionalmente:
Usalo per mantenere una colonna di screenshot a una larghezza uniforme, o per ridurre un'immagine ad alta risoluzione per la visualizzazione.
Didascalie
Racchiudi un'immagine nel componente <Frame> per aggiungere un bordo e una didascalia sotto di essa:
<Frame caption="Dashboard overview showing project statistics">
</Frame>
Frame funziona con qualsiasi contenuto al suo interno, non solo con le immagini.
Clic per ingrandire
Fai clic su un'immagine per aprirla a schermo intero su schermi di larghezza pari o superiore a 768px. Chiudi l'immagine ingrandita con Esc o con un clic in un punto qualsiasi.
Aggiungi noZoom a un tag <img loading="lazy"> per impedirne lo zoom:
<img src="/_jd/images/diagram.png?v=mwdojjfh" alt="Architecture diagram" data-no-zoom="true" />Le immagini Markdown () non supportano la sintassi degli attributi, quindi non possono escludersi dallo zoom. Usa un tag <img loading="lazy"> quando ti serve noZoom.
Modalità chiara e scura
I siti di documentazione spesso richiedono varianti diverse dell'immagine per ogni schema di colori: un logo su sfondo bianco non si vede bene in modalità scura.
L'attributo srcDark
Jamdesk cambia la sorgente dell'immagine in base al tema attivo:
<img
src="/_jd/images/logo-light.webp?v=mwdojjfh"
srcDark="/images/logo-dark.webp"
alt="Company logo"
/>Il browser carica solo l'immagine che corrisponde allo schema di colori corrente.
L'elemento HTML <picture>
Usa <picture> con una media query per HTML standard che funziona anche al di fuori di Jamdesk:
<picture>
<source srcset="/images/logo-dark.webp" media="(prefers-color-scheme: dark)" />
<img src="/_jd/images/logo-light.webp?v=mwdojjfh" alt="Company logo" />
</picture>L'approccio <picture> rispetta l'impostazione dello schema di colori del sistema operativo. L'attributo srcDark, invece, segue il selettore del tema di Jamdesk. Di solito è ciò che serve per la documentazione.
Formati supportati
| Formato | Ideale per | Note |
|---|---|---|
| PNG | Screenshot, acquisizioni UI | Qualità senza perdita, supporta la trasparenza. File più grandi. |
| JPEG | Fotografie | Buona compressione, nessun supporto alla trasparenza. |
| SVG | Icone, diagrammi, loghi | Formato vettoriale scalabile a qualsiasi dimensione senza perdita di qualità. Dimensione del file minima. |
| GIF | Animazioni semplici | Può diventare grande rapidamente. Considera brevi loop .mp4 per tutto ciò che supera qualche fotogramma. |
| WebP | Uso generale | Più piccolo di PNG e JPEG a qualità comparabile. Funziona in tutti i browser moderni. |
WebP offre il miglior rapporto dimensione/qualità per la maggior parte delle immagini di documentazione. Supporta anche la trasparenza, quindi non serve PNG per quello.
Buone pratiche
Gli screen reader leggono ad alta voce il testo alternativo. Viene anche mostrato come segnaposto se l'immagine non si carica. Descrivi cosa mostra l'immagine.
{/* Good -- says what's in the image */}
{/* Bad -- tells you nothing */}
Per le immagini decorative che non aggiungono informazioni (motivi di sfondo, separatori), usa un testo alternativo vuoto: .
Le immagini pesanti rallentano il caricamento delle pagine, soprattutto su connessioni mobili. Dimensioni consigliate:
- Screenshot/UI: PNG o WebP, sotto i 500KB
- Foto: JPEG o WebP, sotto i 200KB
- Icone e diagrammi: SVG quando possibile
Squoosh e TinyPNG comprimono le immagini senza perdita visibile di qualità. Passa gli screenshot in uno di questi strumenti prima di committarli.
Jamdesk può anche comprimere in fase di build. Abilita la conversione automatica in WebP nel tuo docs.json. Con questa opzione attiva, Jamdesk ottimizza ogni PNG o JPG che committi a ogni build.
Gli screenshot con larghezze diverse risultano disordinati. Scegli una larghezza di cattura standard (1200px funziona bene) e usala in tutta la documentazione. Jamdesk ridimensiona le immagini per adattarle all'area del contenuto. Dimensioni sorgente coerenti producono risultati visualizzati coerenti.
Jamdesk genera una card social brandizzata di 1200×630 per ogni pagina. Puoi sovrascriverla per pagina con og:image nel frontmatter. Dopo una build, esegui l'URL della pagina con lo strumento gratuito OpenGraph Preview per vedere come appare la card su X, Facebook, LinkedIn, Slack, Discord e altri. Consulta Ottimizzazione SEO per la configurazione completa.
Organizzazione dei file
Raggruppa le immagini in sottocartelle che rispecchiano la struttura dei contenuti:
your-docs/
├── images/
│ ├── getting-started/
│ │ ├── step-1.png
│ │ └── step-2.png
│ ├── api/
│ │ └── response.png
│ └── logo.svg
└── docs.jsonFai riferimento ad esse con il percorso completo dalla radice del progetto:
Evita gli spazi nei nomi dei file immagine. Usa i trattini: api-response.webp, non api response.webp.