Documentazione con VitePress

Da qualche tempo ho cominciato a lavorare su diversi progetti Web con VueJS, devo dire che mi trovo molto bene, tanto che con Wintech Italia stiamo organizzando dei corsi e ne parleremo anche al prossimo Delphi Day.

Quasi subito ho notato che i siti ufficiali di Vue stesso e di gran parte dell'ecosistema Vue (Vue Router, Pinia, ecc.) sono molto simili e, a mio parere, molto ben fatti. Andando ad indagare ho scoperto che tutti usano VitePress.

Cos'è VitePress

VitePress è un generatore di siti statici, progettato specificamente per creare siti di documentazione tecnica. VitePress è stato sviluppato da Evan You, il creatore di Vue.js, garantendo una profonda integrazione con l'ecosistema Vue. Nonostante questo non richiede la conoscenza di Vue per essere usato, infatti permette di generare la documentazione a partire da una serie di pagine scritte in Markdown.

Devo dire che VitePress mi è piaciuto molto, soprattutto per la sua estrema semplicità d'uso e per la sua flessibilità, tanto che abbiamo deciso di usarlo per riscrivere e aggiornare tutta la documentazione di WiRL.

Come si usa

Se andate sul sito ufficiale troverete un'ottima guida all'installazione ma che purtroppo da per scontato abbiate già un progetto basato su npm. Qui invece voglio partire da zero per chi abbia un progetto che, come WiRL, non ha niente a che fare col mondo Web/JavaScript. In questo esempio creeremo un nuovo progetto contenete solo la documentazione, ma se volete inserire la documentazione in un progetto preesistente i passaggi sono analoghi.

Inizializzazione

Innanzitutto, se già non l'avete, è necessario installare NodeJS. Potete scaricarlo dal sito ufficiale. Quindi aprite un prompt dei comandi e digitate:

node -v

oppure:

npm -v

dovreste vedere le rispettive versioni. Se non funziona probabilmente non li avete installati correttamente o non sono stati aggiunti al path di sistema.

Creiamo il folder dove inserire il progetto e ci posizioniamo li:

mkdir MyNewProject
cd MyNewProject

a questo punto inizializziamo il progetto:

npm init

Npm chiederà un po' di informazioni: nome del progetto, versione, ecc. potete lasciare tutti i default premendo invio o modificarli a vostro piacimento. Al termine verrà creato un file package.json contenente tutte le informazioni richieste in precedenza, che eventualmente è possibile modificare.

Installazione di VitePress

Una volta inizializzato il package possiamo procedere all'installazione di VitePress digitando il seguente comando:

npm add -D vitepress

Questo andrà ad aggiungere al file package.json una dipendenza di sviluppo relativa a VitePress e provvederà anche a scaricare il pacchetto nella directory node_modules. Ricordate di inserire node_modules tra i file da ignorare se usate un version control.

Setup Wizard

Ora potremo andare direttamente a scrivere la configurazione di VitePress e la documentazione ma in realtà è decisamente più comodo farsi generare lo scheletro del codice direttamente dal wizard di VitePress:

npx vitepress init

Anche in questo caso vi verranno fatte alcune domande. Io di solito le confermo tutte tranne per la gestione dei TypeScript per la configurazione e la creazione dei file nella directory docs invece che sulla root.

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◇  Theme:
│  ● Default Theme (Out of the box, good-looking docs)
│  ○ Default Theme + Customization
│  ○ Custom Theme
│
◇  Use TypeScript for config and theme files?
│  ○ Yes
│  ● No
│  
◇  Add VitePress npm scripts to package.json?
│  ● Yes
│  ○ No  
└

Se avete risposto di sì alla domanda sulla generazione degli script potete già avviare il vostro nuovo sito con:

npm run docs:dev

In pochi secondi verrà avviato un server HTTP che potete usare per visualizzare le pagine puntando il browser all'URL indicato. Il server rimane attivo finche non premete q e se modificate o aggiungete una pagina andrà a forzare il caricamento automatico della nuova versione sul browser.

Creazione del sito

A questo punto si può precedere alla configurazione del sito vero è proprio. il wizard in effetti avrà creato diversi file che potete andare a modificare.

.
 ├─ .vitepress
 │  └─ config.mjs
 ├─ api-examples.md
 ├─ markdown-examples.md
 └─ index.md

In particolare:

• index.md: contiene la home page
• .vitepress/config.mjs: contiene l'indice di tutte le pagine
• gli altri sono file di esempio che potete anche eliminare

Quindi semplicemente andando a scrivere le vostre pagine e aggiungendole all'indice potete creare la vostra guida. Tutte le pagine devono essere scritte in markdown, se non lo conoscete trovate una guida qui.

Deployment

Una volta creato un sito che vi soddisfa potete procedere al deployment:

npm run docs:build

Questo comando genererà tutti i file necessari nella directory .vitepress\dist. Potete semplicemente copiarli su qualsiasi sito che vi offre una spazio web e saranno visibili da chiunque.

Eventualmente sito ufficiale trovate una guida per fare deploment su una miriade di piattaforme:

• Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render
• GitHub Pages
• GitLab Pages
• Azure Static Web Apps
• Firebase
• Surge
• Heroku
• Edgio
• Kinsta Static Site Hosting
• Stormkit
• Nginx

Altro

Come dicevo all'inizio VitePress permette una serie infinita di personalizzazioni, alcune offerte direttamente e altre attraverso plugin di terze parti. Giusto per avere un'idea:

• Internazionalizzazione
• Temi custom
• Motore di ricerca integrato
• Supporto a mermaid
• Generazione della sitemap
• Supporto a Frontmatter
• Utilizzo di Vue all'interno dei file markdown