Shortcode é contrato. De um lado, o editor escreve [algo]. Do outro, uma função PHP precisa reconhecer aquilo e devolver HTML. Quando esse contrato quebra, o time de conteúdo vê colchetes crus na página publicada e abre chamado.
Por isso shortcodes no WordPress continuam sendo usados por perfis muito diferentes: gestores de conteúdo, editores e desenvolvedores. E por isso as regras de registro importam mais do que parecem em operações com muitos editores.
Um shortcode precisa ser interpretado em dois cenários: no editor do WordPress e no código que o interpreta e o renderiza. Esse código pode estar nativamente no WordPress, em temas ou em plugins.
No editor do WordPress um shortcode é reconhecido pela sua composição: “[” (abertura de colchete), seguido do seu nome, que pode ser composto por letras minúsculas, números e sublinhados, e “]” (fechamento de colchete).
Evite o uso de “-” (hífen) na composição de nomes de shortcodes.
Alguns caracteres estão fora de discussão no nome do shortcode: [, ], <, >, / e &, além de caracteres não imprimíveis como espaço e tabulação. Essa restrição entrou no roadmap da API de shortcodes a partir do WordPress 4.4 e existe por um motivo prático: nome ambíguo confunde o parser e gera output inconsistente na renderização.
A inserção de uma galeria de fotos, por padrão, se dá pelo shortcode “gallery”. Talvez o mais conhecido deles. Outro caso frequente é o embed, que insere vídeos e outros conteúdos externos aceitando largura e altura como atributos. Em versões mais recentes do WordPress os códigos de shortcodes padrão passaram a ser destacados no editor com uma representação visual, o que reduz erro de digitação de quem publica.
Representação visual do shortcode gallery no editor do WordPress
O código que declara e interpreta um shortcode postado no editor do WordPress é uma função que aceita parâmetros e retorna dados.
Esse retorno é o output desejado, que pode ser personalizado com base nos atributos utilizados, quando suportados. Na prática, o registro segue sempre o mesmo desenho:
add_shortcode( 'apiki_destaque', function( $atts, $content = null, $tag = '' ) {
$atts = shortcode_atts( array(
'tipo' => 'padrao',
), $atts, $tag );
return sprintf(
'<div class="destaque destaque--%s">%s</div>',
esc_attr( $atts['tipo'] ),
do_shortcode( $content )
);
} );Três coisas acontecem aí: os atributos passam por um default explícito, o valor é escapado antes de ir para o HTML e o conteúdo interno volta pelo return. Nada de echo. Já chegamos nesse ponto.
São quatro. E você, como desenvolvedor ou empresa de desenvolvimento, precisa conhecê-las a fundo para aproveitar ao máximo esse recurso.
A função de callback do shortcode recebe três argumentos. São eles: os atributos do shortcode, o conteúdo (se houver) e o nome do shortcode;
Cada shortcode pode conter somente uma função associada a ele. No caso de conflito, por exemplo um plugin que registrou um shortcode com o mesmo nome, a função associada será sobrescrita. A sua função, ou a do plugin, poderá ficar em desuso. É a ordem de carregamento que define a função a ser utilizada. Prefixe os nomes;
Os nomes de atributos serão sempre convertidos para minúsculos. No entanto, seus valores serão preservados. Adote o padrão de manter tudo em minúsculo, nome e atributos;
Funções associadas a shortcodes não devem, em hipótese alguma, imprimir qualquer tipo de conteúdo. O conteúdo deve ser obrigatoriamente retornado. O não respeito a essa regra acarreta comportamentos inesperados, tipicamente output fora de lugar no topo da página.
Quem mantém código WordPress de longo prazo precisa acompanhar o roadmap da API, não só a sintaxe do dia. O rascunho de roadmap publicado no make.wordpress.org desenhou uma transição gradual, pensada para não quebrar de uma vez os plugins de shortcode existentes.
Os três eixos daquele plano:
Nomes mais restritos (a partir da 4.4). A lista de caracteres proibidos no registro, já citada acima;
Prioridade do filtro do_shortcode (4.5). A ideia era reduzir a prioridade do filtro para resolver o impacto de outros filtros que rodam depois do processamento dos shortcodes. Se o seu output vem correto da função e chega estranho na tela, a suspeita começa aqui;
Abandono do HTML antigo dentro de atributos (4.5 e 4.6). O plano previa tags próprias no lugar da sintaxe antiga usada dentro dos atributos de shortcode, com intensificação na 4.6.
A leitura útil para 2026 é de arquitetura, não de versão: shortcode que depende de HTML embutido em atributo é dívida técnica. Quem escreveu o callback devolvendo markup montado por sprintf, com atributos escapados, atravessou essas mudanças sem chamado aberto.
Em um site com equipe de marketing, dezenas de editores e publicação diária, shortcode não é detalhe de implementação. É superfície de erro.
Nome sem prefixo colide com plugin. Callback que dá echo desmonta a página. Shortcode registrado dentro do tema desaparece na troca de tema e deixa colchetes crus em centenas de posts antigos. Cada um desses casos custa fila de TI e campanha atrasada.
A regra que usamos aqui na Apiki: shortcode que o conteúdo depende para publicar mora em plugin próprio, com prefixo, output retornado e escapado. Não é preferência de estilo. É previsibilidade de publicação.
Além dessas quatro regras para a criação de shortcodes, você costuma utilizar alguma outra?
Se a sua operação WordPress já acumulou shortcodes órfãos, plugins sobrepostos e chamados recorrentes de conteúdo quebrado, fale com o nosso time para uma avaliação de WP Care.
