Regole di Scrittura degli Elementi: Quando Usare Ogni Blocco

Ogni pagina del playbook SEO dipende da una distinzione: un pezzo di contenuto ha uno scopo, mentre il suo livello di intestazione e l’aspetto visivo sono solo presentazione. Queste regole di scrittura degli elementi trasformano quella distinzione in un contratto produttivo. Seguile prima di applicare qualsiasi componente, convertire un articolo tra sistemi di pubblicazione o modificare un elemento che appare già su pagine pubblicate.

Panoramica rapida

• Controlla la libreria degli elementi per scopo prima del nome. Se lo scopo di un elemento corrisponde al lavoro che una sezione svolge, quell’elemento è obbligatorio.
• Usa Markdown semplice solo dopo aver confermato che nessun elemento tipizzato rappresenta lo scopo del passaggio. Il testo libero è un ripiego, non un’impostazione predefinita.
• Scrivi prima l’articolo completo come testo semplice. Applica gli elementi in una passata strutturale separata dall’alto verso il basso, così composizione e markup non competono per l’attenzione.
• Tratta la direttiva Markdown come contenuto autorevole canonico. I renderer Hugo e WordPress mappano gli stessi campi e corpo in output nativi della piattaforma.
• Mantieni le pagine pubblicate esistenti sul significato con cui sono state revisionate. Una modifica di definizione sostanziale crea una nuova versione e una migrazione esplicita; non reinterpreta mai silenziosamente vecchi contenuti.

La regola di precedenza dominante

La libreria deve essere controllata in base a ciò che un passaggio fa, non in base a come lo scrittore lo ha chiamato. I nomi variano: uno scrittore può intitolare una sezione “Cos’è il churn?”, un altro “Churn spiegato” e un terzo “Una definizione operativa”. Il loro scopo è identico, quindi tutti e tre si mappano allo stesso elemento di definizione.

Questa precedenza esiste perché il testo libero e un elemento tipizzato possono apparire identici sullo schermo comportandosi in modo completamente diverso a valle. Un’intestazione stilizzata seguita da un paragrafo può assomigliare a un box di definizione nel browser, ma non porta alcuna identità di componente. Non può produrre in modo affidabile l’output strutturato della definizione, esporre i suoi campi a un altro renderer, mantenere la sua semantica durante la migrazione o essere trovato da un controllo di qualità che chiede se la pagina contiene una definizione. L’elemento tipizzato si mappa a un componente e a una forma di dati nota; il testo libero visivamente simile non si mappa a nulla.

La regola è quindi severa:

Prima di scrivere o approvare qualsiasi intestazione o blocco di contenuto, identifica il suo scopo. Se quello scopo corrisponde a una definizione di elemento, usa l’elemento. La somiglianza visiva, un H2 esistente o la capacità di esprimere le stesse parole in un paragrafo non rendono il testo libero equivalente.

La precedenza è semantica piuttosto che visiva. Una pagina può comunque contenere intestazioni ordinarie dentro o attorno a un elemento quando la sua definizione lo permette, ma l’intestazione non sostituisce mai il tipo di elemento.

Testo libero contro un elemento tipizzato

Usa questo percorso decisionale finché il diagramma condiviso non sarà disponibile:

1. Indica il compito del passaggio in un verbo. Esempi includono definire, avvertire, riassumere, confrontare, provare, istruire o invitare all’azione. Questo impedisce al testo dell’intestazione di mascherare lo scopo sottostante.
2. Cerca nella libreria per quello scopo e i suoi sinonimi. Uno scrittore che cerca solo l’intestazione letterale “Cos’è X?” può perdersi un elemento di definizione la cui pagina si intitola “Box di definizione”.
3. Usa l’elemento corrispondente quando esiste. Non confrontare le apparenze né chiederti se Markdown potrebbe imitare il design; il comportamento registrato è il fattore decisivo.
4. Usa il testo libero quando nessuno scopo corrisponde. Questo è corretto per spiegazioni connettive, argomentazioni, analisi, contesto narrativo e transizioni che appartengono al flusso principale dell’articolo e non richiedono un comportamento di componente distinto.
5. Registra una lacuna ricorrente. Se lo stesso scopo non corrispondente appare in diverse pagine, proponi un elemento della libreria invece di inventare una direttiva o un trattamento CSS usa e getta in un articolo.

