Citation keys

Citation keys are unique identifiers for the references in your library. They allow you to easily cite sources in text-based writing and programming environments like LaTeX.

While primarily used for BibTeX workflows, citation keys also provide a quick way to reference and find specific articles within Paperpile. This article explains how Paperpile handles citation keys and how you can customize them to fit your workflow.

How Paperpile sets citation keys

By default, Paperpile automatically generates a unique citation key for every reference you add to your library. The automatic pattern combines the first author's last name, the year of publication, and two random identifying letters.

To avoid citation key clashes, Paperpile adds a random identifying two letter postfix.

You can control citation keys in your library in two ways:

• Custom citation keys - manually set a citation key for a single reference.
• Citation key patterns - control how Paperpile generates citation keys across your whole library.

Set a custom citation key for an individual reference

You can manually set custom citation keys for specific references when you need precise control.

You can view or change the citation key for any reference directly from the metadata edit dialog.

Edit a single citation key

1. In the reference list view, select the reference whose citation key you want to edit.
2. Click the edit button in the toolbar (or press E).
3. In the metadata edit dialog, find the BibTeX key field.

   If that field is missing: at the top of the edit dialog, click Add field and search for BibTeX key in the dropdown list.

4. Enter your custom citation key.
5. Click Save.

Your reference is now saved with a custom citation key that will override the automatic pattern.

Revert to automatic citation key

To remove a custom citation key and return to the automatic pattern:

1. Select the reference whose citation key you want to edit.
2. Click the edit button in the toolbar (or press E)).
3. In the metadata edit dialog, find the BibTeX key field.
4. Click the clear button ( x ) to clear the custom key and revert to the automatic pattern.
5. Click Save.

Paperpile will immediately generate a new citation key using your current citation key pattern.

Find all references with custom keys

To see all the references for which you have manually set a citation key, you can:

1. Click your profile picture in the top right of the web app.
2. Go to Settings > General.
3. In the Citation keys section, click inspect them here.

Set the citation key pattern for your entire library

For full control over your BibTeX workflow, you can change the pattern Paperpile uses to generate citation keys for all references in your library.

1. Click your profile picture in the top right of the web app.
2. Go to Settings > General.
3. In the Citation keys section, click Set citation key pattern.
4. Select one of the predefined patterns in the dropdown list.
5. Click Apply changes.

All new references added to your library will use this pattern for their citation keys.

If you want Paperpile to regenerate citation keys for existing references, click the Reset all keys button in Settings > General > Citation keys.

Set a custom citation key pattern

Within the Set citation key pattern dialog you can customize one of the predefined patterns or create your own pattern from scratch.

1. Open the Set citation key pattern dialog using the steps from the section above.
2. In the Current pattern dropdown, select a predefined pattern or choose Custom.
3. Click Customize pattern…
4. Make changes in the Current pattern text box. Any changes you make appear in the example keys in the preview window on the right.
5. Click Apply changes to set your new pattern.

Citation key pattern preview window

See examples of citation keys that follow your chosen pattern in the preview window. You can also view fields, and variations of those fields, that are available for use.

Fields available for custom patterns

You can use the following fields in your citation key pattern:

• [authors]: Last names of all authors
• [firstauthor]: Last name of the first author
• [lastauthor]: Last name of the last author
• [title]: Title of the reference
• [titleshort]: Title without function words like the, a, in
• [journal]: Abbreviated journal name
• [year]: Publication year
• [unique]: Unique letters for deduplication

Field variations

You can scroll down from the Available fields section to see the advanced syntax for field variations. You can use these methods to control how fields appear in citation keys:

• Lowercase — Makes a field fully lowercase.
  • Example: [firstauthor] → Last name of the first author is in lower case.
  • “Smith” → smith
• Capitalized — Makes the first letter in the field uppercase.
  • Example: [Firstauthor] → Last name of the first author is capitalized.
  • “Smith” → Smith
