https://github.com/hamidi-dev/org-telescope.nvim
https://github.com/hamidi-dev/org-telescope.nvim
Last synced: 11 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/hamidi-dev/org-telescope.nvim
- Owner: hamidi-dev
- Created: 2025-07-11T17:02:41.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-07-13T08:01:20.000Z (11 months ago)
- Last Synced: 2025-07-13T09:25:47.299Z (11 months ago)
- Language: Lua
- Size: 11.7 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.org
Awesome Lists containing this project
README
* org-telescope.nvim
A Neovim plugin that tracks and navigates org-mode headlines with Telescope integration.
** Features
- Automatically tracks org-mode headlines as you navigate
- Browse all headlines across your org files
- Persistent history across Neovim sessions
- History reloaded each time the picker opens
- Telescope integration for browsing and searching history
- Preview headlines with file context
- Filter by headline level and TODO state (TODO, PROGRESS, DONE, WAITING)
- Toggle between chronological and reverse chronological order
- Multi-select entries for batch operations
- Delete history entries
- Refile headlines to other files or under different headings (toggle target mode with )
- Configurable headline level tracking
- Exclude specific files from tracking
** Requirements
- Neovim 0.7+
- [[https://github.com/nvim-telescope/telescope.nvim][telescope.nvim]]
** Installation
*** Using [[https://github.com/folke/lazy.nvim][lazy.nvim]]
#+begin_src lua
{
'username/org-telescope.nvim',
dependencies = { 'nvim-telescope/telescope.nvim' },
config = true,
-- or with custom configuration:
-- config = function()
-- require('org-telescope').setup({
-- -- your custom config here
-- })
-- end
}
#+end_src
** Configuration
The plugin works with default settings, but you can customize it to your needs:
#+begin_src lua
require('org-telescope').setup({
todo_states = {
{ name = "TODO", color = "#FF5555", highlight = "OrgTodoRed", keymaps = { normal = "t", insert = "" } },
{ name = "PROGRESS", color = "#FFAA00", highlight = "OrgProgress", keymaps = { normal = "p", insert = "" } },
{ name = "DONE", color = "#50FA7B", highlight = "OrgDone", keymaps = { normal = "d", insert = "" } },
{ name = "WAITING", color = "#BD93F9", highlight = "OrgWaiting", keymaps = { normal = "w", insert = "" } },
},
picker = {
initial_mode = "insert", -- global initial mode
reverse_sort = true,
},
pickers = {
browse_headlines = { initial_mode = "insert", preview = false },
browse_history = { initial_mode = "normal", preview = true },
refile = { initial_mode = "insert", preview = true },
},
-- File-Scope ---------------------------------------------------------
-- 'patterns' and 'org_folder' work together:
-- only files matching the patterns inside 'org_folder' are considered.
-- If 'org_folder' is nil, patterns apply globally.
patterns = { "*.org" }, -- File patterns to track
org_folder = nil, -- Restrict tracking to this folder (nil tracks all patterns)
exclude_files = { "private.org", "secrets.org" }, -- Files to exclude (full paths or filenames)
smart_tracking = {
enabled = true,
auto_update = true,
search_all_files = true,
interval_ms = 25,
},
refile = {
default_mode = "file", -- or "heading"
},
history = {
history_file = vim.fn.stdpath("state") .. "/org-telescope/history.json",
auto_prune = false,
max_headline_level = 2, -- Maximum headline level to track (default: 2)
org_folder_only = false, -- Limit tracking to org_folder
},
display = {
-- column widths as percentages of the picker window
with_time = { todo = 8, heading = 70, time = 10, file = 10 },
without_time = { todo = 8, heading = 70, file = 20 },
},
-- Keymaps
keymaps = {
open_history = "oh",
browse_headlines = "ob",
refile_heading = "or",
toggle_sort = "",
toggle_level_filter = "",
toggle_preview = "",
clear_history = "ohc",
delete_entry = {
normal = "D",
insert = "",
},
filter_all = { normal = "a", insert = "" },
},
debug = false, -- Debug mode
})
#+end_src
Column widths are calculated from the full picker width, so enabling the preview pane does not change their size. To customize the percentages use the `display` table:
#+begin_src lua
require("org-telescope").setup({
display = {
without_time = { todo = 10, heading = 80, file = 10 },
},
})
#+end_src
** Usage
*** Default Keymaps
| Keymap | Action |
|-----------------------+---------------------------------------------|
| oh | Open org headline history in Telescope |
| ob | Browse all org headlines in Telescope |
| ohc | Clear org headline history |
| or | Refile current heading |
| (in Telescope) | Toggle between newest/oldest first |
| (in Telescope) | Toggle between all levels/only level 1 |
| (in Telescope) | Toggle preview window |
| D (normal mode) | Delete selected entry from history |
| (insert mode) | Delete selected entry from history |
| | Toggle selection and move up |
| t (normal mode) | Filter by TODO state |
| p (normal mode) | Filter by PROGRESS state |
| d (normal mode) | Filter by DONE state |
| w (normal mode) | Filter by WAITING state |
| a (normal mode) | Show all states |
| (insert mode) | Filter by TODO state |
| (insert mode) | Filter by PROGRESS state |
| (insert mode) | Filter by DONE state |
| (insert mode) | Filter by WAITING state |
| (insert mode) | Show all states |
*** Commands
The plugin provides the following Lua functions that you can map to your own keybindings:
- ~require('org-telescope').open_telescope_history()~ - Open the history picker
- ~require('org-telescope').open_telescope_all_headlines()~ - Browse all headlines
- ~require('org-telescope').clear_history()~ - Clear the history
- ~require('org-telescope').delete_history_entry(index)~ - Delete a specific entry
- ~require('org-telescope').delete_multiple_entries(indices)~ - Delete multiple entries
- ~require('org-telescope').refile_current_heading()~ - Refile the current heading
** How It Works
The plugin provides the following main features:
*** History Tracking
The plugin automatically tracks your cursor movements in org files and records headline information when you navigate to them. The history is stored in a JSON file and persists across Neovim sessions.
*** All Headlines Browsing
You can browse all headlines across your org files without needing to visit them first. This is useful for getting an overview of your org files or quickly jumping to a specific headline.
*** Refile Headings
Move the current heading to another file or headline.
Works from anywhere inside the heading.
Press to toggle between file and headline targets.
The source is cleaned up, destination adjusted and saved.
*** Common Features
Both history and all headlines views provide:
- Color-coded TODO states (TODO: red, PROGRESS: orange, DONE: green, WAITING: purple)
- Optional preview of the headline in its file context
- Jump directly to the headline location
- Filter by headline level (all levels or only level 1)
- Filter by TODO state (TODO, PROGRESS, DONE, WAITING, or all)
- Toggle sort order (newest/oldest first)
- Multi-select entries for batch operations (in history view)
- In the refile picker, press to switch between file and heading targets
** Troubleshooting
If you encounter issues:
1. Enable debug mode in your configuration:
#+begin_src lua
require('org-telescope').setup({ debug = true })
#+end_src
2. Check the history file location to ensure it's being created properly
3. If certain files aren't being tracked, check your `org_folder` and `exclude_files` settings