Creare e gestire un progetto VitePress con ServBay

VitePress è un moderno generatore di siti web statici basato su Vue, progettato per realizzare siti di documentazione veloci, belli e facili da mantenere. Costruito su Vite, offre una eccellente esperienza di sviluppo e altissime prestazioni di build. Per gli sviluppatori che devono creare documentazione professionale per progetti, librerie o prodotti, VitePress è una scelta eccellente.

Durante lo sviluppo e il testing di VitePress in locale, è fondamentare avere un ambiente di sviluppo web stabile e facile da configurare. ServBay nasce proprio per soddisfare questa esigenza: integra diverse versioni di Node.js e potenti web server (come Caddy e Nginx), permettendo di servire facilmente i vostri progetti VitePress.

Questa guida spiega come creare, configurare e avviare da zero un sito VitePress grazie all’ambiente integrato di ServBay, compresa la configurazione del proxy inverso per lo sviluppo e del servizio file statici per la distribuzione in produzione.

Cos’è VitePress?

VitePress è un generatore di siti statici (SSG) basato su Vite, che sfrutta tutta la potenza di Vue 3 e la velocità di Vite per produrre siti statici, eccellendo nelle documentazioni tecniche.

Caratteristiche principali e vantaggi di VitePress

• Sviluppo ultra-veloce: Grazie all’Hot Module Replacement (HMR) di Vite, ogni modifica viene subito riflessa nel browser, aumentando enormemente l’efficienza.
• Basato su Vue: Permette di usare componenti Vue direttamente nei file Markdown, migliorando notevolmente l’interattività dei documenti.
• Facile da usare: Configurazione semplice e pronta all’uso, pensata per concentrarsi sui contenuti.
• Prestazioni elevate: Genera file statici leggeri e veloci da caricare; il routing client integrato garantisce una navigazione fluida tipica di una Single Page Application.
• Ottimizzato per SEO: Gli output HTML sono facilmente indicizzabili dai motori di ricerca e supporta l’aggiunta di meta tag personalizzati.
• Markdown avanzato: Supporta CommonMark e GitHub Flavored Markdown (GFM), offrendo anche “syntax sugar” aggiuntivi.

Con VitePress, realizzare siti di documentazione di alta qualità e prestazione diventa un processo semplice e rapido per ogni sviluppatore.

Creazione e gestione di un progetto VitePress con ServBay

ServBay semplifica la gestione delle versioni di Node.js e la configurazione del web server per i vostri progetti VitePress, sia che lavoriate in modalità sviluppo locale o che pubblichiate la versione statica in produzione.

Prerequisiti

Prima di iniziare, assicuratevi di avere:

1. ServBay installato: Assicuratevi che ServBay sia correttamente installato sul vostro sistema. Se non l’avete ancora fatto, seguite la Guida all’installazione di ServBay.
2. Node.js configurato: All’interno di ServBay, verificate di aver installato e attivato la versione di Node.js necessaria tramite la sezione "Pacchetti" del pannello di controllo. Consultate la guida Utilizzo di Node.js.

Creazione del progetto VitePress

1. Inizializzazione della cartella del progetto

   Aprite il vostro terminale. Si consiglia di creare la cartella del progetto nella directory predefinita del web root di ServBay per semplificare la configurazione successiva.

   macOS:

   cd /Applications/ServBay/www
   mkdir servbay-vitepress-app
   cd servbay-vitepress-app

   Windows:

   cd C:\ServBay\www
   mkdir servbay-vitepress-app
   cd servbay-vitepress-app

