Creare e gestire un progetto VitePress con ServBay

VitePress è un moderno generatore di siti statici supportato da Vue, progettato per creare siti di documentazione veloci, eleganti e semplici da mantenere. Costruito su Vite, offre una straordinaria esperienza di sviluppo e prestazioni di build eccellenti. Se devi realizzare una documentazione professionale per un progetto, una libreria o un prodotto, VitePress è una scelta eccellente.

Durante lo sviluppo e il testing locale di VitePress, è fondamentale disporre di un ambiente web stabile e facilmente configurabile. ServBay nasce proprio per questo: integra molteplici versioni di Node.js e potenti web server (come Caddy o Nginx), rendendo semplice fornire servizi al tuo progetto VitePress.

Questa guida ti mostrerà come creare, configurare e avviare un progetto VitePress da zero sfruttando l’ambiente integrato di ServBay, inclusa la configurazione del reverse proxy per il server di sviluppo e il servizio di file statici per la distribuzione in produzione.

Cos'è VitePress?

VitePress è un generatore di siti statici (SSG) basato su Vite, che sfrutta la potenza di Vue 3 e la velocità di Vite per realizzare siti statici, risultando particolarmente indicato per la documentazione tecnica.

Caratteristiche e vantaggi principali di VitePress

• Esperienza di sviluppo ultra veloce: grazie all'Hot Module Replacement (HMR) di Vite, ogni modifica ai contenuti è immediatamente visibile nel browser, massimizzando la produttività.
• Basato su Vue: puoi usare componenti Vue direttamente nei file Markdown, rendendo la documentazione altamente interattiva e versatile.
• Semplice e intuitivo: configurazione minimale, pronto all’uso, favorendo la concentrazione sulla creazione dei contenuti.
• Prestazioni elevate: i file generati sono leggeri e si caricano rapidamente; la routing client integrata offre un'esperienza fluida da Single Page App.
• Ottimizzato per la SEO: la struttura HTML prodotta è ideale per l'indicizzazione dai motori di ricerca ed è possibile personalizzare i tag nel head.
• Markdown potenziato: supporta pienamente CommonMark e GitHub Flavored Markdown (GFM), aggiungendo molte funzionalità extra.

Grazie a VitePress, i developer possono realizzare siti di documentazione di alta qualità e prestazioni senza sforzo.

Creare e gestire un progetto VitePress con ServBay

ServBay rende estremamente facile gestire le versioni di Node.js e configurare il web server per il tuo progetto VitePress, sia che tu sia in fase di sviluppo che in produzione.

Prerequisiti

Prima di iniziare, assicurati di avere completato i seguenti passaggi:

1. Installare ServBay: Assicurati di avere ServBay installato correttamente su macOS. Se manca, consulta la Guida all’installazione di ServBay.
2. Installare il pacchetto Node.js: In ServBay, verifica di avere installato e abilitato la versione richiesta di Node.js tramite la sezione "Pacchetti" del pannello ServBay. Consulta anche Utilizzare Node.js.

Creazione del progetto VitePress

1. Inizializza la directory di progetto

   Prima di tutto, apri il terminale. Si consiglia di creare la cartella di progetto nella directory di default /Applications/ServBay/www di ServBay, per semplificare la configurazione successiva.

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

2. Installa VitePress e inizializza la configurazione

   All’interno della directory servbay-vitepress-app, usa npm o yarn per installare VitePress come dipendenza di sviluppo ed esegui il comando di inizializzazione.

   npm add -D vitepress
   npx vitepress init

   Oppure con Yarn:

   yarn add -D vitepress
   yarn vitepress init

   Il comando di inizializzazione ti guiderà nella configurazione di base come il titolo e la descrizione del sito. Fornisci le informazioni richieste nei prompt:

    ┌  Welcome to VitePress!
    │
    ◇  Where should VitePress initialize the config?
    │  ./docs  # Directory documentazione predefinita, premi invio per confermare
    │
    ◇  Site title:
    │  ServBay VitePress Demo # Inserisci il titolo del tuo sito, ad esempio ServBay VitePress Demo
    │
    ◇  Site description:
    │  A VitePress site running on ServBay # Inserisci la descrizione del sito
    │
    ◇  Theme:
    │  Default Theme # Scegli il tema, il default va bene
    │
    ◇  Use TypeScript for config and theme files?
    │  Yes # Decidi se usare TypeScript per la configurazione, a tua scelta
    │
    ◇  Add VitePress npm scripts to package.json?
    │  Yes # Consigliato aggiungere gli script a package.json
    │
    └  Done! Now run npm run docs:dev and start writing.

   Al termine, VitePress creerà una sotto-cartella docs con i file di configurazione (.vitepress) e le pagine di esempio (index.md, guide/index.md ecc.). Il file package.json verrà aggiornato con gli script docs:dev e docs:build.

Modifica dei contenuti del progetto VitePress

1. Modifica della homepage

   Il file della homepage di default è docs/index.md. Aprilo con un editor di testo a tua scelta e personalizzane il contenuto. Ad esempio:

   # Hello ServBay!
   
   Benvenuto! Utilizza ServBay per gestire il tuo sito di documentazione VitePress.
   
   Questa è una demo locale del sito creato con VitePress e servito tramite ServBay.

Avviare la modalità sviluppo

