Pular para o conteúdo
Referência

Hierarquia de Modelos de Temas de Blocos do WordPress

A hierarquia completa de modelos de temas de blocos (FSE): para cada tipo de requisição, a lista ordenada de modelos que o WordPress procura, do mais específico primeiro, recorrendo ao index.html. O equivalente da era de blocos ao clássico diagrama de hierarquia.

Para cada requisição, o WordPress procura por estes modelos em ordem — do mais específico primeiro — e para no primeiro que existir na pasta /templates do seu tema. A cadeia sempre termina em index.html.

Página inicial

A página inicial do site, esteja ela configurada para exibir os posts mais recentes ou uma página estática.

  1. front-page.html
  2. home.html
  3. index.html

front-page.html vence independentemente da escolha em Configurações → Leitura. Se a página inicial for uma página estática e não existir front-page.html, ela cai na cadeia de página estática, e não em home.html.

Índice de posts do blog

A página que lista seus posts mais recentes (a "página de posts" em Configurações → Leitura).

  1. home.html
  2. index.html

Post individual

Um post individual do blog.

  1. single-post-{slug}.html
  2. single-post.html
  3. single.html
  4. singular.html
  5. index.html

Tipo de post personalizado individual

Uma entrada individual de um tipo de post personalizado (por exemplo, um "livro").

  1. single-{post-type}-{slug}.html
  2. single-{post-type}.html
  3. single.html
  4. singular.html
  5. index.html

Para um tipo de post "book" com slug "dune": single-book-dune.html, depois single-book.html, depois single.html.

Página estática

Uma página comum do WordPress.

  1. page-{slug}.html
  2. page-{id}.html
  3. page.html
  4. singular.html
  5. index.html

Página com modelo personalizado

Uma página à qual foi atribuído um modelo personalizado no painel Modelo do editor.

  1. {custom-template}.html
  2. page-{slug}.html
  3. page-{id}.html
  4. page.html
  5. singular.html
  6. index.html

Os modelos personalizados são declarados no array customTemplates do theme.json e ficam em /templates. O modelo atribuído vence toda a cadeia de página.

Arquivo de categoria

O arquivo que lista os posts de uma categoria.

  1. category-{slug}.html
  2. category-{id}.html
  3. category.html
  4. archive.html
  5. index.html

Arquivo de tag

O arquivo que lista os posts com uma determinada tag.

  1. tag-{slug}.html
  2. tag-{id}.html
  3. tag.html
  4. archive.html
  5. index.html

Arquivo de taxonomia personalizada

O arquivo de um termo em uma taxonomia personalizada.

  1. taxonomy-{taxonomy}-{term}.html
  2. taxonomy-{taxonomy}.html
  3. taxonomy.html
  4. archive.html
  5. index.html

Arquivo de autor

O arquivo com os posts de um autor.

  1. author-{nicename}.html
  2. author-{id}.html
  3. author.html
  4. archive.html
  5. index.html

Arquivo de data

Um arquivo por ano / mês / dia.

  1. date.html
  2. archive.html
  3. index.html

Arquivo de tipo de post

O índice de arquivo de um tipo de post personalizado que tem has_archive definido.

  1. archive-{post-type}.html
  2. archive.html
  3. index.html

Resultados da busca

A página de resultados de uma busca no site.

  1. search.html
  2. index.html

404 (não encontrado)

Exibida quando nenhum conteúdo corresponde à URL.

  1. 404.html
  2. index.html

Página de anexo

A página de um único anexo de mídia.

  1. attachment.html
  2. single.html
  3. singular.html
  4. index.html

Muitos sites desativam completamente as páginas de anexo (são conteúdo raso). Se você mantiver essas páginas, esta é a cadeia.

Página de política de privacidade

A página definida como a política de privacidade do site em Configurações.

  1. page-privacy-policy.html
  2. privacy-policy.html
  3. page.html
  4. singular.html
  5. index.html

Como isso difere da hierarquia clássica (PHP)

  • Os modelos são arquivos .html em /templates, e não arquivos .php na raiz do tema. Não existe single.php — é single.html.
  • As regiões reutilizáveis (cabeçalho, rodapé) são PARTES de modelo em /parts, referenciadas com o bloco wp:template-part, e não com chamadas PHP get_header() / get_footer().
  • Não há cadeia de get_template_part() nem get_header()/get_footer(). A composição é feita com o bloco Parte de Modelo dentro dos arquivos .html.
  • index.html é OBRIGATÓRIO. Um block theme sem templates/index.html não é um block theme válido — é o fallback final obrigatório para todas as rotas acima.
  • O tema é declarado como um block theme pela PRESENÇA de templates/index.html mais um theme.json, e não por qualquer flag de cabeçalho.
  • Você pode editar qualquer um desses modelos no Editor de Site (Aparência → Editor) e salvar as alterações no banco de dados — o que passa a SOBREPOR os arquivos do tema até você limpar a personalização. Isso surpreende quem está tentando entender "por que minha alteração no modelo não faz nada".