fix(docs-html): keycodes, taglinks, column_heading

Problem:
- Docs HTML: "foo ~" headings (column_heading) are not aligned with
  their table columns/contents because the leading whitespace is not
  emitted.
- taglinks starting with hyphen like |-x| were not recognized.
- keycodes like `<foo>` and `CTRL-x` were not recognized.
- ToC is not scrollable.

Solution:
- Add ws() to the column_heading case.
- Update help parser to latest version
  - supports `keycode`
  - fixes for taglink, argument
- Update .toc CSS. https://github.com/neovim/neovim.github.io/issues/297

fix https://github.com/neovim/neovim.github.io/issues/297

cmake.deps/CMakeLists.txt

@@ -201,8 +201,8 @@ set(TREESITTER_LUA_SHA256 564594fe0ffd2f2fb3578a15019b723e1bc94ac82cb6a0103a6b3b
 set(TREESITTER_VIM_URL https://github.com/vigoux/tree-sitter-viml/archive/v0.2.0.tar.gz)
 set(TREESITTER_VIM_SHA256 608dcc31a7948cb66ae7f45494620e2e9face1af75598205541f80d782ec4501)
 
-set(TREESITTER_HELP_URL https://github.com/neovim/tree-sitter-vimdoc/archive/c27e3e21a54f6d90dfb791f37d90eab5b28de971.tar.gz)
+set(TREESITTER_HELP_URL https://github.com/neovim/tree-sitter-vimdoc/archive/d5950211e725fe7f5af50a5eea1b47adfc02ceb2.tar.gz)
-set(TREESITTER_HELP_SHA256 54a6a5b52a395097775f06f96ac1e1c9efdab10243550a467e1198a286b8c59c)
+set(TREESITTER_HELP_SHA256 a5282abda813b976d445665865b9668fbb097f6ce1c554681d15dfd2b24f0692)
 
 set(TREESITTER_URL https://github.com/tree-sitter/tree-sitter/archive/v0.20.7.tar.gz)
 set(TREESITTER_SHA256 b355e968ec2d0241bbd96748e00a9038f83968f85d822ecb9940cbe4c42e182e)

runtime/doc/autocmd.txt

@@ -590,6 +590,7 @@ FileChangedShell		When Vim notices that the modification time of
 				- executing a shell command
 				- |:checktime|
 				- |FocusGained| 
+
 				Not used when 'autoread' is set and the buffer
 				was not changed.  If a FileChangedShell
 				autocommand exists the warning message and

runtime/doc/channel.txt

@@ -48,21 +48,22 @@ a job channel using RPC, bytes can still be read over its stderr. Similarly,
 only bytes can be written to Nvim's own stderr.
 
 						*channel-callback*
-on_stdout({chan-id}, {data}, {name})		*on_stdout* 
+- on_stdout({chan-id}, {data}, {name})		*on_stdout*
-on_stderr({chan-id}, {data}, {name})		*on_stderr* 
+- on_stderr({chan-id}, {data}, {name})		*on_stderr*
-on_stdin({chan-id}, {data}, {name})		*on_stdin* 
+- on_stdin({chan-id}, {data}, {name})		*on_stdin*
-on_data({chan-id}, {data}, {name})		*on_data*
+- on_data({chan-id}, {data}, {name})		*on_data*
+
     Scripts can react to channel activity (received data) via callback
     functions assigned to the `on_stdout`, `on_stderr`, `on_stdin`, or
     `on_data` option keys. Callbacks should be fast: avoid potentially
     slow/expensive work.
 
     Parameters: ~
-      {chan-id}     Channel handle. |channel-id|
+      - {chan-id}   Channel handle. |channel-id|
-      {data}	    Raw data (|readfile()|-style list of strings) read from
+      - {data}	    Raw data (|readfile()|-style list of strings) read from
 		    the channel. EOF is a single-item list: `['']`. First and
 		    last items may be partial lines! |channel-lines|
-      {name}	    Stream name (string) like "stdout", so the same function
+      - {name}	    Stream name (string) like "stdout", so the same function
 		    can handle multiple streams. Event names depend on how the
 		    channel was opened and in what mode/protocol.
 
@@ -83,13 +84,14 @@ on_data({chan-id}, {data}, {name})		*on_data*
     the final `['']` emitted at EOF):
       - `foobar` may arrive as `['fo'], ['obar']` 
       - `foo\nbar` may arrive as
-	   `['foo','bar']`
+	- `['foo','bar']`
-	or `['foo',''], ['bar']`
+	- or `['foo',''], ['bar']`
-	or `['foo'], ['','bar']`
+	- or `['foo'], ['','bar']`
-	or `['fo'], ['o','bar']`
+	- or `['fo'], ['o','bar']`
+
     There are two ways to deal with this:
-    1. To wait for the entire output, use |channel-buffered| mode.
+    - 1. To wait for the entire output, use |channel-buffered| mode.
-    2. To read line-by-line, use the following code: >
+    - 2. To read line-by-line, use the following code: >
 	let s:lines = ['']
 	func! s:on_event(job_id, data, event) dict
 	  let eof = (a:data == [''])

runtime/doc/ft_ada.txt

@@ -51,7 +51,7 @@ for a complete list.
 To enable them, assign a value to the option.  For example, to turn one on:
  >
     > let g:ada_standard_types = 1
->
+
 To disable them use ":unlet".  Example:
 >
     > unlet g:ada_standard_types

runtime/doc/intro.txt

@@ -308,7 +308,7 @@ These names for keys are used in the documentation.  They can also be used
 with the ":map" command.
 
 notation	meaning		    equivalent	decimal value(s)	~
------------------------------------------------------------------------
+----------------------------------------------------------------------- ~
 <Nul>		zero			CTRL-@	  0 (stored as 10) *<Nul>*
 <BS>		backspace		CTRL-H	  8	*backspace*
 <Tab>		tab			CTRL-I	  9	*tab* *Tab*
@@ -530,12 +530,12 @@ Ex		 :vi	  --	  --	 --	    --	      --
 
 -- not possible
 
-*1 Go from Normal mode to Insert mode by giving the command "i", "I", "a",
+* 1 Go from Normal mode to Insert mode by giving the command "i", "I", "a",
     "A", "o", "O", "c", "C", "s" or S".
-*2 Go from Visual mode to Normal mode by giving a non-movement command, which
+* 2 Go from Visual mode to Normal mode by giving a non-movement command, which
     causes the command to be executed, or by hitting <Esc> "v", "V" or "CTRL-V"
     (see |v_v|), which just stops Visual mode without side effects.
-*3 Go from Command-line mode to Normal mode by:
+* 3 Go from Command-line mode to Normal mode by:
     - Hitting <CR> or <NL>, which causes the entered command to be executed.
     - Deleting the complete line (e.g., with CTRL-U) and giving a final <BS>.
     - Hitting CTRL-C or <Esc>, which quits the command-line without executing
@@ -543,15 +543,15 @@ Ex		 :vi	  --	  --	 --	    --	      --
     In the last case <Esc> may be the character defined with the 'wildchar'
     option, in which case it will start command-line completion.  You can
     ignore that and type <Esc> again.
-*4 Go from Normal to Select mode by:
+* 4 Go from Normal to Select mode by:
     - use the mouse to select text while 'selectmode' contains "mouse"
     - use a non-printable command to move the cursor while keeping the Shift
       key pressed, and the 'selectmode' option contains "key"
     - use "v", "V" or "CTRL-V" while 'selectmode' contains "cmd"
     - use "gh", "gH" or "g CTRL-H"  |g_CTRL-H|
-*5 Go from Select mode to Normal mode by using a non-printable command to move
+* 5 Go from Select mode to Normal mode by using a non-printable command to move
     the cursor, without keeping the Shift key pressed.
-*6 Go from Select mode to Insert mode by typing a printable character.  The
+* 6 Go from Select mode to Insert mode by typing a printable character.  The
     selection is deleted and the character is inserted.
 
 			*CTRL-\_CTRL-N* *i_CTRL-\_CTRL-N* *c_CTRL-\_CTRL-N*

runtime/doc/luaref.txt

@@ -24,7 +24,6 @@ Type |gO| to see the table of contents.
 
 ==============================================================================
 1  INTRODUCTION                                                   *luaref-intro*
-==============================================================================
 
 Lua is an extension programming language designed to support general
 procedural programming with data description facilities.  It also offers good
@@ -1504,7 +1503,6 @@ When you run it, it produces the following output:
 
 ==============================================================================
 3  THE APPLICATION PROGRAM INTERFACE                                *luaref-API*
-==============================================================================
 
 This section describes the C API for Lua, that is, the set of C functions
 available to the host program to communicate with Lua. All API functions and
@@ -2979,7 +2977,6 @@ lua_setupvalue                                                *lua_setupvalue()*
 
 ==============================================================================
 4  THE AUXILIARY LIBRARY                                            *luaref-aux*
-==============================================================================
 
 The auxiliary library provides several convenient functions to interface C
 with Lua. While the basic API provides the primitive functions for all
@@ -3511,7 +3508,6 @@ luaL_where                                                        *luaL_where()*
 
 ==============================================================================
 5  STANDARD LIBRARIES                                               *luaref-Lib*
-==============================================================================
 
 The standard libraries provide useful functions that are implemented directly
 through the C API. Some of these functions provide essential services to the
@@ -4064,7 +4060,7 @@ string.gmatch({s}, {pattern})                                  *string.gmatch()*
                end
 <
 
-string.gsub({s}, {pattern}, {repl} [, {n}])                    *string.gsu{b}()*
+string.gsub({s}, {pattern}, {repl} [, {n}])                    *string.gsub()*
         Returns a copy of {s} in which all occurrences of the {pattern} have
         been replaced by a replacement string specified by {repl}, which may
         be a string, a table, or a function. `gsub` also returns, as its
@@ -4831,7 +4827,6 @@ debug.traceback([{thread},] [{message}] [,{level}])          *debug.traceback()*
 
 ==============================================================================
 A  BIBLIOGRAPHY                                            *luaref-bibliography*
-==============================================================================
 
 This help file is a minor adaptation from this main reference:
 
@@ -4858,7 +4853,6 @@ Lua is discussed in these references:
 
 ==============================================================================
 B  COPYRIGHT & LICENSES                                       *luaref-copyright*
-==============================================================================
 
 This help file has the same copyright and license as Lua 5.1 and the Lua 5.1
  manual:
@@ -4885,7 +4879,6 @@ SOFTWARE.
 
 ==============================================================================
 C  LUAREF DOC                 *luarefvim* *luarefvimdoc* *luaref-help* *luaref-doc*
-==============================================================================
 
 This is a Vim help file containing a reference for Lua 5.1, and it is -- with
 a few exceptions and adaptations -- a copy of the Lua 5.1 Reference Manual

runtime/doc/mbyte.txt

@@ -334,8 +334,8 @@ Vim will automatically convert from one to another encoding in several places:
   "utf-8" (requires a gettext version that supports this).
 - When reading a Vim script where |:scriptencoding| is different from
   "utf-8".
-Most of these require the |+iconv| feature.  Conversion for reading and
+Most of these require iconv.  Conversion for reading and writing files may
-writing files may also be specified with the 'charconvert' option.
+also be specified with the 'charconvert' option.
 
 Useful utilities for converting the charset:
     All:	    iconv

runtime/doc/options.txt

@@ -3920,9 +3920,9 @@ A jump table for the options with a short description can be found at |Q_op|.
 	`:lgrepadd`, `:cfile`, `:cgetfile`, `:caddfile`, `:lfile`, `:lgetfile`,
 	and `:laddfile`.
 
-	This would be mostly useful when you use MS-Windows.  If |+iconv| is
+	This would be mostly useful when you use MS-Windows.  If iconv is
-	enabled and GNU libiconv is used, setting 'makeencoding' to "char" has
+	enabled, setting 'makeencoding' to "char" has the same effect as
-	the same effect as setting to the system locale encoding.  Example: >
+	setting to the system locale encoding.  Example: >
 		:set makeencoding=char	" system locale is used
 <
 						*'makeprg'* *'mp'*

runtime/doc/pi_msgpack.txt

@@ -63,16 +63,16 @@ msgpack#is_uint({msgpack-value})			*msgpack#is_uint()*
 							*msgpack#strftime*
 msgpack#strftime({format}, {msgpack-integer})		*msgpack#strftime()*
 	Same as |strftime()|, but second argument may be 
-	|msgpack-special-dict|.  Requires |+python| or |+python3| to really 
+	|msgpack-special-dict|.  Requires |Python| to really work with
-	work with |msgpack-special-dict|s.
+	|msgpack-special-dict|s.
 
 							*msgpack#strptime*
 msgpack#strptime({format}, {time})			*msgpack#strptime()*
 	Reverse of |msgpack#strftime()|: for any time and format 
 	|msgpack#equal|( |msgpack#strptime|(format, |msgpack#strftime|(format, 
-	time)), time) be true.  Requires |+python| or |+python3|, without it 
+	time)), time) be true.  Requires ||Python|, without it only supports
-	only supports non-|msgpack-special-dict| nonnegative times and format 
+	non-|msgpack-special-dict| nonnegative times and format equal to
-	equal to `%Y-%m-%dT%H:%M:%S`.
+	`%Y-%m-%dT%H:%M:%S`.
 
 msgpack#int_dict_to_str({msgpack-special-int})	*msgpack#int_dict_to_str()*
 	Function which converts |msgpack-special-dict| integer value to 

