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: