Shortcodes de WordPress: qué son y cómo crear los tuyos

Escribes [galeria] en una entrada, publicas, y en su lugar aparece una galería de imágenes completa. Esa pequeña magia son los shortcodes de WordPress: atajos de texto entre corchetes que el sistema sustituye por contenido dinámico generado con PHP. Llevan en WordPress desde la versión 2.5 y, aunque el editor de bloques ha ocupado parte de su terreno, siguen siendo una herramienta enormemente práctica: los usan los plugins de formularios, las tablas de precios, los sistemas de reservas y miles de temas. Y lo mejor es que crear los tuyos propios es sorprendentemente sencillo. En esta guía veremos qué son los shortcodes de WordPress y cómo funcionan por dentro, cómo usar los que ya tienes instalados, y sobre todo cómo programar shortcodes propios paso a paso: simples, con atributos, con contenido anidado e incluso con salida de plantillas. Todo con código PHP completo y funcional que puedes copiar, adaptar y usar hoy.

Qué son los shortcodes de WordPress y cómo funcionan

Un shortcode es una etiqueta corta entre corchetes, como [contact-form-7] o [woocommerce_cart], que WordPress busca en el contenido justo antes de mostrarlo. Cuando la encuentra, ejecuta la función PHP asociada y sustituye la etiqueta por lo que esa función devuelva. El proceso ocurre en cada carga de página, sobre el filtro the_content, así que el texto guardado en la base de datos sigue siendo [galeria]: la sustitución es siempre dinámica.

Hay tres formas de escribir un shortcode:

• Simple: [mi_shortcode] — se sustituye tal cual.
• Con atributos: [mi_shortcode color="rojo" numero="5"] — recibe parámetros que modifican la salida.
• Con contenido: [aviso]Texto interior[/aviso] — envuelve un contenido que la función puede procesar.

WordPress incluye varios de serie:

,

,

,

o . Los plugins añaden los suyos: cada formulario de Contact Form 7, por ejemplo, genera un shortcode único que pegas donde quieras mostrarlo. Si un shortcode aparece como texto plano en tu web (con corchetes incluidos), casi siempre significa que el plugin que lo interpretaba está desactivado.

Cómo usar shortcodes en entradas, páginas y widgets

En el editor de bloques (Gutenberg) existe un bloque específico llamado «Shortcode»: añádelo y pega dentro la etiqueta. En realidad también funcionan pegados en un bloque de párrafo, pero el bloque dedicado deja más claro qué es contenido y qué es código. En el editor clásico basta con escribirlos en el texto.

Fuera del contenido principal, tienes dos vías:

1. Widgets: los widgets de texto y HTML personalizado procesan shortcodes desde WordPress 4.9 sin necesidad de código extra.
2. Archivos de plantilla: si necesitas ejecutar un shortcode dentro de un archivo PHP del tema, usa la función do_shortcode():

<?php
// En un archivo de plantilla del tema (por ejemplo, footer.php):
echo do_shortcode( '[mi_formulario id="3"]' );

Conviene no abusar de do_shortcode() en plantillas: si controlas el código, llamar directamente a la función PHP del shortcode es más rápido. Pero como recurso puntual es perfectamente válido.

Cómo crear tu primer shortcode paso a paso

Toda la API gira alrededor de una función: add_shortcode(). Recibe el nombre de la etiqueta y la función de callback que genera la salida. La regla de oro: el callback devuelve el contenido con return, nunca lo imprime con echo. Si haces echo, el contenido aparecerá fuera de lugar (normalmente al principio de la entrada).

Empecemos por el shortcode más útil de todos los sencillos: el año actual, perfecto para avisos de copyright que nunca se quedan anticuados:

<?php
function biblioweb_shortcode_anio() {
    return date_i18n( 'Y' );
}
add_shortcode( 'anio', 'biblioweb_shortcode_anio' );
// Uso: &copy; [anio] Mi Empresa

El registro debe hacerse cuando WordPress ya está cargado, así que lo correcto es engancharlo al hook init. Si aún no dominas el sistema de actions y filters, te recomendamos reforzar antes esa base, porque los shortcodes de WordPress se apoyan directamente en él:

<?php
function biblioweb_registrar_shortcodes() {
    add_shortcode( 'anio', 'biblioweb_shortcode_anio' );
    add_shortcode( 'aviso', 'biblioweb_shortcode_aviso' );
}
add_action( 'init', 'biblioweb_registrar_shortcodes' );

