helptoc.txt (15664B)
1 *helptoc.txt* For Vim version 9.1. Last change: 2025 Aug 10 2 3 4 VIM REFERENCE MANUAL 5 6 Interactive table of contents for help buffers and several other filetypes 7 ============================================================================== 8 9 10 1. OVERVIEW *HelpToc-overview* 11 12 The helptoc.vim plugin provides one command, :HelpToc, which generates a 13 hierarchical table of contents in a popup window, which is based on the 14 structure of a Vim buffer. See |Helptoc-mappings| for a list of supported key 15 mappings in the popup window. 16 17 It was designed initially for help buffers, but it also works with buffers of 18 the following types: 19 - asciidoc 20 - html 21 - man 22 - markdown 23 - terminal 24 - tex 25 - vim Note: only with numbered fold markers, e.g. {{{1 26 - xhtml 27 28 1.1 The :HelpToc command *HelpToc-:HelpToc* 29 30 The :HelpToc command takes no arguments and it cannot be executed from an 31 unsupported filetype. Also, it cannot be used to generate a table of contents 32 for an inactive buffer. 33 34 For most buffers of the supported types, :HelpToc may be entered directly 35 in Vim's |Command-line-mode|. How to use it from Vim's |Terminal-Job| mode is 36 explained in |HelpToc-terminal-buftype|. 37 38 You may choose to map :HelpToc to keys making it easier to use. These are 39 examples of what could be used: > 40 41 nnoremap <Leader>ht <Cmd>HelpToc<CR> 42 tnoremap <C-t><C-t> <Cmd>HelpToc<CR> 43 < 44 45 2. DETAILS *HelpToc-details* 46 47 When the :HelpToc command is executed from an active buffer of a supported 48 type, a popup window is produced. The window contains a hierarchical and 49 interactive table of contents. The entries are based on the "headings" in 50 the buffer. 51 52 Jumping to an entry's position in the buffer can be achieved by pressing 53 enter on the applicable entry. Navigation, and other commands applicable to 54 the popup window, such as expanding and contracting levels, fuzzy searching, 55 and jumping to the previous or next entry (leaving the table of contents 56 itself displayed, using J and K), is provided at |help-TOC|, so that is not 57 reproduced in this help file. 58 59 60 3. TYPES *HelpToc-types* 61 62 Some filetypes have more predictable structures than others. For example, 63 markdown and asciidoc make the identification of headings (aside from edge 64 cases, such as when in quotes) straightforward. Some filetypes do not have 65 such obvious or reliable headings/levels (particularly help buffers). 66 Further, in some instances, how to enter the :HelpToc command is not 67 necessarily obvious, e.g., when in a Vim |terminal-window|. So, the following 68 headings address specific details regarding the in-scope types. 69 70 3.1 asciidoc *HelpToc-asciidoc-filetype* 71 72 The heading levels in asciidoc are typically identified by lines starting 73 with a "=" (up to six, one per level), one or more blank characters, and the 74 heading text. :HelpToc will generate a table of contents based on either 75 that form of heading type or, because asciidoc also allows for ATX heading 76 level syntax (i.e., using the "#" character), headings using that format too. 77 78 As asciidoc is very structured, its table of contents entries are presented 79 in a standardized form - see |HelpToc-standardized-toc|. So, the initial 80 "=" or "#" characters and the following space from the related heading are 81 not included in the table of contents' entries. 82 83 3.2 html *HelpToc-html-filetype* 84 85 HTML provides for six levels of headings, <h1> to <h6>, which may be either 86 upper or lower case and preceded by all sorts of content like <!--comments-->. 87 :HelpToc will produce a table of contents based on the six heading levels. 88 89 As HTML is very structured, its table of contents entries are presented 90 in a standardized form - see |HelpToc-standardized-toc|. So, the <h1> to <h6> 91 tags, any preceding content, and any trailing content after the heading text, 92 is not included in the table of contents' entries. 93 94 3.3 man pages *HelpToc-man-filetype* 95 96 Retrieving man pages is typically performed in the terminal. To use :HelpToc 97 to generate a table of contents, the |man.vim| filetype plugin is a 98 prerequisite. It is provided with Vim, and may be sourced with: > 99 100 :runtime ftplugin/man.vim 101 < 102 Once sourced, the |:Man| command will open the applicable man page in a new 103 buffer (of "man" filetype). For example: > 104 105 :Man pwd 106 < 107 Once in the man buffer, entering :HelpToc opens the table of contents popup, 108 with level 1 containing section names like NAME, SYNOPSIS, etc. Levels 109 below 1 include subsections and options, with the level depending on the 110 number of spaces preceding the content. 111 112 The table of contents for a man buffer's popup window has the same syntax 113 highlighting as man pages. This reflects that its content is reproduced 114 as-is, i.e., no preceding tags, level-indicating data, etc., need be omitted 115 for optimal presentation. 116 117 3.4 markdown *HelpToc-markdown-filetype* 118 119 The headings and levels in markdown typically are ATX formatted headings 120 (lines starting with up to three spaces, one to six "#", then (optionally) 121 one or blank characters and the heading text). The alternate form, 122 setext, uses up to three spaces, the heading 1 text, followed by a 123 line of one or more "=". The setext heading 2 is similar, but for one or 124 more "-" instead of "=". There is no heading 3+ in setext. ATX and setext 125 headings are supported. 126 127 As markdown is very structured, its table of contents entries are presented 128 in a standardized form - see |HelpToc-standardized-toc|. So, they do not 129 include any leading spaces, any initial "#" characters and the following blank 130 character(s) in the table of contents' entries. 131 132 3.5 terminal *HelpToc-terminal-buftype* 133 134 There are no explicit "headings" for a terminal buffer. However, :HelpToc 135 displays the history of executed shell commands. Those may be specified 136 by changing the pattern used to match the Vim terminal's prompt. 137 See |HelpToc-configuration| for examples. 138 139 To access the terminal's table of contents, from the Vim's |Terminal-Job| mode 140 enter CTRL-W N to go to |Terminal-Normal| mode. From there, enter :HelpToc to 141 generate the table of contents. If you use the terminal's table of contents 142 a lot, an appropriate mapping may make it easier than using CTRL-W N - e.g.: > 143 144 tnoremap <C-t><C-t> <Cmd>HelpToc<CR> 145 < 146 As the terminal has only "level 1", the table of contents is presented in a 147 standardized form - see |HelpToc-standardized-toc| - including only the history 148 list of commands. The prompt itself is also omitted since it adds no value 149 repeating it for every entry. 150 151 3.6 tex *HelpToc-tex-filetype* 152 153 In LaTeX, a document may be structured hierarchically using part, chapter, 154 and sectioning commands. Document structure levels are: 155 \part{} 156 \chapter{} 157 \section{} 158 \subsection{} 159 \subsubsection{} 160 161 To keep things simpler, \part{} is supported, though treated as being at 162 the same level as chapter. Consequently, there are four levels displayed 163 for a tex filetype's table of contents, regardless of the \documentclass{}, 164 i.e., part and chapter (at level 1), section (level 2), subsection (level 3), 165 and subsubsection (level 4). 166 167 Also supported are: 168 - The "*" used to produce unnumbered headings, which are not intended 169 for reproduction in a table of contents: > 170 \section*{Unnumbered section heading not produced in the TOC} 171 < - Manual toc entries using \addcontentsline, for example: > 172 \addcontentsline{toc}{section}{entry in the TOC only!} 173 < 174 The table of contents for a tex filetype is in a standardized form - 175 see |HelpToc-standardized-toc|. Omitted are: the "\", the part, chapter, 176 *section, or addcontentsline, and the left and right curly 177 brackets preceding and following each heading's text. 178 179 3.7 vim *HelpToc-vim-filetype* 180 181 Vim script and Vim9 script do not have headings or levels inherently like 182 markup languages. However, Vim provides for |folds| defined by markers (|{{{|), 183 which themselves may be succeeded by a number explicitly indicating the fold 184 level. This is the structure recognized and supported by helptoc.vim. 185 So, for example, the following would produce three table of contents entries: > 186 187 vim9script 188 # Variables {{{1 189 var b: bool = true 190 var s: string = $"Fold markers are great? {b}!" 191 # Functions {{{1 192 def MyFunction(): void #{{{2 193 echo s 194 enddef 195 MyFunction() 196 < 197 The table of contents for that script would appear like this: 198 Variables 199 Functions 200 | MyFunction(): void 201 202 Note: The numbered |{{{| marker structure is the only one supported by 203 helptoc.vim for the vim filetype. 204 205 As the {{{1 to {{{6 markers make the "headings" explicit, the table of 206 contents is in a standardized form - see |HelpToc-standardized-toc|. 207 It does not include any leading comment markers (i.e., either # or ") and 208 omits the markers themselves. 209 210 3.8 xhtml *HelpToc-xhtml-filetype* 211 212 Although XHTML, being XML, is more strictly structured than HTML/HTML5, 213 there is no practical difference in treatment required for the xhtml filetype 214 because, at the heading level, the tags that matter are very similar. 215 See |HelpToc-html-filetype| for how an xhtml filetype's table of contents is 216 supported. 217 218 219 4. STANDARDIZED TOC *HelpToc-standardized-toc* 220 221 The table of contents for a help buffer, terminal, or man page, make sense 222 being presented in the form they appear, minus trailing content (such as tags). 223 224 The table of contents for a markdown, asciidoc, [x]html, terminal, or tex 225 buffer have superfluous content if the entire line was to be returned. 226 For example: 227 - Markdown has "#" characters before headings when using ATX heading notation. 228 - Asciidoc will have either those or, more often, "=" characters before its 229 headings. 230 - HTML, aside from the "<h" headings, may have additional tags, comments, 231 and whitespace before its headings. 232 - The Vim terminal has the shell prompt, which adds nothing if repeated for 233 every heading (and may be very long). 234 - LaTeX has "\" level indicators like "\section{" and a trailing "}". 235 Consequently, standardising these filetypes' tables of contents, removing 236 the "noise", and indicating the contents level of each entry, makes sense. 237 238 HelpToc standardizes the markdown, asciidoc, [x]html, terminal and tex tables 239 of contents by removing extraneous characters, markup indicators, and tags. 240 It also applies simple, unobtrusive syntax highlighting to the text and level 241 indicators. By default, it will appear like the following example (though 242 any level indicators will be less prominent, using |NonText| highlight group). 243 244 Level 1 245 | Level 2 246 | | Level 3 247 | | | Level 4 248 | | | | Level 5 249 | | | | | Level 6 250 251 Note: The "| " level indicator may be changed - see |HelpToc-configuration|. 252 253 254 5. CONFIGURATION *HelpToc-configuration* 255 256 All configuration is achieved utilizing the g:helptoc dictionary. Any of the 257 following may be adjusted to meet your needs or preferences: 258 259 g:helptoc key what it controls 260 ------------- ---------------- 261 shell_prompt The terminal prompt, used for creating a table of contents 262 for the terminal (history list). The default is, 263 '^\w\+@\w\+:\f\+\$\s', which should match many users' bash 264 prompt. To change it, either interactively or in your .vimrc, 265 use (for example for a bare Bourne shell "$ " prompt): > 266 vim9 g:helptoc.shell_prompt = '^\$\s' 267 268 <level_indicator This key's value controls the level indicator used in 269 standardized tables of contents. The default is '| ' 270 (i.e., a vertical bar and a space), but may be changed to 271 whatever you want. For example, for a broken bar and space: > 272 vim9 g:helptoc.level_indicator = '¦ ' 273 < 274 popup_border By default, the table of contents border will appear above, 275 right, below, and left of the popup window. If you prefer 276 not to have the border on the right and left (for example 277 only), you can achieve that with: > 278 vim9 g:helptoc.popup_border = [1, 0, 1, 0] 279 <popup_borderchars 280 The default border characters for the table of contents popup 281 window is the list ['─', '│', '─', '│', '┌', '┐', '┘', '└']. 282 There's nothing wrong with those box drawing characters, 283 though, for example, if you wanted a border that only uses 284 ASCII characters, you could make the border spaces only: > 285 vim9 g:helptoc.popup_borderchars = [' '] 286 <popup_borderhighlight 287 The default border highlight group is Normal. You can change 288 that, perhaps in combination with popup_borderchars, above, 289 to create a very clearly prominent border. For example, if 290 the popup_borderchars are made [' '], like above, the border 291 could be made a solid colour different to the background 292 with: > 293 vim9 g:helptoc.popup_borderhighlight = ['Cursor'] 294 295 < Note: Choosing a highlight group that persists when 296 colorschemes change may be a good idea if you 297 do choose to customize this. 298 299 popup_drag By default, table of contents popup windows may be dragged 300 with a mouse. If you want to prevent that from happening, 301 for whatever reason, you may deactivate it with: > 302 vim9 g:helptoc.popup_drag = false 303 < 304 popup_close Table of contents popups have "none" as the default setting 305 for this option. If you use a mouse, you may want either 306 to have the option to close popup windows by clicking on them 307 or to have a clickable "X" in the top right corner. For the 308 former, use "click", and for the latter, use "button", e.g.: > 309 vim9 g:helptoc.popup_close = "button" 310 <popup_scrollbar 311 No scrollbar is provided on helptoc popups by default. If you 312 do want scrollbars (which may be useful as an indicator of how 313 far through the table of contents you are, not just for using 314 with a mouse) you may choose to have them with: > 315 vim9 g:helptoc.popup_scrollbar = true 316 < 317 NOTE: Information about the "popup_*" options, above, relate to popup options, 318 which are explained at the 'second argument' part of |popup_create-arguments|. 319 320 321 6. LIMITATIONS *HelpToc-limitations* 322 323 - The help filetype may have edge case formatting patterns. Those may result 324 in some "headings" not being identified and/or may impact the heading levels 325 of entries in the table of contents itself. 326 - Terminal window table of contents may not be active (insofar as jumping to 327 entries going to the Vim terminal's related command line). For example, if 328 Vim's terminal is set to Windows PowerShell Core, the table of contents will 329 display successfully, though the entries go nowhere when Enter, J, or K are 330 entered on them. 331 - The tex filetype may have variable sectioning commands depending on the 332 document class. Consequently, some compromises are made, though they should 333 have minimal impact. Specifically: 334 * In instances where \part{} and \chapter{} appear in the same buffer, they 335 will both present at the top level in the table of contents. This should 336 be a minor matter because, in many instances, chapters will be in a 337 separate document using \include{}. 338 * An article or beamer \documentclass without a \part{} (or any document 339 with neither any \part{} nor any \chapter{} command) will have no content 340 at level 1. Consequently, its table of contents entries will all appear 341 preceded by at least one "| " (by default) because its headings start at 342 level 2 (presuming \section{} is present). 343 - The vim filetype is only supported where numbered fold markers are applied. 344 This is intentional (including not handling unnumbered markers, which, when 345 used in combination with numbered ones, may be used for folding comments). 346 helptoc.vim itself provides an exemplar of how to use numbered fold markers, 347 not only for folds, but to support generating a useful table of contents 348 using :HelpToc. 349 350 ============================================================================== 351 vim:tw=78:ts=8:fo=tcq2:ft=help: