Plugin per Claude Code e Codex

Installazione

Il plugin si trova in due repository GitHub, uno per Claude Code e uno per Codex. Hanno lo stesso contenuto e lo stesso numero di versione. Cambia solo il modo in cui ciascuno strumento li carica. Installa quello del tuo strumento, perché l'altro non verrebbe caricato.

Seleziona il tuo strumento ed esegui entrambi i comandi, uno dopo l'altro:

Il primo comando aggiunge da GitHub il catalogo dei plugin (il marketplace). Il secondo installa html2wp da lì. Codex ha bisogno di un repository suo perché trova i plugin tramite il file .agents/plugins/marketplace.json, che nel repository per Claude Code non c'è.

Aggiornamenti

Il comando di aggiornamento ha un nome diverso in ciascuno strumento. In Codex è upgrade, in Claude Code è update:

Per vedere la versione installata, in Codex esegui codex plugin list. In Claude Code vai su /plugin → Marketplaces → html2wp.

Se dopo un aggiornamento la versione in Codex non è cambiata, Codex ha in memoria una copia vecchia. Cancellala e installa di nuovo il plugin:

Se neanche questo basta, Codex potrebbe avere anche un'altra copia più vecchia, da un'installazione manuale. Il comando codex plugin marketplace list stampa tutti i cataloghi. Se lì vedi html2wp@<other-name>, rimuovilo con codex plugin remove html2wp@<that-name>.

Gran parte del lavoro avviene nel servizio html2wp, che si aggiorna da solo: la tua prossima conversione usa già la nuova versione. Devi aggiornare solo la parte che gira sul tuo computer, cioè i controlli, gli script e il filtro dei dati in uscita. Cosa è cambiato in ogni versione lo trovi nella cronologia dei commit su GitHub.

Requisiti

Non devi controllarlo tu. Quando avvii una conversione, il plugin controlla prima il tuo computer ed elenca cosa manca:

Node.js                ok        v22.14.0
Python                 ok        3.12.4
Playwright             MISSING   mirroring, prerendering and every screenshot
Docker                 NOT RUNNING  installed, but the daemon is not up

I pacchetti che si installano solo nella tua cartella utente, come Playwright o il browser chromium, il plugin si offre di installarli per te. Chiede conferma prima di ogni comando. Quello che cambia l'intero sistema, come Docker Desktop o un Node.js più recente, si limita a segnalarlo. Poi aspetta che lo installi tu.

Se vuoi installare a mano i pacchetti Python:

Quale modello usare

Durante una conversione l'AI deve prendere molte decisioni. Per esempio quale pagina è la home, perché un controllo è fallito, o se un cliente noterebbe davvero la differenza tra due screenshot. Per questo la scelta del modello incide sul risultato più di qualsiasi altra impostazione.

In Claude Code, Opus 5 fa il lavoro e Fable 5 viene consultato sulle decisioni importanti, che sono il punto in cui una conversione va storta più spesso.

Chiave di licenza

Con il piano gratuito la chiave non ti serve, quindi salta questa sezione. Se hai una licenza, salva la chiave sul tuo computer prima della prima conversione. Lo fai una volta sola, da qualsiasi cartella:

Puoi anche passare la chiave nella variabile d'ambiente H2WP_KEY, che ha la precedenza sul file. Il file è più sicuro, perché così la chiave non finisce nella cronologia del terminale.

Nel file va la chiave di licenza html2wp che ricevi quando compri Pro. Una chiave Visual Edit Pro non va lì. Quella la inserisci nel plugin Visual Edit sul sito che modifichi, e per le conversioni non funziona.

Per sapere se una chiave è valida, per cosa puoi usarla e fino a quando, esegui npx html2wp-license YOUR-KEY. Il controllo della chiave nella pagina delle licenze spiega cosa significa il risultato. Cosa include una licenza e come comprarla lo trovi nella pagina delle licenze.

Convertire un progetto

Apri un terminale nella cartella del progetto che vuoi convertire e avvia lì il tuo agente:

Se usi Claude Code, nell'ultima riga scrivi claude al posto di codex.

Poi dai all'agente un solo comando:

Tutto qui. Non esegui npm install né npm run build, e non configuri niente. I progetti da Bolt, v0, shadcn o un export Next.js si convertono allo stesso modo. In Claude Code puoi anche scrivere solo /html2wp:html2wp, oppure chiedere a Codex di usare html2wp. Il plugin ti chiede allora cosa convertire.

I primi minuti di una conversione

> convert this project

  Checking this machine first…
    Node.js     ok    v22.14.0
    Playwright  MISSING
  Two Python packages are missing. Shall I install them? (they go in your
  user directory, no root)

> yes

  … installed. Building the project, then prerendering it.
  7 routes found: /, /about, /pricing, /blog, /blog/launch, /contact, /faq
  Decided: /blog is the listing, /blog/launch an article, the rest are pages.
  Written to the manifest; carrying on.