2. Installazione di VitePress e inizializzazione

   Dentro la cartella servbay-vitepress-app, installate VitePress come dipendenza di sviluppo e avviate la procedura di inizializzazione.

   npm add -D vitepress
   npx vitepress init

   Oppure, con Yarn:

   yarn add -D vitepress
   yarn vitepress init

   La procedura guidata vi aiuterà a configurare aspetti basilari come titolo e descrizione del sito. Seguite le istruzioni inserendo i vostri dati:

    ┌  Benvenuto in VitePress!
    │
    ◇  Dove vuoi che VitePress inizializzi la configurazione?
    │  ./docs  # Directory documenti predefinita, premi invio per confermare
    │
    ◇  Titolo del sito:
    │  ServBay VitePress Demo # Inserite il titolo del vostro sito, ad esempio ServBay VitePress Demo
    │
    ◇  Descrizione del sito:
    │  Un sito VitePress in esecuzione su ServBay # Inserite la descrizione del sito
    │
    ◇  Tema:
    │  Default Theme # Scegliete il tema, di solito quello predefinito
    │
    ◇  Utilizzare TypeScript per file di configurazione e tema?
    │  Yes # Scegliete se usare TypeScript secondo le preferenze
    │
    ◇  Aggiungere gli script npm di VitePress a package.json?
    │  Yes # Consigliato scegliere Yes
    │
    └  Fatto! Ora esegui npm run docs:dev e inizia a scrivere.

   VitePress crea la sottocartella docs nella directory di progetto, aggiungendo i file di configurazione predefiniti (.vitepress) e le pagine di esempio (index.md, guide/index.md, ecc.). Anche package.json viene aggiornato con gli script docs:dev e docs:build.

Modifica dei contenuti del sito VitePress

1. Modifica della homepage

Il file della homepage si trova in `docs/index.md`. Apritelo con qualsiasi editor di testo per modificarlo secondo le vostre necessità. Ad esempio:
```markdown
# Hello ServBay!

Benvenuto! ServBay ti permette di gestire facilmente il tuo sito di documentazione VitePress.

Questo è un esempio locale creato con VitePress e servito tramite ServBay.
```

Avvio in modalità sviluppo

Durante lo sviluppo, si utilizza solitamente il server di sviluppo integrato di VitePress con hot-reloading per vedere gli aggiornamenti in tempo reale. ServBay permette inoltre di usare un dominio personalizzato per accedere al server tramite proxy inverso, beneficiando anche della SSL automatica.

1. Avviare il server di sviluppo VitePress

   Da terminale, nella root del progetto (macOS: /Applications/ServBay/www/servbay-vitepress-app, Windows: C:\ServBay\www\servbay-vitepress-app), eseguite:

   npm run docs:dev -- --port 8585

   Oppure con Yarn:

   yarn docs:dev --port 8585

   Il server di sviluppo sarà attivo sulla porta indicata (ad esempio 8585), solitamente accessibile su http://localhost:8585.

2. Configurazione del sito ServBay (proxy inverso)

   Dal pannello di ServBay, accedete alla sezione "Siti web" e aggiungete una nuova configurazione:

   • Nome: Scegliete un nome identificativo, ad esempio Sito di sviluppo VitePress.
   • Dominio: Inserite il dominio locale desiderato, preferibilmente con il suffisso .servbay.demo, come vitepress-dev.servbay.demo.
   • Tipo sito: Selezionate Proxy inverso.
   • IP: 127.0.0.1 (localhost).
   • Porta: La porta selezionata in precedenza, ad esempio 8585.

   Salvate e applicate le modifiche: ServBay configurerà automaticamente il web server (Caddy o Nginx) per inoltrare le richieste da https://vitepress-dev.servbay.demo a http://127.0.0.1:8585.

3. Accesso al sito di sviluppo

   Aprite il browser e visitate https://vitepress-dev.servbay.demo. Dovreste vedere il vostro sito VitePress servito tramite il server di sviluppo, con dominio personalizzato e SSL automatico (certificato rilasciato da ServBay User CA).

Build della versione di produzione

Terminato lo sviluppo, è possibile generare una versione ottimizzata e statica del vostro sito.

1. Generare la build di produzione

   Da terminale, nella root del progetto (macOS: /Applications/ServBay/www/servbay-vitepress-app, Windows: C:\ServBay\www\servbay-vitepress-app), eseguite:

   npm run docs:build

   Oppure con Yarn:

   yarn docs:build

   I file Markdown e i componenti Vue saranno compilati e raggruppati in HTML, CSS e JS ottimizzati, salvati di default in docs/.vitepress/dist.

