How to create your own CSL citations style

Contribute to the CSL Repository

If you think the style you created can be useful to others, we strongly encourage you to submit to the CSL repository. First of all, this is a great way to give back to the CSL community that has contributed hundreds of styles already. The styles you submit there are used not just by Papers, but by other software packages as well. If it's in the repository, it will eventually be added to the default list of styles in Papers (typically at the next update). That also means your name will be in the Papers acknowledgments as well!

If you want to do so, it's very straightforward. There are simple instructions on the wiki of the CSL repository:

https://github.com/citation-style-language/styles/wiki/Submitting-S...
https://github.com/citation-style-language/styles/wiki/Style-Requir...

Again, if you go through the trouble of reading the instructions below, consider contributing back to the repository!

General recommendations

If Papers or the CSL repository don't have the style you're after it is possible to make your own styles using one of the options below. After you create a CSL file using one of these options, you will need to move the file into your Papers library folder using the instructions above, and you will then need to restart Papers. However, it is also important to remember the following constraints:

  • make sure the file name is unique, and is not used by one of the built-in CSL files; the best way to make sure of that is to append a unique prefix or suffix to the file name

    This is correct: alex_csl-journal-irreproducible-results.csl

    This is not correct: nature.csl

  • make sure the file has the csl extension and no other extension after that

    This is correct: alex_csl-journal-irreproducible-results.csl

    This is not correct: alex_csl-journal-irreproducible-results.csl.xml

    This is not correct: alex_csl-journal-irreproducible-results.txt

  • make sure the id tag used in the XML file itself is unique, again for instance by adding a unique prefix, or use the zotero prefix if you submit to the official repository

    This is correct: <id>http://www.zotero.org/styles/journal-irreproducible-results</id>

    This is correct: <id>alex/journal-irreproducible-results</id>

    This is not correct: <id>1</id>

  • make sure the 'Title' tag in the XML file can be easily found later, as this is what will be displayed in Papers as the journal/style name

    This is correct: <title>Journal of Irreproducible Results</title>

    This is not correct: <title>j_irreproducible_res</title>

Option 1

  • Edit the XML files that are used by CSL files using CSL specifications
  • This is tricky, but if you are comfortable with XML and have a good text editor like Sublime or similar, then it's not out of reach.

Option 2

Some Papers users have reported success with creating CSL files at this CSL editor webpage.

  • Once you've navigated to this webpage, click on 'Info' and give your style a useful name (e.g., 'Astronomy')

ishot9.jpg

  • After you've created your desired style for citations and bibliographies press the 'Generate CSL' button on the bottom right of the page
  • Copy the CSL that's generated into the text editor application on your PC
  • In the 'Format' menu of TextEdit click on 'Make Plain Text'

ishot7.jpg

  • edit the part with the id tag, to make sure it's unique and descriptive, e.g. <id>alex/journal-irreproducible-results</id>

  • Click on 'File', then 'Save'. Unselect the box at the bottom of the save dialog box that says 'If no text is provided, use '.txt'. Save your file with the .csl extension by manually typing in '.csl' after the name of your file.

ishot8.jpg

  • Move the file into your papers library folder using the instructions above making sure you restart Papers.

Option 3

A new experimental CSL editor is being currently developed. While still in flux and considered at a beta stage, it has many interesting features that could make it a better fit for CSL editing. If you give it a try, and find it useful, or find bugs, be sure to let the developers know.

The steps necessary to add a style developed with this editor to your Papers library are similar to the ones described in 'Option 2' above.

Tweaking an existing style

  • If you have a CSL file of a style you'd like to tweak you can load this file into the CSL editor mentioned above and make the changes required.
  • To do this click on 'Load CSL' at the bottom of the page
  • When you're done making changes follow the instructions above to get this style into Papers.