Il Markdown semplice è genuinamente corretto quando le parole formano il ragionamento continuo dell’articolo e non necessitano di un’etichetta indipendente, un contratto dati, un’interazione o un percorso di riutilizzo. Ad esempio, due paragrafi che spiegano perché una raccomandazione segue dalle prove precedenti sono prosa normale. Un insieme compatto di conclusioni all’inizio non è prosa normale solo perché può essere scritto come elenco puntato; ha lo scopo riconosciuto di un elemento panoramica o punti chiave.

Confusioni comuni che causano markup errato

Questi casi sono elencati esplicitamente perché superano facilmente una revisione visiva. L’errore diventa visibile solo quando un altro renderer, validatore, indice di ricerca o consumatore di output strutturato riceve la pagina.

La distinzione tra punti chiave e panoramica rapida è particolarmente importante. Usa i punti chiave quando gli elementi sono conclusioni che il lettore dovrebbe ricordare, il che significa che spesso possono essere scritti solo dopo che l’articolo esiste. Usa una panoramica quando gli elementi orientano il lettore sulla portata o la sequenza prima della lettura. Scegli in base a quel compito editoriale, anche se il tema corrente rende entrambi i componenti simili nell’aspetto.

Sintassi di direttive e attributi

La forma Markdown canonica utilizza una direttiva di blocco nominata. Gli attributi seguono il nome della direttiva tra parentesi graffe:

:::nome-elemento{chiave=valore chiave2="valore con spazi" .classe}
Corpo del contenuto
:::

Gli attributi esistono per trasportare proprietà piccole e stabili che influenzano il significato dell’elemento o la presentazione supportata. Mantenerli leggibili dalla macchina impedisce agli autori di nascondere configurazioni nella prosa. Usa chiave=valore per un valore senza spazi e chiave2="valore con spazi" quando sono presenti spazi. Un valore di attributo non quotato non può contenere spazi. Un punto iniziale aggiunge una classe supportata, come in .compatto; non è un posto per inventare stili specifici della pagina.

Le chiavi degli attributi sono in minuscolo e usano l’ortografia esatta definita nella pagina dell’elemento. Anche i valori booleani ed enumerati seguono il contratto di quella pagina. Non creare un attributo perché un renderer lo tollera accidentalmente: un attributo non dichiarato non ha garanzia multipiattaforma.

I delimitatori di chiusura ::: appartengono all’elemento esterno. Mantienili sulle proprie righe in modo che un parser possa distinguere il corpo dal paragrafo successivo. Gli esempi di codice che dimostrano le direttive devono rimanere all’interno di blocchi di codice delimitati, come fanno in questa pagina, in modo che Hugo non li interpreti come contenuto.

Mappatura predefinita del corpo

La maggior parte degli elementi necessita di un titolo breve e di un corpo più lungo. Richiedere agli autori di ripeterli come attributi renderebbe il testo lungo difficile da modificare e facile da sfuggire in modo errato, quindi il corpo fornisce la mappatura predefinita:

:::esempio
## Un'intestazione concreta

Il resto del corpo può contenere paragrafi, elenchi, link e altri contenuti consentiti dalla definizione dell'elemento.
:::

Salvo che una pagina di elemento non sovrascriva esplicitamente la regola, la prima intestazione nel corpo si mappa a title e tutto ciò che segue quella intestazione si mappa a content. Il marcatore di intestazione esprime la gerarchia sorgente per gli editor; il campo mappato permette a ciascuna piattaforma di renderizzare il livello di intestazione semantico appropriato nel contesto.

Solo la prima intestazione del corpo riceve questo trattamento speciale. Le intestazioni successive rimangono parte di content. Se il corpo non ha intestazione, title è assente; ciò è valido solo quando la definizione dell’elemento segna il suo titolo come opzionale. Se un elemento definisce slot nominati o una mappatura diversa, la sua pagina ha la precedenza su questa impostazione predefinita perché il renderer deve sapere esattamente dove appartiene ogni frammento.

Elementi annidati

Alcuni elementi contengono un elenco ripetibile i cui elementi necessitano ciascuno di attributi e un corpo, come passaggi con identificatori, carte con etichette o elementi di checklist con uno stato iniziale. Appiattire quegli elementi in un unico elenco Markdown perderebbe i loro campi individuali, quindi gli elementi annidati usano una direttiva di elemento esplicita:

