Per chi

Documentazione in Markdown senza ripulire

Migrare una documentazione di solito vuol dire convertire l’HTML e poi passare più tempo a togliere quello che il convertitore ha tenuto. Quella rimozione è la ragione per cui Clean Clipper esiste, ed è la parte che viene misurata: zero tag HTML rimasti sulle 512 pagine della prova, e dodici tabelle su quindici tenute intere contro sette per ciascun motore confrontato.

La pulizia dopo la conversione

Il convertitore fa la parte facile e lascia a te quella lunga. Il Markdown esce con la barra laterale di navigazione ripetuta in cima a ogni file, il selettore di versione, il banner «questa pagina riguarda la 2.x» e l’indice laterale trasformato in un elenco puntato. Su cinquanta pagine è una settimana di pulizia manuale che nessuno ha messo nel preventivo.

E la pulizia non è solo noiosa: è rischiosa. Cancellando a mano un blocco di navigazione si porta via anche il primo paragrafo, un titolo vuoto lasciato dal menu rompe la generazione dell’indice, e una tabella di parametri già schiacciata viene ricostruita a occhio con una colonna in meno. Gli errori che si introducono in quella fase si scoprono mesi dopo, in produzione.

E intanto la documentazione di partenza continua a vivere. Una migrazione di cinquanta pagine dura settimane, e in quelle settimane qualcuno pubblica correzioni sul sito vecchio: alla fine non sai più quali pagine hai preso prima della modifica e quali dopo. Senza un file che dichiari da quale indirizzo viene e quando è stato preso, l’unico modo per esserne sicuri è rifare il confronto pagina per pagina, cioè rifare la migrazione.

Che cosa passa e che cosa no

• Titoli, elenchi, tabelle, blocchi di codice e note diventano tutti Markdown standard
• La marcatura del linguaggio resta sui blocchi di codice: 73 blocchi su 156 sul corpus tecnico, contro 20 e 0
• Zero tag HTML rimasti sulle 512 pagine misurate, quindi non serve un secondo passaggio di pulizia
• Barre laterali di navigazione, selettori di versione e indici laterali tagliati, non convertiti
• I titoli vuoti lasciati dai blocchi di navigazione vengono eliminati, così l’indice si genera pulito
• Il modello del nome file e la sottocartella tengono in ordine un insieme importato
• I file sono testo UTF-8 con intestazione YAML: entrano nel repository e la revisione si fa con un diff invece che a occhio
• Il campo source in ogni file dice da quale pagina viene, quindi durante una migrazione lunga si sa sempre che cosa è già stato preso

---
title: "Linee guida di design per i servizi digitali"
source: "https://docs.italia.it/italia/designers-italia/design-linee-guida-docs/"
extraction: "dom"
---

## Struttura del contenuto

> Nota: le indicazioni di questo capitolo valgono per tutti i canali del servizio.

| Elemento | Obbligatorio |
| --- | --- |
| Titolo della pagina | sì |
| Descrizione breve | sì |

Impostarlo per una migrazione

Una migrazione si decide nella prima mezz’ora, non nell’ultima settimana. Queste sei mosse stabiliscono nomi, cartelle e campi prima che ci siano cinquanta file da rinominare.

1. Apri le opzioni con il clic destro sull’icona e imposta come destinazione la cartella dei contenuti del nuovo sito – docs/ nel repository, o la cartella sorgente del generatore statico che userai.
2. Metti il modello del nome file su {title}, ma solo se il nuovo albero dei file è organizzato per argomento. Se invece importi da più siti, usa {domain}-{title}: quattro documentazioni hanno tutte una pagina «Per iniziare».
3. Tieni accesi title e source e spegni il resto. source è il registro della migrazione: dice da quale pagina viene ogni file, ed è quello che permette di sapere che cosa è già stato preso senza tenere un elenco a parte.
4. Lascia il clic sull’icona sulla finestra di anteprima e controlla due cose su ogni pagina: che i blocchi di codice abbiano la loro marcatura e che le tabelle di parametri abbiano tutte le colonne. Sono i due punti in cui una conversione si rompe in silenzio.
5. Prima di salvare, apri sulla pagina le schede e le sezioni a fisarmonica. Quello che il sito inserisce solo al clic non è nel DOM finché non clicchi, e in una documentazione è spesso proprio lì che stanno gli esempi per l’altro linguaggio.
6. Metti la cartella sotto controllo di versione fin dal primo file. Da quel momento ogni ripulitura manuale è un commit rivedibile, e un paragrafo cancellato per sbaglio si recupera invece di essere scoperto in produzione mesi dopo.

