A reference guide for authoring, styling, and formatting native Vim help documentation files (doc/*.txt).
Writing Help Files
File Creation & Filetypes
:edit doc/myplugin.txt
:set filetype=help " Preview rendering and tag highlights
:set filetype=text " Convenient editing mode
Use ft=help to preview the document styling and ft=text during initial editing.
Sample Structure
*ack.txt* Plugin that integrates ack with Vim
==============================================================================
USAGE INSTRUCTIONS *ack-usage*
:Ack[!] {pattern} *:Ack*
Search recursively for {pattern}. See |:AckAdd|.
Also see http://beyondgrep.com for more information.
vim:tw=78:ts=8:ft=help:norl:
See :help help-writing inside Vim for full official guidelines.
Syntax & Elements
Markup Reference
| Syntax | Description | Example |
|---|---|---|
*tag* |
Definitive jump target tag | *myplugin-intro* |
|tag| |
Hyperlink jumping to tag | |:command| |
'option' |
Vim configuration option | 'textwidth' |
{placeholder} |
Required / optional argument | {Visual}gf |
<key> |
Special keyboard key | <PageDown>, <CR> |
`command` |
Inline command or code string | `set fo=want` |
CTRL-X |
Key combination with Control | CTRL-] |
HEADING *tag* |
Uppercase section header with tag | INSTALLATION *my-install* |
Heading~ |
Subheading or column header with tilde | Options~ |
===== |
Major section divider rule (78 chars) | ====================== |
----- |
Subsection divider rule (78 chars) | ---------------------- |
Tags & Navigation
- Wrap target anchor names with asterisks:
*plugin-tag* - Link to targets with pipe characters:
|plugin-tag| - Press
Ctrl-]on a pipe-delimited link to jump directly to the target tag; pressCtrl-TorCtrl-Oto return.
Code Blocks
Indicate code blocks by ending the preceding paragraph with > and ending the block with < at the beginning of a line:
Example: >
let g:loaded_myplugin = 1
call myplugin#setup()
<
Document Header
*myplugin.txt* Extended utility toolkit for Vim
Always place a primary tag containing the filename on the very first line, followed by a brief summary description.
Help Modeline
Add a modeline to the very last line of the file:
vim:tw=78:ts=8:ft=help:norl:
Conventions
Table of Contents
CONTENTS *myplugin-contents*
1. Introduction .............................. |myplugin-intro|
2. Commands .................................. |myplugin-commands|
3. Configuration Options ..................... |myplugin-options|
Author & License Block
Author: Jack Hackness <[email protected]> *myplugin-author*
License: Same terms as Vim itself (see |license|)