Skip to content

Tudo para WordPress, desenvolvimento web — e não só

🛠️ Criar um tema WordPress a partir de HTML: guia passo a passo (parte 1)
Temas WordPressDesenvolvimento web
9 min1,785 palavras

🛠️ Criar um tema WordPress a partir de HTML: guia passo a passo (parte 1)

Um site HTML concluído não tem de ser descartado quando se muda para o WordPress. Pode pegar no seu markup, index.html e style.css, e transformá-los num tema totalmente funcional em cerca de uma hora. Isto não é magia: o WordPress é construído sobre templates PHP, que por sua vez são montados a partir de HTML comum dividido em partes lógicas.

O problema é que a maioria dos tutoriais ou o sobrecarrega com terminologia desde os primeiros parágrafos ou assume silenciosamente que já sabe PHP. Vamos adotar uma abordagem diferente: começaremos com uma maquete HTML específica (cabeçalho, conteúdo, barra lateral, rodapé) e, metodicamente, ficheiro a ficheiro, construiremos um tema funcional a partir dela. Sem magia, apenas código e lógica.

No final deste guia, terá um tema pronto que pode carregar no painel de administração do WordPress, ativar e ver o seu HTML dentro de uma plataforma dinâmica. Esta é a primeira parte, a base. Na segunda parte, abordaremos modelos de página individuais, campos personalizados e o personalizador.

💡 Visão geral rápida:

  • Dê ao tema um nome único e preencha o cabeçalho do style.css; o WordPress reconhece os temas por estes metadados.
  • Divida o index.html original em quatro ficheiros PHP: header.php, index.php, sidebar.php e footer.php.
  • Implemente os hooks padrão do WordPress (get_header, get_sidebar, get_footer, wp_head e wp_footer) para que a plataforma «veja» e integre o seu markup.
  • Adicione o Loop do WordPress ao index.php, o trecho de código que exibe os artigos do blog dentro da sua estrutura HTML.
  • Crie um arquivo ZIP, carregue o tema no painel de administração e ative-o; o seu site ganha vida no WordPress.

1. Dar nome ao tema e ao ficheiro style.css

A primeira coisa que precisa de fazer é dar um nome único ao seu tema. Mesmo que esteja a criar o tema exclusivamente para o seu próprio site, o WordPress precisa de o identificar de alguma forma no painel «Aparência → Temas».

Condições iniciais:

  • Tem um index.html e uma folha de estilos style.css (ou qualquer outro ficheiro CSS).
  • Tem uma instalação do WordPress a funcionar com pelo menos um tema padrão, por exemplo, o Twenty Twenty-Five.
  • Já criou uma pasta para o seu futuro tema dentro de /wp-content/themes/.

Abra o seu editor de código (recomendamos o Sublime Text ou o VS Code), copie o conteúdo da sua folha de estilos para um novo ficheiro e guarde-o como style.css na pasta do tema. No topo do ficheiro, antes de todo o código CSS, adicione o bloco de metadados:

1/*
2Theme Name: My HTML-to-WordPress Theme
3Theme URI: https://example.com
4Description: Theme assembled from a static HTML layout.
5Version: 1.0
6Author: Your Name
7Author URI: https://example.com
8Tags: custom-theme, html-to-wordpress, beginner
9*/

Não remova os símbolos de comentário /* e */; o WordPress lê exatamente estes. O campo Theme Name é fundamental aqui: este é o nome sob o qual o tema aparecerá no painel de administração. Os outros campos são opcionais, mas recomendamos que os preencha a todos; é uma boa prática.

Guarde o ficheiro. Nesta fase, o WordPress já consegue reconhecer o seu tema, embora ainda esteja vazio e não faça nada de útil.

2. Dividir o HTML em templates PHP

Um tema WordPress clássico é montado a partir de vários ficheiros PHP, cada um responsável pela sua própria secção da página. O layout mais comum é cabeçalho, conteúdo, barra lateral, rodapé. Se o seu HTML estiver estruturado de forma diferente (por exemplo, barra lateral à esquerda ou duas barras laterais), o princípio mantém-se; basta adaptar a divisão à sua estrutura.