Nelle ultime righe il plugin ha registrato come ha classificato le pagine: /blog è l'elenco degli articoli, /blog/launch è un articolo e il resto sono pagine normali. Controlla questa decisione sul sito finito, alla fine.

Altri input

Il comando convert this project converte la cartella in cui ti trovi. Se i file sono altrove, scrivi il loro percorso, per esempio convert ./dist.

L'input deve sempre stare sul tuo disco. Il plugin non converte l'indirizzo di un sito online. Gli servono i file da cui il sito è costruito, non quello che mostra il browser.

Come si converte un progetto Lovable

Un'app Lovable è fatta in React. Il suo index.html contiene solo un elemento vuoto e uno script, e la pagina prende vita solo nel browser. Per questo il plugin prima compila il progetto, lo apre in un browser vero e salva ogni pagina come HTML finito. Cattura anche i contenuti che compaiono solo dopo l'esecuzione degli script, come accordion aperti o menu a tendina. Poi crea il tema da queste pagine. I dettagli sono nella guida Lovable in WordPress.

Cosa decide al posto tuo

Quale pagina è quale

Una decisione pesa più di tutte sul risultato: quale pagina è la home, quale l'elenco degli articoli, quali sono articoli e quali prodotti. Il plugin lo ricava dal codice delle pagine, lo annota e prosegue senza chiedere. Si ferma solo quando non riesce a decidere. Per esempio quando il sito ha più pagine di quante ne consenta il tuo limite, o quando due pagine sembrano la stessa.

Se sbaglia, correggere costa poco. Sistemi la classificazione e lanci di nuovo la conversione. Questa è una riesecuzione e non conta nel tuo limite di conversioni.

Poi va avanti quasi da solo

Flash richiede circa mezz'ora, Full circa un'ora, a seconda del numero di pagine e della velocità del tuo computer. Nel frattempo il plugin costruisce il sito, lo confronta con l'originale e lo invia al servizio html2wp per la conversione. Dopo installa il tema finito in un WordPress temporaneo in Docker sul tuo computer e lo testa lì.

Il controllo da non saltare

Alla fine il plugin ti mostra ogni pagina accanto all'originale in un'unica immagine. Guarda ogni immagine e di' cosa vedi.

Cosa ottieni

• Il tema come file ZIP. Lo carichi in WordPress da Aspetto → Temi → Aggiungi nuovo → Carica tema. Il plugin non crea proprio un tema rotto: per esempio se il PHP avesse un errore di sintassi, se mancassero contenuti, se lo screenshot del tema avesse le dimensioni sbagliate o se nel negozio non si potesse comprare nulla.
• Il report CONVERSION-REPORT.md nella stessa cartella dello ZIP. Elenca le pagine convertite, i menu collegati, tutto quello che hai trovato nel controllo, ogni avviso della conversione e cosa resta da fare.
• Un link a Visual Edit Lite, l'editor gratuito per modifiche con clic. L'editor non fa parte del tema, e il tema funziona anche senza. Visual Edit Pro è una licenza a pagamento separata.

Il tema è autonomo. Pagine, blog, moduli, menu, SEO e reindirizzamenti fanno parte del suo codice e funzionano senza plugin. Il codice è PHP, CSS e JavaScript leggibile. È tuo e non è legato a noi. Il tema non si collega da nessuna parte. Come modificarlo con i clic lo trovi nella parte su Visual Edit della documentazione dell'app.

Cosa esce dal tuo computer

Il tuo computer fa il lavoro del browser: costruisce le pagine, confronta gli screenshot e fa girare un WordPress temporaneo in Docker per i controlli finali. Il tema vero e proprio lo crea il servizio html2wp. Per questo il plugin gli invia il sito compilato e riceve indietro il tema.

I controlli del tema girano dalla tua parte, quindi il servizio non ne vede i risultati. Così alla fine il plugin glieli invia. È un passaggio obbligatorio: il servizio non avvia la conversione successiva finché la precedente non ha inviato i suoi risultati.

• Cosa viene inviato: i nomi dei controlli, se sono passati, il numero di pagine, la percentuale di corrispondenza peggiore e i nomi brevi delle pagine fallite, come about o pricing.
• Cosa non viene inviato: l'indirizzo o il dominio del sito, il codice, i testi, gli screenshot, i percorsi dei file, la chiave di licenza o il nome del sito. Il plugin invia solo campi predefiniti, nient'altro.
• Verificalo tu: il comando send-verdicts.sh <workspace> --dry-run stampa esattamente cosa verrebbe inviato, ma non invia nulla. È un solo script breve che puoi leggere.

Il plugin non invia altri dati, e il tema finito non invia proprio nulla. La descrizione completa, compreso per quanto tempo conserviamo i dati, è nella pagina sulla privacy.

Segnalare un bug

Se è il convertitore stesso a sbagliare, segnalalo con questo comando:

Una persona legge ogni segnalazione. La correzione finisce poi nel servizio, quindi aiuta tutti gli utenti.