crispgm / telescope-heading.nvim

An extension for telescope.nvim that allows you to switch between headings

telescope-heading.nvim

An extension for telescope.nvim that allows you to switch between document's headings.

Supported File Types

File Type	Tree-sitter	Notes
AsciiDoc	✅
Beancount	✅
LaTeX	⬜
Markdown	✅	including vimwiki, vim-pandoc-syntax, and vim-gfm-syntax
Neorg	✅
OrgMode	⬜
ReStructuredText	✅
Vimdoc (help)	✅

Setup

Install with your favorite package manager:

use('nvim-telescope/telescope.nvim')
use('crispgm/telescope-heading.nvim')

You can setup the extension by adding the following to your config:

require('telescope').load_extension('heading')

Tree-sitter Support

telescope-heading supports Tree-sitter for parsing documents and finding headings. But not all file types are supported, you may check Supported File Types section and inspect the Tree-sitter column.

-- add nvim-treesitter
use('nvim-treesitter/nvim-treesitter')

-- make sure you have already installed treesitter modules
require('nvim-treesitter.configs').setup({
    ensure_installed = {
        -- ..
        'markdown',
        'rst',
        -- ..
    },
})

-- enable treesitter parsing
local telescope = require('telescope')
telescope.setup({
    -- ...
    extensions = {
        heading = {
            treesitter = true,
        },
    },
})

-- `load_extension` must be after `telescope.setup`
telescope.load_extension('heading')

If nvim-treesitter was not correctly loaded, it would have fallen back to normal parsing. You may check nvim-treesitter configurations and whether your language is TSInstalled.

Telescope Picker Options

We may specific picker options for telescope-heading, which overrides the general telescope picker options.

local telescope = require('telescope')
telescope.setup({
    -- ...
    extensions = {
        heading = {
          picker_opts = {
              layout_config = { width = 0.8, preview_width = 0.5 },
              layout_strategy = 'horizontal',
          },
        },
        -- ...
    },
})

Usage

:Telescope heading

Development

Init:

make init

Load telescope-heading locally:

nvim --noplugin -u scripts/minimal_init.vim ./README.md # replace with /path/to/testfile
# or
make test

Lint:

make lint

Contributing

All contributions are welcome.

License

Copyright 2023 David Zhang. MIT License.

telescope-heading.nvim's Issues

Option for preview

Hey, thanks for the extension ! Can you add option to show preview of the content of the headings ?

Vim help headings don’t show

The headings work fine for me in Markdown documents but not in help files

Support for vim help file

It would be convenient if telescope-heading shows headers of vim help file, like this:

==================================
SECTION 1
...
==================================
SECTION 2
...

Help treesitter parser has changed

I am getting the following error if I invoke :Telescope heading in a vim help file:

No treesitter language parser installed for [help]. Fallback to normal parser.

My guess is this is related to the change of the treesitter parser for help files to "vimdoc" neovim/tree-sitter-vimdoc@b2ec4ec

Use TreeSitter to parse document for headings

Are there any plans to use https://github.com/nvim-treesitter/nvim-treesitter for parsing documents and finding headings? I think it would be a cool improvement and this could open up the possibility for more features later on, such as finding code blocks, lists, etc.

I'm talking mostly about Markdown here.

Is there a way to not sort the headings?

hello,

what an awesome plugin!

Is there a way to not sort the headings in the picker?

this would be very convenient for markdown files, where the headings have a logical order.

for example:

# heading 1
## sub1
## sub2
# heading 2
## a title
## another title

The plugin works perfectly as is, just wondering if I've missed something.

feat: better preview with the heading line at the top of the window

Hello, thanks for an awesome plugin!

Currently, default previewer (typically telescope.previewers.vim_buffer_vimgrep) positions the selected line at the center of preview window.
This behavior is good for pickers like telescope's builtin live_grep, but I prefer selected line (heading line) is positioned at the top of preview window for the heading picker, because all contents relevant to the selected heading are after (and not before) the heading line.

So, I implemented custom previewer for this purpose.

local previewers = require "telescope.previewers"
local from_entry = require "telescope.from_entry"
local conf = require("telescope.config").values

local ns = vim.api.nvim_create_namespace("")

function make_heading_previewer()
  local jump_to_line = function (self, bufnr, entry)
    print(self.state.bufname)
    print(vim.inspect(entry))
    vim.api.nvim_buf_clear_namespace(bufnr, ns, 0, -1)
    vim.api.nvim_buf_add_highlight(bufnr, ns, "TelescopePreviewLine", entry.lnum-1, 0, -1)
    vim.api.nvim_win_set_cursor(self.state.winid, { entry.lnum, 0 })
    vim.api.nvim_buf_call(bufnr, function()
      vim.cmd "norm! zt"
    end)
  end
  return previewers.new_buffer_previewer {
    title = "Heading Preview",
    get_buffer_by_name = function (self, entry)
      return from_entry.path(entry, false)
    end,
    define_preview = function (self, entry)
      local p = from_entry.path(entry, true)
      if p == nil or p == "" then
        return
      end
      conf.buffer_previewer_maker(p, self.state.bufnr, {
        bufname = self.state.bufname,
        winid = self.state.winid,
        callback = function(bufnr)
          jump_to_line(self, bufnr, entry)
        end,
      })
    end,
  }
end

And it shows preview like this.

This configuration can be controlled completely in user side, but I don't think all users of this plugin want to implement custom previewer. So I think it is nice to use this heading previewer as default if you would like, or at least provide this previewer as the part of this plugin.
If you like this idea, I will happily submit PR.

Thank you!

Support Markdown Pandoc filetype

Hello,
Is it possible to modify the Markdown.lua file to accept Markdown.pandoc filetypes ? I'm using vim-pandoc/vim-pandoc-syntax with

augroup pandoc_syntax                                                                                                                                                                               
    au! BufNewFile,BufFilePre,BufRead *.md set filetype=markdown.pandoc                                                                                                                             
    au! BufNewFile,BufFilePre,BufRead *.eml set filetype=markdown.pandoc                                                                                                                            
augroup END  

So Telescope won't recognize the .md files.

Thank you !

Telescope deprecation warning

Invoking :Telescope heading and making a selection raises this warning from Telescope.

actions.get_selected_entry() is deprecated. Use require('telescope.actions.state').get_selected_entry() instead

Feature request: Support for custom filetypes using header characters (or just .vimrc / init.vim)

Hello,
thanks for the plugin!

I use mutliple comment symbols to define headings in several filetypes (including my .vimrc)

" this is a comment
"" Heading: where my settings go
let g:foo=bar
"" Heading: where my plugins go
Plug 'crispgm/telescope-heading.nvim'
""" this is a subheading

This is almost identical to how headings are managed in markdown for instance. Is it possible with the current plugin to extend heading search to work in my .vimrc? Or would it be possible to add configurable parameters for additional filetypes by specifying the characters used for headings?

Possibility to support LaTeX tex files

Is it possible to implement searching through sections for tex files?