Default Heading highlight group configuration

[gibbage]

Hello!

I have a question about how the highlight groups for Markdown headings.

In all the examples the top 5 headings each has a different background colour:

However, in the Colors section of the README, the various RenderMarkdownHXBg highlight groups only refer to 3 Default Groups:

With this default configuration I'm confused how someone would see the 5 different colors out of the box without adding additional config.

Here's what mine look like:

Which have no backgrounds - so I realise I have more issues than what I've described above. I'm using NvChad, so maybe there's something in there... but regardless of that issue, I feel like I'm missing some fundamental understanding of how this works.

Thanks heaps for the great plugin!

[MeanderingProgrammer]

Yeah, I can explain what's going on here.

This plugin adopts a common pattern for making plugins have some default color setup while allowing color scheme authors to set plugin specific values. This is done through "default link" highlight groups.

So as a base if your color scheme does not specify a value for "RenderMarkdownH1Bg" the color for "DiffAdd" will be used as a fallback, which every color scheme should define (though not all do).

This also lets you as a user modify the color used by either modifying the call to setup where "RenderMarkdownH1Bg" is set and changing it to any other highlight group, or you can directly set a value for "RenderMarkdownH1Bg" using the vim api:

vim.api.nvim_set_hl(0, 'RenderMarkdownH1Bg', { bg = '#ff0000' })
require('render-markdown').setup({})

In this version you don't need to do anything to the configuration, just set the colors you'd like to use, the above example will set a red background.

The point of all of this though is like I said, color schemes can set values for this plugin to make it fit in nicer with their aesthetic. Each plugin integration is a one off so not every color scheme will support this plugin, but many of the popular ones do. The one used in the examples is tokyonight which sets values here: https://github.com/folke/tokyonight.nvim/blob/main/lua/tokyonight/groups/render-markdown.lua.

Your color scheme should list the plugins it supports somewhere in its README, and you're always welcome to create a PR to add support if they don't, though up to their contributing guidelines.

I wrote a comprehensive document about how colors work in Neovim that you might find helpful as well: https://github.com/MeanderingProgrammer/render-markdown.nvim/wiki/Colors.

[gibbage]

That makes a lot of sense. Thanks for the great explanation! I had a look into the NvChad themes and it looks like they don't support the Render Markdown highlight groups yet. Thanks again!

[srackham]

Thanks for the explanation, I can set the H1 background color with:

vim.api.nvim_set_hl(0, 'RenderMarkdownH1Bg', { bg = '#23273B' })

But cannot not set foreground color RenderMarkdownH1 (documented here https://github.com/MeanderingProgrammer/render-markdown.nvim#colors) with:

vim.api.nvim_set_hl(0, 'RenderMarkdownH1', { fg = '#7CA7FE', bold = true })

This only sets the icon and sign column color (see screenshot).

The only way I was able to change the text foreground color was:

vim.api.nvim_set_hl(0, '@markup.heading.1.markdown', { fg = '#7CA7FE', bold = true })

I'm also unclear about the apparent contradiction with "Fg" being appended to the header foreground name here https://github.com/folke/tokyonight.nvim/blob/775f82f08a3d1fb55a37fc6d3a4ab10cd7ed8a10/lua/tokyonight/groups/render-markdown.lua#L20

[MeanderingProgrammer]

RenderMarkdownH1 description in the linked documentation H1 icons. The heading body comes from your color scheme. You'd need to change the @markup.heading.1.markdown highlight.

I'm also unclear about the apparent contradiction with "Fg" being appended to the header foreground name here

This is an incorrect implementation, that highlight groups is not used by this plugin. Instead we'll use the underlying linked value, i.e. @markup.heading.1.markdown, good catch.

[srackham]

Thank you for the clarification, I didn't twig to the meaning of the H1 icons description.

And thank you for this amazing plugin.

[srackham]

I ended up with the following Lua code to customise header and blockquote colors:

    local header_colors = {
      { '#FFA500', '#2D282C' },
      { '#FFA500', '#2D282C' },
      { '#9FCB71', '#252C2C' },
      { '#19BC9C', '#182931' },
      { '#B89AF0', '#29273A' },
      { '#9B7DD4', '#262336' },
    }
    for i = 1, 6 do
      local fg, bg = header_colors[math.min(i, #header_colors)][1], header_colors[math.min(i, #header_colors)][2]
      vim.api.nvim_set_hl(0, '@markup.heading.' .. i .. '.markdown', { fg = fg, bold = true })
      vim.api.nvim_set_hl(0, 'RenderMarkdownH' .. i, { fg = fg, bold = true })
      vim.api.nvim_set_hl(0, 'RenderMarkdownH' .. i .. 'Bg', { bg = bg })
    end
    vim.api.nvim_set_hl(0, '@markup.quote', { fg = '#F2CDCD' })
    vim.api.nvim_set_hl(0, 'RenderMarkdownQuote', { fg = '#F2CDCD' })