feat(defaults): pretty :help headings #30544

Problem:
Headings in :help do not stand out visually.

Solution:
Define a non-standard `@markup.heading.1.delimiter` group and
special-case it in `highlight_group.c`.

FUTURE:
This is a cheap workaround until we have #25718 which will enable:
- fully driven by `vimdoc/highlights.scm` instead of using highlight
  tricks (`guibg=bg guifg=bg guisp=fg`)
- better support of "cterm" ('notermguicolors')

runtime/doc/news.txt

@@ -119,6 +119,9 @@ API
 
 DEFAULTS
 
+• Highlighting:
+  • Improved styling of :checkhealth and :help buffers.
+
 • Mappings:
   • |grn| in Normal mode maps to |vim.lsp.buf.rename()|
   • |grr| in Normal mode maps to |vim.lsp.buf.references()|

runtime/ftplugin/help.lua

@@ -1,7 +1,7 @@
 -- use treesitter over syntax (for highlighted code blocks)
 vim.treesitter.start()
 
--- add custom highlights for list in `:h highlight-groups`
+-- Add custom highlights for list in `:h highlight-groups`.
 local bufname = vim.fs.normalize(vim.api.nvim_buf_get_name(0))
 if vim.endswith(bufname, '/doc/syntax.txt') then
   require('vim.vimhelp').highlight_groups({

runtime/queries/vimdoc/highlights.scm

@@ -1,9 +1,9 @@
 (h1
-  (delimiter) @markup.heading.1
+  (delimiter) @markup.heading.1.delimiter
   (heading) @markup.heading.1)
 
 (h2
-  (delimiter) @markup.heading.2
+  (delimiter) @markup.heading.2.delimiter
   (heading) @markup.heading.2)
 
 (h3

runtime/syntax/help.vim

@@ -15,7 +15,7 @@ set cpo&vim
 syn match helpHeadline		"^[A-Z.][-A-Z0-9 .,()_']*?\=\ze\(\s\+\*\|$\)"
 syn match helpSectionDelim	"^===.*===$"
 syn match helpSectionDelim	"^---.*--$"
-" Neovim: support language annotation in codeblocks
+" Nvim: support language annotation in codeblocks
 if has("conceal")
   syn region helpExample	matchgroup=helpIgnore start=" >[a-z0-9]*$" start="^>[a-z0-9]*$" end="^[^ \t]"me=e-1 end="^<" concealends
 else

src/nvim/highlight_group.c

@@ -301,6 +301,11 @@ static const char *highlight_init_both[] = {
   "default link @tag         Tag",
   "default link @tag.builtin Special",
 
+  // :help
+  // Higlight "===" and "---" heading delimiters specially.
+  "default @markup.heading.1.delimiter.vimdoc guibg=bg guifg=bg guisp=fg gui=underdouble,nocombine ctermbg=NONE ctermfg=NONE cterm=underdouble,nocombine",
+  "default @markup.heading.2.delimiter.vimdoc guibg=bg guifg=bg guisp=fg gui=underline,nocombine ctermbg=NONE ctermfg=NONE cterm=underline,nocombine",
+
   // LSP semantic tokens
   "default link @lsp.type.class         @type",
   "default link @lsp.type.comment       @comment",

test/functional/treesitter/highlight_spec.lua

@@ -894,9 +894,45 @@ describe('treesitter highlighting (help)', function()
       [3] = { bold = true, foreground = Screen.colors.Brown },
       [4] = { foreground = Screen.colors.Cyan4 },
       [5] = { foreground = Screen.colors.Magenta1 },
+      title = { bold = true, foreground = Screen.colors.Magenta1 },
+      h1_delim = { nocombine = true, underdouble = true },
+      h2_delim = { nocombine = true, underline = true },
     }
   end)
 
+  it('defaults in vimdoc/highlights.scm', function()
+    -- Avoid regressions when syncing upstream vimdoc queries.
+
+    insert [[
+    ==============================================================================
+    NVIM DOCUMENTATION
+
+    ------------------------------------------------------------------------------
+    ABOUT NVIM                                                     *tag-1* *tag-2*
+
+    |news|			News
+    |nvim|			NVim
+    ]]
+
+    feed('gg')
+    exec_lua(function()
+      vim.wo.wrap = false
+      vim.bo.filetype = 'help'
+      vim.treesitter.start()
+    end)
+
+    screen:expect({
+      grid = [[
+        {h1_delim:^========================================}|
+        {title:NVIM DOCUMENTATION}                      |
+                                                |
+        {h2_delim:----------------------------------------}|
+        {title:ABOUT NVIM}                              |
+                                                |
+      ]],
+    })
+  end)
+
   it('correctly redraws added/removed injections', function()
     insert [[
     >ruby