:::elemento-genitore{variante=compatto}
::elemento{chiave=valore}
### Titolo primo elemento

Spiegazione del primo elemento.
::
::elemento{chiave2="valore con spazi"}
### Titolo secondo elemento

Spiegazione del secondo elemento.
::
:::

Il contratto è ::elemento{chiave=valore} … ::: due due punti aprono ogni elemento, il nome singolare è elemento e due due punti lo chiudono. Il genitore mantiene il suo delimitatore di chiusura a tre due punti. Questa differenza visiva è importante perché rende l’annidamento inequivocabile senza fare affidamento sull’indentazione, che è facilmente danneggiata da copia e incolla.

Ogni elemento applica la stessa mappatura predefinita del corpo salvo che la pagina dell’elemento genitore dica diversamente: la sua prima intestazione diventa title di quell’elemento e il resto diventa il suo content. Metti gli attributi sull’elemento quando descrivono solo quell’elemento; mettili sul genitore quando influenzano la raccolta nel suo insieme.

Link, immagini e pulsanti inline

Il codice sorgente portabile necessita di percorsi prevedibili. Un URL relativo dovrebbe essere relativo alla radice del sito, non al file Markdown corrente, perché la stessa sorgente può essere renderizzata a una profondità di filesystem diversa in Hugo o importata in WordPress.

• I link a pagine interne usano una barra iniziale e finale, come fa il link alla libreria degli elementi . Non usare ../, omettere la barra iniziale o codificare il dominio di produzione per una pagina interna.
• I link esterni usano un URL https:// completo. Lo schema fa parte della destinazione e non deve essere dedotto da un renderer.
• I file immagine sorgente risiedono sotto cdn-assets/seo-playbook/ e i loro percorsi pubblici iniziano con /cdn-assets/seo-playbook/. Aggiungi il gruppo e il nome file approvati solo dopo che l’asset esiste.
• Il testo alternativo descrive le informazioni veicolate da un’immagine, non il suo nome file o l’aspetto decorativo. Un’immagine decorativa usa un testo alternativo vuoto, ma la pagina dell’elemento pertinente deve permettere esplicitamente la decorazione.
• Un invito all’azione inline usa :button[Etichetta visibile]{href="/destinazione/"}. Il testo tra parentesi quadre è l’etichetta accessibile e href segue le stesse regole di percorso interno o esterno. Usa un pulsante solo per una genuina azione successiva, non per rendere più prominente un normale link di riferimento.

Un’immagine è contenuto, non un’elusione per un layout non supportato. Se l’immagine contiene etichette, numeri o istruzioni essenziali, ripeti quelle informazioni in testo accessibile o usa un elemento strutturato che le esponga. Le richieste di cattura schermata rimangono commenti HTML finché l’asset nominato non esiste; non sono riferimenti di immagine pubblicati e devono impostare screenshotsPending = true nel frontmatter.

Frontmatter ed elementi del corpo hanno compiti diversi

Il frontmatter descrive il documento come documento. Le direttive del corpo descrivono blocchi significativi all’interno dell’esperienza di lettura. Mantenere questi livelli separati permette alle pagine di elenco, agli schemi, al routing e agli strumenti di pubblicazione di leggere i metadati senza analizzare la prosa visibile.

Gli elementi di metadati risiedono quindi nel frontmatter: titolo della pagina, descrizione, parole chiave, date di pubblicazione e aggiornamento, informazioni canoniche o alias, proprietà, tassonomia, collegamenti al playbook e qualsiasi raccolta orientata allo schema che il contratto della pagina vi colloca, come le voci FAQ sulle pagine academy. Questi campi non vengono mai scritti come direttive :::. Un blocco visibile che ripete alcuni metadati non sposta il campo autorevole fuori dal frontmatter; riceve un proprio elemento del corpo solo quando ha uno scopo separato rivolto al lettore.

Gli elementi di contenuto vivono nel corpo: definizioni, avvisi, suggerimenti, panoramiche, punti chiave, checklist, confronti, blocchi di prove, esempi, passaggi e inviti all’azione. Sono direttive perché la loro posizione nella narrazione è importante. Spostare un avviso nel frontmatter lo disconnetterebbe dal passaggio a cui si riferisce; nascondere i metadati in una direttiva del corpo renderebbe impossibile per i sistemi a livello di documento trovarli in modo affidabile.

I metadati sono obbligatori per impostazione predefinita

