https://github.com/krissen/blink-cmp-bibtex
A lightweight BibTeX citation source for Blink completion.
https://github.com/krissen/blink-cmp-bibtex
bibtex blink-cmp neovim neovim-plugin
Last synced: 25 days ago
JSON representation
A lightweight BibTeX citation source for Blink completion.
- Host: GitHub
- URL: https://github.com/krissen/blink-cmp-bibtex
- Owner: krissen
- License: mit
- Created: 2025-11-15T20:24:03.000Z (6 months ago)
- Default Branch: master
- Last Pushed: 2026-01-16T15:18:08.000Z (3 months ago)
- Last Synced: 2026-01-17T04:53:03.664Z (3 months ago)
- Topics: bibtex, blink-cmp, neovim, neovim-plugin
- Language: Lua
- Homepage:
- Size: 134 KB
- Stars: 9
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: docs/security-review.md
Awesome Lists containing this project
- awesome-neovim-sorted - krissen/blink-cmp-bibtex
- awesome-neovim - krissen/blink-cmp-bibtex - `blink.cmp` source for BibTeX citation files. (Completion / Diagnostics)
README
# blink-cmp-bibtex
BibTeX and Hayagriva completion source for [blink.cmp](https://github.com/Saghen/blink.cmp).
It indexes `\addbibresource` declarations and project bibliography files to offer
citation-key completion together with APA-styled previews in LaTeX, Typst,
Markdown and R Markdown buffers.
---
[Features](#features) · [Installation](#installation) · [Configuration](#configuration) · [Usage](#usage) · [Alternatives](#alternatives)
---
## Why this plugin?
`blink-cmp-bibtex` was created to bring BibTeX citation completion to [blink.cmp](https://github.com/Saghen/blink.cmp) users. While excellent alternatives exist, they have different trade-offs:
- **[VimTeX](https://github.com/lervag/vimtex)** is the comprehensive LaTeX plugin with built-in completion, syntax highlighting, compilation, and more. It can integrate with blink.cmp through [blink.compat](https://github.com/saghen/blink.compat) using its `omni` source. However, VimTeX is primarily a full-featured LaTeX environment rather than a focused completion source.
- **[cmp-bibtex](https://github.com/texlaborg/cmp-bibtex)** is the established citation source for `nvim-cmp`. It's GPL-licensed and tightly coupled to the `cmp` API, making it unsuitable for direct use with blink.cmp.
`blink-cmp-bibtex` fills the gap by providing a native, MIT-licensed completion source designed specifically for blink.cmp. It focuses solely on citation completion with minimal overhead, making the transition from cmp seamless for users with citation-heavy workflows in LaTeX, Typst, Markdown, and R Markdown.
## Features
- Native blink.cmp source implemented in pure Lua (no `blink.compat`).
- Discovers `.bib` files (BibTeX) and `.yml`/`.yaml` files (Hayagriva) from the current buffer, configured search paths or an explicit `files` list.
- For Typst files, follows `#import` statements to find bibliography declarations in imported files.
- Parses entries lazily, normalizes common LaTeX accents (e.g. `{"a}`, `\aa`)
and caches the results with modification-time tracking.
- Supports common citation commands (`\cite`, `\parencite`, `\textcite`,
`\smartcite`, `\footcite`, `\nocite`, Pandoc `[@key]`, Typst `@key` and `#cite()`, …) including optional
pre/post notes.
- Generates APA-inspired previews showing author, year, title and container data
with selectable templates (APA default, IEEE optional).
- Shows `[L]`/`[G]` source indicators to distinguish local (project) from global
(shared) bibliography files.
- Ships with sane defaults yet allows overriding behavior via
`require("blink-cmp-bibtex").setup()` or provider-level `opts`.
## Installation
Example with [lazy.nvim](https://github.com/folke/lazy.nvim):
```lua
{
"saghen/blink.cmp",
dependencies = {
"krissen/blink-cmp-bibtex",
},
opts = {
sources = {
default = function(list)
table.insert(list, "bibtex")
return list
end,
providers = {
bibtex = {
module = "blink-cmp-bibtex",
name = "BibTeX",
min_keyword_length = 2,
score_offset = 10,
async = true,
opts = {
-- provider-level overrides (optional)
},
},
},
},
},
}
```
## Configuration
Call `require("blink-cmp-bibtex").setup()` early in your config to change defaults.
Only values you set will override the built-ins.
```lua
require("blink-cmp-bibtex").setup({
filetypes = { "tex", "plaintex", "markdown", "rmd", "typst" },
files = { "references.bib" }, -- Local project files
global_files = { vim.fn.expand("~/research/master.bib") }, -- Global shared files
search_paths = { "bib/*.bib" },
root_markers = { ".git", "texmf.cnf" },
citation_commands = { "cite", "parencite", "textcite" },
preview_style = "ieee", -- or "apa" (default)
source_indicator = true, -- Show source indicators (default: true)
})
```
### Source indicators
When you have both local (project) and global (shared) bibliography files,
completion items display nuanced indicators showing where each entry comes from
and whether local and global versions differ:
| Indicator | Meaning |
|-----------|---------|
| `[L]` | Entry exists **only** in local bibliography |
| `[G]` | Entry exists **only** in global bibliography |
| `[L=G]` | Entry exists in **both**, content is **identical** |
| `[L≠G]` | Entry exists in **both**, content **differs** |
Indicators only appear when your configuration includes both local and global
sources. If all entries come from the same source type (e.g., only local files),
no indicators are shown.
When an entry exists in both local and global files, the completion menu shows
the local version (deduplication prefers local).
To disable indicators, set `source_indicator = false` in your configuration.
### Local bibliography management
When working with both global (shared) and local (project) bibliography files, you can
automatically copy entries from global files to a local project file. This is useful
when you want to maintain a self-contained project bibliography while drawing from a
master reference library.
```lua
require("blink-cmp-bibtex").setup({
global_files = { vim.fn.expand("~/research/master.bib") },
search_paths = { "references.bib" },
local_bib = {
enabled = true,
target = "plus.bib", -- Local file to copy entries to
auto_add = true, -- Copy on completion accept
create_if_missing = true, -- Create target if it doesn't exist
notify_on_add = true, -- Show notification when entry is added
duplicate_check = true, -- Skip if entry already exists (default: true)
},
})
```
**How it works:**
1. When you accept a completion for a `[G]` (global-only) entry, the BibTeX entry
is automatically copied to your `local_bib.target` file.
2. The entry appears in future completions as `[L=G]` (exists in both, identical).
3. You can also manually copy entries using the `:BibTeXCopyToLocal [key]` command.
**Configuration options:**
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `false` | Enable local bibliography management |
| `target` | string | `nil` | Path to local bib file (relative to project root) |
| `targets` | table | `{}` | Per-directory targets: `{ ["/path/to/project"] = "refs.bib" }` |
| `patterns` | table | `{ "local.bib", "references.bib" }` | Fallback patterns to search |
| `auto_add` | boolean | `false` | Automatically copy global entries on accept |
| `create_if_missing` | boolean | `false` | Create target file if it doesn't exist |
| `notify_on_add` | boolean | `true` | Show notification when entry is added |
| `notify_on_duplicate` | boolean | `false` | Show notification for duplicate entries |
| `duplicate_check` | boolean | `true` | Check for existing entries before adding |
### Preview styles
`preview_style` picks the formatter for the completion detail and documentation
pane. The built-in options are:
- `apa` (default) – Author-year summaries with multiline APA documentation.
- `ieee` – IEEE-inspired strings using quoted titles plus volume/issue metadata.
Custom styles can be added by extending `require("blink-cmp-bibtex").setup()` with a
`preview_style` that matches one of the registered templates.
### Buffer discovery
- `\addbibresource{}`, `\addglobalbib`, `\addsectionbib` and legacy
`\bibliography{}` statements are scanned inside TeX buffers.
- Missing `.bib` extensions are appended automatically so classic
`\bibliography{references}` declarations resolve to `references.bib` on disk.
- Buffer-local paths resolve relative to the current file's directory (with the
project root as a fallback) so chapter subdirectories can reference sibling
bibliographies.
- Markdown YAML metadata lines such as `bibliography: references.bib` are
respected.
- Typst `#bibliography()` declarations are detected, including those in imported files via `#import` statements.
- Both BibTeX (`.bib`) and Hayagriva (`.yml`, `.yaml`) bibliography files are supported and automatically detected based on file extension.
- `opts.search_paths` accepts either file paths or glob patterns relative to the
detected project root (based on `opts.root_markers`). These are treated as
**local** sources.
- `opts.files` is a list of absolute or `vim.fn.expand`-friendly paths that are
always included. These are treated as **local** sources (shown with `[L]`
indicator when source indicators are enabled).
- `opts.global_files` is a list of paths to shared/master bibliography files.
These are treated as **global** sources (shown with `[G]` indicator).
**Note:** Source indicators (`[L]`, `[G]`, `[L=G]`, `[L≠G]`) only appear when
you have both local and global sources configured. If you only use `files`
and `search_paths` without `global_files`, no indicators are shown since all
entries are implicitly local.
### blink.cmp provider options
Any table supplied as `providers.bibtex.opts` in the blink.cmp configuration is
merged into the global setup options. This enables per-source overrides for
`files`, `filetypes`, preview style, etc.
## Usage
`blink-cmp-bibtex` triggers autocompletion as you type citation keys in your documents:
### In LaTeX files
Start typing a citation command followed by an opening brace, then begin typing
the citation key. For example, when you have a BibTeX entry with the key
`Niemi2025`:
```latex
\cite{Nie
```
As you type `Nie`, blink.cmp will show matching citation keys. The completion
menu displays each key with a concise APA-style summary, and selecting an entry
shows expanded details in the documentation pane.
This works with all supported citation commands: `\parencite{`, `\textcite{`,
`\footcite{`, `\smartcite{`, `\autocite{`, `\nocite{`, `\citep{`, `\citet{`, and
more. Optional arguments are also supported (e.g., `\cite[see][42]{Nie`).
### In Markdown and R Markdown files
Use Pandoc-style citations with the `@` symbol. For the same `Niemi2025` entry:
```markdown
@Nie
```
Or within brackets for inline citations:
```markdown
[@Nie
```
Multiple references are supported using semicolons:
```markdown
[@ref1; @Nie
```
As you type, blink.cmp shows matching keys with the same preview information as
in LaTeX mode.
### In Typst files
Typst supports both simple `@key` citations and the more explicit `#cite()` syntax:
```typst
@Nie
```
Or using the cite function:
```typst
#cite(