Imagine: está a adicionar uma galeria de 20 imagens a um artigo. Sem shortcodes, seriam dezenas de linhas de HTML com wrappers, classes, atributos de dados e links de miniaturas. Com um shortcode, é uma linha: [gallery]. Foi precisamente para este contraste entre volume rotineiro e resultados que o WordPress 2.5 introduziu os shortcodes e, quase duas décadas depois, o mecanismo continua a ser indispensável.

O problema é que a maioria dos utilizadores ou teme os shortcodes como «magia de programador» ou copia-os cegamente sem compreender a sintaxe. Entretanto, um único shortcode personalizado pode substituir um plugin de quarenta megabytes ou poupar uma hora de trabalho rotineiro por mês. Esta análise, desde os [gallery] e [audio] integrados até ao seu próprio shortcode no functions.php, dar-lhe-á controlo total sobre a ferramenta.

💡 Visão geral rápida:

• O que é um shortcode: uma etiqueta entre parênteses retos que o WordPress substitui pelo resultado de uma função PHP ao carregar uma página.
• Shortcodes integrados: gallery, audio, video, caption, embed e playlist funcionam logo após instalar o WordPress, sem plugins.
• Parâmetros de shortcodes: a sintaxe key="value" permite personalizar o output sem alterar código.
• Criar o seu próprio shortcode: desde uma simples substituição de URL até um shortcode de imagem com atributos, código PHP pronto para o functions.php.
• Shortcodes em widgets e templates: como ativar o suporte com uma linha e onde isso é útil.

O que é um shortcode e como funciona

Um shortcode é uma etiqueta breve entre parênteses retos que o WordPress substitui pelo resultado da execução de uma função PHP no momento em que uma página é renderizada. Escreve [gallery] no editor, os visitantes veem uma grelha organizada de imagens. Não há magia: por trás de cada shortcode está uma função registada via add_shortcode() no núcleo, tema ou plugin.

A diferença chave em relação a inserções estáticas de HTML: um shortcode é executado no lado do servidor. Passa-lhe parâmetros e o resultado é gerado dinamicamente. O conteúdo muda, o output muda, sem editar manualmente dezenas de páginas.

Da perspetiva do editor, há uma nuance. O editor visual (Gutenberg ou o clássico TinyMCE) renderiza imediatamente o shortcode como uma pré-visualização, por isso, para trabalhar com parâmetros e etiquetas aninhadas, mude para o modo de texto. Só aí consegue ver a estrutura real: etiqueta de abertura, atributos, conteúdo, etiqueta de fecho.

Shortcodes integrados do WordPress: o que está disponível sem plugins

O WordPress vem com seis shortcodes registados. Não precisa de os ativar ou configurar, basta inseri-los num artigo e obter resultados.

O mais flexível entre eles é o [gallery]. O atributo ids permite especificar imagens específicas por ID, mesmo aquelas que não estão anexadas ao artigo atual. O atributo size define o tamanho da miniatura (thumbnail, medium, large ou full). A combinação destes dois parâmetros cobre a maioria dos cenários para os quais se costumava instalar um plugin de galeria separado.

O [audio] e o [video] suportam múltiplas fontes, o navegador escolherá um formato compatível. As playlists via [playlist] são montadas a partir de IDs de anexos, de forma semelhante a uma galeria, mas produzem um leitor com alternância de faixas.

Parâmetros de shortcodes: como controlar o output

A maioria dos shortcodes aceita atributos no formato key="value". Substituir valores altera a lógica da função sem interferir com o código.

Veja o [gallery]. Sem parâmetros, mostra todas as imagens do artigo no tamanho padrão. Adicione especificações:

1
[gallery ids="12,34,56" size="large" columns="3"]

Agora o output está limitado a três imagens especificadas, o tamanho é aumentado para large e a grelha está organizada em três colunas. Os parâmetros podem ser combinados arbitrariamente, os que não forem especificados recebem valores padrão.

Alguns shortcodes usam etiquetas de abertura e fecho quando é necessário passar conteúdo entre elas. Por exemplo, um plugin do Google Maps pode esperar uma construção como:

1
[maps]New York, USA[/maps]

A etiqueta de fecho começa sempre com uma barra /. O WordPress usa esta notação para distinguir o conteúdo entre etiquetas dos atributos dentro da etiqueta de abertura.

Como criar o seu próprio shortcode

Quando já inseriu o mesmo URL, bloco HTML ou call-to-action em artigos pela décima vez numa semana, está na hora de escrever um shortcode. Isto não exige ser um programador PHP: a construção básica cabe em três linhas.

