https://github.com/antlis/telescope-gist
Telescope extension for managing GitHub Gists — list, preview with syntax highlighting, edit, delete, and create from inside Neovim
https://github.com/antlis/telescope-gist
gists github lazyvim neovim neovim-plugin telescope-extension
Last synced: 3 days ago
JSON representation
Telescope extension for managing GitHub Gists — list, preview with syntax highlighting, edit, delete, and create from inside Neovim
- Host: GitHub
- URL: https://github.com/antlis/telescope-gist
- Owner: antlis
- License: mit
- Created: 2026-04-15T23:50:20.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-16T01:05:40.000Z (2 months ago)
- Last Synced: 2026-04-16T02:35:37.021Z (2 months ago)
- Topics: gists, github, lazyvim, neovim, neovim-plugin, telescope-extension
- Language: Lua
- Size: 22.5 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# telescope-gist
A [Telescope](https://github.com/nvim-telescope/telescope.nvim) extension for managing
your GitHub Gists from inside Neovim — built for [LazyVim](https://www.lazyvim.org/), works anywhere.
## Why
Existing options are incomplete:
- `gh.nvim` ignores gists entirely.
- `gist.nvim` can list/open but editing is clunky and delete is missing.
- `telescope-github.nvim` shows gists with no syntax highlight in preview and is effectively unmaintained.
`telescope-gist` aims to be the missing piece: a Telescope-native picker with **list, preview, open-and-edit, delete, create, and refresh** — all with a fast cache so it never feels slow.
## Features
- `:Telescope gist list` — picker with visibility, description, file count, relative date
- Preview with **filetype-aware syntax highlighting**
- `:GistCreate` — create a gist from the current buffer; supports visual selection (`:'<,'>GistCreate` or `gn` in visual mode)
- Picker actions:
- `` open gist for editing — one buffer per file for multi-file gists; `:w` PATCHes content back to GitHub
- `` delete gist (with confirm)
- `` new gist from current buffer
- `` yank gist URL to clipboard
- `` force-refresh cached list
- **Two-layer cache** (memory + disk JSON, TTL 10 min) — picker opens instantly after first load, even across Neovim restarts
## Requirements
- Neovim 0.10+
- [`gh`](https://cli.github.com/) CLI, authenticated via `gh auth login`
- [`telescope.nvim`](https://github.com/nvim-telescope/telescope.nvim)
- [`plenary.nvim`](https://github.com/nvim-lua/plenary.nvim) (transitively required by Telescope)
## Installation
### lazy.nvim / LazyVim
```lua
{
"antlis/telescope-gist",
dependencies = {
{
"nvim-telescope/telescope.nvim",
cmd = "Telescope",
dependencies = { "nvim-lua/plenary.nvim" },
},
},
config = function()
require("telescope-gist").setup({})
require("telescope").load_extension("gist")
end,
keys = {
{ "gG", "Telescope gist list", desc = "Gist List" },
{ "gn", ":GistCreate", desc = "Create Gist", mode = { "n", "v" } },
},
}
```
### packer.nvim
```lua
use {
"antlis/telescope-gist",
requires = { "nvim-telescope/telescope.nvim", "nvim-lua/plenary.nvim" },
config = function()
require("telescope-gist").setup({})
require("telescope").load_extension("gist")
end,
}
```
### vim-plug
```vim
Plug 'nvim-lua/plenary.nvim'
Plug 'nvim-telescope/telescope.nvim'
Plug 'antlis/telescope-gist'
```
Then in your `init.lua`:
```lua
require("telescope-gist").setup({})
require("telescope").load_extension("gist")
```
### mini.deps
```lua
MiniDeps.add({
source = "antlis/telescope-gist",
depends = { "nvim-telescope/telescope.nvim", "nvim-lua/plenary.nvim" },
})
require("telescope-gist").setup({})
require("telescope").load_extension("gist")
```
### Manual / other managers
Clone the repo anywhere on your `runtimepath` and ensure `telescope.nvim` + `plenary.nvim` are installed. Then add to your config:
```lua
require("telescope-gist").setup({})
require("telescope").load_extension("gist")
```
## Configuration
```lua
require("telescope-gist").setup({
limit = 100, -- gh gist list --limit
cache = {
enabled = true,
ttl_minutes = 10,
dir = vim.fn.stdpath("cache") .. "/telescope-gist",
},
keymaps = {
open = "", -- opens for editing; :w pushes back via PATCH /gists/
delete = "",
new = "",
yank_url = "",
refresh = "",
},
})
```
## Roadmap: data backend
v0.1 uses the `gh` CLI as the data source — zero auth code, ships fast, and
the two-layer cache hides subprocess overhead.
v0.2 will move to a **hybrid model**: keep `gh` for auth bootstrap (`gh auth token`)
but talk to the GitHub REST/GraphQL API directly via `plenary.curl`. Wins:
- **ETag / `If-None-Match`** — cache validation in <50ms with no payload transfer
- Lower per-call latency (no subprocess spawn)
- Single round-trip for list + first-file content (GraphQL)
- Still no PAT prompts: token comes from the user's existing `gh` auth
The boundary lives entirely inside `lua/telescope-gist/gh.lua` — every other
module already consumes a normalized shape that matches the REST API, so the
swap is contained.
## Architecture
```
lua/
├── telescope/_extensions/gist.lua -- Telescope extension entry point
└── telescope-gist/
├── init.lua -- public API: setup(), list()
├── config.lua -- defaults + tbl_deep_extend merge
├── gh.lua -- async wrapper around `gh` CLI
├── cache.lua -- two-layer cache (memory + disk TTL)
├── pickers.lua -- Telescope picker construction
├── previewer.lua -- filetype-aware preview buffer
└── actions.lua -- open / edit / delete / new / yank / refresh
```
## License
MIT