runtime/doc/starting.txt

@@ -35,7 +35,7 @@ filename	One or more file names.  The first one will be the current
 		no other options or "+command" argument can follow.
 
 							*--*
--		Alias for stdin (standard input).
+`-`		Alias for stdin (standard input).
 		Example: >
 			echo text | nvim - file
 <		"text" is read into buffer 1, "file" is opened as buffer 2.
@@ -1182,7 +1182,7 @@ exactly four MessagePack objects:
                        encoding   Binary, effective 'encoding' value.
                        max_kbyte  Integer, effective |shada-s| limit value.
                        pid        Integer, instance process ID.
-                       *          It is allowed to have any number of
+                       `*`          It is allowed to have any number of
                                   additional keys with any data.
    2 (SearchPattern)   Map containing data describing last used search or
                        substitute pattern.  Normally ShaDa file contains two
@@ -1213,7 +1213,7 @@ exactly four MessagePack objects:
                        sp   Binary   N/A      Actual pattern.  Required.
                        sb   Boolean  false    True if search direction is
                                               backward.
-                       *    any      none     Other keys are allowed for
+                       `*`    any      none     Other keys are allowed for
                                               compatibility reasons, see
                                               |shada-compatibility|.
    3 (SubString)       Array containing last |:substitute| replacement string.