Crie quatro ficheiros vazios na pasta do tema:

  • header.php, cabeçalho do site
  • index.php, template principal, ponto de montagem
  • sidebar.php, painel da barra lateral
  • footer.php, rodapé

Para já estão vazios, não espere milagres. Vamos por ordem.

2.1 Header.php, cabeçalho do site

Aceda ao painel de administração do WordPress, abra «Aparência → Editor de ficheiros do tema» e selecione o tema padrão (por exemplo, Twenty Twenty-Five). Encontre o seu header.php e copie todo o bloco <head>; este é o conjunto mínimo de meta tags e hooks sem os quais o WordPress não funcionará corretamente. Eis o que precisa de transferir para o seu header.php:

1<head>
2    <meta charset="<?php bloginfo( 'charset' ); ?>">
3    <meta name="viewport" content="width=device-width">
4    <title>&lt;?php wp_title( '|', true, 'right' ); ?&gt;</title>
5    <link rel="profile" href="https://gmpg.org/xfn/11">
6    <link rel="pingback" href="<?php bloginfo( 'pingback_url' ); ?>">
7    <?php wp_head(); ?>
8</head>

A função bloginfo() substitui dinamicamente as configurações do site (codificação, URL de pingback). O hook wp_head() é crítico: os plugins e o núcleo do WordPress inserem os seus scripts, estilos e meta tags através dele. Sem ele, o tema fica meio morto.

Agora abra o seu index.html original e copie o código do cabeçalho, tudo o que está dentro de <header> ou de um bloco semelhante, e cole-o no header.php **logo após a tag de fecho </head> e a tag de abertura **<body>. No nosso markup de demonstração, fica assim:

1<body>
2    <header class="header">
3        <p>This is header section. Put your logo and other details here.</p>
4    </header>
5

Adicione a ligação à sua folha de estilos entre as tags <head>:

1<link rel="stylesheet" type="text/css" media="all" href="<?php echo get_template_directory_uri(); ?>/style.css" />

A função get_template_directory_uri() devolve o URL da pasta do seu tema; o caminho para o CSS funcionará em qualquer servidor sem necessidade de o codificar manualmente. Guarde o header.php.

2.2 Index.php, ponto de montagem

O index.php no WordPress é um ficheiro obrigatório. Não armazena markup propriamente dito, mas monta a página a partir de partes. Abra o seu index.php vazio e adicione três linhas:

1<?php get_header(); ?>
2 
3<?php get_sidebar(); ?>
4<?php get_footer(); ?>

A primeira linha inclui o header.php. As duas últimas, sidebar.php e footer.php, ficam no final. O conteúdo principal (área de conteúdo e o Loop, mais sobre isto na próxima secção) será colocado entre elas.

Copie o bloco com a classe .content (área de conteúdo principal) do seu index.html original e cole-o entre get_header() e get_sidebar():

1<?php get_header(); ?>
2 
3    <div class="content">
4        <p>This is the main content area.</p>
5    </div><!-- .content -->
6 
7<?php get_sidebar(); ?>
8<?php get_footer(); ?>
9

O esquema é simples: o WordPress monta sequencialmente a página de cima para baixo: cabeçalho, conteúdo, barra lateral, rodapé. Cada get_*() chama o ficheiro PHP correspondente.

2.3 Sidebar.php e footer.php

A barra lateral e o rodapé são muito diretos. Copie o conteúdo dos blocos .sidebar e .footer do seu index.html para os ficheiros PHP correspondentes.

sidebar.php:

1<aside class="sidebar">
2    <p>This is the side bar</p>
3</aside>
4 
5<?php dynamic_sidebar( 'sidebar' ); ?>
6

A função dynamic_sidebar() exibe os widgets atribuídos no painel de administração («Aparência → Widgets»). Se a barra lateral não for necessária, elimine esta linha.

footer.php:

1<footer class="footer">
2    <p>And this is the footer.</p>
3</footer>
4 
5<?php wp_footer(); ?>
6</body>
7</html>
8

Nota: </body> e </html> são movidos para o footer.php. No seu HTML original, provavelmente também estão no final, e é assim que deve ser. O hook wp_footer() é tão obrigatório como o wp_head(): sem ele, muitos plugins e o próprio WordPress não funcionam (por exemplo, a barra de administração não aparece).

