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