@@ -1284,7 +1284,7 @@ exactly four MessagePack objects:
                                                GlobalMark and LocalMark
                                                entries.
                        f    Binary    N/A      File name.  Required.
-                       *    any       none     Other keys are allowed for
+                       `*`    any       none     Other keys are allowed for
                                                compatibility reasons, see
                                                |shada-compatibility|.
    9 (BufferList)      Array containing maps.  Each map in the array
@@ -1294,10 +1294,10 @@ exactly four MessagePack objects:
                                                greater then zero.
                        c    UInteger  0        Position column number.
                        f    Binary    N/A      File name.  Required.
-                       *    any       none     Other keys are allowed for
+                       `*`    any       none     Other keys are allowed for
                                                compatibility reasons, see
                                                |shada-compatibility|.
-   * (Unknown)         Any other entry type is allowed for compatibility
+   `*` (Unknown)         Any other entry type is allowed for compatibility
                        reasons, see |shada-compatibility|.
 
 								*E575* *E576*

runtime/doc/testing.txt

@@ -134,7 +134,7 @@ assert_match({pattern}, {actual} [, {msg}])
 		When {pattern} does not match {actual} an error message is
 		added to |v:errors|.  Also see |assert-return|.
 
-		{pattern} is used as with |=~|: The matching is always done
+		{pattern} is used as with |expr-=~|: The matching is always done
 		like 'magic' was set and 'cpoptions' is empty, no matter what
 		the actual value of 'magic' or 'cpoptions' is.
 

