WordPress : afficher un shortcode dans un article, une page, un bloc Gutenberg ou une template

Les shortcodes font partie de WordPress depuis longtemps, et ils restent très pratiques pour afficher du contenu dynamique dans un article, une page, un widget, un bloc Gutenberg ou une template PHP.

On les reconnaît facilement : ils utilisent une syntaxe entre crochets, par exemple [gallery], [contact-form-7], [products] ou encore [hello].

Dans un contenu WordPress, le shortcode est interprété au moment de l’affichage. WordPress appelle alors la fonction associée, récupère son retour HTML, puis l’insère dans la page.

C’est simple, efficace, et parfois encore plus rapide à mettre en place qu’un bloc sur mesure. Même si, soyons honnêtes, dès qu’un besoin devient éditorialement récurrent ou complexe, un bloc Gutenberg dynamique devient souvent plus propre.

Qu’est-ce qu’un shortcode WordPress ?

Un shortcode est un petit code textuel que WordPress remplace par un contenu généré dynamiquement.

Par exemple, ce shortcode :

[hello]Code language: JSON / JSON with Comments (json)

peut afficher :

Hello readers!

L’avantage est évident : on évite de coller du HTML ou du PHP dans l’éditeur, et on centralise la logique dans une fonction PHP.

La fonction WordPress add_shortcode() permet d’enregistrer un shortcode et de l’associer à une fonction de rappel. La documentation officielle précise que le callback peut recevoir trois arguments : les attributs, le contenu éventuel, et le nom du shortcode. Voir la documentation WordPress de add_shortcode().

Où placer le code d’un shortcode ?

On voit souvent des exemples qui placent le code dans le fichier functions.php du thème. Cela fonctionne, mais ce n’est pas toujours le meilleur choix.

Si le shortcode appartient vraiment au thème, par exemple pour un affichage purement visuel lié au design, le fichier functions.php d’un thème enfant peut convenir.

En revanche, si le shortcode fournit une fonctionnalité de contenu, mieux vaut le placer dans une petite extension dédiée ou dans un mu-plugin. Ainsi, le shortcode continue de fonctionner même si vous changez de thème.

Pour un site de production, évitez de modifier le thème parent. Utilisez plutôt :

• un thème enfant ;
• un plugin spécifique au site ;
• un mu-plugin dans wp-content/mu-plugins/.

C’est plus maintenable. Et ça évite le fameux “j’ai mis à jour le thème et mon shortcode a disparu”. Grand classique. Très mauvais feuilleton.

Créer un shortcode simple

Voici un shortcode minimaliste, compatible PHP 8.3+, documenté et conforme à une écriture WordPress propre.

<?php
/**
 * Plugin Name: SKY Shortcode Demo
 * Description: Adds a simple [hello] shortcode example.
 * Author: Matt Biscay
 * Version: 1.0.0
 */

declare(strict_types=1);

defined( 'ABSPATH' ) || exit;

/**
 * Render a simple hello message.
 *
 * @param array<string, mixed> $atts    Shortcode attributes.
 * @param string|null          $content Optional shortcode enclosed content.
 * @param string               $tag     Shortcode tag.
 * @return string Shortcode output.
 */
function sky_render_hello_shortcode( array $atts = array(), ?string $content = null, string $tag = '' ): string {
	return '<p>' . esc_html__( 'Hello readers!', 'sky-shortcode-demo' ) . '</p>';
}

add_shortcode( 'hello', 'sky_render_hello_shortcode' );Code language: HTML, XML (xml)

Le shortcode est maintenant disponible dans WordPress avec :

[hello]Code language: JSON / JSON with Comments (json)

Point important : une fonction de shortcode doit retourner son contenu, pas l’afficher directement avec echo. Cela permet à WordPress d’insérer le résultat au bon endroit dans le contenu.

Afficher un shortcode dans un article ou une page

Dans l’éditeur classique, il suffit de placer le shortcode directement dans le contenu :

[hello]Code language: JSON / JSON with Comments (json)

WordPress l’interprétera automatiquement lors de l’affichage de l’article ou de la page.

Dans Gutenberg, vous pouvez aussi coller le shortcode dans un paragraphe, mais il est plus propre d’utiliser le bloc dédié aux codes courts.

WordPress documente un bloc “Code court” que l’on peut ajouter depuis l’éditeur, notamment avec la commande slash /shortcode. Voir la documentation WordPress du bloc Code court.

Afficher un shortcode dans Gutenberg

Dans l’éditeur de blocs, ajoutez un bloc Code court, puis insérez simplement :

