Bonnes pratiques pour la création d’un style CSL
Billet rédigé par ✏️ Frédérique Flamerie et ✏️ Laure Mellifluo

Malgré la disponibilité de plus de 10’000 styles sur le dépôt officiel de Zotero, il se peut que l’on ne trouve pas exactement LE style qui réponde à 100% à nos besoins. Pour cette raison, plusieurs billets de ce blog ont déjà fourni des pistes pratiques pour adapter des styles existants (notamment en 2022 et en 2019). L’objectif de ce billet est de fournir des conseils pratiques et méthodologiques d’ordre général à celles et ceux qui souhaiteraient se lancer dans l’adaptation, voire dans la création d’un style CSL. De retouche en adaptation mineure, on arrive de fait finalement souvent à la création d’un nouveau style.
Avez-vous la certitude d’avoir besoin d’un style sur mesure pour votre projet ? Ne pouvez-vous pas vous accommoder d’un style déjà existant ? Disposez-vous du temps et des compétences nécessaires pour vous lancer dans l’édition CSL ? Ou alors, avez-vous reçu un mandat pour la création d’un style personnalisé ? Si tel est le cas, ce billet vous donnera les bases pour produire un style avec rigueur et efficacité.
Sommaire
- Délimiter le projet
- Choisir le “bon” style de départ
- Du code aussi propre que possible
- Valider et diffuser son style
Délimiter le projet
La démarche de création d’un nouveau style peut s’envisager de différentes manières, qu’il s’agisse de répondre à un besoin individuel et limité ou à un besoin collectif plus ou moins étendu (département d’école ou d’université, revue, etc.), qu’il s’agisse d’effectuer la création pour ses besoins propres ou en réponse à la demande d’un commanditaire.
Dans tous les cas, il convient de ne pas négliger le travail préparatoire et de cerner précisément les résultats attendus. L’objectif est d’aboutir à un cahier des charges clair et définitif, idéalement constitué de tous les éléments suivants :
- une base bibliographique test rassemblant tous les types de document à prendre en charge, avec le plus détails ou de variantes possibles dans les informations bibliographiques pour chaque type de document,
- un exemple du résultat à produire incluant les citations et la bibliographie,
- des consignes explicites décrivant les règles de mise en forme appliquées pour produire ce résultat,
- un récapitulatif des livrables à produire : seulement un fichier de style, et/ou une documentation, et/ou une version accessible en ligne des consignes bibliographiques dont le style est la traduction CSL si le style a vocation à rejoindre le dépôt officiel des styles.
Tous ces éléments peuvent sembler excessifs dans le cas d’un style personnalisé individuel que vous souhaitez créer pour vos besoins propres, néanmoins ils vous permettront, même allégés, de ne négliger aucun point et de valider votre démarche. Au fil de ces différentes étapes, peut-être vous rendrez-vous compte qu’un style existant peut finalement convenir, moyennant éventuellement des adaptations minimes de vos attentes. Ces éléments nous semblent indispensables dans le cas de la création d’un style visant à répondre à un besoin collectif comme dans celui de la réponse à la demande d’un commanditaire : ces deux situations impliquent différentes parties prenantes, et ces éléments permettent de structurer et d’organiser le travail et les échanges. S’il s’agit de répondre à la demande d’un commanditaire individuel, ils pourront être allégés. Toutefois, fixer dès le départ le cadre de travail évitera toute dérive : de petite retouche en ajout mineur, on n’en finit pas parfois de modifier le code pour qu’il réponde à de nouvelles demandes sans cesse renouvelées. Or certains paramétrages, pensés dès le départ, auraient conduit à des choix différents de ceux effectués au fur et à mesure sans vision d’ensemble. Penser globalement le codage d’un style dès le départ se révèle beaucoup plus efficace que de revenir sans cesse sur le travail effectué.
La première étape du cahier des charges consiste tout d’abord à constituer une base bibliographique test, sous la forme d’une bibliothèque de groupe Zotero (exemple pour le style de l’école doctorale de droit de l’université de Bordeaux) ou simplement d’une collection dans votre bibliothèque Zotero personnelle. Cela présente un double intérêt méthodologique et pratique. Du point de vue méthodologique, c’est un moyen simple et concret de vous assurer de ne négliger aucun des types de documents que votre style doit prendre en charge : prenez le temps de considérer la diversité des documents qui pourront être cités par les utilisateurs et les utilisatrices. Prenez également le temps de rassembler des exemples suffisamment divers et de vous assurer que vous saisissez correctement et de façon exhaustive les références dans votre bibliothèque. Si vous n’avez encore jamais consulté la page “Les types de documents et les champs associés dans Zotero” de la documentation Zotero, c’est le moment de le faire. D’un point de vue pratique, cette bibliothèque d’exemples vous fournira une base pour tester votre code au fur et à mesure. Si vous répondez à la demande d’un commanditaire, valider ensemble cette bibliothèque, même modeste, permettra aussi de s’assurer du bon usage du logiciel. À ce stade, il peut être profitable d’effectuer de nouveaux tests de mise en forme dans l’Aperçu des styles de Zotero avec des styles existants que vous auriez repérés : peut-être vous rendrez-vous compte que les changements nécessaires devaient être apportés aux données bibliographiques et non au style.
Une fois rassemblés les différents types de documents à prendre en charge par votre style, la deuxième étape consiste à produire un exemple du résultat souhaité, incluant à la fois les citations et la bibliographie. Dans les faits, vous disposez probablement déjà de cet exemple, et c’est même de lui qu’est parti votre souhait de créer un nouveau style. Il s’agit toutefois ici de l’étoffer, en prévoyant différents cas de figure : par exemple des livres avec et sans auteur, des articles avec deux ou plusieurs auteurs, etc. Établir cet exemple de rendu à partir de la bibliothèque test constituée à l’étape précédente vous permettra de vous assurer au fur et à mesure de l’atteinte de votre objectif. Dans l’idéal, doubler ces exemples de modèles génériques facilite la compréhension du style.