Impostazioni per chi documenta

La differenza rispetto alla lettura è che qui il file non è il fine: è la materia prima di un altro sito. Queste impostazioni servono a farla arrivare pronta da lavorare.

> **Attenzione**
> La configurazione precedente resta valida fino alla migrazione completa.

Sulla pagina era un riquadro giallo con l’icona di avviso, dichiarato come
`admonition warning`. Markdown non ha una sintassi standard per i riquadri:
si conserva il contenuto e l’etichetta in grassetto, non lo stile né il tipo.
Chi importa in un generatore che ha i propri richiami dovrà rimapparli.

Tre fasi di una migrazione

Il censimento, fatto salvando

Prima di preventivare la migrazione devi sapere che cosa c’è. Passi le cinquanta pagine della documentazione di partenza salvandole una a una in docs/importate/, con source acceso e il resto del frontmatter spento.

A fine giornata la cartella è il censimento: cinquanta file, ciascuno con l’indirizzo da cui viene. La stima delle ore non si fa più a occhio sul sito, si fa contando pagine, tabelle e blocchi di codice nei file – e i file si contano con grep.

La revisione fatta con un diff invece che a occhio

Ogni file importato entra nel repository come commit separato, e la ripulitura manuale che segue è un secondo commit. Chi rivede vede esattamente che cosa è stato tolto dal testo importato e che cosa era già così all’arrivo.

È la differenza che conta quando un paragrafo sparisce. Con una conversione fatta a mano dentro un editor, un capoverso perso insieme al blocco di navigazione si scopre in produzione; con due commit distinti si vede in revisione, che è dove costa dieci minuti.

I richiami, rimappati una volta sola

La documentazione di partenza usa quattro tipi di riquadro – nota, attenzione, avvertenza, suggerimento – e nei file arrivano tutti come citazioni con l’etichetta in grassetto, perché Markdown non ha una sintassi standard per i riquadri.

Siccome l’etichetta è conservata, la rimappatura verso i richiami del nuovo generatore è una sostituzione per tipo, non una rilettura di cinquanta pagine. Il lavoro resta, ma diventa meccanico e verificabile – e il file dice sempre quale riquadro era.

Rispetto agli altri modi di convertire

Portare una documentazione da HTML a Markdown si fa in cinque modi. La terza colonna dice dove ciascuno lascia il lavoro, il nostro compreso.

Quando la conversione zoppica

Perché il riquadro «Attenzione» è diventato una citazione?

Perché Markdown non ha una sintassi standard per i riquadri di richiamo. Ogni generatore ha la sua – direttive, blocchi con due punti, estensioni proprietarie – e sceglierne una vorrebbe dire produrre file che funzionano su un sistema e si rompono su tutti gli altri. Il contenuto e l’etichetta in grassetto restano, quindi la rimappatura verso i richiami del tuo generatore è una sostituzione per tipo.

Perché i link interni puntano ancora al vecchio sito?

Perché non vengono riscritti: restano indirizzi assoluti verso la pagina di partenza. Riscriverli richiederebbe conoscere l’albero dei file di destinazione, che al momento del salvataggio non esiste ancora. Il vantaggio pratico è che i link continuano a funzionare durante tutta la migrazione, e la riscrittura si fa in una passata sola alla fine, quando l’albero è deciso.

Perché mancano gli esempi per l’altro linguaggio?

Perché stavano in una scheda che non era stata aperta. Molte documentazioni mettono lo stesso esempio in quattro linguaggi dentro schede che il sito inserisce solo al clic: quello che non è nel DOM non viene convertito. Apri ogni scheda e salva una volta per variante, oppure verifica nella vista lettura che ci siano tutte prima di passare alla pagina successiva.

Perché l’indice generato dal nuovo sito è sbagliato?

Di solito perché i livelli dei titoli della pagina di partenza non erano coerenti – un h4 dopo un h2, o un titolo di sezione usato come etichetta grafica. I livelli vengono riportati come stanno nel corpo dell’articolo, e i titoli vuoti lasciati dai blocchi di navigazione vengono eliminati, ma una gerarchia sbagliata all’origine resta sbagliata: va corretta nel file, dove è una modifica di una riga.

Che cosa non fa

Non percorre un sito di documentazione: non c’è nessun crawler e nessuna elaborazione in blocco, quindi si salva una pagina alla volta, quella che hai davanti. Non riscrive i link interni verso il nuovo albero dei file: restano indirizzi assoluti verso il sito di partenza. Non scarica le immagini, che restano link. E i riquadri di richiamo diventano citazioni, perché Markdown non ha una sintassi standard per i riquadri.

Domande