Custom Settings & Partials Ghost 2026 : Options dans l’Admin et Code Réutilisable

Les thèmes Ghost permettent une personnalisation poussée sans toucher au code source. Les custom settings et les partials sont deux outils essentiels pour cela. Les custom settings ajoutent des options directement dans l'interface d'administration Ghost, accessibles via Design & branding > Thème. Cela permet aux utilisateurs, comme les propriétaires de petites entreprises ou de startups, de modifier des éléments visuels sans éditer de fichiers. Les partials, quant à eux, sont des morceaux de code Handlebars réutilisables, stockés dans un dossier dédié, pour éviter les duplications et simplifier la maintenance.

Dans cet article, nous couvrons les bases pour débutants, avec des exemples concrets basés sur la documentation officielle Ghost. Nous intégrons aussi des tutoriels pratiques pour des fonctionnalités courantes comme les bannières d'offres, le temps de lecture ou les icônes sociales. Tout est adapté à Ghost 5.x et plus récent, sans changements majeurs notés en 2025.

Qu'est-ce que les Custom Settings ?

Les custom settings sont des métadonnées définies dans le fichier package.json de votre thème, sous la clé config.custom. Une fois le thème installé, Ghost les rend disponibles dans l'admin, sous forme de champs interactifs : sélecteurs, cases à cocher, sélecteurs de couleurs, etc.

Avantages pour un public débutant ou SMB :

• Pas besoin d'éditer le code pour changer des couleurs ou du texte.
• Organisation claire : les settings sont groupés en Site-wide, Homepage ou Post.
• Limite à 20 settings par thème, ce qui encourage des choix ciblés (ex. : couleurs, typographie, images CTA).

Règles de nommage :

• Utilisez du snake_case (ex. : button_color).
• Tout en minuscules, sans caractères spéciaux.
• Changer un nom entre versions efface les valeurs existantes – attention lors des mises à jour.

Comment Ajouter des Custom Settings dans package.json

Ouvrez package.json et ajoutez un objet sous config.custom. Chaque setting est un objet avec au minimum une clé type.

Exemple basique :

{
  "config": {
    "custom": {
      "button_color": {
        "type": "color",
        "default": "#15171A"
      }
    }
  }
}

Après sauvegarde et upload du thème, ce setting apparaît dans l'admin comme un sélecteur de couleur.

Groupes optionnels :

• Ajoutez "group": "homepage" pour des options spécifiques à la page d'accueil.
• "group": "post" pour les articles.

Descriptions :

• Ajoutez "description": "Choisissez la couleur des boutons CTA" (max 100 caractères) pour guider l'utilisateur.

Types de Settings et Exemples

Ghost supporte cinq types principaux. Voici un tableau récapitulatif avec code et utilisation en template.

Validation : Ghost vérifie les settings lors de l'upload. Par exemple, pour select, le default doit être dans options, sinon le thème est rejeté.

Visibilité conditionnelle : Utilisez "visibility": "autre_setting:[valeur1, valeur2]" pour masquer un setting en fonction d'un autre.
Exemple :

{
  "header_style": {
    "type": "select",
    "options": ["Simple", "Image"],
    "default": "Simple"
  },
  "background_image": {
    "type": "image",
    "visibility": "header_style:Image"
  }
}

Si header_style n'est pas "Image", @custom.background_image vaut null.

Utiliser les Custom Settings dans les Templates

Accédez aux settings via @custom.nom_du_setting. Utilisez toujours des conditionnels pour éviter les erreurs si vide.

Exemple complet dans default.hbs :

