CSL relies on volunteers to develop, edit, and maintain its library of citation styles. Below are guidelines and tips for editing and developing CSL styles.
To edit styles, you can use the Visual CSL Editor, developed in a cooperation between Mendeley and Columbia University Library. See the CSL Visual Editor user guide. If you have questions about editing styles with the CSL Visual Editor, you can still ask for help on the Zotero forums or on the CSL Discourse page. Please only use the Issues page of this repository to report bugs, not to ask general style editing questions.
You can also edit CSL styles manually. Zotero includes a built-in CSL Style Editor that allows you to see how your edits change style output in real time.
You can also edit CSL styles in any plain text editor (e.g. Notepad on Windows or TextEdit on macOS). Note that text editors with XML support can be very useful by offering features like syntax highlighting and real-time validation. Popular choices are Atom Editor, VS Code, the oXygen XML Editor, Emacs in nXML mode, and jEdit.
Currently, most documentation for editing CSL styles can be found at:
If you want to improve an existing CSL style, make sure that you start from the most recent version.
The most recent version of each CSL style can be found in the master branch of this repository.
If you want to create a new style, find an existing style that closely matches what you need using the previews in the style repository. Typically the best way to find a most similar style is the "search by example" function of the CSL Visual Editor.
Download the style you want to edit to your computer, and open it your plain text editor.
Make any edits and save your style.
Be sure that the new file has a .csl file extension (you can generally do this by simply typing ”.csl” after the name of your file).
If you are using the Zotero CSL Editor, be sure to save your edits often using the "Save" button to avoid losing your changes.
Refer to the CSL specification for information on the various options available in CSL styles. Below, we discuss a few common style edits to get you started.
In this example, we want to display the publisher ("CSHL Press") and the location of the publisher ("Cold Spring Harbor, NY") in a bibliographic entry. While this can be achieved with the code:
<text variable="publisher"/>
<text variable="publisher-place"/>this would result in "CSHL PressCold Spring Harbor, NY".
Fortunately, we can add some punctuation with the prefix, suffix, and delimiter attributes.
Let's say we want to separate the publisher and publisher-place by a comma-space, and wrap the whole in parentheses, i.e. "(CSHL Press, Cold Spring Harbor, NY)".
This can be done with:
<group delimiter=", " prefix="(" suffix=")">
<text variable="publisher"/>
<text variable="publisher-place"/>
</group>The advantage of use a group element is that whenever you have a publisher, but no publisher-place, you don't end up with incorrect punctuation: the output would become "(CSHL Press)".
If you would set the punctuation directly onto the text elements, e.g.:
<text variable="publisher" prefix="("/>
<text variable="publisher-place" prefix=", " suffix=")"/>you would lose the closing bracket, i.e. "(CSHL Press".
There are two main settings for et-al abbreviation (e.g., rendering the names "Doe, Smith & Johnson" as "Doe et al."). The minimum number of names that activates et-al abbreviation, and the number of names shown before "et al.".
In CSL, these settings can appear on the style, citation, bibliography or names elements in the form of the et-al-min and et-al-use-first attributes (it is possible to have separate settings for items that have been cited previously by using the et-al-subsequent-min and et-al-subsequent-use-first attributes).
For example,
<citation et-al-min="3" et-al-use-first="1">
...
</citation>will result in name lists like "Doe", "Doe & Smith" and, if there are three or more names, "Doe et al.". Try changing these numbers and observe the effect.
CSL offers multiple methods to disambiguate cites or names. For example, a style might normally render only the family name (e.g., "(Doe 1999, Doe 2002)"). If the authors are Jane Doe and Thomas Doe, these names can be disambiguated by adding initials or the full given names (e.g., "(J. Doe 1999, T. Doe 2002)").
Disambiguation methods are selected on the citation element.
For example, to disable given name disambiguation, delete the disambiguate-add-givenname attribute, e.g., change:
<citation disambiguate-add-givenname="true">
...
</citation>to:
<citation>
...
</citation>By default, several authors are separated by a delimiter , and the word and.
This settings can be changed, for example to use the symbol & instead:
<names variable="author">
<name form="short" and="symbol" delimiter=", "/>
...
</names>or to not use and at all, but to use the delimiter /:
<names variable="author">
<name form="short" delimiter="/"/>
..
</names>The appearance of citations in (full) footnote styles may depend on their position in the paper. If the same source is cited twice, it may be that a shortened version is used in the second (and any further) citation. To handle this distinction, one can use conditional rendering based on the position of the citation. A generic structure could then look like:
<citation>
<layout>
<choose>
<if position="ibid-with-locator">
...
</if>
<else-if position="ibid">
...
</else-if>
<else-if position="subsequent">
...
</else-if>
<else>
...
</else>
</citation>
</layout>
</citation>If a case is missing in your style, you can add a new case and specify how information should be rendered in that case (e.g. see Chicago (full note) for an example).
You should alway begun editing from a style that uses the current version of CSL. If you are starting from an older version of CSL (e.g. CSL 0.8.1), you should first upgrading it to the current CSL version to take advantage of the newest CSL features.
CSL 0.8.1 and 1.0 styles can be easily distinguished by looking at the <style/> element at the top of the style.
CSL 1.0 styles include a version attribute on this element with a value of "1.0", e.g. <style xmlns="http://purl.org/net/xbiblio/csl" class="in-text" version="1.0">.
CSL 0.8.1 styles lack this attribute.
Important: Before installing your edited style in your reference manager or otherwise using it, you must change the style title and ID at the top of the style code. If you don't change these, your reference manager may overwrite your modified style the next time the original style is updated.
The style title and ID are stored within the <title/> and <id/> elements near the top of the style.
For example:
<title>American Psychological Association 6th edition</title>
<title-short>APA</title-short>
<id>http://www.zotero.org/styles/apa</id>can be changed to:
<title>American Psychological Association 6th edition - Modified</title>
<title-short>APA - modified</title-short>
<id>http://www.zotero.org/styles/apa-modified</id>We rely heavily on validation against the CSL schema to make sure all CSL styles and locale files are of sufficient quality. Only styles and locales that are valid XML and conform to the CSL schema can be expected to work correctly with all CSL-compatible applications.
To validate your style or locale file, please use our own CSL Validator. Styles and locales can be selected via URL, file upload, or copy and paste into a text field.
If the CSL Validator website is down or doesn't work, you can try one of the validators below.
CSL styles and locale files can also be validated at . Just paste in your style or locale and click the "Validate" button to validate against the CSL 1.0.1 schema. If there aren't any validation errors you will get the message "Validation successful.".
You can also use Validator.nu:
- Select your style or locale. You can provide an URL if your style/locale is accessible online (the "Address" option), select the file on your computer ("File Upload"), or copy and paste the complete code into the text box ("Text Field").
- (pre-selected if using the link above) Enter the URL to the CSL schema in the "Schemas" text field. For CSL 1.0.1, this is https://github.com/citation-style-language/schema/raw/v1.0.1/csl.rnc. To validate styles in the older CSL 1.0 and 0.8.1 formats, use https://github.com/citation-style-language/schema/raw/v1.0/csl.rnc or https://github.com/citation-style-language/schema/raw/v0.8.1/csl.rnc, respectively.
- (pre-selected if using the link above) In the "Parser" drop-down menu, select the "XML; don't load external entities" option. Also check the "Be lax about HTTP Content-Type" check-box.
- Click the “Validate” button. If the style/locale is valid, you will get the message “The document validates according to the specified schema(s) and to additional constraints checked by the validator.”, or, if the style/locale is invalid, "There were errors.". Warnings can be ignored; only errors are important.
You can also validate your style/locale on your own computer with any tool that offers XML validation and supports the RELAX NG Compact schema language. Examples are the Atom with the atomic-csl plugin, Emacs with the nXML addon, jEdit with the XML addon and the CSL schema, and the command-line utilities Jing and RNV.
We strive to keep the CSL Style Repository in tip-top shape. Becuase we have thousands of styles and hundreds of contributors, we rely heavily on automated quality control and periodic maintenance. Please see Quality Control for our best practices.
If you think that your modified style might be useful to other people, consider submitting it to the CSL Style Repository.
You can also host CSL styles on your own website.
If you have questions about editing CSL styles, you can still ask for help on the Zotero forums or on the CSL Discourse page. Please only use the Issues page of this repository to report bugs, not to ask general style editing questions.