Gerarchia dei template WordPress: guida completa per temi classici e a blocchi

La gerarchia dei template è il meccanismo con cui WordPress decide quale file di template caricare per ogni URL richiesto dal browser. È un algoritmo deterministico: dato un URL, WordPress costruisce una lista ordinata di nomi di file candidati, cerca il primo che esiste nel tema attivo e lo usa per il rendering. Se nessun candidato specifico viene trovato, il fallback finale è sempre index.php (o index.html nei temi a blocchi).

Questo meccanismo è identico per i temi classici (file .php) e per i temi a blocchi (file .html): cambia il formato dei file e la directory in cui risiedono, ma la logica di selezione è la stessa. In questa guida tratto entrambi gli approcci in modo completo.

Come funziona la gerarchia dei template WordPress

Quando un utente visita una pagina, WordPress esegue una query al database per determinare il tipo di contenuto richiesto: è un singolo post? Una pagina? Un archivio di categoria? Una pagina di ricerca? Una volta identificato il tipo di query, WordPress costruisce una catena di fallback — una lista ordinata di nomi di template dal più specifico al più generico.

Il processo segue tre passaggi:

1. Identificazione della query — WordPress analizza l’URL e determina il tipo di richiesta (single post, page, category, tag, archive, search, 404, ecc.) usando le conditional tags interne.
2. Costruzione della lista candidati — Per ogni tipo di query, WordPress genera una lista di nomi di file template ordinati per specificità decrescente. Ad esempio, per una categoria con slug seo e ID 42, la lista sarà: category-seo.php → category-42.php → category.php → archive.php → index.php.
3. Risoluzione del file — WordPress cerca il primo file della lista che esiste fisicamente nel tema. Il primo trovato viene usato per il rendering della pagina.

Nei temi a blocchi la risoluzione aggiunge un livello: WordPress cerca prima eventuali template personalizzati dall’utente salvati nel database (post type wp_template), poi nel child theme nella directory /templates/, infine nel parent theme nella directory /templates/. Questa struttura a tre livelli permette di personalizzare i template sia dal codice sia dal Site Editor di WordPress (FSE) senza modificare i file originali del tema.

Il codice sorgente responsabile di questo processo si trova in wp-includes/template-loader.php, che delega a funzioni specifiche come get_single_template(), get_page_template(), get_category_template() e così via, ciascuna delle quali costruisce la lista candidati per il proprio tipo di query.

Temi classici vs temi a blocchi

A partire da WordPress 5.9, i temi a blocchi (block themes) sono diventati l’architettura di riferimento. I temi predefiniti di WordPress — Twenty Twenty-Three, Twenty Twenty-Four, Twenty Twenty-Five — sono tutti temi a blocchi. La differenza fondamentale con i temi classici riguarda il formato dei template e il sistema di configurazione, non la logica della gerarchia.

Aspetto	Tema classico	Tema a blocchi
Formato template	.php	.html (markup blocchi)
Posizione template	Root del tema	/templates/
Parti riutilizzabili	get_header(), get_footer(), get_sidebar()	/parts/header.html, /parts/footer.html
Configurazione design	functions.php + Customizer	theme.json + Site Editor
Override child theme	File nella root del child theme	File in /templates/ del child theme
Template personalizzati	Header Template Name: nel file PHP	Registrazione in theme.json + file HTML
Gerarchia template	Identica	Identica

Per un approfondimento sulla scelta del tema e sulle differenze architetturali, puoi consultare la guida sui migliori temi SEO per WordPress e lo strumento per confrontare due temi WordPress.

Il ruolo di theme.json

theme.json è il file di configurazione centralizzato dei temi a blocchi. Definisce il design system del tema: palette colori, tipografia, spaziatura, layout, impostazioni per singolo blocco. È importante chiarire che theme.json non partecipa alla gerarchia dei template — non decide quale template caricare — ma definisce l’aspetto visivo applicato ai template una volta caricati.

