Markdown Headers is a simple/basic Neovim plugin that allows you to easily navigate between headings in a Markdown file.

• It saves time and effort when navigating long and complex markdown documents.
• It works for both Markdown and HTML headings.
• It helps you keep track of your location in the document.
• It can improve your productivity and efficiency when writing or editing markdown documents.

There are probably plenty of other plugins that do the exact same thing and are probably nicer to look at 😅, feel free to use them. I only made this plugin to learn a bit more about the Neovim API and for FUN 😉.

Currently, the plugin is only able to recognize and extract headings that are constructed on a single line. This is because the regular expression used to match headings only looks for the start and end tags of a heading element on the same line.

# Heading

<h1>Heading</h1>

Headings that span multiple lines, such as the one shown in the example below, will not be recognized by the plugin because the start and end tags are not on the same line. This means that the regular expression will not match the heading, and it will not be included in the list of headings displayed in the popup window.

<h1>
    Heading
</h1>

I understand that this limitation may be frustrating, and I apologize for the inconvenience. I am open to considering adding support for headings that span multiple lines in the future. If you would like to see this feature implemented, please feel free to submit a pull request or open an issue. Your contributions are always welcome and appreciated 😀!

1. Add this to your Neovim config:

use {
    'ESSO0428/md-headers.nvim',
    requires = {
        'nvim-lua/plenary.nvim'
    }
}

2. Run :PackerSync to install the plugin on your machine.

1. Add the following to your Neovim config:

Plug 'nvim-lua/plenary.nvim'
Plug 'ESSO0428/md-headers.nvim'

2. Run :PlugInstall to install the plugin on your machine.

1. Clone this repository into your Neovim ~/.config/nvim/pack/plugins/start/directory.

You can configure the plugin by adding the following to your init.lua:

All the examples below are in lua. You can use the same examples in .vim files by wrapping them in lua heredoc like this:

lua << END
    require('md-headers').setup()
END

Here is an example of how you can configure the plugin in your init.lua file. The example below shows the default configuration, which you can customize by modifying the values of the different settings.

local md_headers_status_ok, md_headers = pcall(require, 'md-headers')
if not md_headers_status_ok then
    return
end

-- Configure the popup window settings.
md_headers.setup {
    width = 60,
    height = 10,
    borderchars = { '─', '│', '─', '│', '╭', '╮', '╯', '╰'}
}

-- Shorten function name.
local keymap = vim.keymap.set
-- Silent keymap option.
local opts = { silent = true }

-- Set keymap.
keymap('n', '<leader>mdh', ':MarkdownHeaders<CR>', opts)
keymap('n', '<leader>mdhc', ':MarkdownHeadersClosest<CR>', opts)

You can customize the following settings:

• width: The width of the Markdown Headers popup window.
  • For example, setting the width to '100' will result in the popup window being 100 columns wide.
• height: The height of the Markdown Headers popup window.
  • For example, setting the height to '30' will result in the popup window being 30 lines high.
• borderchars: The character that will be used to draw the border around the popup window.
  • For example, setting the borderchars to '{ '', '', '', '', '', '', '', '' }' will result in the popup window being drawn without a border.

If you do not configure Markdown Headers or leave certain settings unconfigured, it will use its default settings for those settings.

NOTE: This will start Markdown Headers with it's default configuration (refer to the header above).

To use the Markdown Headers plugin, use the :MarkdownHeaders command to display a list of headings in the current buffer in a floating window. The headings will include both Markdown and HTML headings. You can navigate to a heading by pressing Enter on it, and the cursor will move to the corresponding heading in the main window. You can also press Escape or q to close the window. The window will also close automatically when you've selected a heading.

To start the plugin with the cursor already positioned on the closest heading, use the :MarkdownHeadersClosest command instead.

Examples:

:MarkdownHeaders
:MarkdownHeadersClosest

Markdown Headers is licensed under the MIT License. See the LICENSE.md file for more information.

Contributions are welcome! Please feel free to submit a pull request or open an issue for any bugs or feature requests.

• Support headings that are spread across multiple lines.
  • HTML only.
• To be continued...