Validare il markup HTML con HTML-Validate dalla riga di comando

Introduzione

La validazione HTML non serve soltanto a trovare tag scritti male. Un markup formalmente corretto può comunque contenere problemi pratici: attributi obbligatori assenti, elementi annidati in modo scorretto, ID duplicati o una struttura semantica difficile da mantenere. Per controllare questi aspetti in modo ripetibile possiamo usare HTML-Validate, uno strumento eseguibile dalla riga di comando e integrabile in un progetto basato su Node.js.

HTML-Validate analizza i file HTML secondo un insieme di regole configurabili. A differenza di un controllo manuale nel browser, il risultato è riproducibile e può essere utilizzato durante lo sviluppo, prima di una revisione del codice o prima della pubblicazione. In questo tutorial creeremo un piccolo progetto, configureremo alcune regole e correggeremo un documento HTML contenente errori realistici.

Codice completo

Per iniziare, creiamo una cartella e inizializziamo un progetto Node.js:

mkdir sito-demo
cd sito-demo
npm init -y
npm install --save-dev html-validate

Creiamo quindi il file .htmlvalidate.json, che contiene la configurazione del validatore:

{
  "extends": [
    "html-validate:recommended"
  ],
  "rules": {
    "element-required-attributes": "error",
    "no-dup-id": "error",
    "require-sri": "off"
  }
}

La regola html-validate:recommended abilita una configurazione consigliata. Le altre regole mostrano come personalizzare il comportamento: gli attributi richiesti e gli ID duplicati sono errori bloccanti, mentre il controllo dell´integrità delle risorse esterne è disattivato in questo esempio.

Ora creiamo la cartella src e il file src/index.html:

<!doctype html>
<html lang="it">
  <head>
    <meta charset="utf-8">
    <title>Catalogo libri</title>
  </head>
  <body>
    <header>
      <h1 id="titolo">Catalogo libri</h1>
    </header>

    <main>
      <section aria-labelledby="titolo">
        <h2>Libri disponibili</h2>
        <img src="copertina.jpg">
        <button id="azione">Aggiungi al carrello</button>
        <button id="azione">Mostra dettagli</button>
      </section>
    </main>
  </body>
</html>

Aggiungiamo uno script nel file package.json:

{
  "scripts": {
    "validate:html": "html-validate "src/**/*.html""
  }
}

Il controllo si avvia con questo comando:

npm run validate:html

Spiegazione

Nel documento di esempio sono presenti alcuni problemi utili da analizzare. L´elemento img non possiede l´attributo alt. Questo testo alternativo è importante per descrivere l´immagine agli utenti che utilizzano tecnologie assistive e per fornire un contenuto sostitutivo quando l´immagine non viene caricata.

Inoltre, i due pulsanti usano lo stesso valore di id. Un ID deve essere unico all´interno del documento, perché JavaScript, CSS e tecnologie assistive potrebbero selezionare l´elemento sbagliato. Infine, il riferimento aria-labelledby="titolo" punta all´ID dell´intestazione principale. Anche se il riferimento è formalmente valido, in questo caso sarebbe più chiaro assegnare un ID specifico all´intestazione della sezione.

Una versione corretta può essere scritta così:

<main>
  <section aria-labelledby="libri-titolo">
    <h2 id="libri-titolo">Libri disponibili</h2>

    <img
      src="copertina.jpg"
      alt="Copertina del libro Il viaggio"
      width="240"
      height="320"
    >

    <button id="aggiungi-carrello">
      Aggiungi al carrello
    </button>

    <button id="mostra-dettagli">
      Mostra dettagli
    </button>
  </section>
</main>

Dopo la correzione, eseguendo nuovamente npm run validate:html, il comando dovrebbe terminare senza errori. In caso contrario, HTML-Validate visualizza il percorso del file, il numero di riga, la colonna e una descrizione del problema. Queste informazioni permettono di intervenire rapidamente anche in documenti molto lunghi.

Best practice

• Configura le regole nel repository: salva .htmlvalidate.json insieme al codice, così tutti gli sviluppatori utilizzano gli stessi controlli.
• Inizia con le regole consigliate: la configurazione predefinita offre una base equilibrata. Personalizza soltanto le regole che non riflettono le esigenze del progetto.
• Non disattivare gli errori senza una motivazione: se una regola non è applicabile, documenta il motivo nella configurazione o nella documentazione tecnica.
• Valida anche i frammenti generati: se il progetto usa template server-side, assicurati che il comando analizzi i file HTML risultanti o i template compatibili.
• Correggi prima gli errori strutturali: elementi non annidati correttamente possono produrre numerosi messaggi secondari. Risolvi prima il problema più vicino all´inizio del documento.
• Usa nomi di ID descrittivi e univoci: valori come azione sono difficili da gestire quando la pagina cresce; nomi come mostra-dettagli comunicano meglio lo scopo.
• Non confondere validazione e accessibilità completa: HTML-Validate aiuta a individuare molti problemi di markup, ma non sostituisce una revisione manuale dell´esperienza utente.

Riepilogo

HTML-Validate permette di controllare il markup HTML in modo locale, veloce e configurabile. Dopo l´installazione come dipendenza di sviluppo, è sufficiente definire le regole nel file .htmlvalidate.json e aggiungere uno script npm dedicato. Il validatore può individuare attributi mancanti, ID duplicati, errori di annidamento e numerosi problemi comuni del markup.

Il vantaggio principale è trasformare la qualità HTML in una procedura ripetibile: invece di affidarsi soltanto all´ispezione manuale, possiamo eseguire lo stesso controllo ogni volta che modifichiamo una pagina. In questo modo gli errori vengono scoperti presto, quando sono più semplici ed economici da correggere.

Approfondisci con risorse ufficiali

• Documentazione di HTML-Validate: consulta l´elenco delle regole, le opzioni di configurazione e gli esempi ufficiali sul sito html-validate.org.
• Guida npm: la documentazione di npm spiega come installare dipendenze di sviluppo e definire script personalizzati nel file package.json.
• MDN Web Docs: usa la documentazione MDN per approfondire la semantica degli elementi HTML, gli attributi globali e l´uso corretto di alt, id e ARIA.
• Specifiche WHATWG HTML: le specifiche ufficiali descrivono la struttura valida dei documenti e il comportamento degli elementi standard.