runtime/doc/usr_41.txt

@@ -1074,8 +1074,8 @@ Various:					*various-functions*
 	wordcount()		get byte/word/char count of buffer
 
 	luaeval()		evaluate |Lua| expression
-	py3eval()		evaluate Python expression (|+python3|)
+	py3eval()		evaluate |Python| expression
-	pyeval()		evaluate Python expression (|+python|)
+	pyeval()		evaluate |Python| expression
 	pyxeval()		evaluate |python_x| expression
 	rubyeval()		evaluate |Ruby| expression
 

runtime/doc/usr_toc.txt

@@ -5,7 +5,7 @@
 			      Table Of Contents			*user-manual*
 
 ==============================================================================
-Overview ~
+Overview
 
 Getting Started
 |usr_01.txt|  About the manuals
@@ -52,7 +52,7 @@ The user manual is online:
 	https://neovim.io/doc/user
 
 ==============================================================================
-Getting Started ~
+Getting Started
 
 Read this from start to end to learn the essential commands.
 
@@ -167,7 +167,7 @@ Read this from start to end to learn the essential commands.
 		|12.8|	Find where a word is used
 
 ==============================================================================
-Editing Effectively ~
+Editing Effectively
 
 Subjects that can be read independently.
 
@@ -275,7 +275,7 @@ Subjects that can be read independently.
 		|32.4|	Time travelling
 
 ==============================================================================
