github-notifications.nvim 🔔
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!
Installation
Use your favourite package manager:
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 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.
local secrets = require 'secrets'
require('github-notifications').setup {
username = secrets.username,
token = secrets.token,
}Default config:
local defaults = {
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 = '<CR>',
hide = 'd', -- remove from Telescope picker, but don't mark as read
-- open_in_browser = 'o', (WIP)
},
prompt_mappings = {
mark_all_read = '<C-r>'
} -- keymaps that apply on a Telescope prompt level (insert mode)
}Lua-based statusline
I've only tested this with lualine, but it should work with any Lua-based statusline that takes a Lua function as an argument for displaying data.
require('lualine').setup {
...
sections = {
...
lualine_b = { 'branch', require('github-notifications').statusline_notification_count },
...
},
...
}You can also use statusline_notifications() and build your own formatter:
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)
endTelescope
Optionally load the extension using:
require('telescope').load_extension 'ghn'So that require('telescope').extensions.ghn.notifications() can open the popup.
Otherwise, you can simply call:
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)
- Refresh UI on state changes (i.e. when marking notifications as read)
- Add highlights to Telescope entries
- Improve Telescope preview UI instead of being lazy with markdown
- Hide notifications without Telescope shitting itself
Contributing 👌
Please lmao