¿Dónde colocar este código? Las mismas tres opciones de siempre: el functions.php de un tema hijo, un plugin propio o, la vía más cómoda para la mayoría, un gestor de fragmentos como WPCode, el gestor de snippets que analizamos en detalle, que valida el PHP antes de guardarlo y permite activar y desactivar cada shortcode individualmente.

Shortcodes con atributos: parámetros que cambian la salida

Los atributos convierten un shortcode fijo en una pieza reutilizable. El callback los recibe en su primer parámetro ($atts), y la función shortcode_atts() se encarga de mezclarlos con los valores por defecto, descartando cualquier atributo no previsto:

<?php
function biblioweb_shortcode_boton( $atts ) {
    $datos = shortcode_atts(
        array(
            'url'   => '#',
            'texto' => 'Más información',
            'color' => '#0057d9',
        ),
        $atts,
        'boton'
    );

    return sprintf(
        '<a class="bw-boton" href="%s" style="background:%s">%s</a>',
        esc_url( $datos['url'] ),
        esc_attr( $datos['color'] ),
        esc_html( $datos['texto'] )
    );
}
add_shortcode( 'boton', 'biblioweb_shortcode_boton' );
// Uso: [boton url="https://ejemplo.com" texto="Descargar guía" color="#1d9e75"]

Tres detalles importantes que este ejemplo aplica y que distinguen un shortcode profesional de uno frágil:

• Escapado de la salida: esc_url(), esc_attr() y esc_html() evitan que un atributo malicioso inyecte HTML o JavaScript.
• Valores por defecto: el shortcode funciona aunque el usuario no pase ningún atributo.
• Tercer parámetro de shortcode_atts(): el nombre del shortcode activa el filtro shortcode_atts_boton, que permite a otros desarrolladores modificar los valores por defecto.

Un aviso práctico: WordPress convierte los nombres de los atributos a minúsculas, así que usa siempre mi_atributo y no miAtributo al leerlos en el callback.

Shortcodes con contenido y shortcodes anidados

Cuando el shortcode envuelve texto ([aviso]...[/aviso]), ese contenido llega al callback como segundo parámetro. El caso de uso clásico es una caja de aviso destacada:

<?php
function biblioweb_shortcode_aviso( $atts, $content = null ) {
    $datos = shortcode_atts(
        array( 'tipo' => 'info' ),
        $atts,
        'aviso'
    );
    $tipos = array( 'info', 'exito', 'alerta' );
    $tipo  = in_array( $datos['tipo'], $tipos, true ) ? $datos['tipo'] : 'info';

    return '<div class="bw-aviso bw-aviso--' . esc_attr( $tipo ) . '">'
        . do_shortcode( wp_kses_post( $content ) )
        . '</div>';
}
add_shortcode( 'aviso', 'biblioweb_shortcode_aviso' );
// Uso: [aviso tipo="alerta"]Haz una copia de seguridad [anio] antes de continuar.[/aviso]

Dos funciones hacen el trabajo fino: wp_kses_post() sanea el contenido permitiendo solo el HTML propio de una entrada, y do_shortcode() aplicado sobre $content hace que los shortcodes anidados (como el [anio] del ejemplo) también se procesen. Sin esa llamada, los corchetes interiores aparecerían tal cual.

Con la misma técnica puedes montar estructuras más ambiciosas, como columnas ([fila][columna]...[/columna][/fila]) o pestañas, aunque para maquetación pura el editor de bloques suele ser hoy mejor herramienta. El punto fuerte del shortcode sigue siendo la lógica dinámica: mostrar contenido solo a usuarios registrados, pintar datos de una API, listar entradas relacionadas.

Un ejemplo completo: listado de entradas recientes con caché

Cerremos la parte técnica con un shortcode realista que combina atributos, consulta a la base de datos y una capa de caché con transients para no penalizar el rendimiento:

<?php
function biblioweb_shortcode_recientes( $atts ) {
    $datos = shortcode_atts(
        array(
            'numero'    => 5,
            'categoria' => '',
        ),
        $atts,
        'recientes'
    );

    $clave = 'bw_recientes_' . md5( serialize( $datos ) );
    $html  = get_transient( $clave );
    if ( false !== $html ) {
        return $html;
    }

    $args = array(
        'posts_per_page'      => absint( $datos['numero'] ),
        'ignore_sticky_posts' => true,
        'no_found_rows'       => true,
    );
    if ( '' !== $datos['categoria'] ) {
        $args['category_name'] = sanitize_title( $datos['categoria'] );
    }

    $consulta = new WP_Query( $args );
    if ( ! $consulta->have_posts() ) {
        return '';
    }

    $html = '<ul class="bw-recientes">';
    while ( $consulta->have_posts() ) {
        $consulta->the_post();
        $html .= '<li><a href="' . esc_url( get_permalink() ) . '">'
            . esc_html( get_the_title() ) . '</a></li>';
    }
    $html .= '</ul>';
    wp_reset_postdata();

    set_transient( $clave, $html, HOUR_IN_SECONDS );
    return $html;
}
add_shortcode( 'recientes', 'biblioweb_shortcode_recientes' );
// Uso: [recientes numero="3" categoria="wordpress"]

