{"id":33789508,"url":"https://github.com/krissen/blink-cmp-bibtex","last_synced_at":"2026-04-04T18:52:43.462Z","repository":{"id":324446312,"uuid":"1097252623","full_name":"krissen/blink-cmp-bibtex","owner":"krissen","description":"A lightweight BibTeX citation source for Blink completion.","archived":false,"fork":false,"pushed_at":"2026-01-16T15:18:08.000Z","size":137,"stargazers_count":9,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-17T04:53:03.664Z","etag":null,"topics":["bibtex","blink-cmp","neovim","neovim-plugin"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/krissen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security-review.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-15T20:24:03.000Z","updated_at":"2025-11-23T22:49:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/krissen/blink-cmp-bibtex","commit_stats":null,"previous_names":["krissen/blink-bibtex","krissen/blink-cmp-bibtex"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/krissen/blink-cmp-bibtex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krissen%2Fblink-cmp-bibtex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krissen%2Fblink-cmp-bibtex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krissen%2Fblink-cmp-bibtex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krissen%2Fblink-cmp-bibtex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/krissen","download_url":"https://codeload.github.com/krissen/blink-cmp-bibtex/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krissen%2Fblink-cmp-bibtex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31409470,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bibtex","blink-cmp","neovim","neovim-plugin"],"created_at":"2025-12-06T01:00:43.609Z","updated_at":"2026-04-04T18:52:43.433Z","avatar_url":"https://github.com/krissen.png","language":"Lua","funding_links":[],"categories":["Completion"],"sub_categories":["Diagnostics"],"readme":"# blink-cmp-bibtex\n\nBibTeX and Hayagriva completion source for [blink.cmp](https://github.com/Saghen/blink.cmp).\nIt indexes `\\addbibresource` declarations and project bibliography files to offer\ncitation-key completion together with APA-styled previews in LaTeX, Typst,\nMarkdown and R Markdown buffers.\n\n---\n\n[Features](#features) · [Installation](#installation) · [Configuration](#configuration) · [Usage](#usage) · [Alternatives](#alternatives)\n\n---\n\n## Why this plugin?\n\n`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:\n\n- **[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.\n\n- **[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.\n\n`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.\n\n## Features\n\n- Native blink.cmp source implemented in pure Lua (no `blink.compat`).\n- Discovers `.bib` files (BibTeX) and `.yml`/`.yaml` files (Hayagriva) from the current buffer, configured search paths or an explicit `files` list.\n- For Typst files, follows `#import` statements to find bibliography declarations in imported files.\n- Parses entries lazily, normalizes common LaTeX accents (e.g. `{\"a}`, `\\aa`)\n  and caches the results with modification-time tracking.\n- Supports common citation commands (`\\cite`, `\\parencite`, `\\textcite`,\n  `\\smartcite`, `\\footcite`, `\\nocite`, Pandoc `[@key]`, Typst `@key` and `#cite(\u003ckey\u003e)`, …) including optional\n  pre/post notes.\n- Generates APA-inspired previews showing author, year, title and container data\n  with selectable templates (APA default, IEEE optional).\n- Shows `[L]`/`[G]` source indicators to distinguish local (project) from global\n  (shared) bibliography files.\n- Ships with sane defaults yet allows overriding behavior via\n  `require(\"blink-cmp-bibtex\").setup()` or provider-level `opts`.\n\n## Installation\n\nExample with [lazy.nvim](https://github.com/folke/lazy.nvim):\n\n```lua\n{\n  \"saghen/blink.cmp\",\n  dependencies = {\n    \"krissen/blink-cmp-bibtex\",\n  },\n  opts = {\n    sources = {\n      default = function(list)\n        table.insert(list, \"bibtex\")\n        return list\n      end,\n      providers = {\n        bibtex = {\n          module = \"blink-cmp-bibtex\",\n          name = \"BibTeX\",\n          min_keyword_length = 2,\n          score_offset = 10,\n          async = true,\n          opts = {\n            -- provider-level overrides (optional)\n          },\n        },\n      },\n    },\n  },\n}\n```\n\n## Configuration\n\nCall `require(\"blink-cmp-bibtex\").setup()` early in your config to change defaults.\nOnly values you set will override the built-ins.\n\n```lua\nrequire(\"blink-cmp-bibtex\").setup({\n  filetypes = { \"tex\", \"plaintex\", \"markdown\", \"rmd\", \"typst\" },\n  files = { \"references.bib\" },                              -- Local project files\n  global_files = { vim.fn.expand(\"~/research/master.bib\") }, -- Global shared files\n  search_paths = { \"bib/*.bib\" },\n  root_markers = { \".git\", \"texmf.cnf\" },\n  citation_commands = { \"cite\", \"parencite\", \"textcite\" },\n  preview_style = \"ieee\",      -- or \"apa\" (default)\n  source_indicator = true,     -- Show source indicators (default: true)\n})\n```\n\n### Source indicators\n\nWhen you have both local (project) and global (shared) bibliography files,\ncompletion items display nuanced indicators showing where each entry comes from\nand whether local and global versions differ:\n\n| Indicator | Meaning |\n|-----------|---------|\n| `[L]` | Entry exists **only** in local bibliography |\n| `[G]` | Entry exists **only** in global bibliography |\n| `[L=G]` | Entry exists in **both**, content is **identical** |\n| `[L≠G]` | Entry exists in **both**, content **differs** |\n\nIndicators only appear when your configuration includes both local and global\nsources. If all entries come from the same source type (e.g., only local files),\nno indicators are shown.\n\nWhen an entry exists in both local and global files, the completion menu shows\nthe local version (deduplication prefers local).\n\nTo disable indicators, set `source_indicator = false` in your configuration.\n\n### Local bibliography management\n\nWhen working with both global (shared) and local (project) bibliography files, you can\nautomatically copy entries from global files to a local project file. This is useful\nwhen you want to maintain a self-contained project bibliography while drawing from a\nmaster reference library.\n\n```lua\nrequire(\"blink-cmp-bibtex\").setup({\n  global_files = { vim.fn.expand(\"~/research/master.bib\") },\n  search_paths = { \"references.bib\" },\n  local_bib = {\n    enabled = true,\n    target = \"plus.bib\",         -- Local file to copy entries to\n    auto_add = true,             -- Copy on completion accept\n    create_if_missing = true,    -- Create target if it doesn't exist\n    notify_on_add = true,        -- Show notification when entry is added\n    duplicate_check = true,      -- Skip if entry already exists (default: true)\n  },\n})\n```\n\n**How it works:**\n\n1. When you accept a completion for a `[G]` (global-only) entry, the BibTeX entry\n   is automatically copied to your `local_bib.target` file.\n2. The entry appears in future completions as `[L=G]` (exists in both, identical).\n3. You can also manually copy entries using the `:BibTeXCopyToLocal [key]` command.\n\n**Configuration options:**\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `enabled` | boolean | `false` | Enable local bibliography management |\n| `target` | string | `nil` | Path to local bib file (relative to project root) |\n| `targets` | table | `{}` | Per-directory targets: `{ [\"/path/to/project\"] = \"refs.bib\" }` |\n| `patterns` | table | `{ \"local.bib\", \"references.bib\" }` | Fallback patterns to search |\n| `auto_add` | boolean | `false` | Automatically copy global entries on accept |\n| `create_if_missing` | boolean | `false` | Create target file if it doesn't exist |\n| `notify_on_add` | boolean | `true` | Show notification when entry is added |\n| `notify_on_duplicate` | boolean | `false` | Show notification for duplicate entries |\n| `duplicate_check` | boolean | `true` | Check for existing entries before adding |\n\n### Preview styles\n\n`preview_style` picks the formatter for the completion detail and documentation\npane. The built-in options are:\n\n- `apa` (default) – Author-year summaries with multiline APA documentation.\n- `ieee` – IEEE-inspired strings using quoted titles plus volume/issue metadata.\n\nCustom styles can be added by extending `require(\"blink-cmp-bibtex\").setup()` with a\n`preview_style` that matches one of the registered templates.\n\n### Buffer discovery\n\n- `\\addbibresource{}`, `\\addglobalbib`, `\\addsectionbib` and legacy\n  `\\bibliography{}` statements are scanned inside TeX buffers.\n- Missing `.bib` extensions are appended automatically so classic\n  `\\bibliography{references}` declarations resolve to `references.bib` on disk.\n- Buffer-local paths resolve relative to the current file's directory (with the\n  project root as a fallback) so chapter subdirectories can reference sibling\n  bibliographies.\n- Markdown YAML metadata lines such as `bibliography: references.bib` are\n  respected.\n- Typst `#bibliography()` declarations are detected, including those in imported files via `#import` statements.\n- Both BibTeX (`.bib`) and Hayagriva (`.yml`, `.yaml`) bibliography files are supported and automatically detected based on file extension.\n- `opts.search_paths` accepts either file paths or glob patterns relative to the\n  detected project root (based on `opts.root_markers`). These are treated as\n  **local** sources.\n- `opts.files` is a list of absolute or `vim.fn.expand`-friendly paths that are\n  always included. These are treated as **local** sources (shown with `[L]`\n  indicator when source indicators are enabled).\n- `opts.global_files` is a list of paths to shared/master bibliography files.\n  These are treated as **global** sources (shown with `[G]` indicator).\n\n  **Note:** Source indicators (`[L]`, `[G]`, `[L=G]`, `[L≠G]`) only appear when\n  you have both local and global sources configured. If you only use `files`\n  and `search_paths` without `global_files`, no indicators are shown since all\n  entries are implicitly local.\n\n### blink.cmp provider options\n\nAny table supplied as `providers.bibtex.opts` in the blink.cmp configuration is\nmerged into the global setup options. This enables per-source overrides for\n`files`, `filetypes`, preview style, etc.\n\n## Usage\n\n`blink-cmp-bibtex` triggers autocompletion as you type citation keys in your documents:\n\n### In LaTeX files\n\nStart typing a citation command followed by an opening brace, then begin typing\nthe citation key. For example, when you have a BibTeX entry with the key\n`Niemi2025`:\n\n```latex\n\\cite{Nie\n```\n\nAs you type `Nie`, blink.cmp will show matching citation keys. The completion\nmenu displays each key with a concise APA-style summary, and selecting an entry\nshows expanded details in the documentation pane.\n\nThis works with all supported citation commands: `\\parencite{`, `\\textcite{`,\n`\\footcite{`, `\\smartcite{`, `\\autocite{`, `\\nocite{`, `\\citep{`, `\\citet{`, and\nmore. Optional arguments are also supported (e.g., `\\cite[see][42]{Nie`).\n\n### In Markdown and R Markdown files\n\nUse Pandoc-style citations with the `@` symbol. For the same `Niemi2025` entry:\n\n```markdown\n@Nie\n```\n\nOr within brackets for inline citations:\n\n```markdown\n[@Nie\n```\n\nMultiple references are supported using semicolons:\n\n```markdown\n[@ref1; @Nie\n```\n\nAs you type, blink.cmp shows matching keys with the same preview information as\nin LaTeX mode.\n\n### In Typst files\n\nTypst supports both simple `@key` citations and the more explicit `#cite(\u003ckey\u003e)` syntax:\n\n```typst\n@Nie\n```\n\nOr using the cite function:\n\n```typst\n#cite(\u003cNie\n```\n\n#### Typst bibliography formats\n\nTypst supports two bibliography file formats:\n\n1. **BibTeX** (`.bib` files) - Traditional format used in LaTeX\n2. **Hayagriva** (`.yml` or `.yaml` files) - Typst's native YAML-based bibliography format\n\nBoth formats are automatically detected and parsed. For example:\n\n```typst\n#bibliography(\"references.bib\")  // BibTeX format\n#bibliography(\"references.yml\")  // Hayagriva format\n```\n\n#### Import tracking\n\nThe plugin automatically follows Typst `#import` statements to find bibliography declarations in imported files. For example:\n\n```typst\n// main.typ\n#import \"refs.typ\": refs\n@Nie  // Completion works here!\n\n// refs.typ (in the same directory)\n#let refs = bibliography(\"references.bib\")\n```\n\nThe plugin will detect the `bibliography()` call in `refs.typ` and index the entries from `references.bib`, even though it's not directly declared in the main file.\n\n### Completion details\n\nblink.cmp renders two panes for each matched item:\n\n- The completion row shows the citation key with an APA-style summary. Source\n  indicators (`[L]`, `[G]`, etc.) appear on the right side of the menu.\n- The documentation pane (typically shown below or beside the menu) expands the\n  same entry with publisher/journal, place, DOI/URL, etc.\n\nEach completion item exposes:\n\n- `label`: the citation key.\n- `detail`: APA-like string (`Author (Year) – Title`).\n- `labelDetails.description`: source indicator (`[L]`, `[G]`, `[L=G]`, `[L≠G]`).\n- `documentation`: multi-line APA preview covering author/editor, year, title,\n  container, publisher and DOI/URL when available.\n\n## Documentation\n\n- [API Reference](docs/api.md) – Detailed API documentation for all modules\n- [Development Guide](docs/development.md) – Architecture, coding style, and contribution guidelines\n- [Specification](docs/spec.md) – High-level feature specification and design goals\n\n## Alternatives\n\nIf `blink-cmp-bibtex` doesn't fit your needs, consider these alternatives:\n\n### VimTeX\n\n[VimTeX](https://github.com/lervag/vimtex) is a comprehensive LaTeX plugin offering completion, syntax highlighting, compilation, PDF viewing, and much more. It provides BibTeX completion through multiple methods:\n\n- **Native completion**: VimTeX has built-in `omni` completion for citations\n- **blink.cmp integration**: Use VimTeX with blink.cmp via [blink.compat](https://github.com/saghen/blink.compat) and its `omni` source ([setup guide](https://cmp.saghen.dev/configuration/sources#vimtex))\n- **Full LaTeX environment**: If you need more than just citations (e.g., compilation, navigation, text objects), VimTeX is the go-to choice\n\n### cmp-bibtex\n\n[cmp-bibtex](https://github.com/texlaborg/cmp-bibtex) is the established BibTeX source for `nvim-cmp`. If you're using `nvim-cmp`, this is the recommended option. Note that it's GPL-licensed and not directly compatible with blink.cmp.\n\n### Other community sources\n\nThe blink.cmp ecosystem has various [community sources](https://cmp.saghen.dev/configuration/sources#community-sources) for different completion needs. Check the documentation for the latest list.\n\n## Migration from blink-bibtex\n\nIf you're upgrading from the old `blink-bibtex` name, you'll need to update your configuration in three places:\n\n### 1. Update your lazy.nvim plugin specification\n\n**Before:**\n\n```lua\n{\n  \"saghen/blink.cmp\",\n  dependencies = {\n    \"krissen/blink-bibtex\",\n  },\n  -- ...\n}\n```\n\n**After:**\n\n```lua\n{\n  \"saghen/blink.cmp\",\n  dependencies = {\n    \"krissen/blink-cmp-bibtex\",\n  },\n  -- ...\n}\n```\n\n### 2. Update the module name in your blink.cmp config\n\n**Before:**\n\n```lua\nproviders = {\n  bibtex = {\n    module = \"blink-bibtex\",\n    -- ...\n  },\n}\n```\n\n**After:**\n\n```lua\nproviders = {\n  bibtex = {\n    module = \"blink-cmp-bibtex\",\n    -- ...\n  },\n}\n```\n\n### 3. Update any direct setup() calls\n\n**Before:**\n\n```lua\nrequire(\"blink-bibtex\").setup({\n  -- config\n})\n```\n\n**After:**\n\n```lua\nrequire(\"blink-cmp-bibtex\").setup({\n  -- config\n})\n```\n\n### 4. Clean up the old plugin\n\nAfter updating your config, remove the old plugin directory and reinstall:\n\n```vim\n:Lazy clean\n:Lazy sync\n```\n\nThen restart Neovim.\n\n## Contributing\n\nIssues and pull requests are welcome. Please read\n[`CONTRIBUTING.md`](CONTRIBUTING.md) for development setup, coding guidelines and\nthe review process. A high-level specification lives in [`docs/spec.md`](docs/spec.md)\nso new features stay consistent with the overall goals.\n\nFor detailed technical information, see the [Development Guide](docs/development.md).\nFor API details, consult the [API Reference](docs/api.md).\n\n## License\n\nMIT © 2025 Kristian Niemi\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrissen%2Fblink-cmp-bibtex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkrissen%2Fblink-cmp-bibtex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrissen%2Fblink-cmp-bibtex/lists"}