Struttura minima di un theme.json:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "primary", "color": "#0073aa", "name": "Primary" }
      ]
    },
    "typography": {
      "fontSizes": [
        { "slug": "small", "size": "14px", "name": "Small" },
        { "slug": "medium", "size": "18px", "name": "Medium" }
      ]
    },
    "layout": {
      "contentSize": "720px",
      "wideSize": "1200px"
    }
  }
}

La directory /templates/ e /parts/

Nei temi a blocchi, i template risiedono nella directory /templates/ e le parti riutilizzabili (header, footer, sidebar) nella directory /parts/. Questa è la struttura tipo di un block theme minimale:

my-block-theme/
├── parts/
│   ├── header.html
│   └── footer.html
├── templates/
│   ├── index.html          ← unico file obbligatorio
│   ├── single.html
│   ├── page.html
│   ├── archive.html
│   ├── search.html
│   ├── 404.html
│   └── home.html
├── theme.json
└── style.css               ← metadati tema (Theme Name, etc.)

L’ordine di risoluzione per i temi a blocchi è:

1. Template salvati nel database — creati o modificati dall’utente tramite il Site Editor (post type wp_template)
2. Child theme /templates/ — se è attivo un child theme, WordPress cerca prima qui
3. Parent theme /templates/ — fallback al tema genitore

Gerarchia completa dei template

Quella che segue è la gerarchia completa per ogni tipo di richiesta gestita da WordPress. I nomi dei file sono indicati senza estensione: per i temi classici aggiungi .php, per i temi a blocchi aggiungi .html e posiziona i file in /templates/. La freccia → indica il fallback al template successivo nella catena.

Front page

La front page è la pagina iniziale del sito. Il suo comportamento dipende dall’impostazione in Impostazioni → Lettura:

• Se è impostata su “Gli ultimi articoli”: front-page → home → index
• Se è impostata su “Una pagina statica”: front-page → gerarchia delle pagine (page-{slug} → page-{id} → page → singular → index)

Il template front-page ha la precedenza assoluta indipendentemente dall’impostazione. Se esiste, viene sempre usato per la home del sito.

Home (blog)

La pagina che mostra l’elenco degli ultimi articoli. Non è necessariamente la front page — se in Impostazioni → Lettura è stata impostata una pagina statica come front page, la pagina dei post viene assegnata a una pagina separata.

home → index

Singolo articolo (single post)

Il template per la visualizzazione di un singolo post.

{custom-template} → single-{post_type}-{slug} → single-{post_type} → single → singular → index

Per il post type standard post, con un articolo dal slug guida-seo, la catena diventa: single-post-guida-seo → single-post → single → singular → index.

Il template singular è un fallback condiviso tra post e pagine, introdotto in WordPress 4.3. Nella pratica viene usato raramente: la maggior parte dei temi definisce single e page separatamente.

Pagina

Il template per le pagine WordPress (post type page).

{custom-template} → page-{slug} → page-{id} → page → singular → index

Se la pagina “Chi siamo” ha slug chi-siamo e ID 15, WordPress cercherà: page-chi-siamo → page-15 → page → singular → index.

Categoria

category-{slug} → category-{id} → category → archive → index

Per la categoria “Guide WordPress” con slug guide-wordpress e ID 294: category-guide-wordpress → category-294 → category → archive → index.

Tag

tag-{slug} → tag-{id} → tag → archive → index

Il funzionamento è analogo alle categorie: WordPress cerca prima il template specifico per lo slug del tag, poi per il suo ID, poi il template generico tag, e risale fino ad archive e index.

Tassonomia personalizzata

taxonomy-{taxonomy}-{term} → taxonomy-{taxonomy} → taxonomy → archive → index

Se hai registrato una tassonomia genere con un termine thriller, la catena sarà: taxonomy-genere-thriller → taxonomy-genere → taxonomy → archive → index. Le tassonomie personalizzate sono create con register_taxonomy() e sono comuni nei siti con custom post type.

Autore

author-{nicename} → author-{id} → author → archive → index

Il campo nicename è lo slug dell’utente, non il display name. Per un autore con nicename giovanni e ID 1: author-giovanni → author-1 → author → archive → index.

Data (archivio cronologico)

date → archive → index