I metadati guidano route, anteprime, scoperta, collegamenti e output strutturato prima che qualcuno legga il corpo. Un campo omesso può quindi rompere i consumatori che non renderizzano mai l’articolo. Per questo motivo, ogni elemento di metadati è obbligatorio salvo che la sua pagina di elemento dica esplicitamente che è opzionale.

Obbligatorio significa popolato con un valore valido, non semplicemente presente come stringa vuota o raccolta vuota. Non dedurre l’opzionalità dall’omissione di un’altra pagina e non aggiungere valori segnaposto per soddisfare la validazione. Se un valore obbligatorio non è ancora noto, la pagina non è pronta per la pubblicazione. Gli elementi del corpo seguono le regole di obbligatorietà del tipo di post pertinente e delle pagine degli elementi, piuttosto che questa impostazione predefinita dei metadati.

Scrivi prima, applica gli elementi dopo

La selezione degli elementi è un compito di classificazione, mentre la stesura è un compito di ragionamento. Cercare di fare entrambi frase per frase porta lo scrittore a ottimizzare prematuramente per i confini dei componenti. Il risultato abituale sono transizioni più deboli, spiegazioni superficiali adattate a un box, intestazioni ripetitive create per soddisfare il markup e direttive scelte perché sono convenienti piuttosto che perché il loro scopo corrisponde.

La produzione avviene quindi in due passaggi distinti:

1. Scrivi l’intero articolo come testo semplice. Completa l’argomentazione, gli esempi, le qualificazioni, le transizioni e la conclusione. In questa fase, le intestazioni possono descrivere la logica della bozza, ma non determinano il tipo finale di elemento.
2. Applica gli elementi in una passata separata dall’alto verso il basso. Per ogni intestazione e blocco, indica il suo scopo, controlla la libreria, avvolgi le sezioni corrispondenti, aggiungi gli attributi dichiarati e conferma la mappatura del corpo e l’annidamento.

La separazione migliora entrambi gli output. La prosa si sviluppa secondo le domande del lettore invece delle dimensioni dei box del tema corrente, mentre la passata di markup può confrontare blocchi simili coerentemente attraverso l’intero documento. Rende anche visibili le omissioni: uno scrittore può vedere che l’articolo contiene un avviso o una definizione prima di decidere come codificarlo.

Dopo la passata strutturale, leggi la pagina una volta senza guardare i nomi delle direttive. Gli elementi devono supportare un articolo coerente, non trasformarlo in una pila di widget scollegati. Poi ispeziona il codice sorgente una volta senza giudicare la prosa, verificando delimitatori, attributi, elementi annidati, percorsi e metadati obbligatori.

Il contratto delle tre notazioni

Un elemento è definito una volta dal suo scopo, campi canonici, valori consentiti, mappatura del corpo, comportamento di accessibilità, comportamento di output strutturato e versione. Quella definizione è la fonte di verità. Le tre notazioni di piattaforma sono adattatori ad essa, non tre progetti di componenti indipendenti.

Le forme rappresentative spiegano la mappatura; la pagina del singolo elemento pubblica il suo nome e i campi esatti supportati. Gli autori lavorano nella notazione richiesta dal loro flusso di lavoro di pubblicazione, ma non rinominano campi, aggiungono significati solo per piattaforma o imitano manualmente l’HTML di un altro renderer.

Il proprietario dell’elemento mantiene la definizione canonica e decide se una modifica proposta è compatibile o versionata. I manutentori di Hugo e WordPress possiedono i loro adattatori e li testano su fixture condivise: lo stesso titolo, contenuto, attributi, elementi, link e aspettative di accessibilità devono sopravvivere a tutti e tre i percorsi. I proprietari editoriali verificano scopo ed esempi. Nessun manutentore di piattaforma può ridefinire localmente il significato editoriale; se una piattaforma non può esprimere il contratto, si tratta di un difetto dell’adattatore o di una modifica proposta al contratto.

Questo modello permette alla presentazione di differire dove le piattaforme lo richiedono mantenendo stabile la semantica. Hugo potrebbe renderizzare HTML lato server e WordPress potrebbe memorizzare un commento di blocco, ma un avviso rimane un avviso, un elemento di checklist rimane un elemento e gli stessi campi obbligatori rimangono disponibili a valle.

Versionamento degli elementi pubblicati

