Writing help files

Creating a document

:e doc/potion.txt
:set ft=help
:set ft=text

Use ft=help to preview it, and ft=text to edit it.

Example

*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:

This is a cheatsheet for writing Vim help files. See: :help help-writing

Syntax

Reference

Code Description Example
Inline items    
*tags* Tags  
|link-to-tags| Links to tags |:command|
'vimoption' Vim option 'textwidth'
{code-text} Code text {Visual}gf
<code-text> Code text <PageDown>
`code-text` Code text `set fo=want`
CTRL-X Code text  
Block items    
INTRODUCTION *tag* Section header  
Column heading~ Highlighting  
www.url.com Web URL  
===== Separator  
----- Separator  

Tags

Code blocks

Example: >
 xyz
<

Surround with > and < characters

File header

*potion.txt*  functionality for the potion programming language

It’s customary to start a file with a tag of the filename, plus a description.

Heading

==============================================================================
CONTENTS                                                     *potion-contents*

Starts with ALL CAPS, ends with *a-tag*

Notes

Using *Todo and *Error will highlight your notes.

	*Todo something to do
	*Error something wrong

Final modeline

vim:tw=78:ts=8:ft=help:norl:

Conventions

Table of contents

|rails-introduction|            Introduction and Feature Summary
|rails-commands|                General Commands
|rails-navigation|              Navigation

    1.Intro...................................|ergonomic|
    2.Note to use..............................|CAPSLOCK|
    3.Insert Mode Remappings............|ergonomicInsert|

Author lines

Author:  Jack Hackness <captain@time.com>         *xyz-author*
License: Same terms as Vim itself (see |license|)