Looking for nvim plugin to navigate between headings in a md or qmd file.

[hopezh]

The md-headers.nvim plugin is simple and easy to use. However, it will mistakenly recognize the comment symbol # in a code block as a heading, as shown below, which defeats the purpose of navigating the headings only.

May I ask if anybody can recommend a neovim plugin for navigating btw headings in a md or qmd file that doesn't have such an issue?

Thanks.

PS: I found markdown-drawer which is very close to what I'm expecting, i.e. it provides a nvim-tree like side panel for your to browse through all the headings in a markdown file. However, there is no guidance on how to install it in nvim. Hope someone can help to shed a light.

[jmbuhr]

You can define a textobject based on treesiter like so: https://github.com/jmbuhr/quarto-nvim-kickstarter/blob/f0c3aef0c31252f0fe8c29167e8920a13291eb33/lua/plugins/quarto.lua#L126
These allow you to do things like jump to next or even select inside etc. like with regular text objects in vim (like word, paragraph etc.).
For example, I use ]] to jump to the next code block or heading.

Furthermore, with a language server for markdown configured such as marskman: https://github.com/jmbuhr/quarto-nvim-kickstarter/blob/f0c3aef0c31252f0fe8c29167e8920a13291eb33/lua/plugins/quarto.lua#L226-L235
headings will become document symbols provided by the lsp. You can view a list with e.g. :Telescope lsp_document_symbols
for :lua vim.lsp.buf.document_symbol() or view them with https://github.com/simrat39/symbols-outline.nvim

Often, you don't need a specialized plugin, you can get a lot of power with these more general plugins that will tie in nicely with the rest of your workflow

[hopezh]

Thank you very much, @jmbuhr.

I managed to edit my nvim config to make marksman work for both markdown md and quarto qmd files. Both symbols-outline.nvim and nvim-navbuddy can recognize the headings in qmd files without including the comment symbol # in a code block.

Using symbols-outline.nvim:

Using nvim-navbuddy:

What I did based on your suggestions:

1. add support to qmd in marksman config file:

[core]
markdown.file_extensions = ['md', 'markdown', 'qmd']

2. add marksman support to quarto in my lua/plugins/nvim-lspconfig.lua file. (I'm still new to the lazyvim config I'm using. So, some of the configs shown below may not be "optimal". Nevertheless, it works!):

return {
    -- add pyright and marksman to lspconfig
    {
        "neovim/nvim-lspconfig",

        ---@class PluginLspOpts
        opts = {
            ---@type lspconfig.options
            servers = {
                -- pyright will be automatically installed with mason and loaded with lspconfig
                pyright = {},
                marksman = {},
            },
        },

        -- add marksman support for markdown and quoarto files
        config = function()
            local lspconfig = require("lspconfig")
            local cmp_nvim_lsp = require("cmp_nvim_lsp")
            local util = require("lspconfig.util")

            local on_attach2 = function(client, bufnr)
                local function buf_set_keymap(...)
                    vim.api.nvim_buf_set_keymap(bufnr, ...)
                end
                local function buf_set_option(...)
                    vim.api.nvim_buf_set_option(bufnr, ...)
                end

                buf_set_option("omnifunc", "v:lua.vim.lsp.omnifunc")
                local opts = { noremap = true, silent = true }

                buf_set_keymap("n", "gh", "<cmd>lua vim.lsp.buf.signature_help()<CR>", opts)
                buf_set_keymap("n", "gi", "<cmd>Telescope lsp_implementations<CR>", opts)
                buf_set_keymap("n", "[d", "<cmd>lua vim.diagnostic.goto_prev()<CR>", opts)
                buf_set_keymap("n", "]d", "<cmd>lua vim.diagnostic.goto_next()<CR>", opts)
                buf_set_keymap("n", "<leader>ll", "<cmd>lua vim.lsp.codelens.run()<cr>", opts)
                client.server_capabilities.document_formatting = true
            end

            local capabilities = vim.lsp.protocol.make_client_capabilities()
            capabilities = cmp_nvim_lsp.default_capabilities(capabilities)
            capabilities.textDocument.completion.completionItem.snippetSupport = true

            -- also need to add the following to $home/.config/marksman/config.toml :
            -- [core]
            -- markdown.file_extensions = ["md", "markdown", "qmd"]
            lspconfig.marksman.setup({
                on_attach = on_attach2,
                capabilities = capabilities,
                filetypes = { "markdown", "quarto" },
                root_dir = util.root_pattern(".git", ".marksman.toml", "_quarto.yml"),
            })
        end,
    },
}