La nécessité de la troisième étape, celle de l’explicitation des consignes de mise en forme, apparaît plus nettement une fois que l’on a essayé de rassembler les différents types de documents et que l’on a produit un exemple du rendu souhaité. À nouveau, les enjeux sont à la fois méthodologiques et pratiques. Expliciter au moins les principales règles de mise en forme (nombre d’auteurs à remplacer par “et al.”, abréviations à utiliser, etc.) permet de prévoir tous les cas, y compris ceux pour lesquels on ne dispose pas d’exemples. Cela évite également de reproduire dans le codage du style des paramétrages qui seraient en fait des erreurs dans les exemples, tel que l’oubli de l’italique. Enfin, déduire des règles générales d’exemples particuliers est à la fois plus fastidieux et moins univoque que d’appliquer des consignes rédigées : ce travail préparatoire constitue un investissement en vue de la phase de codage du style. Si elle peut être omise ou allégée dans le cas d’un style personnel, cette étape s’avère incontournable dans le cas d’un style collectif. Répondre aux questions de paramétrage du style aboutit parfois à réviser les consignes bibliographiques, pour un bénéfice général, car il s’agit alors de simplifier et de clarifier. Ce processus a ainsi conduit à une deuxième édition du guide “Citer des références bibliographiques juridiques”, duquel le style “Université de Bordeaux – École doctorale de droit (Français)” est la traduction en langage CSL.
Enfin, délimiter le projet implique de prévoir dès le départ tous les livrables à fournir. Outre le fichier de style CSL, une documentation pour les utilisateurs et utilisatrices peut être bienvenue pour les styles destinés à un usage collectif (exemples à l’université de Bordeaux, à l’université de Lausanne, à SciencesPo), notamment s’ils requièrent des spécificités de saisie pour certaines informations bibliographiques ou certains types de documents. Un autre livrable doit être anticipé s’il n’existe pas déjà, à savoir une version en ligne des consignes bibliographiques dont le style CSL est la traduction. Si vous envisagez de diffuser le style via le dépôt officiel des styles Zotero, ce livrable est en effet obligatoire. L’anticiper dès cette phase préparatoire permet aussi d’anticiper les questions liées à la diffusion du style.
Choisir le “bon” style de départ
La création d’un nouveau style à partir d’un fichier vierge devrait constituer une exception. À moins de disposer d’une solide expertise en langage CSL, il est plus efficace de partir d’un style existant pour l’adapter. Cependant, tous les styles présents dans le dépôt officiel de Zotero ne sont pas de qualité égale. Quitte à personnaliser un style, il faut donc s’assurer de partir d’une base robuste, sans quoi le travail de personnalisation risque de s’ajouter à celui, fastidieux, de correction des erreurs de conception de base de ce style d’origine. Voici donc quelques conseils pratiques pour choisir un style de départ correct.
- Le style choisi doit être répertorié dans le dépôt des styles, ce qui assure un certain niveau de qualité et de validation formelle (voir ci-dessous).
- Dans l’idéal, le style devrait être du même format général que le style souhaité (auteur-date, numérique ou note). Cela limitera les modifications en profondeur de la structure du style. Notez que ce conseil s’applique plus particulièrement pour les styles avec notes de bas de page ou de fin, qui impliquent un paramétrage poussé des citations. Il est plus aisé de passer d’un format auteur-date à numérique ou inversement, à plus forte raison si la seule modification souhaitée est le changement du système de référencement dans le texte.
- À choisir, mieux vaut sélectionner un style dans lequel l’ordre des informations dans la bibliographie (auteur, date, titre, lieu de publication, etc.) vous convient déjà. Il est en effet plus difficile de réordonner les informations bibliographiques que de revenir sur leur mise en forme ou leur contenu détaillé.
Il convient également de procéder à différentes vérifications formelles dans le fichier du style que l’on souhaite utiliser.
- Le style ne doit pas juste être un dérivé d’un style parent. De nombreux styles CSL sont créés avec un nom propre, mais on remarque dans leur source que le code proposé est très court. Ces styles dérivés, à éviter pour l’adaptation, peuvent être repérés par un lien avec l’attribut
rel="independent-parent"
en début de fichier. Cocher la case “Show only unique styles” dans le dépôt des styles permet de les masquer de la recherche.