[hello]Code language: JSON / JSON with Comments (json)

En code Gutenberg, cela donne :

<!-- wp:shortcode -->
[hello]
<!-- /wp:shortcode -->Code language: HTML, XML (xml)

C’est la méthode la plus lisible pour conserver un shortcode dans une page construite avec Gutenberg.

Si le shortcode devient central dans votre mise en page, envisagez toutefois de le remplacer par un bloc dynamique. Les shortcodes restent utiles, mais les blocs offrent une meilleure expérience d’édition, des attributs typés, une prévisualisation plus propre et une intégration plus moderne.

Créer un shortcode avec des attributs

Un shortcode devient beaucoup plus utile lorsqu’il accepte des attributs.

Exemple d’utilisation :

[hello name="Matt"]Code language: JSON / JSON with Comments (json)

Voici le code PHP correspondant :

<?php
/**
 * Plugin Name: SKY Shortcode Demo
 * Description: Adds a [hello] shortcode with attributes.
 * Author: Matt Biscay
 * Version: 1.0.0
 */

declare(strict_types=1);

defined( 'ABSPATH' ) || exit;

/**
 * Render a personalised hello message.
 *
 * Usage: [hello name="Matt"]
 *
 * @param array<string, mixed> $atts    Shortcode attributes.
 * @param string|null          $content Optional shortcode enclosed content.
 * @param string               $tag     Shortcode tag.
 * @return string Shortcode output.
 */
function sky_render_hello_shortcode( array $atts = array(), ?string $content = null, string $tag = '' ): string {
	$atts = shortcode_atts(
		array(
			'name' => __( 'readers', 'sky-shortcode-demo' ),
		),
		$atts,
		$tag
	);

	$name = is_scalar( $atts['name'] ) ? (string) $atts['name'] : '';

	if ( '' === trim( $name ) ) {
		$name = __( 'readers', 'sky-shortcode-demo' );
	}

	return sprintf(
		'<p>%s</p>',
		esc_html(
			sprintf(
				/* translators: %s: Reader name. */
				__( 'Hello %s!', 'sky-shortcode-demo' ),
				$name
			)
		)
	);
}

add_shortcode( 'hello', 'sky_render_hello_shortcode' );Code language: HTML, XML (xml)

La fonction shortcode_atts() permet de définir des valeurs par défaut et de normaliser les attributs reçus. Cela évite de tester chaque attribut à la main.

Créer un shortcode englobant

Un shortcode peut aussi entourer un contenu.

Exemple :

[box title="Note"]Voici un contenu important.[/box]Code language: CSS (css)

Voici un exemple propre :

<?php
/**
 * Render a simple boxed content shortcode.
 *
 * Usage: [box title="Note"]Content[/box]
 *
 * @param array<string, mixed> $atts    Shortcode attributes.
 * @param string|null          $content Optional enclosed content.
 * @param string               $tag     Shortcode tag.
 * @return string Shortcode output.
 */
function sky_render_box_shortcode( array $atts = array(), ?string $content = null, string $tag = '' ): string {
	$atts = shortcode_atts(
		array(
			'title' => '',
		),
		$atts,
		$tag
	);

	$title   = is_scalar( $atts['title'] ) ? trim( (string) $atts['title'] ) : '';
	$content = null !== $content ? do_shortcode( $content ) : '';

	ob_start();
	?>
	<div class="sky-shortcode-box">
		<?php if ( '' !== $title ) : ?>
			<strong class="sky-shortcode-box__title"><?php echo esc_html( $title ); ?></strong>
		<?php endif; ?>

		<div class="sky-shortcode-box__content">
			<?php echo wp_kses_post( wpautop( $content ) ); ?>
		</div>
	</div>
	<?php

	return (string) ob_get_clean();
}

add_shortcode( 'box', 'sky_render_box_shortcode' );Code language: HTML, XML (xml)

Ici, ob_start() permet d’écrire un HTML lisible, puis de le retourner proprement avec ob_get_clean(). C’est pratique dès que le rendu devient plus long qu’une simple ligne.

Afficher un shortcode dans une template WordPress

Pour afficher un shortcode dans un fichier PHP de thème, un template part ou un plugin, utilisez do_shortcode().

Exemple simple :