Este patrón (consultar, montar HTML, cachear una hora) es aplicable a casi cualquier shortcode que haga consultas. Si un día el listado no se actualiza al momento, recuerda que el transient caduca en una hora o se puede borrar al guardar entradas con un action sobre save_post.

Buenas prácticas y errores que debes evitar

• Return, nunca echo. El error número uno: la salida aparece al principio de la entrada en lugar de donde colocaste el shortcode.
• Prefija los nombres. [boton] puede chocar con el de otro plugin; [bw_boton] no. El último add_shortcode() registrado gana, y el conflicto es silencioso.
• Escapa y sanea siempre. Atributos y contenido son entrada del usuario: esc_html(), esc_url(), esc_attr() y wp_kses_post() son tu cinturón de seguridad.
• Evita lógica pesada sin caché. El shortcode se ejecuta en cada carga de página; los transients son tus aliados.
• No borres el plugin sin limpiar. Si desactivas el plugin que registra un shortcode, quedará el texto con corchetes visible. Antes de retirar shortcodes de un proyecto, búscalos y sustitúyelos.
• Documenta los atributos. Dentro de seis meses no recordarás si era numero o cantidad.

La referencia completa de la API, con todos los detalles del parser y sus limitaciones, está en la documentación oficial de shortcodes de developer.wordpress.org. Y si estás montando tu caja de herramientas de plugins, nuestra selección de plugins esenciales para empezar con WordPress te ayudará a cubrir el resto de básicos.

Preguntas frecuentes

¿Los shortcodes están obsoletos con el editor de bloques?

No. Gutenberg ha sustituido su uso para maquetación (columnas, botones, galerías), pero los shortcodes de WordPress siguen siendo el mecanismo estándar de muchísimos plugins y la forma más rápida de insertar lógica dinámica reutilizable. De hecho, el editor incluye un bloque específico para ellos, y convertir un shortcode en bloque nativo es un proyecto considerablemente más complejo.

¿Por qué mi shortcode aparece como texto con corchetes?

Tres causas habituales: el plugin o snippet que lo registra está desactivado, el nombre está mal escrito (los nombres distinguen guiones y guiones bajos) o lo has colocado en una zona donde no se procesan shortcodes, como algunos campos de widgets antiguos o los títulos. Comprueba primero que el código de registro se está ejecutando.

¿Puedo usar un shortcode dentro de otro?

Sí, siempre que el shortcode exterior procese su contenido con do_shortcode( $content ) en su callback, como hemos visto en el ejemplo de la caja de aviso. Con una limitación del parser: dos shortcodes con el mismo nombre no pueden anidarse entre sí.

¿Shortcode o bloque personalizado: cuál me conviene crear?

Si necesitas una solución rápida, reutilizable y que también funcione en widgets, plantillas o el editor clásico, el shortcode gana por simplicidad: una función PHP y listo. Si buscas una experiencia visual en el editor, con vista previa en tiempo real y controles gráficos, el bloque nativo es superior, a cambio de exigir JavaScript y un proceso de build.

Conclusión

Los shortcodes de WordPress son la vía más directa entre una necesidad («quiero mostrar esto aquí») y una solución dinámica en PHP: una etiqueta entre corchetes, una función que devuelve HTML y el sistema hace el resto. Hemos visto cómo usarlos en entradas, widgets y plantillas, cómo crearlos desde cero con add_shortcode(), cómo hacerlos flexibles con atributos y valores por defecto, cómo procesar contenido anidado de forma segura y cómo cachear su salida para que no pasen factura al rendimiento. Con los patrones de esta guía (return en lugar de echo, escapado sistemático, prefijos en los nombres y transients para las consultas) tienes todo lo necesario para construir shortcodes sólidos y profesionales. Empieza por el más simple, el del año del copyright, y ve subiendo: en poco tiempo tendrás tu propia librería de utilidades reutilizables en cualquier proyecto.