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.

localsecrets=require'secrets'require('github-notifications').setup {
username=secrets.username,
token=secrets.token,
}

Default config:

localdefaults= {
github_api_endpoint='https://api.github.com', -- Github API Endpointusername=nil, -- GitHub usernametoken=nil, -- Your personal access token with `notifications` scopeicon='', -- Icon to be shown in statuslinehide_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 refreshcache=false, -- Opt in/out of cachingsort_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:

localghn_formatter=function()
localdata=require('github-notifications').statusline_notifications()
ifdata.count>10thenreturndata.icon..' purge time'elseifdata.count==0thenreturn''endreturndata.icon..tostring(data.count)
end

Telescope

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