-Tuning Vim ~
+Tuning Vim
 
 Make Vim work as you like it.
 

runtime/doc/vim_diff.txt

@@ -82,27 +82,24 @@ centralized reference of the differences.
 
 Default Mouse ~
 						*default-mouse* *disable-mouse*
-By default the mouse is enabled.  The right button click opens |popup-menu|
+By default the mouse is enabled, and <RightMouse> opens a |popup-menu| with
-with standard actions, such as "Cut", "Copy" and "Paste".
+standard actions ("Cut", "Copy", "Paste", …). Mouse is NOT enabled in
+|command-mode| or the |more-prompt|, so you can temporarily disable it just by
+typing ":".
 
-If you don't like this you can add to your |config| any of the following:
+If you don't like this you can disable the mouse in your |config| using any of
-
+the following:
-- ignore mouse completely >
+- Disable mouse completely by unsetting the 'mouse' option: >
   set mouse=
-<
+- Pressing <RightMouse> extends selection instead of showing popup-menu: >
-- no |popup-menu| but the right button extends selection >
   set mousemodel=extend
->
+- Pressing <A-LeftMouse> releases mouse until the cursor moves:  >
-- pressing ALT+LeftMouse releases mouse until main cursor moves  >
+  nnoremap <A-LeftMouse> <Cmd>
-  nnoremap <M-LeftMouse> <Cmd>
     \ set mouse=<Bar>
     \ echo 'mouse OFF until next cursor-move'<Bar>
     \ autocmd CursorMoved * ++once set mouse&<Bar>
     \ echo 'mouse ON'<CR>
 <
-Also, mouse is not in use in |command-mode| or at |more-prompt|.  So if you
-need to copy/paste with your terminal then just pressing ':' makes Nvim to
-release the mouse cursor temporarily.
 
 Default Mappings ~
 							*default-mappings*

scripts/gen_help_html.lua

@@ -208,7 +208,7 @@ local function get_helppage(f)
     return 'index.html'
   end
 
-  return f:gsub('%.txt$', '.html')
+  return (f:gsub('%.txt$', '.html'))
 end
 
 -- Counts leading spaces (tab=8) to decide the indent size of multiline text.
@@ -255,9 +255,13 @@ end
 
 -- Returns true if the given invalid tagname is a false positive.
 local function ignore_invalid(s)