WordPress non prevede template specifici per anno, mese o giorno: esiste solo il template date che copre tutti gli archivi cronologici. Per personalizzare la presentazione in base al periodo è necessario usare le conditional tag (is_year(), is_month(), is_day()) all’interno del template o intervenire via filtro.

Archivio custom post type

archive-{post_type} → archive → index

Per un custom post type portfolio registrato con has_archive => true: archive-portfolio → archive → index. Senza un template dedicato, l’archivio del CPT utilizzerà lo stesso layout degli archivi standard.

Ricerca

search → index

Il template di ricerca ha una catena molto corta. La pagina dei risultati di ricerca è accessibile di default all’URL /?s=termine. Nei temi classici, il template search.php riceve la query di ricerca tramite get_search_query().

Errore 404

404 → index

Anche la pagina 404 ha solo due livelli. È buona prassi creare un template 404 dedicato che offra all’utente navigazione alternativa (ricerca, link alle sezioni principali, ultimi articoli) anziché limitarsi a un messaggio generico di errore.

Allegato (attachment)

{mime_type}-{sub_type} → {sub_type} → {mime_type} → attachment → single-attachment-{slug} → single-attachment → single → singular → index

Per un file JPEG, la catena sarà: image-jpeg → jpeg → image → attachment → poi la catena single standard. Da WordPress 6.4, le pagine attachment sono disabilitate di default per i nuovi siti (redirect automatico al file originale), risolvendo un problema storico di contenuto thin e duplicato.

Privacy policy

privacy-policy → gerarchia pagina (page-{slug} → page-{id} → page → singular → index)

Introdotto in WordPress 5.2, il template privacy-policy si attiva automaticamente per la pagina designata come Privacy Policy in Impostazioni → Privacy. Se il template non esiste, WordPress tratta la pagina come una normale page.

Embed

embed-{post_type}-{post_format} → embed-{post_type} → embed → fallback a wp-includes/theme-compat/embed.php

I template embed controllano l’aspetto del contenuto quando viene incorporato in un altro sito tramite oEmbed. Per i temi classici sono file PHP; nei temi a blocchi, questa funzionalità è ancora gestita prevalentemente via PHP a livello core.

Tabella riepilogativa della gerarchia

Riferimento rapido con tutti i tipi di richiesta e le relative catene di fallback:

Tipo di richiesta	Catena di template (dal più specifico)	Fallback finale
Front page	front-page → home	index
Home (blog)	home	index
Singolo post	single-{type}-{slug} → single-{type} → single → singular	index
Pagina	page-{slug} → page-{id} → page → singular	index
Categoria	category-{slug} → category-{id} → category → archive	index
Tag	tag-{slug} → tag-{id} → tag → archive	index
Tassonomia custom	taxonomy-{tax}-{term} → taxonomy-{tax} → taxonomy → archive	index
Autore	author-{nicename} → author-{id} → author → archive	index
Data	date → archive	index
Archivio CPT	archive-{post_type} → archive	index
Ricerca	search	index
404	404	index
Allegato	{mime}-{sub} → {sub} → {mime} → attachment → catena single	index
Privacy policy	privacy-policy → catena page	index
Embed	embed-{type}-{format} → embed-{type} → embed	core embed

Come WordPress risolve il template

Il processo tecnico di risoluzione è gestito da tre componenti principali nel core di WordPress:

1. wp-includes/template-loader.php — il dispatcher principale. Dopo che WordPress ha eseguito la query, questo file usa le conditional tag (is_single(), is_page(), is_category(), ecc.) per determinare il tipo di richiesta e chiama la funzione get_{type}_template() corrispondente.
2. get_{type}_template() — funzioni definite in wp-includes/template.php. Ciascuna costruisce l’array dei nomi candidati per quel tipo di query. Ad esempio, get_category_template() genera ['category-{slug}.php', 'category-{id}.php', 'category.php'].
3. locate_template() — riceve l’array dei candidati e cerca il primo file che esiste nel tema (child theme prima, parent theme dopo). Per i temi a blocchi, la funzione _resolve_home_block_template() e simili cercano file .html nella directory /templates/.

