Configurazione iniziale del tema

1. Per iniziare, installa prima tutti i pacchetti necessari con npm install oppure pnpm install, poi esegui una build iniziale per verificare che la configurazione funzioni con npm run build oppure pnpm build.
2. Copia la build di Pagefind (per la ricerca nel sito) in modo che sia disponibile nell’ambiente di sviluppo. La procedura cambia in base al tuo sistema operativo. Ho preparato alcuni comandi per aiutarti.
   • Su Windows, esegui npm run winsearch
   • Su OSX o Linux, esegui npm run osxsearch
3. Poi vorrai configurare l’i18n del tuo sito (una lingua oppure più lingue). Basta eseguire il comando npm run docs:config-i18n e seguire le istruzioni dello script per completare la configurazione!
4. Ora puoi personalizzare il sito come preferisci!

Introduzioni al codice

Ho creato alcuni tour del codice per presentarti la codebase. Per visualizzarli in VSCode o in un altro IDE ti serve l’estensione Code Tour.

Struttura del codice

Il codice è organizzato con la maggior parte degli elementi nella directory src/docs. Questo rende facile trascinare l’intera cartella in un progetto esistente e aggiungere le funzionalità di documentazione in pochi minuti.

Opzioni di configurazione

La configurazione generale del sito avviene nella cartella src/docs/config/. La maggior parte delle impostazioni si trova all’interno delle singole cartelle di lingua, per gestire più facilmente le traduzioni.

Impostazioni del sito

Il file src/docs/config/siteSettings.json.ts serve a configurare le impostazioni del sito. Tra queste ci sono, per esempio, l’attivazione delle view transition, l’attivazione delle animazioni e la visualizzazione dei pulsanti per copiare il link nei titoli della documentazione.

Dati del sito

Il file src/docs/config/[language]/siteData.json.ts serve a configurare i dati del sito. Sono compresi elementi come il titolo del sito, la descrizione, i link social e l’immagine predefinita.

Dati di navigazione

Configura i dati di navigazione della barra superiore nel file src/docs/config/[language]/navData.json.ts.

Struttura della barra laterale

Configura l’ordine delle sezioni della documentazione nel file src/docs/config/[language]/sidebarNavData.json.ts.

Robots

Perché i robot come quello di Google vedano la sitemap corretta, dovrai modificare il file public/robots.txt inserendo il dominio del tuo sito.

Altre risorse

Informazioni generali su Astro

Astro cerca file .astro o .md nella directory src/pages/. Ogni pagina viene esposta come rotta in base al nome del file.

Non c’è nulla di speciale in src/components/, ma è lì che ci piace mettere i componenti Astro/React/Vue/Svelte/Preact.

Qualsiasi asset statico, come le immagini, può essere collocato nella directory public/. Uso spesso anche src/assets per le immagini, quando sfrutto gli Astro assets per l’ottimizzazione delle immagini.

Comandi

Tutti i comandi si eseguono dalla radice del progetto, da un terminale:

Comando	Azione
npm install	Installa le dipendenze
npm run dev	Avvia il server di sviluppo locale su localhost:4321
npm run build	Crea il sito di produzione in ./dist/
npm run preview	Visualizza in anteprima la build in locale, prima del deploy
npm run astro ...	Esegue comandi CLI come astro add, astro check
npm run astro -- --help	Mostra la guida della CLI di Astro

Vuoi saperne di più?

Dai un’occhiata alla documentazione oppure entra nel server Discord.