- Si l’on doit traiter des types de documents particuliers, il faudrait vérifier si des particularités liées à ces types de documents sont prévues. Ce test peut être effectué de différentes manières complémentaires : en testant, à partir de sa base créée pour l’occasion, le rendu de différents types de documents tout comme procéderait toute personne utilisatrice de Zotero, ou alors, directement dans le code CSL, en cherchant dans les macros d’éventuelles exceptions par type de document. Celles-ci sont repérables par le code
<if type="...">
. Les types de document pris en charge sont décrits dans la documentation CSL et leurs correspondances avec Zotero dans la page “Zotero to CSL Mappings”. - Globalement, un fichier CSL devrait comporter beaucoup d’éléments
macro
en début de fichier, car ces éléments sont réutilisables. Le code contenu dans les sectionscitation
etbibliography
devrait quant à lui est relativement concis, comme dans l’exemple ci-dessous tiré du style Chicago Manual of Style 17th edition (author-date).

- Toujours dans le code, il vaut la peine également de vérifier que les
prefix
etsuffix
sont utilisés avec parcimonie. De manière générale, ceux-ci ne devraient pas être utilisés systématiquement pour gérer la ponctuation entre les éléments d’une références. Un code bien écrit utilise si possible desgroup
avec des attributsdelimiter
pour séparer les différents éléments.
Ces deux derniers points de vérification correspondent d’ailleurs aux deux premières bonnes pratiques d’écriture CSL pointées par Sebastian Karcher dans son billet Writing CSL – Features and Best Practices.
Bonne pratique 1 : Préférez les groupes et les séparateurs de groupe aux affixes pour la ponctuation et les espaces entre les objets.
Bonne pratique 2 : Utilisez abondamment les macros. Gardez les élémentscitation
etbibliography
brefs et ne leur intégrez qu’au minimum des élémentschoose
.
[Traduction libre]
Dans le doute sur la qualité d’un style source, mieux vaut partir de grands standards comme ceux installés par défaut dans Zotero pour éviter les mauvaises surprises.
Du code aussi propre que possible
Une fois que vous avez identifié le style à partir duquel créer le vôtre, la phase de codage du style peut débuter. Nous renvoyons pour les aspects techniques à nos billets précédemment cités, notamment Apporter de petites modifications à un style bibliographique pour distinguer votre style de celui dont vous le dérivez. S’agissant du choix de l’outil d’édition, rappelons que l’éditeur CSL intégré à Zotero dispose désormais de la coloration syntaxique.
Votre cahier des charges décrit bien les multiples modifications à apporter, mais par où commencer? Comme nous l’avons souligné pour le choix du style, l’un des aspects les plus déterminants et les plus complexes à modifier est la structure générale, c’est-à-dire l’ordre des informations bibliographiques, leur logique d’affichage et leur organisation. Il est donc recommandé de commencer par la mise en place de cette structure générale, et de réserver à la fin du travail de codage les aspects de mise en forme de type gras, italique, etc.
Pour progresser sûrement dans votre démarche, on ne peut que conseiller d’effectuer des vérifications sur l’ensemble de la base bibliographique test après chaque modification. L’éditeur de style intégré à Zotero permet d’y procéder facilement. Au fur et à mesure de votre avancée, peut-être sentirez-vous la nécessité de procéder à ces vérifications uniquement pour valider les modifications les plus significatives. Produire des versions intermédiaires de votre style (par ex. v01, v02, etc.), au moins à chaque nouvelle étape majeure franchie, pourra vous aider dans cette démarche. Pour cela, n’oubliez pas de renommer le nom du fichier lui-même ainsi que le titre et l’identifiant du style (éléments title
et id
).
Il convient bien sûr d’appliquer vous-même en codant le style les principes qui ont présidé au choix du bon style de départ. Nous ajoutons à ces bonnes pratiques les quatre points suivants.
Revenons tout d’abord sur les macros. Il convient de résister à la facilité qui consiste à créer des macros trop génériques : par exemple une macro “publication” pour à la fois la date, le lieu de publication, la maison d’édition. Si cette option est plus rapide dans l’immédiat que de créer trois macros distinctes, elle peut se révéler un très mauvais calcul à terme. S’il s’avère que l’un de ces trois éléments doive être traité différemment pour un type de document, ou qu’une autre évolution de ce type survienne, le travail de mise à jour du style sera plus complexe, et vous devrez probablement distinguer les éléments que vous aviez rassemblés dans la même macro. Cela rend également le style moins facilement réutilisable, y compris par vous-même. Si le projet de création de style répond à la demande d’un commanditaire et que vous êtes susceptible de recevoir d’autres demandes de ce type, il peut être rentable d’investir du temps pour créer un style aussi modulaire possible, dont vous pourrez par la suite réutiliser facilement le code pour d’autres demandes. Dans cette même perspective, constituer votre bibliothèque personnelle de styles de référence, c’est-à-dire de styles bien écrits et avec lesquels vous avez acquis de la familiarité, vous fera gagner du temps lors de projets ultérieurs.
Le deuxième point concerne les adaptations parfois nécessaires pour afficher toutes les informations bibliographiques souhaitées, y compris si ces dernières ne sont pas prises en charge par Zotero. On pourrait ainsi par exemple vouloir préciser un financement, pour lequel il n’existe pas de champ dédié dans Zotero ni de variable CSL. La seule option possible revient à détourner un champ de sa vocation initiale pour la saisie de cette information. On pourrait penser à utiliser le champ “Cote” pour le financement, s’il n’est pas nécessaire bien sûr de référencer la cote. Il convient toutefois de limiter le plus possible cette pratique et de s’efforcer de conserver une certaine cohérence. Cette cohérence est aussi le gage d’une bonne compréhension, et partant d’un bon usage, du style. Un second exemple illustre plus particulièrement ce point. Pour le style de l’école doctorale de droit de l’université de Bordeaux, il était nécessaire de référencer les préfaciers de livre et les directeurs de thèse, qui, comme le financement, ne sont pris en charge ni par Zotero ni par CSL. On a tout d’abord dû opter pour un rôle d’auteur pris en charge indirectement par Zotero, ce qui imposait une saisie complexe dans le champ Extra. L’évolution de CSL a permis une simplification pour les directeurs de thèse, qui sont désormais saisis dans le champ “Collaborateur” de Zotero, auquel correspond la variable “contributor” de CSL. Il aurait en revanche été risqué d’opter pour le même choix pour les préfaciers. Non seulement il peut y avoir de multiples collaborateurs autres que les préfaciers pour les livres, mais de plus cela aurait contraint les utilisateurs et les utilisatrices à un fastidieux travail de nettoyage de leurs références de livres, d’autant moins justifié que le cas des livres avec préfaciers demeure peu fréquent.
Les deux derniers points visent tant la propreté du code que son caractère réutilisable. Il s’agit tout d’abord de respecter au mieux le vocabulaire CSL, en recourant au maximum aux termes prédéfinis encodés dans les fichiers de configuration locale de CSL et traduits dans toutes les langues (voir par exemple le fichier des traductions en français norme de la France). Ces termes correspondent à des mots ou expressions courants de la rédaction bibliographique et à cet égard codifiés, tels que les intitulés de fonction, les mentions “sans date”, “sans lieu”, etc. Cela constitue la dernière bonne pratique énoncée par Sebastian Karcher dans le billet précédemment cité.
Bonne pratique 3 : Utilisez des terms et des labels. N’ajoutez pas de termes ou d’expressions dans des affixes ou en utilisant text value=
. [Traduction libre]