<body class="{{body_class}} {{#match @custom.theme_mode "dark"}}dark{{/match}}">
  {{#if @custom.hero_image}}
    <header style="background-image: url({{img_url @custom.hero_image size='medium'}});">
      <h1>{{@site.title}}</h1>
    </header>
  {{else}}
    <header><h1>{{@site.title}}</h1></header>
  {{/if}}
</body>

Astuce pour débutants : Ne hardcodez pas de valeurs par défaut en template – définissez-les dans package.json. Utilisez {{#if}} pour la dégradation gracieuse.

Qu'est-ce que les Partials ?

Les partials sont des fichiers .hbs dans le dossier partials/ de votre thème. Ils contiennent du code réutilisable, inclus via {{> "nom-du-partial"}}. Idéal pour les éléments répétitifs comme un header, un footer ou une carte d'article.

Pourquoi les utiliser ?

• Évite la duplication de code.
• Facilite les mises à jour : changez un partial, et tout le site est impacté.
• Structure modulaire : divisez les templates complexes en petits morceaux.

Structure du dossier :

mon-theme/
├── partials/
│   ├── header.hbs
│   ├── post-card.hbs
│   └── icons/
│       └── social.hbs
└── default.hbs

Inclure un partial : {{> "header"}} ou {{> "icons/social"}} pour les sous-dossiers.

Créer et Utiliser des Partials : Guide Pratique

Étape 1 : Créer un partial simple.
Dans partials/post-card.hbs :

<article class="post-card {{classes}}">
  {{#if feature_image}}
    <img src="{{img_url feature_image size='medium'}}" alt="{{title}}">
  {{/if}}
  <h2>{{title}}</h2>
  <p>{{excerpt words="20"}}</p>
</article>

Étape 2 : L'inclure avec props.
Dans index.hbs :

{{#foreach posts}}
  {{> "post-card" classes="featured"}}
{{/foreach}}

Ici, classes est passé comme prop et accessible dans le partial via {{classes}}.

Étape 3 : Passer du contexte.
Pour des données dynamiques, passez des variables :

{{> "post-card" post=@root post_class="large"}}

Dans le partial : {{post.title}} ou {{post_class}}.

Meilleures pratiques :

• Noms descriptifs (ex. : author-bio.hbs).
• Un partial = une responsabilité (ex. : un pour l'image, un pour le meta).
• Organisez en sous-dossiers pour les icônes ou layouts.
• Utilisez l'extension VS Code Ghost pour l'autocomplétion.

Intégrer Custom Settings et Partials

Combinez-les pour une personnalisation avancée. Exemple : un partial header qui utilise un setting pour l'image de fond.

Dans package.json :

{
  "config": {
    "custom": {
      "header_bg": {
        "type": "image",
        "group": "homepage"
      }
    }
  }
}

Dans partials/header.hbs :

<header style="background-image: url({{img_url @custom.header_bg size='full'}});">
  <h1>{{@site.title}}</h1>
</header>

Inclure dans default.hbs : {{> "header"}}.

Tutoriels Pratiques : Appliquez Immédiatement

1. Ajouter des Icônes Sociales avec Partials

Utilisez Font Awesome pour les icônes. Ajoutez ce code dans Code Injection > Site Header :

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/brands.min.css" integrity="sha512-+oRH6u1nDGSm3hH8poU85YFIVTdSnS2f+texdPGrURaJh8hzmhMiZrQth6l56P4ZQmxeZzd2DqVEMqQoJ8J89A==" crossorigin="anonymous" referrerpolicy="no-referrer" />
<style>
  :where(.nav, .gh-head-menu) .nav-x a::before { content: "\e61b"; font-family: "Font Awesome 6 Brands"; font-size: 20px; }
  /* Ajoutez pour d'autres : LinkedIn "\f08c", YouTube "\f167" */
</style>

Créez partials/social-icons.hbs :

<ul class="social-list">
  {{#get "posts" limit="1"}}
    {{#if @site.twitter}}
      <li class="nav-twitter"><a href="{{@site.twitter}}"></a></li>
    {{/if}}
  {{/get}}
</ul>

Ajoutez des liens dans Settings > Navigation (ex. : label "X", URL votre compte). Incluez {{> "social-icons"}} dans le footer.

Pour startups : Personnalisez les URLs via custom text settings pour flexibilité.

2. Ajouter le Temps de Lecture

Ghost a un helper natif {{reading_time}}. Dans post.hbs :

{{#post}}
  <p class="reading-time">{{reading_time minute="Moins d'une minute" minutes="% minutes de lecture"}}</p>
  {{content}}
{{/post}}

Le calcul inclut les images pour plus de précision. Ajoutez une barre de progression :

• HTML dans post.hbs : <progress class="reading-progress" value="0" max="100"></progress>
• CSS via Code Injection :

.reading-progress { position: fixed; top: 0; width: 100%; height: 5px; background: #c5d2d9; }
.reading-progress::-webkit-progress-value { background: var(--ghost-accent-color); }

• JS dans default.hbs (avant {{{ghost_foot}}}) :

{{#is "post"}}
<script>
  const progressBar = document.querySelector('.reading-progress');
  function updateProgress() {
    const total = document.body.clientHeight;
    const windowH = document.documentElement.clientHeight;
    const pos = window.scrollY;
    const prog = pos / (total - windowH) * 100;
    progressBar.value = prog;
    requestAnimationFrame(updateProgress);
  }
  requestAnimationFrame(updateProgress);
</script>
{{/is}}

Idéal pour les blogs de startups : retient les lecteurs plus longtemps.

3. Créer des Bannières d'Offres

Les bannières promeuvent des offres Stripe. Prérequis : Connectez Stripe dans l'admin.

Dans default.hbs (après <body>) :

<a class="gh-banner" href="https://votre-site.com/offer-url/" style="background-image: url({{asset 'images/banner-bg.jpg'}})">
  <div class="gh-banner-inner">
    <div class="gh-banner-left">
      <p class="gh-banner-headline">Soutenez les médias indépendants</p>
      <p class="gh-banner-cta">Offre limitée pour nouveaux abonnés</p>
    </div>
    <div class="gh-banner-right">
      <p class="gh-banner-button">En savoir plus</p>
    </div>
  </div>
</a>

Ajoutez l'image dans assets/images/. Personnalisez via CSS en Code Injection :

.gh-banner { background: #eeeff1; color: #000; }
.gh-banner-button { background: #000; }
@media (max-width: 768px) { .gh-banner::after { content: ''; position: absolute; top: 0; right: 0; bottom: 0; left: 0; background: rgba(0,0,0,0.5); } }

La bannière se cache si le header est ouvert. Alternative native : L'annonce bar de Ghost.

Pour SMB : Liez à des offres pour booster les inscriptions.

Bonnes Pratiques et Limites

• Limites : 20 settings max. Focalisez sur le visuel (pas de layouts complexes).
• Évitez : Demander du HTML/JS en text settings ; préférez des IDs (ex. : Google Analytics).
• Maintenance : Testez avec GScan avant upload. Utilisez {{else}} pour les fallbacks.
• Pour startups : Ces outils rendent votre thème flexible, sans besoin de dev constant.

En appliquant ces étapes, votre thème Ghost devient adaptable en quelques clics. Pour plus, consultez la doc officielle.