Help File Formatting: Tags, Highlighting, and Filetype Completion

following format: > *plugin_name.txt* {short description of the plugin} The first field is a help tag where ":help plugin_name" will jump to. The remainder of the line, after a Tab, describes the plugin purpose in a short way. This will show up in the "LOCAL ADDITIONS" section of the main help file. Check there that it shows up properly: |local-additions|. If you want to add a version number or last modification date, put it in the second line, right aligned. At the bottom of the help file, place a Vim modeline to set the 'textwidth' and 'tabstop' options and the 'filetype' to "help". Never set a global option in such a modeline, that can have undesired consequences. TAGS To define a help tag, place the name between asterisks ("*tag-name*"). The tag-name should be different from all the Vim help tag names and ideally should begin with the name of the Vim plugin. The tag name is usually right aligned on a line. When referring to an existing help tag and to create a hot-link, place the name between two bars ("|") eg. |help-writing|. When referring to a Vim command and to create a hot-link, place the name between two backticks, eg. inside `:filetype`. You will see this is highlighted as a command, like a code block (see below). When referring to a Vim option in the help file, place the option name between two single quotes, eg. 'statusline' When referring to any other technical term, such as a filename or function parameter, surround it in backticks, eg. `~/.path/to/init.vim`. HIGHLIGHTING To define a column heading, use a tilde character at the end of the line, preceded by a space. This will highlight the column heading in a different color. E.g. Column heading ~ To separate sections in a help file, place a series of '=' characters in a line starting from the first column. The section separator line is highlighted differently. *help-codeblock* To quote a block of ex-commands verbatim, place a greater than (>) character at the end of the line before the block and a less than (<) character as the first non-blank on a line following the block. Any line starting in column 1 also implicitly stops the block of ex-commands before it. E.g. > function Example_Func() echo "Example" endfunction < To enable syntax highlighting for a block of code, place a language name annotation (e.g. "vim") after a greater than (>) character. E.g. >vim function Example_Func() echo "Example" endfunction < *help-notation* The following are highlighted differently in a Vim help file: - a special key name expressed either in <> notation as in <PageDown>, or as a Ctrl character as in CTRL-X - anything between {braces}, e.g. {lhs} and {rhs} The word "Note", "Notes" and similar automagically receive distinctive highlighting. So do these: Todo something to do Error something wrong You can find the details in $VIMRUNTIME/syntax/help.vim FILETYPE COMPLETION *ft-help-omni* To get completion for help tags when writing a tag reference, you can use the |i_CTRL-X_CTRL-O| command. vim:tw=78:ts=8:noet:ft=help:norl:

This section details the formatting conventions for Vim help files, including defining tags with asterisks, creating hot-links to existing tags, Vim commands, and options using bars, backticks and single quotes respectively. It also describes highlighting conventions for column headings, section separators, and code blocks, and lists automatically highlighted words like 'Note' and 'Todo'. Finally, it covers filetype completion for help tags using the |i_CTRL-X_CTRL-O| command.