Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rlch/github-notifications.nvim
Statusline + Telescope integration for viewing and interacting with GitHub notifications
https://github.com/rlch/github-notifications.nvim
lua lualine neovim neovim-plugin statusline telescope
Last synced: about 2 months ago
JSON representation
Statusline + Telescope integration for viewing and interacting with GitHub notifications
- Host: GitHub
- URL: https://github.com/rlch/github-notifications.nvim
- Owner: rlch
- Created: 2021-10-09T07:47:55.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2023-06-15T02:27:51.000Z (over 1 year ago)
- Last Synced: 2024-06-17T23:39:39.349Z (3 months ago)
- Topics: lua, lualine, neovim, neovim-plugin, statusline, telescope
- Language: Lua
- Homepage:
- Size: 82 KB
- Stars: 82
- Watchers: 2
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# github-notifications.nvim :bell:
A lightweight, unobstructive, yet WIP neovim plugin for viewing GitHub notifications in your statusline + Telescope popup.
All requests are processed asynchronously, debounced and cached to ensure no delays in your UI! :rocket:
## Installation
Use your favourite package manager:
```lua
use {
'rlch/github-notifications.nvim',
config = [[require('config.github-notifications')]],
requires = {
'nvim-lua/plenary.nvim',
'nvim-telescope/telescope.nvim',
},
}
```
## Getting Started
### Using `gh` CLI (recommended)
Install [the CLI](https://github.com/cli/cli) and you're off!
Make sure you authenticate with `gh auth login`.
### Using personal access token
Call `setup` with your personal access `token` with the `Notifications` scope. You can make one [here](https://github.com/settings/tokens).
```lua
local secrets = require 'secrets'
require('github-notifications').setup {
username = secrets.username,
token = secrets.token,
}
```
**Default config**:
```lua
local defaults = {
github_api_endpoint = 'https://api.github.com', -- Github API Endpoint
username = nil, -- GitHub username
token = nil, -- Your personal access token with `notifications` scope
icon = '', -- Icon to be shown in statusline
hide_statusline_on_all_read = true,
hide_entry_on_read = false, -- Whether to hide the Telescope entry after reading (buggy)
debounce_duration = 60, -- Minimum time until next refresh
cache = false, -- Opt in/out of caching
sort_unread_first = true,
mappings = {
mark_read = '',
hide = 'd', -- remove from Telescope picker, but don't mark as read
-- open_in_browser = 'o', (WIP)
},
prompt_mappings = {
mark_all_read = ''
} -- keymaps that apply on a Telescope prompt level (insert mode)
}
```
### Lua-based statusline
I've only tested this with [lualine](https://github.com/hoob3rt/lualine.nvim), but it should work with any Lua-based statusline that takes a Lua function as an argument for displaying data.
```lua
require('lualine').setup {
...
sections = {
...
lualine_b = { 'branch', require('github-notifications').statusline_notification_count },
...
},
...
}
```
You can also use `statusline_notifications()` and build your own formatter:
```lua
local ghn_formatter = function()
local data = require('github-notifications').statusline_notifications()
if data.count > 10 then
return data.icon .. ' purge time'
elseif data.count == 0 then
return ''
end
return data.icon .. tostring(data.count)
end
```
### Telescope
Optionally load the extension using:
```lua
require('telescope').load_extension 'ghn'
```
So that `require('telescope').extensions.ghn.notifications()` can open the popup.
Otherwise, you can simply call:
```lua
require('github-notifications.menu').notifications()
```
I'm aware my API design is abysmal
## TODOs
- [ ] Add support for CI status for current branch in statusline
- [ ] Redirect to follow-up URL (instead of API url)
- [x] Refresh UI on state changes (i.e. when marking notifications as read)
- [x] Add highlights to Telescope entries
- [ ] Improve Telescope preview UI instead of being lazy with markdown
- [x] Hide notifications without Telescope shitting itself
## Contributing :ok_hand:
Please lmao