3. O Loop do WordPress: exibir artigos

O tema está montado, a estrutura funciona. Mas a área de conteúdo ainda é estática, com texto fixo do HTML original. Para que o WordPress comece a exibir artigos reais do blog, precisa do Loop, uma construção PHP especial que itera pelos artigos publicados e exibe-os um a um dentro do seu markup.

Esta é a peça de código mais importante do tema. Fica no index.php, dentro do bloco <div class="content">, substituindo o texto estático de marcador de posição:

1<?php if ( have_posts() ) : ?>
2    <?php while ( have_posts() ) : the_post(); ?>
3        <article <?php post_class(); ?>>
4            <header class="post-header">
5                <time datetime="<?php echo get_the_date( 'c' ); ?>">
6                    <?php echo get_the_date(); ?>
7                </time>
8                <h2>
9                    <a href="<?php the_permalink(); ?>" rel="bookmark">
10                        <?php the_title(); ?>
11                    </a>
12                </h2>
13                <span class="post-author"><?php the_author(); ?></span>
14            </header>
15 
16            <div class="entry">
17                <?php if ( has_post_thumbnail() ) : ?>
18                    <?php the_post_thumbnail( 'medium' ); ?>
19                <?php endif; ?>
20                <?php the_content(); ?>
21                <?php edit_post_link( 'Edit', '<span class="edit-link">', '</span>' ); ?>
22                <?php wp_link_pages(); ?>
23            </div>
24 
25            <footer class="post-footer">
26                <?php comments_popup_link(
27                    'Leave a comment',
28                    '1 comment',
29                    '% comments'
30                ); ?>
31            </footer>
32        </article>
33    <?php endwhile; ?>
34 
35    <nav class="navigation">
36        <div class="prev-posts"><?php next_posts_link( '← Previous posts' ); ?></div>
37        <div class="next-posts"><?php previous_posts_link( 'Newer posts →' ); ?></div>
38    </nav>
39<?php else : ?>
40    <p>No posts found.</p>
41<?php endif; ?>
42

Como funciona:

  • have_posts() verifica se há artigos para exibir. Se houver, entra no Loop.
  • the_post() prepara os dados para o próximo artigo.
  • post_class() adiciona classes CSS padrão ao <article>, útil para estilizar diferentes tipos de artigos.
  • the_permalink() e the_title() exibem o URL e o título do artigo.
  • the_content() é o corpo real do artigo.
  • the_post_thumbnail() é a imagem destacada do artigo, se estiver definida.
  • comments_popup_link() é o link para os comentários.
  • next_posts_link() e previous_posts_link() tratam da paginação.

O bloco else é acionado quando não há artigos, exibindo uma mensagem de marcador de posição.

Após inserir o Loop, o seu index.php completo fica assim:

1<?php get_header(); ?>
2 
3    <div class="content">
4        <?php if ( have_posts() ) : ?>
5            <?php while ( have_posts() ) : the_post(); ?>
6                <article <?php post_class(); ?>>
7                    <header class="post-header">
8                        <time datetime="<?php echo get_the_date( 'c' ); ?>">
9                            <?php echo get_the_date(); ?>
10                        </time>
11                        <h2>
12                            <a href="<?php the_permalink(); ?>" rel="bookmark">
13                                <?php the_title(); ?>
14                            </a>
15                        </h2>
16                        <span class="post-author"><?php the_author(); ?></span>
17                    </header>
18                    <div class="entry">
19                        <?php if ( has_post_thumbnail() ) : ?>
20                            <?php the_post_thumbnail( 'medium' ); ?>
21                        <?php endif; ?>
22                        <?php the_content(); ?>
23                        <?php edit_post_link( 'Edit', '<span class="edit-link">', '</span>' ); ?>
24                        <?php wp_link_pages(); ?>
25                    </div>
26                    <footer class="post-footer">
27                        <?php comments_popup_link(
28                            'Leave a comment',
29                            '1 comment',
30                            '% comments'
31                        ); ?>
32                    </footer>
33                </article>
34            <?php endwhile; ?>
35            <nav class="navigation">
36                <div class="prev-posts"><?php next_posts_link( '← Previous posts' ); ?></div>
37                <div class="next-posts"><?php previous_posts_link( 'Newer posts →' ); ?></div>
38            </nav>
39        <?php else : ?>
40            <p>No posts found.</p>
41        <?php endif; ?>
42    </div><!-- .content -->
43 
44<?php get_sidebar(); ?>
45<?php get_footer(); ?>
46

