Immagini
Scopri come Jamdesk gestisce dimensioni, didascalie, varianti chiaro/scuro e formati supportati per immagini nitide e accessibili nella documentazione.
Jamdesk visualizza le immagini con angoli arrotondati e spaziatura uniforme. Inserisci i file nella directory /images e fai riferimento a essi con la sintassi Markdown standard.
Gli screenshot mostrano l'interfaccia in inglese.
Markdown standard
Usa la familiare sintassi :
I percorsi partono dalla radice del progetto. Un'immagine in your-docs/images/screenshot.webp viene indicata come /images/screenshot.webp.
Dimensioni delle immagini
Aggiungi =WIDTHxHEIGHT dopo l'URL dell'immagine, separato da uno spazio, per controllarne le dimensioni:
Imposta una sola dimensione per ridimensionare proporzionalmente l'altra:
È utile quando vuoi una colonna uniforme di screenshot con la stessa larghezza o devi ridurre un'immagine ad alta risoluzione a dimensioni di visualizzazione ragionevoli.
Didascalie
Inserisci un'immagine nel componente <Frame> per aggiungere un bordo e una didascalia sotto di essa:
<Frame caption="Dashboard overview showing project statistics">
</Frame>
Frame disegna un bordo discreto intorno all'immagine e posiziona il testo della didascalia sotto di essa. Funziona con qualsiasi contenuto al suo interno, non solo con le immagini.
Modalità chiara/scura
I siti di documentazione spesso richiedono varianti diverse delle immagini per ogni schema di colori: un logo su sfondo bianco non viene visualizzato correttamente in modalità scura.
L'attributo srcDark
È l'approccio più semplice. Jamdesk sostituisce la sorgente dell'immagine in base al tema attivo:
<img
src="/_jd/images/logo-light.webp?v=msuxsk5d"
srcDark="/images/logo-dark.webp"
alt="Company logo"
/>Il browser carica solo l'immagine corrispondente allo schema di colori corrente.
L'elemento HTML <picture>
Se ti serve HTML standard che funzioni anche al di fuori di Jamdesk, usa <picture> con una media query:
<picture>
<source srcset="/images/logo-dark.webp" media="(prefers-color-scheme: dark)" />
<img src="/_jd/images/logo-light.webp?v=msuxsk5d" alt="Company logo" />
</picture>L'approccio <picture> rispetta l'impostazione dello schema di colori del sistema operativo. L'attributo srcDark risponde invece al selettore del tema di Jamdesk, che di solito è ciò che serve per la documentazione.
Formati supportati
| Formato | Ideale per | Note |
|---|---|---|
| PNG | Screenshot, acquisizioni dell'interfaccia | Qualità senza perdita, supporta la trasparenza. File più grandi. |
| JPEG | Fotografie | Buona compressione, non supporta la trasparenza. |
| SVG | Icone, diagrammi, loghi | Formato vettoriale che si ridimensiona a qualsiasi dimensione senza perdita di qualità. File molto piccoli. |
| GIF | Animazioni semplici | Può diventare rapidamente voluminoso. Per loop con più di alcuni fotogrammi, valuta brevi loop .mp4. |
| WebP | Uso generale | Più piccolo di PNG e JPEG a qualità comparabile. Funziona in tutti i browser moderni. |
WebP offre il miglior rapporto tra dimensioni e qualità per la maggior parte delle immagini della documentazione. Se ti serve la trasparenza, WebP la gestisce, quindi non è necessario usare PNG.
Buone pratiche
Il testo alternativo ha due scopi: gli screen reader lo usano per l'accessibilità e viene mostrato come segnaposto quando l'immagine non può essere caricata. Descrivi ciò che l'immagine mostra effettivamente.
{/* Good -- says what's in the image */}
{/* Bad -- tells you nothing */}
Per le immagini decorative che non aggiungono informazioni, come motivi di sfondo e divisori, usa un testo alternativo vuoto: .
Le immagini pesanti rallentano il caricamento delle pagine, soprattutto sulle connessioni mobili. Dimensioni consigliate:
- Screenshot/interfaccia: PNG o WebP, meno di 500KB
- Foto: JPEG o WebP, meno di 200KB
- Icone e diagrammi: SVG quando possibile
Squoosh e TinyPNG comprimono le immagini senza perdite visibili di qualità. Comprimi gli screenshot con uno di questi strumenti prima di eseguire il commit.
In alternativa, lascia che Jamdesk gestisca l'operazione durante la build. Abilita la conversione automatica in WebP nel tuo docs.json: qualsiasi file PNG o JPG sottoposto a commit verrà ottimizzato a ogni build.
Gli screenshot che alternano larghezze diverse hanno un aspetto disordinato. Scegli una larghezza di acquisizione standard, ad esempio 1200px, e usala in tutta la documentazione. Jamdesk ridimensiona automaticamente le immagini per adattarle all'area dei contenuti, quindi dimensioni sorgente uniformi producono risultati visualizzati uniformi.
Jamdesk genera automaticamente una scheda social brandizzata da 1200×630 per ogni pagina e puoi sostituirla per singola pagina con og:image nel frontmatter. Dopo una build, inserisci l'URL della pagina nello strumento gratuito OpenGraph Preview per vedere come viene visualizzata la scheda su X, Facebook, LinkedIn, Slack, Discord e altri servizi. Consulta Ottimizzazione SEO per la configurazione completa.
Organizzazione dei file
Raggruppa le immagini in sottodirectory che rispecchiano la struttura dei contenuti. In questo modo sarà più facile trovarle man mano che la documentazione cresce:
your-docs/
├── images/
│ ├── getting-started/
│ │ ├── step-1.png
│ │ └── step-2.png
│ ├── api/
│ │ └── response.png
│ └── logo.svg
└── docs.jsonFai riferimento a esse usando 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.