bibli-ls 0.1.7.0

A simple LSP server for your bibliographies

Bibli Language Server

A Language Server that brings bibliographies into your notes.

Supported LSP capabilities

LSP Features	Behavior
textDocument/definition	Go to the first definition found in the .bib files.
textDocument/references	Find appearance of prefix + ID with ripgrep.
textDocument/hover	Show metadata from .bib files based on configurations.
textDocument/completion	Triggered by the cite_prefix configuration. Show completion of citation ID for bibtex entries and their documentation.
textDocument/diagnoistic	Find citations without a proper entry in the bibfile.
textDocument/implementation	(Non-standard) Open the bibtex url/attachment.

Configuration

Create a configuration file .bibli.toml at the root of your note directory. Here is a sample configuration. For the complete list of configurations, refer to the documentation and the default config.

[backends] # Specifying backends for bibtex libraries
# Backends can be of any names, e.g.,
[backends.mylib]
backend_type = "bibfile" # Available backends: "bibfile", "zotero_api"
bibfiles = ["references.bib"]

[backends.my_lab_lib]
backend_type = "zotero_api"
library_id = "5123456" # Your library ID
library_type = "user" # "user"" or "group"
api_key = "XXXXXXXXXXXXXXXXXXXXXXXX"

[cite] # How to cite bibtex entires, e.g., "[@john2024paper]"
trigger = "@"

[view] # How to display your document externally
viewer = "browser" # Available viewer: `zotero`, `zotero_bbt` and `browser`

[hover.doc_format] # How to display hover documentation
show_fields = ["abstract", "year", "booktitle", "url"]
format = "table" # Available formats: "table"  and "list" (markdown)

[completion.doc_format] # How to display hover documentation
show_fields = ["abstract", "year", "booktitle"]
format = "list"

Backends

Currently, Bibli supports bibfile and zotero_api backends.

• bibfile backend loads the library from a local bibtex file.
• zotero_api backend connects directly to your Zotero web library, removing the need for maintaining separated bibfiles. It cache the results in a bibfile named .{backend name}_{library type}_{library id}.bib. Run the command LSP library.reload_all to refetch the online content.
  • More on setting up citation keys for online libraries

Viewers

We support openning the url in browser, or openning PDF attachment (for zotero-based backends). TODO: support custom PDF viewer. The current viewers are:

• browser: opens the url field in the bibtx entry in your default browser
• zotero_bbt shows the document in Zotero's PDF viewer (require better bibtex to be installed and Zotero to be running)
• zotero shows the entry in Zotero.

Neovim configuration

Automatic configuration through lspconfig has yet to be supported. To enable bibli-ls, put the following code in your Neovim config.

local lspconfig = require("lspconfig")
local configs = require("lspconfig.configs")

if not configs.bibli_ls then
  configs.bibli_ls = {
    default_config = {
      cmd = { "bibli_ls" },
      filetypes = { "markdown" },
      root_dir = lspconfig.util.root_pattern(".bibli.toml"),
      -- Optional: visit the URL of the citation with LSP DocumentImplementation
      on_attach = function(client, bufnr)
        vim.keymap.set({ "n" }, "<cr>", function()
          vim.lsp.buf.implementation()
        end)
      end,
    },
  }
end

lspconfig.bibli_ls.setup({})

Helix configuration

To enable bibli-ls, put the following code in your Helix config (.config/helix/languages.toml):

  [language-server.bibli-ls]
  command = "bibli_ls"
  required-root-patterns = [".bibli.toml"]

  [[language]]
  name = "markdown"
  language-servers = ["bibli-ls"]  # Add other md lsps like zk, marksman, ...
  roots = [".bibli.toml"]

Installation

Install the latest release of bibli-ls through pip:

pip install bibli-ls

# Alternatively, on Arch:
pipx install bibli-ls

Using Nix

Installation via Flakes

In your flake.nix:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

    bibli-ls = {
      url = "github:kha-dinh/bibli-ls";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  # ...
  outputs =
    {
      self,
      bibli-ls,
      nixpkgs,
      ...
    }@inputs:
    let
      pkgs-flake = {
        bibli-ls = bibli-ls.packages.${system}.default;
      };

      customOverlays = [
        (final: prev: {
          flake = pkgs-flake;
        })
      ];
    in
      nixosConfigurations = {
        yourMachine = nixpkgs.lib.nixosSystem {
          inherit system;
          modules = [
            { nixpkgs.overlays = customOverlays; }
            # ...
          ];
        };
      };
}

Then you can use it in your configuration:

{
  environment.systemPackages = [ pkgs.flake.bibli-ls ];
}

Home Manager Configuration

Add bibli-ls to your home-manager configuration:

{ config, pkgs, ... }:
{
  home.packages = [ pkgs.flake.bibli-ls ];

  home.file."Sync/Notes/zk/permanent/.bibli.toml".text = ''
    [backends]
    [backends.library]
    backend_type = "bibfile"
    bibfiles = ["${config.home.homeDirectory}/Sync/Bibliography/library.bib"]
  '';
}

Building from source

From the root directory:

pip install . # --force-reinstall if needed
# Or for Arch
pipx install . # --force-reinstall if needed
# And Nix
nix build # The built package will be available in `./result`. You can also use `nix run`