4. Construir e instalar o tema

Todos os cinco ficheiros (style.css, header.php, index.php, sidebar.php e footer.php) devem estar na pasta do seu tema (dê-lhe um nome, por exemplo, meu-tema-html). Empacote a pasta num arquivo ZIP.

De seguida, o cenário padrão: administração do WordPress → «Aparência» → «Temas» → «Adicionar tema» → «Carregar tema». Selecione o ficheiro ZIP, clique em «Instalar» e depois em «Ativar». Visite o site; a sua maquete HTML ganhou vida dentro do WordPress e os artigos do blog são exibidos na área de conteúdo.

Isto conclui a primeira parte. Tem agora uma estrutura de tema funcional: o WordPress reconhece-a, integra os hooks e exibe conteúdo dinâmico através do Loop. Na próxima parte, abordaremos modelos de página individuais (single.php, page.php), a hierarquia de templates e a inclusão de scripts via functions.php.

⁉️🤔 Perguntas frequentes

Preciso de saber PHP para construir um tema a partir de HTML?

Não. O mínimo que vai escrever são algumas chamadas de funções como get_header() e um Loop de 15 linhas. Tudo o resto é copiar código HTML que já tem. O PHP aqui atua como «cola», não como a linguagem principal. Se perceber onde <?php ?> abre e fecha, isso é suficiente para começar.

E se a minha maquete HTML não tiver o aspeto «cabeçalho-conteúdo-barra lateral-rodapé»?

O princípio não muda. O WordPress monta a página chamando sequencialmente ficheiros PHP; a sua ordem no index.php determina o layout. Se a sua barra lateral estiver à esquerda, basta chamar get_sidebar() antes do bloco de conteúdo. Duas barras laterais? Crie sidebar-left.php e sidebar-right.php com chamadas separadas. O esquema é flexível.

Posso criar um tema sem barra lateral?

Sim, e isso até simplifica a tarefa. Basta remover a chamada <?php get_sidebar(); ?> do index.php e não criar o ficheiro sidebar.php. Muitos temas modernos, incluindo temas de blocos do WordPress, funcionam totalmente sem barra lateral.

É obrigatório usar exatamente header.php, index.php, sidebar.php e footer.php?

O index.php e o style.css são obrigatórios; sem eles, o WordPress não vê o tema. Os outros ficheiros são opcionais. Mas header.php, sidebar.php e footer.php são o padrão de facto para temas clássicos: todos os programadores os compreendem, e as funções get_header(), get_sidebar() e get_footer() foram concebidas para eles. Para o seu primeiro tema, mantenha este conjunto de quatro.

Esta abordagem funciona com temas de blocos (FSE)?

Não, este guia é para temas PHP clássicos, que ainda estão vivos e são suportados (o WordPress não os abandonou nem tem planos para isso). Os temas de blocos (Full Site Editing) usam templates HTML e um ficheiro theme.json. Se o seu objetivo é transformar rapidamente HTML existente num tema funcional, a abordagem clássica é significativamente mais simples: menos abstrações, modelo familiar «cabeçalho-conteúdo-barra lateral-rodapé».

O que se segue: o seu primeiro passo no desenvolvimento de temas

Montou uma estrutura básica de tema a partir de markup HTML, com um Loop funcional, hooks incluídos e conteúdo dinâmico. O tema já se instala no painel de administração e exibe artigos. Agora há duas direções para evoluir:

  • Se exibir artigos no seu markup for suficiente, preencha o site com conteúdo e refine o CSS para corresponder à sua marca.

Comece com pouco: construa o tema seguindo este guia, ative-o e adicione alguns artigos de teste. Assim que vir o seu HTML com artigos reais lá dentro, tudo o resto se tornará mais fácil.

Redação
RedaçãoEquipa editorial→ All publications

Uma equipa profissional de escritores e editores especializados na criação de conteúdo de qualidade.