Il contenuto pubblicato è stato revisionato rispetto al significato dell’elemento esistente al momento della pubblicazione. Modificare silenziosamente quel significato può alterare avvisi, dati strutturati, accessibilità o importazioni senza che un editor tocchi la pagina. Il versionamento protegge quella approvazione editoriale.

Usa la seguente politica di modifica:

• Modifica compatibile del renderer: Un perfezionamento visivo, un miglioramento delle prestazioni o una correzione di bug che preserva scopo, campi, valori accettati, mappatura del corpo e significato dell’output può essere distribuito all’interno della versione corrente. Le pagine esistenti lo ricevono attraverso il renderer.
• Modifica additiva compatibile: Un nuovo attributo opzionale può unirsi alla versione corrente solo quando la sua assenza preserva l’output esistente e ogni adattatore può tranquillamente ignorarlo o supportarlo. La definizione e i test di piattaforma cambiano insieme.
• Modifica radicale: Un campo rinominato o rimosso, un nuovo campo obbligatorio, una mappatura del corpo modificata, uno scopo modificato, un valore predefinito modificato con effetto semantico o una struttura di elementi annidati incompatibile crea una nuova versione maggiore dell’elemento.
• Deprecazione: La vecchia versione rimane renderizzabile per le pagine pubblicate. La sua pagina di elemento identifica il sostituto e il percorso di migrazione; le nuove pagine usano la versione corrente.
• Migrazione: Una migrazione di contenuto è esplicita, circoscritta, visualizzata in anteprima attraverso Markdown, Hugo e WordPress e validata editorialmente prima della pubblicazione. Registra quali pagine sono cambiate e perché. Non far indovinare a un renderer come il vecchio codice sorgente dovrebbe essere reinterpretato.

Quando nessuna versione è scritta nel codice sorgente, l’elemento usa la versione base definita quando questo contratto è stato adottato. Quella base implicita deve rimanere stabile. Le nuove versioni maggiori si identificano usando il meccanismo di versione dichiarato nella pagina dell’elemento; non riutilizzano la sintassi senza versione.

Anche il rollback è importante. Mantieni il renderer precedente e la rappresentazione sorgente disponibili fino a quando le pagine migrate non superano i controlli strutturali, visivi, di accessibilità e di output strutturato. Se una migrazione fallisce, ripristina la mappatura della versione precedente invece di appiattire l’elemento in testo libero, che scarterebbe la semantica che il versionamento intende proteggere.

Lista di controllo per la revisione di produzione

Usa questa revisione finale dopo la passata di prosa e la passata degli elementi:

• Ogni blocco non di prosa ha uno scopo che può essere espresso in un verbo?
• La libreria è stata cercata per quello scopo e i suoi sinonimi prossimi?
• Ogni scopo corrispondente usa il suo elemento tipizzato, anche quando un H2 e un paragrafo sarebbero sembrati simili?
• Ogni passaggio di testo libero rimanente fa parte della spiegazione continua, dell’analisi, della narrazione o della transizione dell’articolo?
• Gli attributi seguono {chiave=valore chiave2="valore con spazi" .classe}, con gli spazi quotati e solo chiavi dichiarate utilizzate?
• La prima intestazione del corpo si mappa a title e il resto a content, salvo che la pagina dell’elemento dichiari un’altra mappatura?
• I figli ripetibili usano ::elemento{chiave=valore} … ::, con attributi del genitore e dell’elemento posizionati al livello corretto?
• I link interni sono relativi alla radice con barre iniziali e finali, i link esterni sono assoluti e i percorsi delle immagini sono all’interno della radice delle immagini approvata?
• I campi di metadati sono nel frontmatter, mai in direttive del corpo, e tutti i valori di metadati obbligatori sono completi?
• Gli stessi campi canonici possono essere mappati senza perdita a Markdown, Hugo e WordPress?
• Ogni modifica di definizione preserva le pagine vecchie o introduce una versione esplicita e una migrazione?

Questa pagina è un prerequisito per ogni pagina di elemento individuale. Ogni definizione di elemento deve collegarsi a queste regole base, poi documentare solo le sue eccezioni specifiche allo scopo: attributi supportati, campi obbligatori, sovrascritture della mappatura del corpo o degli elementi, annidamento consentito, nomi esatti di piattaforma e cronologia delle versioni. Se una pagina di elemento tace, si applicano le impostazioni predefinite di questa pagina.