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')

6 files changed, 48 insertions, 4 deletions

diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index a359d57a99..789f895b46 100644
--- a/runtime/doc/news.txt
+++ b/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()|
diff --git a/runtime/ftplugin/help.lua b/runtime/ftplugin/help.lua
index eb66e34bc7..8d991be0e4 100644
--- a/runtime/ftplugin/help.lua
+++ b/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({
diff --git a/runtime/queries/vimdoc/highlights.scm b/runtime/queries/vimdoc/highlights.scm
index 829a643ae8..1f809c2f60 100644
--- a/runtime/queries/vimdoc/highlights.scm
+++ b/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
diff --git a/runtime/syntax/help.vim b/runtime/syntax/help.vim
index fced5e7dd1..0f62c26294 100644
--- a/runtime/syntax/help.vim
+++ b/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
diff --git a/src/nvim/highlight_group.c b/src/nvim/highlight_group.c
index b4dcb4b6d0..1a0ae3ac49 100644
--- a/src/nvim/highlight_group.c
+++ b/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",
diff --git a/test/functional/treesitter/highlight_spec.lua b/test/functional/treesitter/highlight_spec.lua
index 50f5734230..b5a6cb5c17 100644
--- a/test/functional/treesitter/highlight_spec.lua
+++ b/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