O que são shortcodes do WordPress? Um guia prático

Shortcodes do WordPress são pequenos trechos de texto envolvidos em colchetes (como [contact-form] ou [gallery ids="1,2,3"]) que o WordPress substitui por conteúdo dinâmico ao renderizar um post ou página. Foram introduzidos no WordPress 2.5 (2008) e se tornaram a forma dominante pela qual plugins adicionavam saída complexa ao conteúdo por mais de uma década. Desde o rollout do editor de blocos Gutenberg no WordPress 5.0 (2018), shortcodes têm um sucessor: blocos. Mas shortcodes não vão desaparecer. Ainda funcionam, milhões de sites dependem deles, e muitos plugins continuam a entregá-los junto com ou em vez de blocos.

Como é um shortcode do WordPress?

O shortcode básico é um nome entre colchetes:

[gallery]

O WordPress vê isso no conteúdo do post, procura o handler registrado para gallery, executa a função PHP, e substitui a tag pelo HTML que o handler emite. O visitante vê uma galeria; o editor vê [gallery].

Shortcodes podem aceitar parâmetros (chamados atributos):

[gallery ids="42,43,44" columns="3" link="file"]

E podem envolver conteúdo (chamados shortcodes envolventes):

[highlight color="yellow"]Texto importante[/highlight]

O handler do shortcode recebe os atributos e o conteúdo interno, processa em PHP, e retorna o HTML para inserir na página. O visitante nunca vê os colchetes; vê a saída renderizada.

Qual é a diferença entre um shortcode e um bloco Gutenberg?

Ambos produzem conteúdo dinâmico; diferem em onde e como esse conteúdo é gerado.

• Shortcodes são do lado servidor. A tag entre colchetes permanece no conteúdo do post armazenado no banco de dados. Quando a página é requisitada, o WordPress parseia o conteúdo, encontra o shortcode, executa o handler PHP, e substitui a saída. A visualização do editor sempre mostra a sintaxe bruta entre colchetes.
• Blocos são armazenados como HTML renderizado (com comentários de metadados). Quando você salva um post no editor de blocos, o plugin do bloco gera o HTML final e o armazena no banco de dados. O editor mostra uma prévia ao vivo do bloco renderizado, não uma tag. No frontend, nenhum PHP é executado para renderizar a maioria dos blocos; o HTML é servido diretamente.

Consequências práticas:

• Performance. Blocos são mais rápidos no frontend porque não há passo de parse-e-substitui. Shortcodes disparam uma varredura regex de cada post em cada render.
• Experiência de edição. Blocos mostram como a saída renderizada vai parecer enquanto você edita. Shortcodes mostram apenas a tag; você visualiza o resultado.
• Portabilidade. Se você desativa o plugin que provê um bloco, o HTML armazenado geralmente permanece visível (congelado na versão de quando foi salvo pela última vez). Se você desativa o plugin que provê um shortcode, a tag entre colchetes fica no conteúdo como texto puro, o que geralmente parece quebrado.
• Reutilizabilidade. Shortcodes podem ser adicionados em qualquer lugar onde PHP rode, incluindo widgets, templates e excerpts. Blocos são projetados para a área do editor de blocos, embora "Blocos Reutilizáveis" e o movimento FSE (full-site editing) estejam fechando essa lacuna.

Quais shortcodes embutidos do WordPress ainda vêm no core?

O core do WordPress historicamente entregou um punhado de shortcodes. Em 2026, os sobreviventes no codebase:

• [gallery] — Galeria de imagens. Ainda usada pelo editor clássico e como fallback quando o bloco Galeria é convertido.
• [caption] — Envolve uma imagem com uma legenda. Largamente substituído pelo bloco Imagem mas ainda emitido em alguns fluxos.
• [audio] e [video] — Player HTML5 nativo para mídia auto-hospedada.
• [embed] — Força uma URL a ser incorporada via o handler oEmbed. Raramente necessário porque o WordPress auto-incorpora a maioria das URLs.
• [playlist] — Playlists de áudio e vídeo. Uso de nicho.

A grande maioria dos shortcodes em qualquer site WordPress real vem de plugins e temas, não do core.

Que tipos de plugins usam shortcodes?

Cinco categorias cobrem quase todo uso real de shortcodes:

• Formulários de contato. Contact Form 7 ([contact-form-7 id="123"]), WPForms, Gravity Forms e Formidable todos expõem formulários via shortcodes. Mesmo quando esses plugins também oferecem blocos Gutenberg, o shortcode permanece suportado para compatibilidade retroativa.
• E-commerce. WooCommerce usa shortcodes para Carrinho, Checkout, Minha Conta e listagens de produtos ([products limit="4"]). O editor de blocos agora tem blocos equivalentes, mas shortcodes ainda dominam porque a maioria dos temas foi construída em torno deles.
• Page builders (em modo legacy). Os antigos Visual Composer, WPBakery e similares produzem shortcodes massivos aninhados quando usados no editor clássico. Desligar o page builder deixa uma parede de tags [vc_row][vc_column]... como texto puro no post — um famoso problema de lock-in.
• Tabelas de preço, sliders, accordions. A maioria dos plugins de "widget de conteúdo" (Soliloquy, Smart Slider, Easy Pricing Tables) historicamente vinham como shortcodes. Muitos ainda são ativamente mantidos mas adicionaram blocos.
• Sites de membros e aprendizado. MemberPress, LearnDash e similares restringem conteúdo com wrappers de shortcode como [restrict role="member"]...[/restrict].

Como um shortcode realmente funciona por baixo dos panos?

Três linhas de código de plugin criam um shortcode. Este exemplo mínimo registra um shortcode que emite um destaque amarelo:

add_shortcode('highlight', function ($atts, $content = null) {
    $atts = shortcode_atts([
        'color' => 'yellow',
    ], $atts, 'highlight');

    return '<mark style="background:' . esc_attr($atts['color']) . '">' . do_shortcode($content) . '</mark>';
});

O que acontece quando o WordPress renderiza [highlight color="pink"]Olá[/highlight]:

1. WordPress roda o filtro the_content, que inclui do_shortcode().
2. do_shortcode() usa uma regex para encontrar tags de shortcode no conteúdo do post.
3. Para cada correspondência, chama o handler registrado com os atributos (['color' => 'pink']) e o conteúdo interno ('Olá').
4. O handler retorna uma string, que substitui a tag do shortcode na saída.
5. O conteúdo do post é então renderizado ao navegador com a tag substituída.

O parse regex em cada render de post é o custo de performance. Em um site com milhares de posts, sem cache e com shortcodes em cada post, isso soma. Um cache de página (Redis, WP Super Cache) corrige isso armazenando o HTML final renderizado e pulando o parse.

Quando ainda devo usar shortcodes em 2026?

Três casos legítimos:

• Compatibilidade retroativa. Se seu site já usa shortcodes do Contact Form 7, WooCommerce ou qualquer plugin estabelecido, continue usando. Converter em massa posts antigos para blocos é um projeto de vários dias com pouco retorno.
• Fora do editor de blocos. Widgets (em áreas de widgets clássicas), excerpts, loops de tipos de post personalizados, conteúdo de page builder e emails enviados via templates do Mailchimp ainda aceitam shortcodes mas não blocos. Shortcodes funcionam em qualquer contexto onde do_shortcode() possa ser chamado.
• Templates e código de tema. Colocar echo do_shortcode('[my-form id="3"]'); num template PHP é uma forma de uma linha de injetar saída de plugin. Blocos requereriam renderização de bloco do lado servidor, que é mais código.

Para funcionalidade genuinamente nova num site novo, prefira blocos. Eles são a direção do core do WordPress, têm uma experiência de edição melhor, e evitam o overhead de parse de shortcodes.

O que é "shortcode bloat" e por que importa?

Shortcode bloat acontece quando um site depende de dezenas de shortcodes de plugins inativos ou desativados. Dois modos de falha seguem:

• Plugin desativado mas tags permanecem. Você desativa um plugin de slider para testar algo. Cada página que tinha [slider id="3"] agora mostra o texto literal "[slider id="3"]" em vez de um slider. A correção é reativar o plugin ou remover manualmente todas as tags de shortcode do banco de dados, o que é tedioso.
• Migração de page builder. Um site construído em Visual Composer ou WPBakery contém shortcodes aninhados como [vc_row][vc_column width="1/2"][vc_column_text]Olá[/vc_column_text][/vc_column][/vc_row]. Trocar de tema ou desativar o builder revela tudo isso como texto puro. Esta é a fonte do ponto de dor "não consigo migrar meu site para o Gutenberg" que prendeu milhares de sites.

A prevenção pragmática: escolher plugins com os quais você se compromete a longo prazo, e preferir plugins que também suportem blocos para que você possa migrar gradualmente. Para sites construídos antes de 2018, espere um projeto de migração real em vez de uma troca limpa.

Posso criar meu próprio shortcode sem escrever um plugin?

Sim, três maneiras:

1. No functions.php de um child theme. Adicione a chamada add_shortcode(). O shortcode fica disponível em todo o site. Funciona mas o shortcode fica vinculado a esse tema; troca de tema e o shortcode desaparece.
2. Em um mu-plugin customizado. Crie wp-content/mu-plugins/my-shortcodes.php e coloque suas chamadas add_shortcode() lá. Sobrevive a trocas de tema e à maioria das atualizações. A solução mais limpa.
3. Via um plugin "Code Snippets". Plugins como Code Snippets ou WPCode permitem adicionar PHP através da UI do admin. Conveniente se você não pode editar arquivos, mas adiciona uma dependência de nível admin para código que idealmente vive em arquivos.

Quais são os erros comuns com shortcodes?

• Esquecer do_shortcode() no conteúdo interno. Se seu shortcode envolve conteúdo (shortcode envolvente), você deve chamar do_shortcode($content) na parte interna para que shortcodes aninhados funcionem. Sem isso, [outer][inner][/outer] renderiza só o shortcode externo e deixa [inner] como texto puro.
• Fazer echo dentro do handler. Handlers de shortcode devem retornar sua saída, não fazer echo. Um shortcode com echo renderiza antes do conteúdo no qual está embutido, quebrando o layout da página de formas sutis.
• Esquecer esc_attr() em atributos. Sem escape, valores de atributo fornecidos pelo usuário podem escapar do HTML e criar vulnerabilidades XSS. Sempre escape o que você emite.
• Shortcodes em widgets que não os executam. Alguns tipos de widget clássicos (como o widget Text básico pré-WordPress 4.9) não auto-executam shortcodes. Correção: add_filter('widget_text', 'do_shortcode');.
• Tags dentro de outras tags causando confusão no parse. Um atributo de shortcode contendo um caractere de colchete ([shortcode label="Click [here]"]) confunde o parser. WordPress trata muitos casos mas não todos; usar entidades HTML ([ e ]) é o workaround seguro.
• Adicionar shortcodes a do_shortcode recursivamente. Dentro de um handler de shortcode, chamar do_shortcode() em conteúdo que contém o mesmo shortcode cria um loop infinito. WordPress tem proteções contra isso mas o sintoma é uma página em branco ou um erro de memória esgotada.

Como encontro cada shortcode usado no meu site?

Três abordagens rápidas:

1. Busca no banco de dados. Execute uma query SQL contra wp_posts: SELECT DISTINCT REGEXP_SUBSTR(post_content, '\\[[a-z_-]+') FROM wp_posts WHERE post_status = 'publish';. Lista cada tag de shortcode que aparece em conteúdo publicado.
2. WP-CLI. wp shortcode list mostra cada handler de shortcode registrado. Compare com a lista do banco de dados para encontrar shortcodes que são usados mas não têm mais handler ativo (provavelmente de um plugin desativado).
3. Os plugins tipo "Shortcode Cleaner" ou "Find My Blocks". Escaneiam o conteúdo em busca de uso de shortcode e bloco. Útil antes de desativar um plugin para ver quão amplamente seus shortcodes são usados.

E quanto à segurança?

Shortcodes por si não são inseguros; a questão é o que o handler faz com os atributos. Dois modelos de ameaça:

• Um usuário não confiável submete conteúdo contendo shortcodes. Se um colaborador ou assinante pode submeter posts e o shortcode executa código do lado servidor (como [exec command="..."] de um plugin de dev), isso é um caminho para execução arbitrária de código. O core do WordPress remove shortcodes de conteúdo submetido por usuários com baixos privilégios por padrão; não desfaça essa proteção.
• Atributos de shortcode são emitidos de forma insegura. Um shortcode mal escrito poderia fazer echo de [badge text="..."] direto na página sem escape, permitindo a um admin que edita um post injetar tags script. Mantenha edição de posts apenas para admins, e sempre escape valores de atributo ao escrever shortcodes customizados.

O que o InspectWP verifica

Shortcodes não são parte direta de um relatório de segurança ou performance do InspectWP, mas seus efeitos aparecem em vários lugares. Um site com shortcodes de plugins desativados tipicamente tem achados de "layouts quebrados" (texto renderizado contendo colchetes). Um site com uso pesado de shortcodes sem cache de página aparece como TTFB lento. E um site onde shortcodes de Visual Composer ou WPBakery vazam para o HTML renderizado (porque o page builder está quebrado ou desativado) aparece como erros de render e violações de acessibilidade. O padrão recomendado em 2026 é continuar usando shortcodes por razões legacy, preferir blocos para novo conteúdo, e auditar seu site periodicamente em busca de shortcodes cujos handlers não estão mais registrados.