Tous les Helpers Ghost : Guide Ultime (Data, Functional, Utility)

Les helpers Handlebars sont au cœur du système de templating de Ghost. Ils permettent d'accéder aux données, de contrôler le flux logique et d'ajouter des utilitaires pour construire des thèmes efficaces. Dans ce guide, nous couvrons les trois catégories principales : Data (accès aux données), Functional (logique conditionnelle et boucles) et Utility (fonctions pratiques). Basé sur la documentation officielle Ghost (version 2025), nous listons plus de 50 helpers avec syntaxe, paramètres et exemples simples. Idéal pour les débutants en développement de thèmes, les PME qui personnalisent leur site ou les startups qui intègrent Ghost en headless CMS.

Ce guide est structuré pour une lecture fluide : chaque catégorie commence par un aperçu, suivi d'une liste des helpers avec exemples concrets. Utilisez ces helpers dans vos fichiers .hbs pour rendre vos thèmes dynamiques sans code JavaScript lourd.

Helpers Data : Accéder aux Données du Site et du Contenu

Les helpers Data récupèrent et formatent les informations comme les posts, les auteurs, les tags ou les configurations du site. Ils sont essentiels pour afficher du contenu dynamique sans requêtes API supplémentaires.

Aperçu

Utilité : Rendre accessible les objets comme @site, post ou tags avec formatage intégré (liens, images, etc.).
Conseil pour débutants : Commencez par {{@site.title}} pour afficher le nom de votre publication.

1. `{{authors}}`

Affiche une liste liée des auteurs d'un post. Par défaut, séparés par des virgules.

Syntaxe : {{authors [separator=","] [prefix=""] [suffix=""] [autolink="true"] [limit="all"] [from="1"] [to="last"] [visibility="public"]}}

Exemple :

{{authors separator=" | " prefix="Par :"}}

Sortie : Par : Auteur1 | Auteur2

2. `{{comments}}`

Affiche le système de commentaires pour membres (si activé).

Syntaxe : {{comments [title="Discussion"] [count="true"] [mode="auto"] [saturation="60"]}}

Exemple :

{{comments title="Rejoignez la discussion" count="false"}}

Affiche le formulaire sans compteur.

3. `{{@config}}`

Accède aux configs du thème (ex. : posts par page) définies dans package.json.

Syntaxe : {{@config.property}} (ex. : posts_per_page)

Exemple :

<a href="{{page_url}}">{{@config.posts_per_page}} posts</a>

4. `{{content}}`

Affiche le contenu HTML d'un post, avec limite optionnelle. Pour les non-membres, montre un CTA d'abonnement.

Syntaxe : {{content [words="all"]}}

Exemple :

{{content words="100"}}

Limite à 100 mots avec tags HTML préservés.

5. `{{@custom}}`

Accède aux settings personnalisés du thème (dans package.json).

Syntaxe : {{@custom.setting}}

Exemple :

