Skip to content

README.md

Latest commit

 

History

History
111 lines (79 loc) · 3.88 KB

README.md

File metadata and controls

111 lines (79 loc) · 3.88 KB

telescope-orgmode.nvim

tests

Fuzzy search, refile, and link insertion for orgmode with telescope.nvim or snacks.nvim.

Full reference: DOCS.org (source) — or :help telescope-orgmode once installed.

Features

Search Headlines

Jump to any heading in your org_agenda_files. Filter by typing — the search matches against filename, tags, TODO state, and title.

search-headlines.webm

Search Org Files

Press <C-Space> to switch to file-level search. Files with a #+TITLE: show the title instead of the filename.

Refile

Move a headline under a different parent. Place the cursor on a headline, open the refile picker, pick the destination.

refile.webm

Tag Search

Pick a tag, then browse the headlines that carry it. <C-t> returns to the tag list.

tag-search.webm

Insert Link

Search a headline or file and insert an org link at the cursor.

insert-link.webm

Quick start

Snacks.picker

{
  "nvim-orgmode/telescope-orgmode.nvim",
  event = "VeryLazy",
  dependencies = {
    "nvim-orgmode/orgmode",
    "folke/snacks.nvim",
  },
  config = function()
    local tom = require("telescope-orgmode")
    tom.setup({ adapter = "snacks" })

    vim.keymap.set("n", "<leader>fh", tom.search_headings, { desc = "Org headlines" })
    vim.keymap.set("n", "<leader>ft", tom.search_tags,     { desc = "Org tags" })
    vim.keymap.set("n", "<leader>r",  tom.refile_heading,  { desc = "Org refile" })
    vim.keymap.set("n", "<leader>li", tom.insert_link,     { desc = "Org insert link" })
  end,
}

Telescope

{
  "nvim-orgmode/telescope-orgmode.nvim",
  event = "VeryLazy",
  dependencies = {
    "nvim-orgmode/orgmode",
    "nvim-telescope/telescope.nvim",
  },
  config = function()
    require("telescope").load_extension("orgmode")

    local ext = require("telescope").extensions.orgmode
    vim.keymap.set("n", "<leader>fh", ext.search_headings, { desc = "Org headlines" })
    vim.keymap.set("n", "<leader>ft", ext.search_tags,     { desc = "Org tags" })
    vim.keymap.set("n", "<leader>r",  ext.refile_heading,  { desc = "Org refile" })
    vim.keymap.set("n", "<leader>li", ext.insert_link,     { desc = "Org insert link" })
  end,
}

See DOCS.org for Without plugin manager and other setups.

Documentation

The full reference manual lives in DOCS.org and ships as a Vim help file. After install: :help telescope-orgmode.

  • Pickers — search_headings, search_tags, refile_heading, insert_link
  • Keybindings — <C-Space>, <C-f>, <C-t>, <C-s>
  • Configuration — display options, custom property columns, search priority, picker defaults
  • Adapter options — Telescope passthrough and Snacks snacks sub-namespace
  • Profiles — custom data sources, factory resolvers, resolver interface
  • Architecture — adapter / lib / entry_maker layering

Contributing

make test       # Run tests
make format     # Format with StyLua
make lint       # Check formatting
make docs       # Regenerate doc/telescope-orgmode.txt from DOCS.org
make demo-env   # Interactive demo environment

doc/telescope-orgmode.txt is generated from DOCS.org via panvimdoc — do not edit it directly. CI rebuilds and commits it on push to main.