+  return not not (
+    exclude_invalid[s]
     -- Strings like |~/====| appear in various places and the parser thinks they are links, but they
     -- are just table borders.
-  return not not (s:find('===') or exclude_invalid[s])
+    or s:find('===')
+    or s:find('---')
+  )
 end
 
 local function ignore_parse_error(s)
@@ -281,10 +285,14 @@ end
 
 local function validate_link(node, bufnr, fname)
   local helppage, tagname = get_tagname(node:child(1), bufnr)
-  if not has_ancestor(node, 'column_heading') and not node:has_error() and not tagmap[tagname] and not ignore_invalid(tagname) then
+  local ignored = false
+  if not tagmap[tagname] then
+    ignored = has_ancestor(node, 'column_heading') or node:has_error() or ignore_invalid(tagname)
+    if not ignored then
       invalid_links[tagname] = vim.fs.basename(fname)
     end
-  return helppage, tagname
+  end
+  return helppage, tagname, ignored
 end
 
 -- Traverses the tree at `root` and checks that |tag| links point to valid helptags.
@@ -325,7 +333,7 @@ local function visit_validate(root, level, lang_tree, opt, stats)
       invalid_urls[text] = vim.fs.basename(opt.fname)
     end
   elseif node_name == 'taglink' or node_name == 'optionlink' then
-    local _, _ = validate_link(root, opt.buf, opt.fname)
+    local _, _, _ = validate_link(root, opt.buf, opt.fname)
   end
 end
 
@@ -341,7 +349,7 @@ local function visit_node(root, level, lang_tree, headings, opt, stats)
   -- Parent kind (string).
   local parent = root:parent() and root:parent():type() or nil
   local text = ''
-  local toplevel = level < 1
+  local trimmed
   local function node_text(node)
     return vim.treesitter.get_node_text(node or root, opt.buf)
   end
@@ -352,6 +360,8 @@ local function visit_node(root, level, lang_tree, headings, opt, stats)
 
   if root:named_child_count() == 0 or node_name == 'ERROR' then
     text = node_text()
+    trimmed = html_esc(trim(text))
+    text = html_esc(text)
   else
     -- Process children and join them with whitespace.
     for node, _ in root:iter_children() do
@@ -360,8 +370,8 @@ local function visit_node(root, level, lang_tree, headings, opt, stats)
         text = string.format('%s%s', text, r)
       end
     end
+    trimmed = trim(text)
   end
-  local trimmed = trim(text)
 
   if node_name == 'help_file' then  -- root node
     return text
@@ -369,7 +379,7 @@ local function visit_node(root, level, lang_tree, headings, opt, stats)
     local fixed_url, removed_chars = fix_url(trimmed)
     return ('%s<a href="%s">%s</a>%s'):format(ws(), fixed_url, fixed_url, removed_chars)
   elseif node_name == 'word' or node_name == 'uppercase_name' then
-    return html_esc(text)
+    return text
   elseif node_name == 'h1' or node_name == 'h2' or node_name == 'h3' then
     if is_noise(text, stats.noise_lines) then
       return ''  -- Discard common "noise" lines.
@@ -387,7 +397,7 @@ local function visit_node(root, level, lang_tree, headings, opt, stats)
     if root:has_error() then
       return text
     end
-    return ('<div class="help-column_heading">%s</div>'):format(trimmed)
+    return ('<div class="help-column_heading">%s%s</div>'):format(ws(), trimmed)
   elseif node_name == 'block' then
     if is_blank(text) then
       return ''
@@ -425,28 +435,28 @@ local function visit_node(root, level, lang_tree, headings, opt, stats)
 
     return string.format('<div class="help-li" style="%s">%s</div>', margin, text)
   elseif node_name == 'taglink' or node_name == 'optionlink' then
-    if root:has_error() then
+    local helppage, tagname, ignored = validate_link(root, opt.buf, opt.fname)
+    if ignored then
       return text
     end
-    local helppage, tagname = validate_link(root, opt.buf, opt.fname)
     return ('%s<a href="%s#%s">%s</a>'):format(ws(), helppage, url_encode(tagname), html_esc(tagname))
-  elseif node_name == 'codespan' then
+  elseif vim.tbl_contains({'codespan', 'keycode'}, node_name) then
     if root:has_error() then
       return text
     end
