Imaginez: vous ajoutez une galerie de 20 images à un article. Sans shortcodes, cela représente des dizaines de lignes de HTML avec des conteneurs, des classes, des attributs de données et des liens de vignettes. Avec un shortcode, cela tient en une ligne: [gallery]. C’est précisément pour ce contraste entre volume de travail routinier et résultat que WordPress 2.5 a introduit les shortcodes, et près de deux décennies plus tard, le mécanisme reste indispensable.

Le problème, c’est que la plupart des utilisateurs craignent les shortcodes, qu’ils perçoivent comme de la «magie de développeur», ou les copient sans comprendre la syntaxe. Pourtant, un seul shortcode personnalisé peut remplacer un plugin de quarante mégaoctets ou vous faire gagner une heure de travail répétitif par mois. Ce décryptage, du [gallery] et [audio] natifs jusqu’à votre propre shortcode dans functions.php, va vous donner un contrôle total sur cet outil.

💡 Aperçu rapide:

• Ce qu’est un shortcode: une balise entre crochets que WordPress remplace par le résultat d’une fonction PHP au chargement de la page.
• Les shortcodes natifs: gallery, audio, video, caption, embed et playlist fonctionnent dès l’installation de WordPress, sans plugin.
• Les paramètres de shortcode: la syntaxe key="value" vous permet de personnaliser le rendu sans modifier le code.
• Créer votre propre shortcode: du simple remplacement d’URL à un shortcode image avec attributs, avec le code PHP prêt à l’emploi pour functions.php.
• Les shortcodes dans les widgets et les templates: comment activer la prise en charge avec une ligne et dans quels cas cela s’avère utile.

Ce qu’est un shortcode et comment il fonctionne

Un shortcode est une balise concise entre crochets que WordPress remplace par le résultat de l’exécution d’une fonction PHP au moment où la page est générée. Vous écrivez [gallery] dans l’éditeur, les visiteurs voient une grille d’images bien ordonnée. Aucune magie: derrière chaque shortcode se trouve une fonction enregistrée via add_shortcode() dans le cœur, le thème ou un plugin.

La différence clé par rapport à une insertion HTML statique: un shortcode s’exécute côté serveur. Vous lui passez des paramètres et le résultat est généré dynamiquement. Le contenu change, le rendu change, sans avoir à modifier manuellement des dizaines de pages.

Du point de vue de l’éditeur, il y a une nuance. L’éditeur visuel (Gutenberg ou le TinyMCE classique) affiche immédiatement le shortcode sous forme d’aperçu. Pour travailler avec les paramètres et les balises imbriquées, passez en mode texte. C’est uniquement là que vous voyez la structure réelle: balise ouvrante, attributs, contenu, balise fermante.

Les shortcodes natifs de WordPress: ce qui est disponible sans plugin

WordPress est livré avec six shortcodes enregistrés. Vous n’avez pas besoin de les activer ni de les configurer, il suffit de les insérer dans un article pour obtenir le résultat.

Le plus flexible d’entre eux est [gallery]. L’attribut ids vous permet de spécifier des images précises par leur ID, même celles qui ne sont pas attachées à l’article en cours. L’attribut size définit la taille des vignettes (thumbnail, medium, large ou full). La combinaison de ces deux paramètres couvre la plupart des scénarios pour lesquels on installait auparavant un plugin de galerie dédié.

[audio] et [video] prennent en charge plusieurs sources, le navigateur choisira le format compatible. Les playlists via [playlist] sont constituées à partir d’identifiants de fichiers joints, de manière similaire à une galerie, mais produisent un lecteur avec changement de piste.

Les paramètres de shortcode: comment contrôler le rendu

La plupart des shortcodes acceptent des attributs au format key="value". La substitution des valeurs modifie la logique de la fonction sans toucher au code.

Prenons [gallery]. Sans paramètre, il affiche toutes les images de l’article en taille standard. Ajoutez des précisions:

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

Désormais, le rendu est limité à trois images spécifiques, la taille passe à large et la grille s’organise en trois colonnes. Les paramètres peuvent être combinés librement, ceux qui ne sont pas spécifiés reçoivent leurs valeurs par défaut.

Certains shortcodes utilisent des balises ouvrantes et fermantes lorsqu’il est nécessaire de transmettre du contenu entre elles. Par exemple, un plugin Google Maps pourrait attendre une construction comme:

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

La balise fermante commence toujours par une barre oblique /. WordPress utilise cette notation pour distinguer le contenu entre les balises des attributs à l’intérieur de la balise ouvrante.

Comment créer votre propre shortcode