Shortcode simples para URL

Adicione este código ao final do ficheiro functions.php do seu tema (Aparência → Editor de Temas → functions.php):

1
function techblog_short_url() {
2
    return 'https://techblog.sdstudio.top';
3
}
4
add_shortcode( 'techblog', 'techblog_short_url' );

Agora, em qualquer artigo, [techblog] será automaticamente substituído pelo URL do site. A função devolve uma string, o WordPress substitui-a no lugar do shortcode.

Duas regras extremamente importantes da documentação oficial:

• A função devolve um valor através de return, não produz saída com echo. A saída direta quebra a ordem de renderização e leva a resultados inesperados.
• Registe os shortcodes no hook init para que o WordPress tenha tempo de carregar todas as dependências:

1
add_action( 'init', 'techblog_register_shortcodes' );
2
function techblog_register_shortcodes() {
3
    add_shortcode( 'techblog', 'techblog_short_url' );
4
}

Shortcode para imagem com atributos personalizáveis

Um cenário ligeiramente mais complexo: pretende inserir uma imagem, definindo a largura e a altura diretamente no editor. No functions.php:

1
function techblog_img_shortcode( $atts, $content = null ) {
2
    $atts = shortcode_atts(
3
        array(
4
            'width'  => '',
5
            'height' => '',
6
        ),
7
        $atts,
8
        'img'
9
    );
10
    return '<img src="' . esc_url( $content ) . '" width="' . esc_attr( $atts['width'] ) . '" height="' . esc_attr( $atts['height'] ) . '" alt="" />';
11
}
12
add_shortcode( 'img', 'techblog_img_shortcode' );

Utilização no editor:

1
[img width="800" height="600"]https://example.com/photo.jpg[/img]

A função shortcode_atts() combina os atributos passados com os valores predefinidos; esta é a forma padrão e segura de lidar com parâmetros. Repare em esc_url() e esc_attr(): o escape é obrigatório ao enviar dados introduzidos pelo utilizador para o frontend. Uma lista completa dos atributos de imagem disponíveis encontra-se na especificação W3C.

Vale a pena mencionar separadamente a validação de atributos. Quando aceita valores vindos do editor e os insere em HTML, verifique sempre os tipos de dados. Para atributos numéricos como width e height, utilize intval(); isto eliminará letras introduzidas acidentalmente. Para strings, defina um conjunto de valores permitidos através de in_array(), por exemplo, tamanhos de miniaturas (thumbnail, medium, large). Desta forma, o layout mantém-se intacto e os resultados no frontend serão previsíveis, mesmo que o autor cometa um erro no valor do atributo.

Shortcodes em widgets de texto e ficheiros PHP

Desde a versão do WordPress 4.9 (novembro de 2017), os shortcodes funcionam automaticamente em widgets de texto. Mas se estiver a usar um tema personalizado sem suporte integrado, pode ativá-lo com uma linha no functions.php:

1
add_filter( 'widget_text', 'do_shortcode' );

Para evitar a inserção automática de tags <p> e <br> à volta do shortcode num widget (o WordPress formata automaticamente as quebras de linha), adicione também:

1
add_filter( 'widget_text', 'shortcode_unautop' );

O mesmo princípio aplica-se aos templates PHP. Se precisar de executar um shortcode diretamente no header.php ou noutro ficheiro do tema, envolva-o em do_shortcode():

1
echo do_shortcode( '[techblog]' );

Desta forma, a mesma lógica fica disponível no editor, no widget e no template, sem duplicar código.

Escapar: como mostrar o texto do shortcode sem execução

Por vezes, precisa de mostrar a sintaxe de um shortcode ao leitor, em vez de o executar, como neste artigo. Se inserir simplesmente [gallery] no editor, o WordPress executa-o de imediato ou mostra um placeholder. Há duas formas de evitar isto.

Parênteses retos duplos. O método mais simples: duplicar os parênteses exteriores:

1
[[gallery]]

Para tags emparelhadas, duplicam-se o primeiro de abertura e o último de fecho:

1
[[maps]New York, USA[/maps]]

Códigos de caracteres HTML. No editor de texto, pode substituir os parênteses pelos seus códigos ASCII: [ em vez de [ e ] em vez de ]. A entrada [gallery] será exibida como texto [gallery], mas não será executada.

O primeiro método é mais simples e legível no código-fonte; o segundo é mais fiável com formatação complexa. Escolha parênteses duplos para edições rápidas no editor de texto e códigos ASCII quando o shortcode estiver próximo de outros parênteses retos, por exemplo, dentro de blocos de código ou descrições de meta-campos. Em ambos os casos, os visitantes do site veem exatamente o texto do shortcode e o WordPress não o executa.

