# Citations from BibTeX for Sublime Text

This [Sublime Text 3](https://www.sublimetext.com/3) plugin provides citation search and Tab-completion for citations stored in a BibTeX file. Configure the file path and you are good to go!

The default set up is optimized to work with [AcademicMarkdown](https://github.com/mangecoeur/AcademicMarkdown).

Uses the [bibtexparser](https://github.com/sciunto/python-bibtexparser) library from sciunto.

# Configuration

You must specify the location of your BibTeX file or files in the `Citer-sublime-settings` preferences file. Multiple files can be added as a list.

Optionally you can define 
- `search_fields` the BibTeX fields to search in when using Citer: Search
- `citation_format` the citation format
- `completions_scopes` the list of scopes to limit the operation of the plugin (by default, Citer will only suggest citations within plain text scopes and is disabled in source code)
- `excluded_scopes` list of scopes to explicitly exclude from Citer completions
- `enable_completions` enable/disable citation completions (when you hit @)
- `quickview_format` customise the format when listing library entries in the quickview panel (e.g. with the Citer: Show All command). Place variables between `{}` braces. Available variables are `citekey`, `title`, `author`, `year`.
- `auto_merge_citations` Whether to automatically merge citations that are inserted next to each other. `[@Fred2000][@Mary2001]` becomes `[@Fred2000; @Mary2001]`. Equivalent to running `Citer: Combine adjacent citations` on every insert

See below for example (default) configuration


```js
{
    //REQUIRED:

    "bibtex_file ": "example/path/to/file.bib",
    // You can also specify a list
    //"bibtex_file_path": ["example/path/to/file.bib", "example/path/to/fileTwo.bib"],

    //OPTIONAL:

    //By default Citer Search looks for your keyword in the 
    //author, title, year, and Citekey (id) fields
    "search_fields": ["author", "title", "year", "id"] ,
    //Default format is @Citekey
    "citation_format": "@%s",
    //list of scopes. Could be top level "text" or "source", or limit to
    // e.g "text.html.markdown"
    "completions_scopes": ["text"],
    "enable_completions": true,
    //Customise the quickview of you library, using python format syntax
    "quickview_format": "{citekey} - {title}",
    "auto_merge_citations": false,
    "excluded_scopes": [],
}
```


# Commands

**Citer: Search** - enter a search term. All results where the term is found in the author, title, citekey, or year fields will be shown (the searched fields are configurable)

**Citer: Show All** - show all the entries in your BibTeX in a quick view (you can then search in the title)

**Citer: Insert Title** - show all the entries in your BibTeX in a searchable quick view, inserts the title

**Citer: Combine adjacent citations** - Combines neighbouring citations i.e. `[@Fred2000][@Mary2001]` becomes `[@Fred2000; @Mary2001]`


# Completions

Citer provides autocompletions for your citekeys, these are enabled by default and can be disabled in the config.

# Compatibility

Citer has been tested with BibTeX generated by [Mendeley](https://www.mendeley.com/), Jabref, and Zotero. It should work with any well-formed BibTeX file.

# TODO

- [ ] Look into providing snippets for [pandoc](http://pandoc.org/index.html) citation format in markdown files.

# Licence

LGPLv3. See [COPYING](https://github.com/mangecoeur/Citer/blob/master/COPYING) for details.