Notez qu’il est possible de personnaliser ces traductions dans le code de votre style.
Enfin, commenter votre code, au moins pour en décrire chacune des grandes sections ou chacune des macros, facilite sa compréhension et sa réutilisation, à nouveau y compris par vous-même.


Valider et diffuser son style
Pour terminer, il convient de procéder à une validation du style grâce aux outils proposés. Cela peut être fait facilement grâce au service en ligne CSL Style and Locale Validator. Il est important de ne plus avoir de message d’erreur à ce stade. Une fois son fichier validé, il est recommandé d’utiliser le CSL Style Formatter qui corrigera la mise en forme du code. Une fois ces deux étapes passées, votre style est considéré comme terminé et prêt à être utilisé et partagé. Le fichier CSL peut être mis à disposition via n’importe quel site web (journal, éditeur, institution, etc.).
Cependant, il est utile de se demander quelle est l’audience potentielle de son style. Si celle-ci est suffisamment large, il est envisageable de soumettre le nouveau style dans le dépôt officiel. Ainsi, on pourra facilement le trouver et le télécharger, et en recevoir les mises à jour automatiquement. Pour être versé dans le dépôt officiel, un style doit reposer sur une documentation publiée et accessible (par exemple un guide de citation sur le site web d’une association ou d’une institution). Si vous décidez de soumettre votre style, la qualité en sera également examinée (selon la procédure décrite ici), mais ce contrôle devrait être une formalité si vous avez suivi toutes les recommandations de ce billet. De plus, les éventuels retours experts que vous obtiendrez sur votre soumission seront une occasion supplémentaire de parfaire votre pratique d’édition CSL.
En conclusion, l’une des clés de la réussite de la création d’un style nous semble être la préparation : outre le fait qu’elle facilite et fluidifie la phase de codage du style, elle peut même dans certains cas vous en dispenser s’il s’avère finalement qu’un style existant peut convenir. Une autre clé de réussite, notamment dans le cas d’un projet collectif, peut être la qualité de la documentation fournie (historique du projet, personnes-contact, intentions, choix à faire et décisions prises, détails techniques, etc.).
Nous avons donné quelques exemples de style dans ce billet, n’hésitez pas à partager en commentaire vos exemples de réalisation.
OpenEdition vous propose de citer ce billet de la manière suivante :
Collectif (21 mars 2025). Bonnes pratiques pour la création d’un style CSL. Le blog Zotero francophone. Consulté le 15 mai 2025 à l’adresse https://doi.org/10.58079/13jfp