Written and maintained by CASRAI Editorial Board
Last updated
Every reference manager that is not EndNote — Zotero, Mendeley, Pandoc, Quarto and most of the rest — formats citations using the Citation Style Language, an XML format with thousands of published styles. Occasionally the journal you are submitting to has none of them, or has one that is subtly wrong.
You do not write a CSL style from scratch. You find the closest one and change what differs, which is a much smaller job than it looks.
First: is the style really missing?
The Zotero Style Repository holds CSL 1.0.2 styles, and it is larger than most people expect — many journals are covered under a parent style rather than their own name. Before building anything, use the repository’s previews to check whether an existing style already produces the output you need.
This matters because of how CSL organises styles:
- An independent style contains the actual formatting instructions for citations, notes and bibliographies, and relies on locale files for language-specific data.
- A dependent style is an alias. Its contents are limited to style metadata — it carries no formatting instructions of its own and points at an independent style instead.
That design exists precisely for your situation. Journals sharing a house style do not each duplicate the formatting rules; they get a dependent style pointing at one independent style. So if your journal formats identically to another that already has a style, the correct answer is a dependent style — a few lines of metadata — not a new independent one. Writing a full independent style when a dependent one would do is the most common wasted effort here.
Start from the closest existing style
When you do need formatting changes, the recommended route is to begin from the most recent version of the nearest style in the repository rather than an empty file. The visual editor’s “search by example” function is the intended way to find that nearest style: you give it the output you want and it finds styles that produce something close.
This is worth doing carefully. The difference between “closest style plus four edits” and “closest style plus forty edits” is entirely down to which base you picked, and picking well takes minutes.
The two editors
The CSL editor offers two views of the same style, and they suit different jobs.
- The visual editor shows a live preview that updates as you edit — the right choice for adjusting what a style does without learning the schema.
- The code editor gives direct access to the XML, also with live preview — necessary when the change is structural rather than cosmetic.
Work with the preview visible. CSL has non-obvious interactions between macros, conditionals and sort order, and a change that looks right in the XML can produce something unexpected in the rendered citation. The preview is the fastest way to notice.
Validate before you use it
A style that loads is not necessarily a valid style. Two official tools exist for this: the CSL Style Formatter, which normalises formatting, and the CSL Style and Locale Validator, which checks conformance to the CSL schema.
CSL is defined with a RELAX NG Compact schema, so any XML tool that supports RELAX NG Compact can validate a style locally. Documented options include Atom with the atomic-csl plugin, Emacs with nXML, jEdit with the XML add-on, and the command-line validators Jing and RNV.
Validation catches the failure mode that wastes the most time: a style that works for the three references you tested and breaks on a fourth reference type you did not. The schema check finds structural problems the preview never exercises.
A practical order of work
- Check the repository first, using previews, for a style that already matches.
- If a match exists but under another name, make a dependent style pointing at it. You are done.
- Otherwise find the nearest independent style with search-by-example and start from its current version.
- Edit with the preview open, visual editor for behaviour, code editor for structure.
- Test against every reference type you will actually cite — journal article, book, chapter, dataset, preprint, web page. Styles usually break on the types nobody tested.
- Validate with the official validator or a local RELAX NG tool.
- Update the style metadata so the title and identifiers reflect what it is, particularly if it will be shared.
Related
If your problem is a specific citation rather than the whole style — a page locator, a prefix, suppressing an author — that is handled per-citation, not by editing CSL; see Zotero citation customization. In a Markdown-based workflow, the CSL file is supplied to the processor directly, covered in citations in Quarto, R Markdown and Pandoc. For manuscript work in Word, see reference managers that work inside Word.
Frequently asked questions
Do I have to write a style from scratch?
No, and you should not. Start from the most recent version of the closest style in the repository and edit it. Search-by-example in the visual editor exists to find that starting point.
What is the difference between a dependent and an independent style?
An independent style holds the formatting instructions. A dependent style holds only metadata and points at an independent style. Journals sharing a house style use dependent styles so the rules are not duplicated.
Can I edit CSL without learning XML?
Largely, yes. The visual editor with live preview handles most behavioural changes. The code editor is there for structural edits where the XML has to be touched directly.
How do I check my style is valid?
Use the CSL Style and Locale Validator, or validate locally with any RELAX NG Compact-capable tool — Jing and RNV on the command line, or editor plugins for Atom, Emacs and jEdit.
Why does my style work for articles but break on books?
Because it was only ever tested on articles. CSL styles branch by reference type, and an untested branch is an untested code path. Cite one of every type you will use before trusting it.
Which CSL version should I target?
The Zotero Style Repository distributes CSL 1.0.2 styles for CSL 1.0.2-compatible software, so match what the repository is serving rather than an older specification you may find referenced elsewhere.
References
- Editing CSL styles — step-by-step guide — Zotero documentation
- CSL 1.0.2 specification — docs.citationstyles.org
- Style development guide — citation-style-language/styles
- Zotero Style Repository — zotero.org/styles
