feature: Highlight groups

[scottmckendry]

Is your feature request related to a problem? Please describe.

There is currently no easy way for colorsheme maintainers to add support for this plugin. While the defaults are sensible, there are a few things one might like to change to give the best out-of-the-box experience without users having to make too many changes in the config.

Describe the solution you'd like

Each component currently has one or more "highlight` properties that use either tree-sitter groups or a default Neovim highlight group.

What I propose is to define new highlight groups in the plugin that link to the existing highlights. This can be executed somewhere in the plugin's setup() logic.

For example, for headings, you might add something to the effect of:

vim.api.nvim_set_hl(0, "RenderMarkdownHeading1", { link = "@markup.heading.1.markdown", default = true })
vim.api.nvim_set_hl(0, "RenderMarkdownHeading2", { link = "@markup.heading.2.markdown", default = true })

vim.api.nvim_set_hl(0, "RenderMarkdownHeading1Bg", { link = "DiffAdd", default = true })
vim.api.nvim_set_hl(0, "RenderMarkdownHeading2Bg", { link = "DiffChange", default = true })

default = true is important here as it preserves the current setting if the highlight group is already defined somewhere else (like in a colorscheme 😉)

The naming convention I've used in the example is just a suggestion. Feel free to use whatever you see fit - the namespace is global so unique-ness is important.

Using links keeps the current highlight groups the same for existing users, so no breaking changes should be expected. But it allows colorschemes to adopt their own styling should they choose to add support in the future.

Describe alternatives you've considered

N/A

Additional information

For a good example of how to define many highlight groups at once, I recommend looking at Folke's implementation in trouble.nvim:
https://github.com/folke/trouble.nvim/blob/main/lua/trouble/config/highlights.lua

[MeanderingProgrammer]

Proposal makes sense to me, the idea of setting a default = true link to allow color schemes to override the value is neat. Super simple and powerful.

I implemented it here: 0f32655, and used the RenderMarkdown prefix as suggested.

Added a table with all of the highlights and their defaults to the README as well: https://github.com/MeanderingProgrammer/markdown.nvim?tab=readme-ov-file#colors

LMK if I missed anything, really curious how you go about integrating this. Thanks for the interest and the proposal!

[scottmckendry]

This is excellent! Pretty much exactly what I had in mind 🙂

The only (minor) changes I would suggest would be:

1. Add H4-H6 bg groups, linking all three to the H3Bg group. This will allow me to consistently set backgrounds that match headings.
   
2. In the image above, all the signs are the same color. I think it would be a nice addition to have the sign match the fg color of each heading.
3. Create a group for the border at the bottom of code blocks. I don't see a straightforward way of setting this currently.
   

[scottmckendry]

Ignore #2 in my previous comment! I've got it working now :)

[scottmckendry]

It looks like 3 was due to the same error I was running into with the signs. This looks good now:

That just leaves heading 4-6 background groups.

[MeanderingProgrammer]

Ah, understandable, updated here: 6aa19e9.

Am curious what updates you needed to make to resolve issues 2 & 3? Since if you had a fg defined for headings 1 through 6 I would expect the signs to be correctly colored. Similar but both a fg and a bg for the code block highlight.

[scottmckendry]

Legend! Thanks so much @MeanderingProgrammer!

Here's the final look:

[MeanderingProgrammer]

Looks great!

[jeremija]

@scottmckendry how did you solve the issue with horizontal line color? I just opened an issue #77, but now I'm wondering if there's something wrong with my config perhaps?