vim-help.md

   1 ---
   2 title: Vim helpfiles
   3 category: Vim
   4 layout: 2017/sheet
   5 updated: 2017-09-09
   6 ---
   7
   8 ## Writing help files
   9 {: .-left-reference}
  10
  11 ### Creating a document
  12
  13 ```nohighlight
  14 :e doc/potion.txt
  15 :set ft=help
  16 :set ft=text
  17 ```
  18
  19 Use `ft=help` to preview it, and `ft=text` to edit it.
  20
  21 ### Example
  22
  23 ```nohighlight
  24 *ack.txt*   Plugin that integrates ack with Vim
  25
  26 ==============================================================================
  27 USAGE INSTRUCTIONS                                                 *ack-usage*
  28
  29 :Ack[!] {pattern}                                                       *:Ack*
  30
  31     Search recursively for {pattern}. See |:AckAdd|.
  32     Also see http://beyondgrep.com for more information.
  33
  34 vim:tw=78:ts=8:ft=help:norl:
  35 ```
  36
  37 This is a cheatsheet for writing Vim help files. See: `:help help-writing`
  38
  39 ## Syntax
  40
  41 ### Reference
  42
  43 | Code                 | Description    | Example             |
  44 | -----                | -----          | -----               |
  45 | *Inline items*                                              |
  46 | -----                | -----          | -----               |
  47 | `*tags*`             | Tags           |                     |
  48 | `|link-to-tags|`     | Links to tags  | `|:command|`        |
  49 | `'vimoption'`        | Vim option     | `'textwidth'`       |
  50 | -----                | -----          | -----               |
  51 | `{code-text}`        | Code text      | `{Visual}gf`        |
  52 | `<code-text>`        | Code text      | `<PageDown>`        |
  53 | `` `code-text` ``    | Code text      | `` `set fo=want` `` |
  54 | `CTRL-X`             | Code text      |                     |
  55 | -----                | -----          | -----               |
  56 | *Block items*                                               |
  57 | -----                | -----          | -----               |
  58 | `INTRODUCTION *tag*` | Section header |                     |
  59 | `Column heading~`    | Highlighting   |                     |
  60 | `www.url.com`        | Web URL        |                     |
  61 | -----                | -----          | -----               |
  62 | `=====`              | Separator      |                     |
  63 | `-----`              | Separator      |                     |
  64
  65 ### Tags
  66
  67  * Tags are created with asterisks, eg, `*potion-usage*`
  68  * Links to tags are `|potion-usage|`
  69  * Press `^]` to jump to a tag
  70
  71 ### Code blocks
  72
  73 ```
  74 Example: >
  75  xyz
  76 <
  77 ```
  78
  79 Surround with `>` and `<` characters
  80
  81 ### File header
  82
  83 ```
  84 *potion.txt*  functionality for the potion programming language
  85 ```
  86
  87 It's customary to start a file with a tag of the filename, plus a description.
  88
  89 ### Heading
  90
  91 ```
  92 ==============================================================================
  93 CONTENTS                                                     *potion-contents*
  94 ```
  95
  96 Starts with `ALL CAPS`, ends with `*a-tag*`
  97
  98 ### Notes
  99 Using `*Todo` and `*Error` will highlight your notes.
 100
 101 ```
 102         *Todo something to do
 103         *Error something wrong
 104 ```
 105
 106 ### Final modeline
 107
 108 ```nohighlight
 109 vim:tw=78:ts=8:ft=help:norl:
 110 ```
 111
 112 ## Conventions
 113
 114 ### Table of contents
 115
 116 ```nohighlight
 117 |rails-introduction|            Introduction and Feature Summary
 118 |rails-commands|                General Commands
 119 |rails-navigation|              Navigation
 120 ```
 121
 122 ```nohighlight
 123     1.Intro...................................|ergonomic|
 124     2.Note to use..............................|CAPSLOCK|
 125     3.Insert Mode Remappings............|ergonomicInsert|
 126 ```
 127
 128 ### Author lines
 129
 130 ```nohighlight
 131 Author:  Jack Hackness <captain@time.com>         *xyz-author*
 132 License: Same terms as Vim itself (see |license|)
 133 ```