{{#if @custom.cta_text}}
  <h2>{{@custom.cta_text}}</h2>
{{/if}}

6. `{{date}}`

Formate une date avec Moment.js.

Syntaxe : {{date date format="DD MMMM YYYY" [timeago="false"] [timezone=""] [locale=""]}}

Exemple :

{{date published_at format="DD MMMM YYYY" timeago="true"}}

Sortie : 5 minutes ago

7. `{{excerpt}}`

Affiche un extrait du post sans HTML, avec limite.

Syntaxe : {{excerpt [characters="all"] [words="all"]}}

Exemple :

{{excerpt characters="140"}}

Extrait de 140 caractères.

8. `{{img_url}}`

Génère l'URL d'une image avec redimensionnement et format.

Syntaxe : {{img_url image [size=""] [format=""] [absolute="false"]}}

Exemple :

<img src="{{img_url feature_image size='small' format='webp'}}">

9. `{{link}}`

Crée un lien <a> avec classes dynamiques (active si URL courante).

Syntaxe : {{#link href="url" [class=""] [activeClass="nav-current"] [target=""]}}Contenu{{/link}}

Exemple :

{{#link href=site.url class="logo"}}Logo{{/link}}

10. `{{navigation}}`

Affiche le menu de navigation (primaire ou secondaire).

Syntaxe : {{navigation [type="primary"]}}

Exemple :

{{navigation type="secondary"}}

Personnalisez via partials/navigation.hbs.

11. `{{@page}}`

Accède aux données de page (ex. : afficher titre/image).

Syntaxe : @page.show_title_and_feature_image (booléen, défaut true).

Exemple :

{{#match @page.show_title_and_feature_image}}
  <h1>{{title}}</h1>
{{/match}}

12. `{{price}}`

Formate un prix monétaire.

Syntaxe : {{price value [currency=""] [locale=""] [numberFormat="short"] [currencyFormat="symbol"]}}

Exemple :

{{price monthly_price currency="EUR"}}

Sortie : 5 €

13. `{{readable_url}}`

Nettoie une URL pour affichage (supprime protocole, www, params).

Syntaxe : {{readable_url "url"}}

Exemple :

{{readable_url site.url}}

Sortie : ghostcms.fr

14. `{{recommendations}}`

Affiche des recommandations de posts.

Syntaxe : {{recommendations [limit="5"] [order=""] [page="1"] [filter=""]}}

Exemple :

{{recommendations limit="3"}}

15. `{{@site}}`

Accède aux données globales du site (titre, logo, etc.).

Syntaxe : {{@site.property}} (ex. : title, url, members_enabled)

Exemple :

{{#if @site.members_enabled}}
  <a href="{{@site.signup_url}}">S'abonner</a>
{{/if}}

16. `{{social_url}}`

Génère une URL sociale (Twitter, Facebook, etc.).

Syntaxe : {{social_url type="twitter"}}

Exemple :

{{#if author.twitter}}
  <a href="{{social_url type='twitter'}}">Twitter</a>
{{/if}}

17. `{{tags}}`

Affiche une liste liée des tags d'un post.

Syntaxe : {{tags [separator=","] [prefix=""] [suffix=""] [autolink="true"] [limit="all"] [from="1"] [to="last"] [visibility="public"]}}

Exemple :

{{tags separator=" • " visibility="all"}}

18. `{{tiers}}`

Formate les noms de tiers d'abonnement.

Syntaxe : {{tiers [prefix=""] [separator=","] [lastSeparator="and"] [suffix="tiers"]}}

Exemple :

{{tiers prefix="Accès :" suffix="niveaux"}}

19. `{{title}}`

Affiche le titre d'un post avec formatage correct.

Syntaxe : {{title}}

Exemple :

<h1>{{title}}</h1>

20. `{{total_members}}`

Affiche le nombre total d'abonnés (arrondi).

Syntaxe : {{total_members}}

Exemple :

{{total_members}} abonnés

Sortie : 1,200+

21. `{{total_paid_members}}`

Affiche le nombre d'abonnés payants (arrondi).

Syntaxe : {{total_paid_members}}

Exemple :

{{total_paid_members}} payants

22. `{{url}}`

Génère l'URL relative ou absolue d'un objet.

Syntaxe : {{url [absolute="false"]}}

Exemple :

<a href="{{url absolute='true'}}">Lien absolu</a>

Astuce pour PME : Utilisez ces helpers pour afficher dynamiquement les stats d'abonnés sur votre page d'accueil, sans mise à jour manuelle.

Helpers Functional : Contrôler la Logique et les Boucles

Les helpers Functional gèrent les conditions, boucles et comparaisons. Ils remplacent les boucles basiques de Handlebars pour une meilleure flexibilité.

Aperçu

Utilité : Boucler sur des collections (foreach), tester des conditions (if, has).
Conseil pour startups : {{#get}} est puissant pour fetcher des données API dans les templates, idéal pour des previews dynamiques.

1. `{{#foreach}}`

Boucle sur une collection avec options avancées.

Syntaxe : {{#foreach collection [limit=""] [from=""] [to=""] [visibility=""] [columns=""] [as |item|]}}...{{/foreach}}

Exemple :

{{#foreach posts limit="3"}}
  <h2>{{title}}</h2>
{{/foreach}}

2. `{{#get}}`

Requête API pour fetcher des données (posts, tags, etc.).

Syntaxe : {{#get "resource" [limit=""] [page=""] [order=""] [include=""] [filter=""] [as |data|]}}...{{/get}}

Exemple :

{{#get "posts" filter="featured:true" limit="5"}}
  {{#foreach posts}}
    {{title}}
  {{/foreach}}
{{/get}}

3. `{{#has}}`

Teste la présence de propriétés (tags, auteurs, etc.).

Syntaxe : {{#has [tag=""] [author=""] [slug=""] [id=""] [any=""] [all=""] [number=""]}}...{{else}}...{{/has}}

Exemple :

{{#has tag="photo"}}
  <img src="{{feature_image}}">
{{/has}}

4. `{{#if}}`

Condition basique (truthy/falsy).

Syntaxe : {{#if condition}}...{{else if condition}}...{{else}}...{{/if}}

Exemple :

{{#if feature_image}}
  <img src="{{img_url feature_image}}">
{{else}}
  <p>Aucune image</p>
{{/if}}

5. `{{#is}}`

Vérifie le contexte de la route (home, post, etc.).

Syntaxe : {{#is "home,post"}}...{{/is}} (ou ^is pour négation)

Exemple :

{{#is "home"}}
  <h1>Bienvenue</h1>
{{/is}}

6. `{{#match}}`

Compare valeurs avec opérateurs (=, >, ~ pour contains).

Syntaxe : {{#match value operator="=" target}}...{{else match ...}}...{{/match}}

Exemple :

{{#match @custom.color "Dark"}}
  <body class="dark-mode">
{{/match}}

7. `{{#unless}}`

Inverse de if (exécute si faux).

Syntaxe : {{#unless condition}}...{{else}}...{{/unless}}

Exemple :

{{#unless featured}}
  <p>Post standard</p>
{{/unless}}

Astuce pour débutants : Combinez {{#get}} et {{#foreach}} pour lister les derniers posts sur une sidebar.

Helpers Utility : Outils Pratiques pour le Templating

Les helpers Utility facilitent la manipulation de strings, classes CSS et inclusions de partials.

Aperçu

Utilité : Ajouter des classes dynamiques, paginer, logger pour debug.
Conseil pour PME : {{pagination}} simplifie la navigation sur les blogs longs.

1. `{{asset}}`

Chemin vers un fichier dans /assets avec cache.

Syntaxe : {{asset "path" [hasMinFile="false"]}}

Exemple :

<link href="{{asset 'css/style.css' hasMinFile='true'}}">

2. `{{block}}`

Placeholder pour héritage de templates.

Syntaxe : {{{block "name"}}}
Utilisez avec {{#contentFor}} dans l'enfant.

Exemple : Voir docs pour héritage.

3. `{{body_class}}`

Classes CSS dynamiques pour <body> (ex. : post-template tag-photo).

Syntaxe : {{body_class}}

Exemple :

<body class="{{body_class}}">

4. `{{concat}}`

Concatène des strings.

Syntaxe : {{concat item1 item2 [separator=""]}}

Exemple :

class="{{concat 'nav-' slug}}"

5. `{{encode}}`

Encode pour URL (espaces en %20).

Syntaxe : {{encode "string"}}

Exemple :

<a href="https://twitter.com/share?text={{encode title}}">Partager</a>

6. `{{ghost_head}}` et `{{ghost_foot}}`

Inclut metas, scripts et injections de code.

Syntaxe : {{ghost_head}} avant </head>, {{ghost_foot}} avant </body>

Exemple : Placement standard dans default.hbs.

7. `{{link_class}}`

Classe active pour liens de navigation.

Syntaxe : {{link_class for="slug" [activeClass="nav-current"] [class=""]}}

Exemple :

<li class="{{link_class for='/about/'}}">

8. `{{log}}`

Debug en console (dev mode).

Syntaxe : {{log "message" [context]}}

Exemple :

{{log post}}

9. `{{pagination}}`

Liens de pagination.

Syntaxe : {{pagination}}
Personnalisez via partials/pagination.hbs.

Exemple : Placement après liste de posts.

10. `{{> partials}}`

Inclut un partial.

Syntaxe : {{> "partial-name" [property="value"]}}

Exemple :

{{> "post-card" heading="Titre"}}

11. `{{plural}}`

Gère singulier/pluriel.

Syntaxe : {{plural number [empty=""] [singular=""] [plural=""]}}

Exemple :

{{plural pagination.total empty="Aucun post" singular="1 post" plural="% posts"}}

12. `{{post_class}}`

Classes pour conteneur de post (ex. : post featured tag-photo).

Syntaxe : {{post_class}}

Exemple :

<article class="{{post_class}}">

13. `{{prev_post}}` et `{{next_post}}`

Navigation vers post précédent/suivant.

Syntaxe : {{#prev_post}}...{{/prev_post}} (similaire pour next)

Exemple :

{{#prev_post}}<a href="{{url}}">Précédent</a>{{/prev_post}}

14. `{{reading_time}}`

Temps de lecture estimé.

Syntaxe : {{reading_time [minute=""] [minutes=""]}}

Exemple :

{{reading_time minute="1 min" minutes="% mins"}}

15. `{{search}}`

Bouton de recherche.

Syntaxe : {{search}}

Exemple :

{{search}}

16. `{{#split}}`

Divise une string en array.

Syntaxe : {{#foreach (split "string" separator=",")}}...{{/foreach}}

Exemple :

{{#foreach (split "a,b,c" separator=",")}}
  {{this}}<br>
{{/foreach}}

17. `{{t}}` (translate)

Traduit du texte.

Syntaxe : {{t "key" [placeholder="value"]}}

Exemple :

{{t "Subscribe to {blog}" [email protected]}}

Astuce pour startups : Utilisez {{body_class}} et {{post_class}} pour des styles conditionnels sans JS, accélérant le chargement.

Conclusion : Maîtrisez les Helpers pour des Thèmes Efficaces

Avec ces helpers, vous pouvez créer des thèmes Ghost flexibles et performants. Pour les débutants, testez-les dans un thème local ; pour les PME, intégrez-les à des partials réutilisables. Consultez toujours la doc officielle pour les mises à jour 2025. Si vous développez un thème, commencez par {{#get}} pour des requêtes dynamiques. Questions ? Commentez ci-dessous.

Tous les Helpers Ghost : Guide Ultime (Data, Functional, Utility)

Helpers Data : Accéder aux Données du Site et du Contenu

Aperçu

1. {{authors}}

2. {{comments}}

3. {{@config}}

4. {{content}}

5. {{@custom}}

6. {{date}}

7. {{excerpt}}

8. {{img_url}}

9. {{link}}

10. {{navigation}}

11. {{@page}}

12. {{price}}

13. {{readable_url}}

14. {{recommendations}}

15. {{@site}}

16. {{social_url}}

17. {{tags}}

18. {{tiers}}

19. {{title}}

20. {{total_members}}

21. {{total_paid_members}}

22. {{url}}

Helpers Functional : Contrôler la Logique et les Boucles

Aperçu

1. {{#foreach}}

2. {{#get}}

3. {{#has}}

4. {{#if}}

5. {{#is}}

6. {{#match}}

7. {{#unless}}

Helpers Utility : Outils Pratiques pour le Templating

Aperçu

1. {{asset}}

2. {{block}}

3. {{body_class}}

4. {{concat}}

5. {{encode}}

6. {{ghost_head}} et {{ghost_foot}}

7. {{link_class}}

8. {{log}}

9. {{pagination}}

10. {{> partials}}

11. {{plural}}

12. {{post_class}}

13. {{prev_post}} et {{next_post}}

14. {{reading_time}}

15. {{search}}

16. {{#split}}

17. {{t}} (translate)

Conclusion : Maîtrisez les Helpers pour des Thèmes Efficaces

You may be interested

Admin API Ghost Détail

Tutoriels Ghost

1. `{{authors}}`

2. `{{comments}}`

3. `{{@config}}`

4. `{{content}}`

5. `{{@custom}}`

6. `{{date}}`

7. `{{excerpt}}`

8. `{{img_url}}`

9. `{{link}}`

10. `{{navigation}}`

11. `{{@page}}`

12. `{{price}}`

13. `{{readable_url}}`

14. `{{recommendations}}`

15. `{{@site}}`

16. `{{social_url}}`

17. `{{tags}}`

18. `{{tiers}}`

19. `{{title}}`

20. `{{total_members}}`

21. `{{total_paid_members}}`

22. `{{url}}`

1. `{{#foreach}}`

2. `{{#get}}`

3. `{{#has}}`

4. `{{#if}}`

5. `{{#is}}`

6. `{{#match}}`

7. `{{#unless}}`

1. `{{asset}}`

2. `{{block}}`

3. `{{body_class}}`

4. `{{concat}}`

5. `{{encode}}`

6. `{{ghost_head}}` et `{{ghost_foot}}`

7. `{{link_class}}`

8. `{{log}}`

9. `{{pagination}}`

10. `{{> partials}}`

11. `{{plural}}`

12. `{{post_class}}`

13. `{{prev_post}}` et `{{next_post}}`

14. `{{reading_time}}`

15. `{{search}}`

16. `{{#split}}`

17. `{{t}}` (translate)