Durante lo sviluppo del sito VitePress, si sfrutta generalmente il server di sviluppo integrato, ideale per il live preview grazie al reload automatico. Grazie alla funzione di reverse proxy di ServBay, puoi accedere al server di sviluppo tramite un dominio personalizzato e con SSL abilitato.

1. Avvia il server di sviluppo VitePress

   Da terminale, assicurati di essere nella root del progetto (/Applications/ServBay/www/servbay-vitepress-app) e avvia il server sulla porta desiderata (ad esempio 8585):

   npm run docs:dev -- --port 8585

   Oppure con Yarn:

   yarn docs:dev --port 8585

   Il server si avvierà sulla porta scelta (es: 8585) e nel terminale verrà mostrato l'indirizzo locale, tipicamente http://localhost:8585.

2. Configura il sito su ServBay (reverse proxy)

   Dal pannello di controllo di ServBay, vai su "Siti" e aggiungi una nuova configurazione:

   • Nome: scegli un nome descrittivo, ad esempio Sito di sviluppo VitePress.
   • Dominio: imposta il dominio locale desiderato, consigliando il suffisso .servbay.demo, es: vitepress-dev.servbay.demo.
   • Tipo sito: seleziona Reverse proxy.
   • IP: inserisci 127.0.0.1 (localhost).
   • Porta: inserisci la porta scelta in precedenza, es. 8585.

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

3. Accedi al sito di sviluppo

   Ora puoi visitare https://vitepress-dev.servbay.demo dal browser. Visualizzerai il contenuto fornito dal server di sviluppo VitePress, godendo anche del dominio personalizzato e del certificato SSL emesso dalla CA locale di ServBay per un accesso HTTPS sicuro.

Build per la produzione

Quando il sito VitePress è pronto per la pubblicazione, puoi generarne una versione ottimizzata e statica.

1. Esegui la build di produzione

   Dal terminale, sempre nella root del progetto /Applications/ServBay/www/servbay-vitepress-app, esegui:

   npm run docs:build

   Oppure con Yarn:

   yarn docs:build

   Il processo compilerà i file Markdown, componenti Vue ecc. in una struttura ottimizzata composta da HTML, CSS e JavaScript. I file statici saranno disponibili in docs/.vitepress/dist.

2. Configura il sito ServBay (servizio file statici)

   La versione di produzione di VitePress è composta da file statici, quindi si può usare come "sito statico" in ServBay.

   Dal pannello ServBay, aggiungi un nuovo sito:

   • Nome: es. Sito di produzione VitePress.
   • Dominio: es. vitepress-prod.servbay.demo.
   • Tipo sito: seleziona Statico.
   • Directory root: indica il percorso assoluto della cartella con i file generati, ad esempio /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist.

   Salva e applica. ServBay configurerà il server per erogare direttamente i file statici dalla directory indicata.

3. Accedi al sito di produzione

   Visita https://vitepress-prod.servbay.demo dal browser. Vedrai il sito VitePress in modalità produzione, completo di dominio personalizzato e SSL automatico fornito da ServBay.

Supporto Clean URLs (cleanUrls: true)

VitePress supporta la configurazione cleanUrls: true, che elimina l’estensione .html dagli URL (ad esempio, /guide/ invece di /guide/index.html, oppure /about al posto di /about.html). Per permettere al web server di ServBay di gestire correttamente queste richieste è necessario configurare alcune regole extra.

ServBay utilizza Caddy o Nginx. Qui sotto trovi un esempio di configurazione Caddy usando l’istruzione try_files per cercare il file richiesto nelle diverse varianti (.html o index.html).

1. Attiva cleanUrls nella configurazione di VitePress

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

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

   Ricostruisci la versione di produzione con npm run docs:build.

2. Configura il sito ServBay (Caddy custom)

   Dal pannello "Siti" di ServBay, individua il sito di produzione (es: vitepress-prod.servbay.demo):

   • Premi ‘modifica’.
   • Spunta Configurazione personalizzata.
   • Nel campo Configurazione Caddy inserisci quanto segue, personalizzando dominio e path con i tuoi dati reali.

   # Sostituisci con il tuo dominio reale, es. vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # Attiva compressione Brotli (zstd) e Gzip per prestazioni migliori
       encode zstd gzip
   
       # Importa le impostazioni di logging ServBay (opzionale)
       import set-log vitepress-cleanurl.servbay.demo
   
       # Gestione automatica certificato SSL interno
       tls internal
   
       # Regole di risoluzione file:
       # 1. Cerca il file richiesto direttamente (es. /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
   
       # Percorso radice dei file statici
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # Abilita il servizio di file statici
       file_server
   }

   Salva e applica le modifiche.

3. Accedi al sito con URL semplificati

   Ora puoi navigare il sito tramite il dominio configurato (es: https://vitepress-cleanurl.servbay.demo). Le pagine saranno accessibili direttamente via URL senza l’estensione .html, ad esempio /about per la pagina about.html.

Conclusioni

Grazie a questa guida ora sai come creare, sviluppare e distribuire un sito di documentazione VitePress sfruttando al massimo la praticità di ServBay. ServBay semplifica la gestione di Node.js e la configurazione dei web server locali, sia per il reverse proxy durante lo sviluppo che per il servizio file statici in produzione, offrendo inoltre supporto automatico a dominio personalizzato e certificati SSL.

La combinazione di ServBay e VitePress ti permette di costruire e mantenere documentazione tecnica di alto livello in modo rapido, efficace e sicuro.