# biblatex-csl-converter

[![Test CI](https://github.com/fiduswriter/biblatex-csl-converter/actions/workflows/test.yml/badge.svg)](https://github.com/fiduswriter/biblatex-csl-converter/actions/workflows/test.yml)
[![Coverage Status](https://coveralls.io/repos/github/fiduswriter/biblatex-csl-converter/badge.svg?branch=main)](https://coveralls.io/github/fiduswriter/biblatex-csl-converter?branch=main)
[![npm version](https://img.shields.io/npm/v/biblatex-csl-converter.svg)](https://www.npmjs.com/package/biblatex-csl-converter)
[![npm downloads](https://img.shields.io/npm/dm/biblatex-csl-converter.svg)](https://www.npmjs.com/package/biblatex-csl-converter)
[![License: LGPL-3.0](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)

A set of JavaScript converters.

Try the demo [here](https://fiduswriter.github.io/biblatex-csl-converter/).

## Supported Conversions

### Main formats

| From | To |
|------|----|
| BibLaTeX | Internal JSON |
| CSL | Internal JSON |
| Internal JSON | CSL |
| Internal JSON | BibLaTeX |

### Additional import formats

| From | To |
|------|----|
| EndNote | Internal JSON |
| RIS | Internal JSON |
| Citavi | Internal JSON |
| DOCX native format | Internal JSON |
| ODT native format | Internal JSON |

We can even read the citation information from various citation managers inside ODT/DOCX files!

## Usage

```JavaScript
import {BibLatexParser} from "biblatex-csl-converter"

// synchronous:
let parser = new BibLatexParser(input, {processUnexpected: true, processUnknown: true})
let bib = parser.parse()

// asynchronous:
let parser = new BibLatexParser(input, {processUnexpected: true, processUnknown: true})
parser.parseAsync().then((bib) => { ... })
```

## API Documentation

For comprehensive API documentation, see **[API.md](API.md)**.

## Extracting Citations from ODT and DOCX Files

See [CITATIONS_IN_DOCS.md](CITATIONS_IN_DOCS.md) for documentation on how Zotero, Mendeley, EndNote, Citavi, and JabRef store citations and bibliographies inside ODT and DOCX files.

## Note on quality of conversions

While writing this library, we have had a lot of experience converting between CSL and BibLaTeX and have also worked with the exports and imports generated by Zotero. This is open source/free software, making it easy to verify whether conversions are correct. Conversions involving these formats are therefore generally more reliable.

Other software, such as EndNote, Citavi, and Mendeley, is proprietary and closed source, making testing more difficult—especially without licenses for these products. We rely on publicly available documentation and ODT/DOCX test files produced by others to understand how these formats work and to test our conversions. If something is not converted correctly, please report it so we can improve the library; example files are welcome.

## FAQ

---

**Q:** Why do you use a different JSON as an internal format instead of just the JSON format of CSL? Wouldn't that save you one conversion step?

**A:** Unfortunately, the CSL JSON format cannot hold all the information we import from BibLaTeX. If we used CSL JSON internally, we would lose information that we may want to export to BibLaTeX later on.

---

**Q:** Do you import all information from the imported BibTeX/BibLaTeX files?

**A:** We only keep the information found in any of the required or optional fields defined in the BibLaTeX documentation. Other fields are removed upon import.

---

**Q:** How do I see if there are errors when parsing the BibTeX/BibLaTeX file?

**A:** An array of errors encountered while parsing the file can be found at `parser.errors` after parsing. There is also `parser.warnings` for less serious issues.

---

**Q:** I need access to the raw/non-processed contents of certain fields. What do I do?

**A:** The fields in their almost raw form can be found under `entry.raw_fields[FIELD_NAME]`.

---

**Q:** What if I need to process fields that don't follow the BibLaTeX definition?

**A:** You can initialize the parser with a config object like this: `new BibLatexParser(inputString, {processUnexpected: true, processUnknown: {collaborator: 'l_name'}})`. The `processUnexpected` setting enables parsing of fields that are known but shouldn't appear in a bibliography entry due to its type. The `processUnknown` setting allows parsing of entirely unknown fields. You can set it to `true`, or to an object containing descriptions of how these unknown fields should be processed. If a field is not specified, it will be processed as a literal field (`f_literal`). These fields will be available under `entry.unexpected_fields[FIELD_NAME]` and `entry.unknown_fields[FIELD_NAME]`, respectively.

---

**Q:** I use variables in my BibLaTeX files. Will your converter read them?

**A:** Yes, but for the converter to create a string, the variables need to be defined. Undefined variables can also be handled by the BibLaTeX importer/exporter, but when exporting to CSL, they simply print out the variable name inside an HTML tag that is not supported by citeproc (and an error is thrown).

---

**Q:** I want to run the demo locally.

**A:** [http-server](https://www.npmjs.com/package/http-server) is handy. Do a global install of http-server with `npm install http-server -g` and run `http-server docs`.

---

**Q:** I want to include this on my website, and I don't use npm packages, etc. Is there a file I can just add to the header of my webpage?

**A:** Yes, you can download such a file [here](https://github.com/fiduswriter/biblatex-csl-converter/tree/browser).

---

## Upgrading

### From 2.x to 3.x

Note that the `output` getter has been removed. Use `parse()` instead.

This applies to `BibLatexExporter`, `CSLExporter`, and `BibLatexParser`. Note that the output of `BibLatexParser` is structured differently when using the `parse()` function if you previously used the `output` getter.

In the case of `BibLatexExporter` and `CSLExporter`, instead of:

```JavaScript
const output = parser.output
```

Do:

```JavaScript
const output = parser.parse()
```

In the case of `BibLatexParser`, instead of:

```JavaScript
const output = parser.output
```

Do:

```JavaScript
const parsed = parser.parse()
const output = parsed.entries
```

### From 1.x to 2.x

Note that the API for the asynchronous parser has changed.

You need to change instances of this:

```JavaScript
let parser = new BibLatexParser(input, {processUnexpected: true, processUnknown: true, async: true})
parser.parse().then((bib) => { ... })
```

to:

```JavaScript
let parser = new BibLatexParser(input, {processUnexpected: true, processUnknown: true})
parser.parseAsync().then((bib) => { ... })
```