2. Configurazione del sito ServBay (servizio file statici)

   Il sito generato può essere servito come "sito statico" direttamente da ServBay.

   Dal pannello di amministrazione, aggiungete un nuovo sito:

   • Nome: Ad esempio Sito di produzione VitePress.
   • Dominio: Scegliete il dominio locale per la produzione, ad esempio vitepress-prod.servbay.demo.
   • Tipo sito: Selezionate Statico.
   • Root sito web: Inserite il percorso assoluto della cartella dei file statici generati:
     • macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   Salvate e applicate: ServBay offrirà direttamente il servizio file statici dal percorso indicato.

3. Accesso al sito di produzione

   Visitando il dominio configurato (https://vitepress-prod.servbay.demo) potrete navigare la versione finale del vostro sito VitePress con dominio personalizzato e SSL fornito da ServBay.

Utilizzo della modalità "Clean URL" (cleanUrls: true)

VitePress supporta l’opzione cleanUrls: true, generando link senza estensione .html (es. /guide/ al posto di /guide/index.html o /about invece di /about.html). Per gestire correttamente queste richieste, è necessario personalizzare la configurazione del web server.

ServBay usa Caddy o Nginx come web server. Di seguito un esempio di configurazione Caddy che sfrutta la direttiva try_files per individuare file con estensione .html o index all’interno della directory.

1. Abilitare cleanUrls nella configurazione VitePress

   Modificate il file di configurazione VitePress (docs/.vitepress/config.mts o docs/.vitepress/config.ts) aggiungendo l’opzione cleanUrls:

   // docs/.vitepress/config.mts
   import { defineConfig } from 'vitepress'
   
   export default defineConfig({
     // ... altre impostazioni
     cleanUrls: true, // Abilita URL puliti
     // ... altre impostazioni
   })

   Rigenerate il sito con npm run docs:build.

2. Configurare il sito ServBay (Caddy personalizzato)

   Nel pannello ServBay, individuate la configurazione per il sito di produzione (ad esempio vitepress-prod.servbay.demo).

   • Cliccate su "Modifica".
   • Attivate la voce Configurazione personalizzata.
   • Copiate e incollate la seguente configurazione nell’area dedicata, sostituendo servbay-vitepress-test.prod con il vostro dominio reale e il percorso della root con quello del vostro sito:
     • macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   # Sostituire con il vostro dominio effettivo, es: vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # Abilita compressione Brotli (zstd) e Gzip per velocizzare il caricamento
       encode zstd gzip
   
       # Include la configurazione log di ServBay per facilitare debug
       import set-log vitepress-cleanurl.servbay.demo
   
       # Certificato SSL interno automatico
       tls internal
   
       # Configurazione principale: cerca il file in ordine
       # 1. Percorso diretto (es: /about -> /about)
       # 2. Cerca index.html nella directory (es: /guide/ -> /guide/index.html)
       # 3. Cerca il file con estensione .html (es: /about -> /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # Directory root del sito
       # macOS: root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
       # Windows: root * C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # Abilita servizio file statici
       file_server
   }

   Salvate e applicate.

3. Navigazione del sito in modalità Clean URL

   Da questo momento, visitando il dominio impostato (es. https://vitepress-cleanurl.servbay.demo), potrete accedere alle pagine senza la necessità di specificare l’estensione .html, ad esempio https://vitepress-cleanurl.servbay.demo/about.

Conclusione

Questa guida vi ha mostrato come creare, sviluppare e distribuire documentazione VitePress in ambiente ServBay. ServBay semplifica la gestione delle versioni Node.js e la configurazione del web server locale, sia durante lo sviluppo (proxy inverso) che in produzione (servizio file statici), offrendo in automatico domini personalizzati e certificati SSL.

Grazie alla sinergia tra ServBay e VitePress, potrete realizzare e mantenere documentazione tecnica di alta qualità, in modo ancora più rapido ed efficiente.