WordPress espone due hook fondamentali per intervenire su questo processo:

• {$type}_template_hierarchy — filtro introdotto in WordPress 4.7. Permette di modificare la lista dei candidati prima che venga cercato il file. Utile per aggiungere o rimuovere template dalla catena di fallback.
• template_include — filtro applicato dopo che WordPress ha individuato il file template. Permette di sovrascrivere completamente la scelta del template, indipendentemente dalla gerarchia. È l’hook più usato dai plugin per forzare un template personalizzato.

Per verificare quale template WordPress sta effettivamente usando su una pagina specifica, puoi usare questo snippet da inserire in functions.php o in un mu-plugin:

add_action('template_include', function($template) {
    if (current_user_can('manage_options')) {
        error_log('Template in uso: ' . $template);
    }
    return $template;
});

Il template attivo apparirà nel file debug.log di WordPress (con WP_DEBUG_LOG abilitato). In alternativa, il plugin Query Monitor mostra il template corrente direttamente nella barra di admin, insieme ai template candidati che sono stati valutati nella gerarchia.

Template personalizzati

Oltre ai template standard della gerarchia, WordPress supporta template personalizzati che possono essere assegnati a specifiche pagine o post type. Nei diagrammi della gerarchia, i custom template appaiono sempre in cima alla catena di fallback.

Temi classici

Nei temi classici, un template personalizzato è un file PHP con un header comment Template Name:. Questo header dice a WordPress di renderlo disponibile nel selettore dei template nell’editor di pagina.

<?php
/**
 * Template Name: Landing Page
 * Template Post Type: page, post
 */

get_header();
?>

<main class="landing-content">
    <?php
    while (have_posts()) :
        the_post();
        the_content();
    endwhile;
    ?>
</main>

<?php get_footer(); ?>

Il campo Template Post Type (opzionale, introdotto in WordPress 4.7) specifica per quali post type il template è disponibile. Senza questo campo, il template appare solo per le pagine.

Temi a blocchi

Nei temi a blocchi, i template personalizzati richiedono due passaggi: creare il file HTML nella directory /templates/ e registrarlo in theme.json.

Registrazione in theme.json:

{
  "customTemplates": [
    {
      "name": "landing-page",
      "title": "Landing Page",
      "postTypes": ["page", "post"]
    }
  ]
}

Il file corrispondente /templates/landing-page.html:

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
    <!-- wp:post-content /-->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

In alternativa, i template personalizzati possono essere creati direttamente dal Site Editor (Aspetto → Editor) senza toccare codice. Le modifiche vengono salvate nel database come post type wp_template e hanno la precedenza sui file del tema.

Esempio pratico: creare un template per una pagina specifica

Scenario: il sito ha una pagina “Servizi” (slug: servizi, ID: 50) che necessita di un layout diverso dalle altre pagine. Ci sono tre approcci, in ordine di specificità crescente.

Approccio 1: template basato sullo slug (senza registrazione)

Sfrutta la gerarchia nativa. Basta creare un file con il nome corretto:

• Tema classico: crea page-servizi.php nella root del tema
• Tema a blocchi: crea /templates/page-servizi.html

WordPress lo selezionerà automaticamente per la pagina con slug servizi, senza necessità di registrazione o assegnazione manuale.

Approccio 2: template personalizzato registrato

Se il template deve essere riutilizzabile su più pagine, registralo come custom template (vedi sezione precedente) e assegnalo dalla sidebar dell’editor di pagina in Pagina → Template.

Approccio 3: override programmatico via filtro

Per i casi in cui serve logica condizionale complessa (es. template diverso in base al ruolo utente o a un campo ACF):

add_filter('template_include', function($template) {
    if (is_page('servizi') && some_custom_condition()) {
        $custom = locate_template('templates/servizi-special.php');
        if ($custom) {
            return $custom;
        }
    }
    return $template;
});

Questo approccio usa il filtro template_include per sovrascrivere la gerarchia in modo chirurgico, solo quando la condizione è soddisfatta.

Errori comuni e debugging