<?php
echo do_shortcode( '[hello]' ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
?>Code language: HTML, XML (xml)

La fonction do_shortcode() cherche les shortcodes dans une chaîne et exécute les fonctions associées. Si aucun shortcode n’est enregistré, elle retourne le contenu sans le filtrer. Voir la documentation WordPress de do_shortcode().

Contrairement à ce que l’on lit parfois, les guillemets simples et doubles fonctionnent en PHP pour appeler un shortcode :

<?php
echo do_shortcode( '[hello]' ); // OK.
echo do_shortcode( "[hello]" ); // OK aussi.
?>Code language: HTML, XML (xml)

La vraie subtilité n’est donc pas le type de guillemets. La vraie subtilité, c’est l’échappement du résultat.

Faut-il échapper le résultat de do_shortcode() ?

Oui, mais pas toujours de la même façon.

Un shortcode retourne souvent du HTML. Si vous utilisez esc_html(), vous allez afficher les balises sous forme de texte. Si vous utilisez wp_kses_post(), vous autorisez seulement le HTML permis dans un contenu d’article.

Pour un shortcode que vous contrôlez et qui retourne déjà un HTML échappé correctement, cette forme peut être acceptable dans un template :

<?php
echo do_shortcode( '[hello]' ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
?>Code language: HTML, XML (xml)

Pour un shortcode dont la sortie doit rester limitée au HTML autorisé dans les contenus WordPress, utilisez plutôt :

<?php
echo wp_kses_post( do_shortcode( '[hello]' ) );
?>Code language: HTML, XML (xml)

Le meilleur modèle reste simple : échappez les données dans le callback du shortcode, au moment où vous construisez la sortie. Ensuite, la template n’a plus à deviner si le HTML est sûr.

Exécuter les shortcodes dans un champ personnalisé

Si un champ personnalisé contient un shortcode, WordPress ne l’exécutera pas automatiquement dans tous les contextes.

Par exemple, avec un champ post meta :

<?php
$custom_content = get_post_meta( get_the_ID(), '_sky_custom_content', true );

if ( is_string( $custom_content ) && '' !== trim( $custom_content ) ) {
	echo wp_kses_post( do_shortcode( $custom_content ) );
}
?>Code language: HTML, XML (xml)

Attention toutefois : n’exécutez pas des shortcodes depuis des champs que des utilisateurs non fiables peuvent modifier. Un shortcode peut faire bien plus qu’afficher trois mots gentils.

Exécuter les shortcodes dans un widget texte

Historiquement, on ajoutait parfois ce filtre pour activer les shortcodes dans les widgets texte :

add_filter( 'widget_text', 'do_shortcode' );Code language: JavaScript (javascript)

Sur les versions modernes de WordPress, ce besoin est beaucoup moins fréquent, car les widgets utilisent désormais l’éditeur de blocs sur la plupart des installations.

Si vous utilisez encore d’anciens widgets classiques et que vous avez un besoin précis, vous pouvez appliquer ce filtre dans un plugin spécifique au site. Sinon, préférez le bloc Code court.

Afficher un shortcode dans un template FSE ou un fichier HTML de thème bloc

Dans un thème bloc, les templates sont souvent des fichiers HTML placés dans templates/ ou parts/. Ces fichiers ne permettent pas d’exécuter directement du PHP.

Pour afficher un shortcode dans une page ou une template FSE, le plus simple reste d’insérer un bloc Code court dans l’éditeur de site ou dans le contenu de la page :

<!-- wp:shortcode -->
[hello]
<!-- /wp:shortcode -->Code language: HTML, XML (xml)

Si vous avez besoin d’un rendu dynamique propre dans une template FSE, envisagez plutôt un bloc dynamique PHP. WordPress fournit des fonctions comme do_blocks(), qui parse le contenu en blocs dynamiques, et render_block(), qui rend un bloc donné. Voir do_blocks() et voir render_block().

Créer un shortcode qui charge ses CSS uniquement quand il est utilisé

Un shortcode ne doit pas forcément charger ses styles sur tout le site. Pour un petit exemple comme [box], on peut enregistrer le CSS globalement, puis l’enqueue uniquement au moment où le shortcode s’exécute.

Exemple propre :

<?php
/**
 * Register shortcode assets.
 *
 * @return void
 */
function sky_register_shortcode_assets(): void {
	wp_register_style(
		'sky-shortcode-box',
		plugins_url( 'assets/box.css', __FILE__ ),
		array(),
		'1.0.0'
	);
}
add_action( 'wp_enqueue_scripts', 'sky_register_shortcode_assets' );

/**
 * Render a box shortcode and enqueue its CSS only when used.
 *
 * @param array<string, mixed> $atts    Shortcode attributes.
 * @param string|null          $content Optional enclosed content.
 * @param string               $tag     Shortcode tag.
 * @return string Shortcode output.
 */
function sky_render_box_shortcode_with_assets( array $atts = array(), ?string $content = null, string $tag = '' ): string {
	wp_enqueue_style( 'sky-shortcode-box' );

	$atts = shortcode_atts(
		array(
			'title' => '',
		),
		$atts,
		$tag
	);

	$title   = is_scalar( $atts['title'] ) ? trim( (string) $atts['title'] ) : '';
	$content = null !== $content ? do_shortcode( $content ) : '';

	ob_start();
	?>
	<aside class="sky-shortcode-box">
		<?php if ( '' !== $title ) : ?>
			<strong class="sky-shortcode-box__title"><?php echo esc_html( $title ); ?></strong>
		<?php endif; ?>

		<div class="sky-shortcode-box__content">
			<?php echo wp_kses_post( wpautop( $content ) ); ?>
		</div>
	</aside>
	<?php

	return (string) ob_get_clean();
}

add_shortcode( 'box', 'sky_render_box_shortcode_with_assets' );Code language: HTML, XML (xml)

Cette approche évite de charger inutilement un fichier CSS sur les pages qui n’utilisent pas le shortcode.

Bonnes pratiques pour créer un shortcode WordPress

Un shortcode propre respecte quelques règles simples :

• il retourne une chaîne avec return, au lieu d’afficher directement avec echo ;
• il utilise un préfixe unique pour éviter les collisions ;
• il valide et normalise ses attributs ;
• il échappe les données avec esc_html(), esc_attr(), esc_url() ou wp_kses_post() selon le contexte ;
• il évite les requêtes lourdes non mises en cache ;
• il ne charge ses assets que lorsqu’ils sont utiles ;
• il ne dépend pas du thème parent ;
• il reste documenté.

La documentation WordPress précise aussi qu’un seul callback peut être enregistré pour un même tag de shortcode. Si deux extensions déclarent le même shortcode, l’une peut écraser l’autre selon l’ordre de chargement. Voir la note de la documentation add_shortcode().

Shortcode ou bloc Gutenberg ?

Les shortcodes restent utiles, surtout pour des besoins simples, des intégrations historiques ou des contenus déjà existants.

Mais pour un nouveau développement éditorial, un bloc Gutenberg est souvent plus moderne. Il offre une interface visuelle, des attributs mieux structurés, une meilleure prévisualisation et une expérience plus claire pour les rédacteurs.

En résumé :

Besoin	Solution conseillée
Insérer une sortie simple dans un contenu	Shortcode
Conserver une compatibilité avec un ancien site	Shortcode
Créer une interface éditoriale moderne	Bloc Gutenberg
Ajouter plusieurs options visuelles	Bloc Gutenberg
Afficher un rendu serveur simple	Shortcode ou bloc dynamique

Le shortcode n’est pas mort. Il a simplement quitté le centre de la scène. Comme beaucoup de bons outils WordPress, il reste redoutable quand on l’utilise au bon endroit.

Résumé rapide

Pour créer un shortcode :

add_shortcode( 'hello', 'sky_render_hello_shortcode' );Code language: JavaScript (javascript)

Pour l’utiliser dans un article ou une page :

[hello]Code language: JSON / JSON with Comments (json)

Pour l’utiliser dans Gutenberg :

<!-- wp:shortcode -->
[hello]
<!-- /wp:shortcode -->Code language: HTML, XML (xml)

Pour l’appeler dans une template PHP :

echo wp_kses_post( do_shortcode( '[hello]' ) );Code language: PHP (php)

Et pour un shortcode qui retourne du HTML déjà parfaitement contrôlé :

echo do_shortcode( '[hello]' ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscapedCode language: PHP (php)

Conclusion

Afficher un shortcode dans WordPress est simple : on l’insère directement dans le contenu, dans un bloc Code court, ou dans une template PHP avec do_shortcode().

Pour créer un shortcode propre, il faut surtout retourner le contenu, valider les attributs, échapper les données, éviter les collisions de noms et placer le code dans un endroit maintenable.

Les shortcodes restent très utiles pour des besoins rapides, des intégrations existantes et des contenus dynamiques simples. Pour une expérience éditoriale moderne, les blocs Gutenberg prennent souvent le relais.

Bref : shortcode pour l’efficacité, bloc pour l’édition visuelle. Les deux peuvent cohabiter sans se tirer dessus dans le couloir.

Sources utiles

• WordPress Developer Resources : add_shortcode()
• WordPress Developer Resources : do_shortcode()
• WordPress.org : bloc Code court
• WordPress Developer Resources : do_blocks()
• WordPress Developer Resources : render_block()

Report a typo