-    return ('%s<code>%s</code>'):format(ws(), text)
+    return ('%s<code>%s</code>'):format(ws(), trimmed)
   elseif node_name == 'argument' then
     return ('%s<code>{%s}</code>'):format(ws(), text)
   elseif node_name == 'codeblock' then
     if is_blank(text) then
       return ''
     end
-    return ('<pre>%s</pre>'):format(html_esc(trim(trim_indent(text), 2)))
+    return ('<pre>%s</pre>'):format(trim(trim_indent(text), 2))
   elseif node_name == 'tag' then  -- anchor
     if root:has_error() then
       return text
     end
-    local in_heading = (parent == 'h1' or parent == 'h2')
+    local in_heading = vim.tbl_count({'h1', 'h2', 'h3'}, parent)
     local cssclass = (not in_heading and get_indent(node_text()) > 8) and 'help-tag-right' or 'help-tag'
     local tagname = node_text(root:child(1))
     if vim.tbl_count(stats.first_tags) < 2 then
@@ -471,12 +481,12 @@ local function visit_node(root, level, lang_tree, headings, opt, stats)
     end
 
     -- Store the raw text to give context to the bug report.
-    local sample_text = not toplevel and getbuflinestr(root, opt.buf, 3) or '[top level!]'
+    local sample_text = level > 0 and getbuflinestr(root, opt.buf, 3) or '[top level!]'
     table.insert(stats.parse_errors, sample_text)
     return ('<a class="parse-error" target="_blank" title="Report bug... (parse error)" href="%s">%s</a>'):format(
       get_bug_url_vimdoc(opt.fname, opt.to_fname, sample_text), trimmed)
   else  -- Unknown token.
-    local sample_text = not toplevel and getbuflinestr(root, opt.buf, 3) or '[top level!]'
+    local sample_text = level > 0 and getbuflinestr(root, opt.buf, 3) or '[top level!]'
     return ('<a class="unknown-token" target="_blank" title="Report bug... (unhandled token "%s")" href="%s">%s</a>'):format(
       node_name, get_bug_url_nvim(opt.fname, opt.to_fname, sample_text, node_name), trimmed), ('unknown-token:"%s"'):format(node_name)
   end
@@ -751,6 +761,8 @@ local function gen_css(fname)
     }
     .toc {
       /* max-width: 12rem; */
+      height: 95%;  /* Scroll if there are too many items. https://github.com/neovim/neovim.github.io/issues/297 */
+      overflow: auto;  /* Scroll if there are too many items. https://github.com/neovim/neovim.github.io/issues/297 */
     }
     .toc > div {
       text-overflow: ellipsis;
@@ -809,7 +821,7 @@ local function gen_css(fname)
     .help-tag-right {
       color: var(--tag-color);
     }
-    h1 .help-tag, h2 .help-tag {
+    h1 .help-tag, h2 .help-tag, h3 .help-tag {
       font-size: smaller;
     }
     .help-heading {

test/functional/lua/help_spec.lua

@@ -21,7 +21,7 @@ describe(':help docs', function()
     ok(rv.helpfiles > 100, '>100 :help files', rv.helpfiles)
     -- Check that parse errors did not increase wildly.
     -- TODO: Fix all parse errors in :help files.
-    ok(rv.err_count < 280, '<280 parse errors', rv.err_count)
+    ok(rv.err_count < 150, '<150 parse errors', rv.err_count)
     eq({}, rv.invalid_links, exec_lua([[return 'found invalid :help tag links:\n'..vim.inspect(...)]], rv.invalid_links))
   end)
 
@@ -43,7 +43,7 @@ describe(':help docs', function()
       tmpdir
     )
     eq(4, #rv.helpfiles)
-    ok(rv.err_count <= 6, '<=6 parse errors', rv.err_count)
+    ok(rv.err_count <= 1, '<=1 parse errors', rv.err_count)
     eq({}, rv.invalid_links, exec_lua([[return 'found invalid :help tag links:\n'..vim.inspect(...)]], rv.invalid_links))
   end)
 end)