doc/vim-markdown.txt

   1 *vim-markdown*  Vim Markdown
   2
   3 ===============================================================================
   4 Contents ~
   5
   6  1. Introduction                                    |vim-markdown-introduction|
   7  2. Installation                                    |vim-markdown-installation|
   8  3. Options                                              |vim-markdown-options|
   9   1. Disable Folding                             |vim-markdown-disable-folding|
  10   2. Change fold style                         |vim-markdown-change-fold-style|
  11   3. Set header folding level           |vim-markdown-set-header-folding-level|
  12   4. Disable Default Key Mappings   |vim-markdown-disable-default-key-mappings|
  13   5. Enable TOC window auto-fit       |vim-markdown-enable-toc-window-auto-fit|
  14   6. Syntax Concealing                         |vim-markdown-syntax-concealing|
  15   7. Syntax extensions                         |vim-markdown-syntax-extensions|
  16    1. LaTeX math                                      |vim-markdown-latex-math|
  17    2. YAML Front Matter                        |vim-markdown-yaml-front-matter|
  18    3. TOML Front Matter                        |vim-markdown-toml-front-matter|
  19    4. JSON Front Matter                        |vim-markdown-json-front-matter|
  20  4. Mappings                                            |vim-markdown-mappings|
  21  5. Commands                                            |vim-markdown-commands|
  22  6. Credits                                              |vim-markdown-credits|
  23  7. License                                              |vim-markdown-license|
  24  8. References                                        |vim-markdown-references|
  25
  26 ===============================================================================
  27                                                     *vim-markdown-introduction*
  28 Introduction ~
  29
  30 Syntax highlighting, matching rules and mappings for the original Markdown [1]
  31 and extensions.
  32
  33 ===============================================================================
  34                                                     *vim-markdown-installation*
  35 Installation ~
  36
  37 If you use Vundle [2], add the following line to your '~/.vimrc':
  38 >
  39   Plugin 'godlygeek/tabular'
  40   Plugin 'plasticboy/vim-markdown'
  41 <
  42 The 'tabular' plugin must come _before_ 'vim-markdown'.
  43
  44 Then run inside Vim:
  45 >
  46   :so ~/.vimrc
  47   :PluginInstall
  48 <
  49 If you use Pathogen [3], do this:
  50 >
  51   cd ~/.vim/bundle
  52   git clone https://github.com/plasticboy/vim-markdown.git
  53 <
  54 To install without Pathogen using the Debian vim-addon-manager [4], do this:
  55 >
  56   git clone https://github.com/plasticboy/vim-markdown.git
  57   cd vim-markdown
  58   sudo make install
  59   vim-addon-manager install markdown
  60 <
  61 If you are not using any package manager, download the tarball [5] and do this:
  62 >
  63   cd ~/.vim
  64   tar --strip=1 -zxf vim-markdown-master.tar.gz
  65 <
  66 ===============================================================================
  67                                                          *vim-markdown-options*
  68 Options ~
  69
  70 -------------------------------------------------------------------------------
  71                                                  *vim-markdown-disable-folding*
  72 Disable Folding ~
  73
  74 Add the following line to your '.vimrc' to disable the folding configuration:
  75 >
  76   let g:vim_markdown_folding_disabled = 1
  77 <
  78 This option only controls Vim Markdown specific folding configuration.
  79
  80 To enable/disable folding use Vim's standard folding configuration.
  81 >
  82   set [no]foldenable
  83 <
  84 -------------------------------------------------------------------------------
  85                                                *vim-markdown-change-fold-style*
  86 Change fold style ~
  87
  88 To fold in a style like python-mode [6], add the following to your '.vimrc':
  89 >
  90   let g:vim_markdown_folding_style_pythonic = 1
  91 <
  92 -------------------------------------------------------------------------------
  93                                         *vim-markdown-set-header-folding-level*
  94 Set header folding level ~
  95
  96 Folding level is a number between 1 and 6. By default, if not specified, it is
  97 set to 1.
  98 >
  99   let g:vim_markdown_folding_level = 6
 100 <
 101 Tip: it can be changed on the fly with:
 102 >
 103   :let g:vim_markdown_folding_level = 1
 104   :edit
 105 <
 106 -------------------------------------------------------------------------------
 107                                     *vim-markdown-disable-default-key-mappings*
 108 Disable Default Key Mappings ~
 109
 110 Add the following line to your '.vimrc' to disable default key mappings:
 111 >
 112   let g:vim_markdown_no_default_key_mappings = 1
 113 <
 114 You can also map them by yourself with '<Plug>' mappings.
 115
 116 -------------------------------------------------------------------------------
 117                                       *vim-markdown-enable-toc-window-auto-fit*
 118 Enable TOC window auto-fit ~
 119
 120 Allow for the TOC window to auto-fit when it's possible for it to shrink. It
 121 never increases its default size (half screen), it only shrinks.
 122 >
 123   let g:vim_markdown_toc_autofit = 1
 124 <
 125 -------------------------------------------------------------------------------
 126                                                *vim-markdown-syntax-concealing*
 127 Syntax Concealing ~
 128
 129 Concealing is set for some syntax.
 130
 131 For example, conceal '[link text](link url)' as just 'link text'.
 132
 133 To enable/disable conceal use Vim's standard conceal configuration.
 134 >
 135   set conceallevel=2
 136 <
 137 -------------------------------------------------------------------------------
 138                                                *vim-markdown-syntax-extensions*
 139 Syntax extensions ~
 140
 141 The following options control which syntax extensions will be turned on. They
 142 are off by default.
 143
 144 -------------------------------------------------------------------------------
 145                                                       *vim-markdown-latex-math*
 146 LaTeX math ~
 147
 148 Used as '$x^2$', '$$x^2$$', escapable as '\$x\$' and '\$\$x\$\$'.
 149 >
 150   let g:vim_markdown_math = 1
 151 <
 152 -------------------------------------------------------------------------------
 153                                                *vim-markdown-yaml-front-matter*
 154 YAML Front Matter ~
 155
 156 Highlight YAML front matter as used by Jekyll or Hugo [7].
 157 >
 158   let g:vim_markdown_frontmatter = 1
 159 <
 160 -------------------------------------------------------------------------------
 161                                                *vim-markdown-toml-front-matter*
 162 TOML Front Matter ~
 163
 164 Highlight TOML front matter as used by Hugo [7].
 165
 166 TOML syntax highlight requires vim-toml [8].
 167 >
 168   let g:vim_markdown_toml_frontmatter = 1
 169 <
 170 -------------------------------------------------------------------------------
 171                                                *vim-markdown-json-front-matter*
 172 JSON Front Matter ~
 173
 174 Highlight JSON front matter as used by Hugo [7].
 175 >
 176   let g:vim_markdown_json_frontmatter = 1
 177 <
 178 ===============================================================================
 179                                                         *vim-markdown-mappings*
 180 Mappings ~
 181
 182 The following work on normal and visual modes:
 183
 184                                                                            *gx*
 185 - 'gx': open the link under the cursor in the same browser as the standard
 186   'gx' command. '<Plug>Markdown_OpenUrlUnderCursor'
 187
 188   The standard 'gx' is extended by allowing you to put your cursor anywhere
 189   inside a link.
 190
 191   For example, all the following cursor positions will work:
 192 >
 193   [Example](http://example.com)
 194   ^  ^    ^^   ^       ^
 195   1  2    34   5       6
 196
 197   <http://example.com>
 198   ^  ^               ^
 199   1  2               3
 200 <
 201   Known limitation: does not work for links that span multiple lines.
 202
 203                                                                            *]]*
 204 - ']]': go to next header. '<Plug>Markdown_MoveToNextHeader'
 205
 206                                                                            *[[*
 207 - '[[': go to previous header. Contrast with ']c'.
 208   '<Plug>Markdown_MoveToPreviousHeader'
 209
 210                                                                            *][*
 211 - '][': go to next sibling header if any.
 212   '<Plug>Markdown_MoveToNextSiblingHeader'
 213
 214                                                                            *[]*
 215 - '[]': go to previous sibling header if any.
 216   '<Plug>Markdown_MoveToPreviousSiblingHeader'
 217
 218                                                                            *]c*
 219 - ']c': go to Current header. '<Plug>Markdown_MoveToCurHeader'
 220
 221                                                                            *]u*
 222 - ']u': go to parent header (Up). '<Plug>Markdown_MoveToParentHeader'
 223
 224 This plugin follows the recommended Vim plugin mapping interface, so to change
 225 the map ']u' to 'asdf', add to your '.vimrc':
 226 >
 227   map asdf <Plug>Markdown_MoveToParentHeader
 228 <
 229 To disable a map use:
 230 >
 231   map <Plug> <Plug>Markdown_MoveToParentHeader
 232 <
 233 ===============================================================================
 234                                                         *vim-markdown-commands*
 235 Commands ~
 236
 237 The following requires ':filetype plugin on'.
 238
 239                                                               *:HeaderDecrease*
 240 - ':HeaderDecrease':
 241
 242   Decrease level of all headers in buffer: 'h2' to 'h1', 'h3' to 'h2', etc.
 243
 244   If range is given, only operate in the range.
 245
 246   If an 'h1' would be decreased, abort.
 247
 248   For simplicity of implementation, Setex headers are converted to Atx.
 249
 250                                                               *:HeaderIncrease*
 251 - ':HeaderIncrease': Analogous to ':HeaderDecrease', but increase levels
 252   instead.
 253
 254                                                                   *:SetexToAtx*
 255 - ':SetexToAtx':
 256
 257   Convert all Setex style headers in buffer to Atx.
 258
 259   If a range is given, e.g. hit ':' from visual mode, only operate on the
 260   range.
 261
 262                                                                  *:TableFormat*
 263 - ':TableFormat': Format the table under the cursor like this [9].
 264
 265   Requires Tabular [10].
 266
 267   The input table _must_ already have a separator line as the second line of
 268   the table. That line only needs to contain the correct pipes '|', nothing
 269   else is required.
 270
 271                                                                          *:Toc*
 272 - ':Toc': create a quickfix vertical window navigable table of contents with
 273   the headers.
 274
 275   Hit '<Enter>' on a line to jump to the corresponding line of the markdown
 276   file.
 277
 278                                                                         *:Toch*
 279 - ':Toch': Same as ':Toc' but in an horizontal window.
 280
 281                                                                         *:Toct*
 282 - ':Toct': Same as ':Toc' but in a new tab.
 283
 284                                                                         *:Tocv*
 285 - ':Tocv': Same as ':Toc' for symmetry with ':Toch' and 'Tocv'.
 286
 287 ===============================================================================
 288                                                          *vim-markdown-credits*
 289 Credits ~
 290
 291 The main contributors of vim-markdown are:
 292
 293 - **Ben Williams** (A.K.A. **plasticboy**). The original developer of vim-
 294   markdown. Homepage [11].
 295
 296 If you feel that your name should be on this list, please make a pull request
 297 listing your contributions.
 298
 299 ===============================================================================
 300                                                          *vim-markdown-license*
 301 License ~
 302
 303 The MIT License (MIT)
 304
 305 Copyright (c) 2012 Benjamin D. Williams
 306
 307 Permission is hereby granted, free of charge, to any person obtaining a copy of
 308 this software and associated documentation files (the "Software"), to deal in
 309 the Software without restriction, including without limitation the rights to
 310 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
 311 of the Software, and to permit persons to whom the Software is furnished to do
 312 so, subject to the following conditions:
 313
 314 The above copyright notice and this permission notice shall be included in all
 315 copies or substantial portions of the Software.
 316
 317 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 318 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 319 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 320 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 321 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 322 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 323 SOFTWARE.
 324
 325 ===============================================================================
 326                                                       *vim-markdown-references*
 327 References ~
 328
 329 [1] http://daringfireball.net/projects/markdown/
 330 [2] https://github.com/gmarik/vundle
 331 [3] https://github.com/tpope/vim-pathogen
 332 [4] http://packages.qa.debian.org/v/vim-addon-manager.html
 333 [5] https://github.com/plasticboy/vim-markdown/archive/master.tar.gz
 334 [6] https://github.com/klen/python-mode
 335 [7] https://gohugo.io/content/front-matter/
 336 [8] https://github.com/cespare/vim-toml
 337 [9] http://www.cirosantilli.com/markdown-style-guide/#tables
 338 [10] https://github.com/godlygeek/tabular
 339 [11] http://plasticboy.com/
 340
 341 vim: ft=help