Lorsque vous avez inséré la même URL, le même bloc HTML ou le même appel à l’action dans des articles pour la dixième fois de la semaine, il est temps d’écrire un shortcode. Nul besoin d’être développeur PHP: la construction de base tient en trois lignes.

Shortcode simple pour une URL

Ajoutez ce code à la fin du fichier functions.php de votre thème (Apparence → Éditeur de thème → functions.php):

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

Désormais, dans n’importe quel article, [techblog] sera automatiquement remplacé par l’URL du site. La fonction retourne une chaîne de caractères, WordPress la substitue à l’emplacement du shortcode.

Deux règles essentielles issues de la documentation officielle:

• La fonction renvoie une valeur via return, elle n’affiche rien via echo. Une sortie directe casse l’ordre de rendu et produit des résultats imprévisibles.
• Enregistrez les shortcodes sur le hook init pour que WordPress ait le temps de charger toutes les dépendances:

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

Shortcode pour une image avec attributs personnalisables

Un scénario un peu plus complexe: vous souhaitez insérer une image en définissant sa largeur et sa hauteur directement dans l’éditeur. Dans 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' );

Utilisation dans l’éditeur:

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

La fonction shortcode_atts() fusionne les attributs passés avec les valeurs par défaut, c’est la méthode standard et sûre pour gérer les paramètres. Notez esc_url() et esc_attr(): l’échappement est obligatoire quand vous affichez une saisie utilisateur en frontend. La liste complète des attributs d’image disponibles se trouve dans la spécification W3C.

La validation des attributs mérite une mention à part. Lorsque vous acceptez des valeurs provenant de l’éditeur et les insérez dans du HTML, vérifiez toujours les types de données. Pour les attributs numériques comme width et height, utilisez intval(), cela supprimera les lettres saisies par erreur. Pour les chaînes, définissez un ensemble de valeurs autorisées via in_array(), par exemple les tailles de vignettes (thumbnail, medium, large). Ainsi la mise en page reste intacte et les résultats en frontend seront prévisibles, même si l’auteur commet une erreur dans la valeur d’un attribut.

Shortcodes dans les widgets texte et les fichiers PHP

Depuis la version 4.9 de WordPress (novembre 2017), les shortcodes fonctionnent automatiquement dans les widgets texte. Mais si vous utilisez un thème personnalisé sans prise en charge native, vous pouvez l’activer avec une ligne dans functions.php:

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

Pour éviter l’insertion automatique de balises <p> et <br> autour du shortcode dans un widget (WordPress formate automatiquement les sauts de ligne), ajoutez également:

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

Le même principe s’applique aux templates PHP. Si vous devez exécuter un shortcode directement dans header.php ou un autre fichier de thème, enveloppez-le dans do_shortcode():

1
echo do_shortcode( '[techblog]' );

Ainsi la même logique est disponible dans l’éditeur, le widget et le template, sans dupliquer le code.

Échapper: comment afficher le texte d’un shortcode sans l’exécuter

Il arrive que vous ne souhaitiez pas exécuter un shortcode, mais en montrer la syntaxe au lecteur, comme dans cet article. Si vous insérez simplement [gallery] dans l’éditeur, WordPress l’exécutera immédiatement ou affichera un espace réservé. Deux méthodes permettent d’éviter cela.

Doubles crochets. La méthode la plus simple consiste à doubler les crochets extérieurs:

1
[[gallery]]

Pour les balises par paire, le premier crochet ouvrant et le dernier crochet fermant sont doublés:

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

Codes de caractères HTML. Dans l’éditeur de texte, vous pouvez remplacer les crochets par leurs codes ASCII: [ au lieu de [ et ] au lieu de ]. La saisie [gallery] s’affichera sous forme de texte [gallery], mais ne sera pas exécutée.

La première méthode est plus simple et plus lisible dans le code source, la seconde est plus fiable avec une mise en forme complexe. Privilégiez les doubles crochets pour des modifications rapides dans l’éditeur de texte et les codes ASCII lorsque le shortcode côtoie d’autres crochets, par exemple dans des blocs de code ou des descriptions de méta-champs. Dans les deux cas, les visiteurs du site voient exactement le texte du shortcode, et WordPress ne l’exécute pas.

Vidéo: analyse complète des shortcodes WordPress

Pour ceux qui préfèrent une explication visuelle, voici un tutoriel détaillé proposé par l’équipe Kinsta. L’auteur montre la création, le débogage et des exemples concrets de shortcodes dans un projet réel, de l’installation du thème jusqu’au rendu frontend.

⁉️🤔 Foire aux questions

Peut-on utiliser des shortcodes dans Gutenberg?

