## 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

- Tags are created with asterisks, eg, `*potion-usage*`
- Links to tags are `|potion-usage|`
- Press `^]` to jump to a tag

### 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|)

0 Comments for this cheatsheet. Write yours!