My attempt at implementing your idea in PR #79

[rsforge]

I don't expect you to merge this.
I just thought it might help if you ever find the time to implement your comment from PR #79.
Also, I am not a Lua programmer, or even a Neovim plugin developer for that matter, so take my suggestions with a grain of salt.

You had mentioned "setup itself should be callable per buffer.". This is just me taking a crack at it.

Here is how you would attach, or setup if you will, locally to a buffer.

local config = {
    headline_highlights = { 'CustomHighlight' }
}

vim.api.nvim_create_autocmd('BufEnter', {
    pattern = '*.norg', -- '*.md', '*.org'
    callback = function(ev)
        -- attach(buffer, config)
        require('headlines').attach(ev.buf, config)
    end
})

When passing config to attach it will figure out the file type you are attaching to. Then use the correct defaults, so long as they have been implemented in by the dev, otherwise it will use a generic set of defaults.

After you have attached it to a buffer, it will automatically refresh when the buffer changes.

You will also notice that I split the code into multiple files. This is just the way I like it.
However, this could easily be changed to fit your style.

Most of the heavy lifting is still being done by your code. I have basically just put a wrapper around it.

I have done some light testing, and so far it seems to work.

If you have any questions, feel free to ask.
And again, I don't expect you to merge this. This is just a quick implementation. That may be useful later on.