Oui, via le bloc «Shortcode» dans le panneau d’insertion de blocs. Vous insérez le shortcode dans le champ du bloc, et WordPress l’exécute lors du rendu. Cependant, les shortcodes complexes avec du contenu imbriqué peuvent avoir un comportement imprévisible; dans ce cas, il est plus fiable de basculer en mode d’édition de code. Gutenberg effectue le rendu des shortcodes via une fonction de rappel côté serveur, les résultats dépendent donc de la capacité de la fonction à renvoyer un HTML correct. Les thèmes en blocs (Full Site Editing) avec theme.json peuvent partiellement restreindre la sortie des shortcodes dans les templates: vérifiez la compatibilité spécifique du thème.

Que faire si un shortcode ne fonctionne pas?

Vérifiez trois causes classiques. Premièrement: vous avez inséré le shortcode dans l’éditeur visuel, ce qui a converti les crochets en entités HTML; passez en mode texte et assurez-vous que les crochets sont droits. Deuxièmement: le plugin qui enregistre le shortcode est désactivé; allez dans «Extensions» et vérifiez son état. Troisièmement: la fonction du shortcode utilise echo au lieu de return; c’est une erreur de développement, la sortie apparaît au mauvais endroit sur la page. Méthode de diagnostic systématique: ouvrez wp-config.php, activez WP_DEBUG et WP_DEBUG_LOG. Après avoir chargé la page contenant le shortcode, consultez wp-content/debug.log: vous y trouverez les erreurs PHP spécifiques indiquant le fichier et la ligne.

Peut-on insérer du code PHP directement dans un shortcode?

Non. Un shortcode est un déclencheur, pas un conteneur pour du code arbitraire. C’est la fonction enregistrée côté serveur via add_shortcode() qui s’exécute. Si vous avez besoin d’une logique personnalisée, écrivez-la dans functions.php (ou dans un plugin dédié) et liez-la au shortcode. Entre les crochets, vous pouvez uniquement passer du contenu et des attributs, pas du code exécutable. Pour une exécution sécurisée de PHP dans le contenu, explorez des plugins comme «Code Snippets»: ils vous permettent de gérer des extraits via l’interface d’administration sans modifier functions.php et avec une protection contre les erreurs fatales.

Les shortcodes ralentissent-ils le site?

En eux-mêmes, non. add_shortcode() se contente d’enregistrer la correspondance entre une balise et une fonction dans le tableau global $shortcode_tags. La surcharge apparaît lorsque la fonction du shortcode effectue des requêtes lourdes en base de données ou des appels à des API externes à chaque chargement de page. Le problème ne vient pas du mécanisme des shortcodes, mais de l’implémentation spécifique du plugin. Règle générale: si une page contient plus de 20 shortcodes, chacun déclenchant WP_Query ou wp_remote_get(), mettez les résultats en cache via l’API Transients. Pour les scénarios courants (un ou deux shortcodes par page), l’impact sur les performances est négligeable.

Comment supprimer un shortcode de la sortie sans l’effacer de la publication?

Utilisez remove_shortcode() dans functions.php. Par exemple, pour désactiver la galerie native: remove_shortcode( 'gallery' ). Après cela, [gallery] dans le texte de la publication s’affichera comme du texte ordinaire entre crochets, sans être exécuté. C’est utile lors d’une migration vers une autre solution ou pour déboguer des conflits. Désactivation partielle: vous pouvez surcharger un shortcode en enregistrant votre propre gestionnaire avec la même balise via add_shortcode(). Le dernier gestionnaire enregistré a la priorité.

Vaut-il la peine d’apprendre les shortcodes en 2026

Gutenberg et l’éditeur de blocs ont couvert de nombreux besoins pour lesquels on écrivait auparavant des shortcodes: colonnes, boutons, insertion de médias, conteneurs. Mais les shortcodes n’ont pas disparu. Les plugins en enregistrent encore par centaines, des formulaires d’abonnement aux paniers WooCommerce. Et surtout, un seul shortcode personnalisé peut remplacer un plugin et faire exactement ce dont votre projet a besoin, sans alourdir l’administration avec les réglages d’un tiers.

Si vous répétez régulièrement le même bloc HTML, lien ou modèle dans vos articles, consacrez 10 minutes à add_shortcode() dans functions.php. Retour sur investissement: des dizaines d’heures par an que vous ne passez pas à faire du copier-coller. Les shortcodes sont rétrocompatibles: le code écrit aujourd’hui fonctionnera dans les futures versions de WordPress, car l’API des shortcodes n’a pas changé depuis son apparition et reste l’un des éléments du cœur les plus stables.