Rendering Markdown in help buffers

[thevinchi]

I'm trying to ensure all help filetypes are rendered as markdown. Unfortunately the config below is not working:

{
    'MeanderingProgrammer/render-markdown.nvim',
    dependencies = { 'nvim-treesitter/nvim-treesitter', 'echasnovski/mini.nvim' },
    ft = {
        'markdown', 'codecompanion', 'help'
    },
    opts = {
        enabled = true,
        render_modes = true,
        sign = {
            enabled = false
        }
    },
}

I was able to get this to work by adding the following to init.lua but I worry about the implications of clobbering the filetype:

vim.api.nvim_create_autocmd("FileType", {
    pattern = 'help',
    callback = function(args)
        vim.bo.filetype = 'markdown'
    end
})

Is this the only way, or am I missing something obvious? Searching for "Render neovim help buffers as markdown" is useless given the ubiquity of the word "help" and it's association with "neovim" in google's index. :)

For bonus points, whenever a buffer with snacks_picker_preview has help content, it would also render as markdown, but I imagine that's near impossible as just about any file type can populate those buffers.

[MeanderingProgrammer]

I'm trying to ensure all help filetypes are rendered as markdown.

By default help files are parsed as vimdoc. You can override this to markdown by adding this line somewhere in your config:

vim.treesitter.language.register('markdown', 'help')

Which tells neovim to parse help files as markdown without changing the filetype. You also need to keep help in the ft list for this plugin since the filetype has not been changed.

While this will technically "work" this doesn't actually change the contents of the help docs which are not written using markdown so the results are probably worse than just using treesitter with the vimdoc parser installed. But if you like the result feel free to use it.

In order to produce what I'm assuming you're looking for you'd need something to actively overwrite help buffers from the vimdoc format to markdown, which would be non-trivial and is not something I personally have any interest in attempting. It could be a good idea for a plugin if one doesn't already exist if you want to give it a shot. I generate the help doc for this plugin from the README using panvimdoc which itself uses pandoc, you might be able to use a similar approach to do the opposite.

For bonus points, whenever a buffer with snacks_picker_preview has help content

I don't use the snacks picker so am unsure what you mean by the preview having "help content", but in general interacting with picker preview windows is not straightforward since they have things in place to speed up rendering that essentially make the buffer invisible to other plugins. Typically an integration needs to be added either with some option the plugin provides or directly in the code for the picker.

[thevinchi]

I'm relatively new to the neovim ecosystem so I was totally unaware of vimdoc as a thing, and now I feel silly. :)

The markup is similar enough to markdown, that it didn't even occur to me it was something different. Adding vimdoc to the list of parsers installed by treesitter was exactly what I needed to hear. Now my help buffers are all properly rendered and much easier to read.

Thank you for taking the time to respond and learn me some things. ;-)

[MeanderingProgrammer]

No problem, happy to help!

There are some APIs available if you ever run into something like this in the future.

• vim.bo.filetype: stores the filetype of the current buffer
• vim.treesitter.language.get_lang: returns the language associated with an input filetype

So combining these running the following command :lua vim.print(vim.treesitter.language.get_lang(vim.bo.filetype)) will print the language of the current buffer.

The language is the same as the parser name, so once you have that you can check if you have the parser installed and add it if not.