• All uppercase — Makes a field all uppercase.
  • Example: [FIRSTAUTHOR] → Last name of the first author is in uppercase.
  • “Smith” → SMITH
• Word or character limit — Specify the number of words, letters, or digits in a field.
  • Example: [Firstauthor:1] → uses just the first letter of the first author’s last name.
  • “Smith” → S
  • Example: [Firstauthor:2] → uses the first two letters of the first author’s last name.
  • “Smith” → Sm
  • Example: [Authors:2] → uses the last names of the first two authors.
  • “Smith and Miller” → SmithMiller
  • Example: [Authors:2:3] → uses the first three letters of the last names of the first two authors.
  • “Smith and Miller” → SmiMil
  • Example: year:2 → uses the last two digits of the year of publication
  • “2015” → 15

Handle duplication of citation keys

Citation keys need to be unique to identify each reference in your library. For example, a single author might publish multiple papers in the same year, or different authors with common last names might appear frequently in your library. The citation keys for these references must be different from each other.

You can choose how to handle duplicate citation keys in the Handle duplicate keys dropdown:

• Random letters — Adds a specified number of random letters to all citation keys. Use [unique:1] for one letter, [unique:2] for two letters, and so on.
• Sufficient unique random letters — Adds random letters only to duplicate keys. Use [unique:1] for one letter, [unique:2] for two letters, and so on.
• Sufficient ordered letters A, B, C,… — Adds sequential letters (A, B, C,..) only to duplicate keys. For example, [Firstauthor][year]-[unique:1] creates Smith2018, Smith2018-a, Smith2018-b.
• Sufficient ordered letters B, C, D,… — Adds sequential letters (B, C, D,…) only to duplicate keys, leaving the first occurrence unchanged. For example, [Firstauthor][year]-[unique:1] creates Smith2018, Smith2018-b, Smith2018-c.
• Sufficient ordered numbers 1, 2, 3,… — Adds sequential numbers (1, 2, 3,…) only to duplicate keys. For example, [Firstauthor][year]-[unique:1] creates Smith2018, Smith2018-1, Smith2018-2.

Other options

• Fallback key — Specify the fallback key, if fields are missing in a reference and the key would end up empty.
• Spaces — Choose how to handle spaces from the dropdown list. Since spaces are not allowed in citation keys, they are removed by default, but you can also choose to replace spaces with an underscore or to replace spaces with a hyphen.
• Combine two authors with — Specify how to combine the Last names for references with exactly two authors, such as “Smith and Miller”.
• Combine multiple authors with — Specify one or multiple characters to combine names of multiple authors, e.g., “Smith, Miller, Johnson”. Relevant for patterns displaying multiple authors with a field like authors:5.
• Abbreviate list of authors with — Specify how and where to abbreviate author lists. You can abbreviate author lists at the end or in the middle. To set the maximum number of authors, use a pattern such as authors:2.
• Abbreviate any other fields with — Specify how and where to abbreviate fields longer than their maximum length. You can abbreviate fields at the end or in the middle. To set the maximum length, use a pattern like title:5.

Reset all keys

Some citation keys in your library may not follow your automatic pattern. If you have keys that you have set manually, or if you have imported references with the Paperpile mobile apps, you can change all of them to your chosen pattern in a few steps.

1. Click your profile picture in the top right of the web app.
2. Go to Settings > General.
3. In the Citation keys section, click Reset all keys.
4. In the Reset citation keys modal window, click Reset to confirm the action.

Common questions

What citation key pattern is used in shared folders?

In shared folders, citation keys follow the pattern set in the folder creator's library.

Can I customize the citation key pattern for a shared library?

No. In shared libraries, citation keys follow Paperpile's default pattern to ensure consistency for all users with library access.

How are citation keys handled when importing a BibTeX file?

When you import references from a BibTeX (.bib) file, Paperpile automatically changes the keys to the pattern you have selected for your library.