Vídeo: análise completa dos shortcodes do WordPress

Para quem prefere uma explicação visual, aqui está um tutorial detalhado da equipa Kinsta. O autor mostra a criação, depuração e exemplos reais de shortcodes num projeto ao vivo, desde a instalação do tema até ao output no frontend.

⁉️🤔 Perguntas frequentes

É possível usar shortcodes no Gutenberg?

Sim, através do bloco «Shortcode» no painel de inserção de blocos. Insere o shortcode no campo do bloco e o WordPress executa-o durante a renderização. No entanto, shortcodes complexos com conteúdo aninhado podem funcionar de forma imprevisível; nesses casos, é mais fiável mudar para o modo de edição de código. O Gutenberg renderiza shortcodes via callback do servidor, pelo que os resultados dependem de a função devolver HTML correto. Temas de blocos (Full Site Editing) com theme.json podem restringir parcialmente o output de shortcodes nos templates; verifique a compatibilidade do tema específico.

O que fazer se um shortcode não funcionar?

Verifique três causas típicas. Primeira: inseriu o shortcode no editor visual, que converteu os parênteses em entidades HTML; mude para o modo de texto e certifique-se de que os parênteses estão direitos. Segunda: o plugin que regista o shortcode está desativado; vá a «Plugins» e verifique o estado. Terceira: a função do shortcode usa echo em vez de return; isto é um erro do programador e o output aparece no local errado da página. Método de diagnóstico sistemático: abra o wp-config.php, ative o WP_DEBUG e o WP_DEBUG_LOG. Depois de carregar a página com o shortcode, verifique o ficheiro wp-content/debug.log; lá estarão erros PHP específicos a indicar o ficheiro e a linha.

É possível inserir código PHP diretamente num shortcode?

Não. Um shortcode é um gatilho, não um contentor para código arbitrário. A função registada no lado do servidor via add_shortcode() é que é executada. Se precisar de lógica personalizada, escreva-a no functions.php (ou num plugin separado) e associe-a ao shortcode. Entre parênteses retos, só pode passar conteúdo e atributos, não código executável. Para execução segura de PHP no conteúdo, explore plugins como «Code Snippets»; eles permitem gerir snippets através da interface de administração, sem editar o functions.php e com proteção contra erros fatais.

Os shortcodes tornam o site mais lento?

Por si só, não. O add_shortcode() limita-se a registar a correspondência entre a tag e a função no array global $shortcode_tags. A sobrecarga surge quando a função do shortcode executa consultas pesadas à base de dados ou chamadas a APIs externas em cada carregamento de página. O problema não está no mecanismo de shortcodes, mas na implementação específica do plugin. Orientação: se uma página contiver mais de 20 shortcodes, cada um a puxar WP_Query ou wp_remote_get(), coloque os resultados em cache via Transients API. Para cenários típicos (um ou dois shortcodes por página), o impacto no desempenho é insignificante.

Como remover um shortcode do output sem o apagar do artigo?

Use remove_shortcode() no functions.php. Por exemplo, para desativar a galeria incorporada: remove_shortcode( 'gallery' ). Após isto, [gallery] no texto do artigo será exibido como texto normal entre parênteses retos, sem execução. É útil ao migrar para outra solução ou ao depurar conflitos. Desativação parcial: pode substituir um shortcode registando o seu próprio handler com a mesma tag via add_shortcode(). O último handler registado tem prioridade.

Vale a pena aprender shortcodes em 2026

O Gutenberg e o editor de blocos resolveram muitas tarefas para as quais antes se escreviam shortcodes: colunas, botões, inserção de media, wrappers. Mas os shortcodes não desapareceram. Os plugins continuam a registá-los às centenas, desde formulários de subscrição a carrinhos do WooCommerce. E, mais importante, um shortcode personalizado pode substituir um plugin e fazer exatamente o que o seu projeto precisa, sem sobrecarregar a administração com definições de terceiros.

Se repete regularmente o mesmo bloco de HTML, link ou template nos artigos, invista 10 minutos no add_shortcode() no functions.php. Retorno do investimento: dezenas de horas por ano que não gasta em copy-paste. Os shortcodes são retrocompatíveis; o código escrito hoje funcionará em versões futuras do WordPress, porque a API de shortcodes não mudou desde que apareceu e continua a ser um dos elementos centrais mais estáveis.