Metadata-Version: 2.1
Name: bibli_ls
Version: 0.1.6.2
Summary: A simple LSP server for your bibliographies
Author-email: Kha Dinh <dalo2903@gmail.com>
Project-URL: Homepage, https://github.com/kha-dinh/bibli-ls
Project-URL: Issues, https://github.com/kha-dinh/bibli-ls/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bibtexparser==2.0.0b4
Requires-Dist: watchdog==6.0.0
Requires-Dist: pyzotero==1.5.25
Requires-Dist: py_markdown_table==1.2.0
Requires-Dist: pygls==2.0.0a2
Requires-Dist: tosholi==0.1.0
Requires-Dist: mdformat==0.7.19
Requires-Dist: ripgrepy==2.0.0
Requires-Dist: typing_extensions==4.12.2
Provides-Extra: test
Requires-Dist: pytest==8.3.3; extra == "test"
Requires-Dist: pytest-asyncio; extra == "test"
Requires-Dist: pyhamcrest==2.1.0; extra == "test"
Provides-Extra: doc
Requires-Dist: pydoc-markdown==4.8.2; extra == "doc"

<h3 align="center">
  <img
    src="https://raw.githubusercontent.com/kha-dinh/bibli-ls/main/docs/logo.jpeg"
    width="100"
    alt="Logo"
  /><br />
</h3>

# Bibli Language Server

A [Language Server](https://microsoft.github.io/language-server-protocol/) that brings bibliographies into your notes.

[![image-version](https://img.shields.io/pypi/v/bibli-ls.svg)](https://python.org/pypi/bibli-ls)
[![image-license](https://img.shields.io/pypi/l/bibli-ls.svg)](https://python.org/pypi/bibli-ls)
[![image-python-versions](https://img.shields.io/badge/python->=3.8-blue)](https://python.org/pypi/bibli-ls)

## Supported LSP capabilities

| LSP Features                                                                                                                                           | Behavior                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| [textDocument/definition](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_definition)         | Go to the first definition found in the `.bib` files.                                                                    |
| [textDocument/references](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_references)         | Find appearance of `prefix + ID` with ripgrep.                                                                           |
| [textDocument/hover](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_hover)                   | Show metadata from `.bib` files based on configurations.                                                                 |
| [textDocument/completion](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_completion)         | Triggered by the `cite_prefix` configuration. Show completion of citation ID for bibtex entries and their documentation. |
| [textDocument/diagnoistic](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_completion)        | Find citations without a proper entry in the bibfile.                                                                    |
| [textDocument/implementation](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_implementation) | (Non-standard) Open `url` field of the citation in an external browser (TODO: make configurable).                        |

## 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](/docs/configurations.md) and the [default config](/docs/default-config.toml).

```toml

[backends]
# Backends can be of any names
[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]
prefix = "@" # e.g., "@john2024paper"

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

[completion.doc_format]
show_fields = ["abstract", "year", "booktitle"]
format = "list"

```

## Installation

Install the latest release of `bibli-ls` through `pip`:

```bash
pip install bibli-ls

# Alternatively, on Arch:
pipx install bibli-ls
```

### Neovim

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

```lua
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({})
```

## 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](/docs/custom-cite-keys.md)

## Building from source

From the root directory:

```bash
pip install . # --force-reinstall if needed
# Or for Arch
pipx install . # --force-reinstall if needed


```