I problemi più frequenti legati alla gerarchia dei template:

• Nome file errato — il caso più comune. single-post.php funziona, singlepost.php no. I nomi devono rispettare esattamente la convenzione: tipo, trattino, parametro. Verifica maiuscole/minuscole su server Linux (case-sensitive).
• Directory sbagliata — nei temi a blocchi, i template devono stare in /templates/, non nella root del tema. Un file single.html nella root viene ignorato.
• Mancata registrazione in theme.json — i custom template nei temi a blocchi richiedono la registrazione nell’array customTemplates di theme.json per apparire nel selettore dell’editor.
• Cache del tema — alcuni hosting e plugin di caching (es. WP Super Cache, LiteSpeed Cache) possono servire versioni cached che non riflettono il template aggiornato. Svuota la cache dopo ogni modifica ai template.
• Confusione tra singular e single/page — singular.php è il fallback condiviso tra single e page. Se il tuo tema ha solo singular.php e vuoi differenziare post e pagine, devi creare single.php e page.php separati.
• Pagine attachment indesiderate — prima di WordPress 6.4, ogni media caricato generava automaticamente una pagina attachment indicizzabile. Se il tuo sito è su una versione precedente, valuta di disabilitarle con un redirect o con il plugin di Yoast.

Strumenti di debugging:

• Query Monitor — plugin gratuito che mostra il template attivo, i template candidati valutati, le conditional tag attive e molto altro. È lo strumento più completo per il debugging della gerarchia.
• Hook template_include — lo snippet mostrato nella sezione precedente logga il template in uso nel file debug.log.
• get_page_template_slug() — funzione PHP che restituisce lo slug del custom template assegnato a una pagina. Restituisce stringa vuota se la pagina usa il template di default dalla gerarchia.

Implicazioni SEO della gerarchia template

La gerarchia dei template ha impatto diretto sull’ottimizzazione per i motori di ricerca. Ogni tipo di template genera URL e contenuti con caratteristiche diverse in termini di unicità, valore e rischio di duplicazione.

Archivi (category, tag, date, author) — questi template generano pagine che elencano post già presenti altrove nel sito. Senza intervento, creano contenuto duplicato. Le best practice:

• Le categorie possono avere valore SEO se arricchite con una descrizione unica e usate come hub tematici. Indicizzale solo se hanno contenuto originale nella pagina archivio.
• I tag, se numerosi e con pochi post ciascuno, generano thin content. In molti casi conviene impostarli come noindex o eliminarli del tutto.
• Gli archivi per data sono quasi sempre thin content puro — aggregano post già raggiungibili da categorie e pagina blog. Imposta noindex o disabilitali.
• Gli archivi autore su siti mono-autore duplicano l’elenco post della pagina blog. Disabilitali con un redirect alla pagina autore o imposta noindex.

Pagina di ricerca — il template search genera URL dinamici con parametri query string (/?s=). Deve essere sempre impostato come noindex per evitare l’indicizzazione di pagine con contenuto non controllato e potenzialmente manipolabile.

Template 404 — una pagina 404 ben progettata non è solo buona UX, è un’opportunità SEO: riduce il bounce rate, mantiene l’utente nel sito e può veicolare link interni verso contenuti rilevanti. Investi tempo nel creare un template 404 che offra ricerca, link alle sezioni principali e articoli recenti.

Custom post type — se registri CPT con has_archive => true senza creare un template archive-{post_type} dedicato, WordPress userà archive.php generico, che potrebbe non presentare il contenuto in modo ottimale per utenti e motori di ricerca. Crea sempre template dedicati per i CPT che vuoi indicizzare.

Per approfondire la gestione SEO di categorie, tag e archivi, consulta le guide WordPress dedicate.

Fonti e riferimenti

• WordPress Developer Resources — Template Hierarchy (documentazione ufficiale della gerarchia)
• WordPress Developer Resources — Block Themes (guida ufficiale temi a blocchi)
• WordPress Developer Resources — theme.json (Global Settings and Styles)
• Source code: wp-includes/template-loader.php
• Source code: wp-includes/template.php