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 JSON syntax highlight requires vim-json [9].
 177 >
 178   let g:vim_markdown_json_frontmatter = 1
 179 <
 180 ===============================================================================
 181                                                         *vim-markdown-mappings*
 182 Mappings ~
 183
 184 The following work on normal and visual modes:
 185
 186                                                                            *gx*
 187 - 'gx': open the link under the cursor in the same browser as the standard
 188   'gx' command. '<Plug>Markdown_OpenUrlUnderCursor'
 189
 190   The standard 'gx' is extended by allowing you to put your cursor anywhere
 191   inside a link.
 192
 193   For example, all the following cursor positions will work:
 194 >
 195   [Example](http://example.com)
 196   ^  ^    ^^   ^       ^
 197   1  2    34   5       6
 198
 199   <http://example.com>
 200   ^  ^               ^
 201   1  2               3
 202 <
 203   Known limitation: does not work for links that span multiple lines.
 204
 205                                                                            *]]*
 206 - ']]': go to next header. '<Plug>Markdown_MoveToNextHeader'
 207
 208                                                                            *[[*
 209 - '[[': go to previous header. Contrast with ']c'.
 210   '<Plug>Markdown_MoveToPreviousHeader'
 211
 212                                                                            *][*
 213 - '][': go to next sibling header if any.
 214   '<Plug>Markdown_MoveToNextSiblingHeader'
 215
 216                                                                            *[]*
 217 - '[]': go to previous sibling header if any.
 218   '<Plug>Markdown_MoveToPreviousSiblingHeader'
 219
 220                                                                            *]c*
 221 - ']c': go to Current header. '<Plug>Markdown_MoveToCurHeader'
 222
 223                                                                            *]u*
 224 - ']u': go to parent header (Up). '<Plug>Markdown_MoveToParentHeader'
 225
 226 This plugin follows the recommended Vim plugin mapping interface, so to change
 227 the map ']u' to 'asdf', add to your '.vimrc':
 228 >
 229   map asdf <Plug>Markdown_MoveToParentHeader
 230 <
 231 To disable a map use:
 232 >
 233   map <Plug> <Plug>Markdown_MoveToParentHeader
 234 <
 235 ===============================================================================
 236                                                         *vim-markdown-commands*
 237 Commands ~
 238
 239 The following requires ':filetype plugin on'.
 240
 241                                                               *:HeaderDecrease*
 242 - ':HeaderDecrease':
 243
 244   Decrease level of all headers in buffer: 'h2' to 'h1', 'h3' to 'h2', etc.
 245
 246   If range is given, only operate in the range.
 247
 248   If an 'h1' would be decreased, abort.
 249
 250   For simplicity of implementation, Setex headers are converted to Atx.
 251
 252                                                               *:HeaderIncrease*
 253 - ':HeaderIncrease': Analogous to ':HeaderDecrease', but increase levels
 254   instead.
 255
 256                                                                   *:SetexToAtx*
 257 - ':SetexToAtx':
 258
 259   Convert all Setex style headers in buffer to Atx.
 260
 261   If a range is given, e.g. hit ':' from visual mode, only operate on the
 262   range.
 263
 264                                                                  *:TableFormat*
 265 - ':TableFormat': Format the table under the cursor like this [10].
 266
 267   Requires Tabular [11].
 268
 269   The input table _must_ already have a separator line as the second line of
 270   the table. That line only needs to contain the correct pipes '|', nothing
 271   else is required.
 272
 273                                                                          *:Toc*
 274 - ':Toc': create a quickfix vertical window navigable table of contents with
 275   the headers.
 276
 277   Hit '<Enter>' on a line to jump to the corresponding line of the markdown
 278   file.
 279
 280                                                                         *:Toch*
 281 - ':Toch': Same as ':Toc' but in an horizontal window.
 282
 283                                                                         *:Toct*
 284 - ':Toct': Same as ':Toc' but in a new tab.
 285
 286                                                                         *:Tocv*
 287 - ':Tocv': Same as ':Toc' for symmetry with ':Toch' and 'Tocv'.
 288
 289 ===============================================================================
 290                                                          *vim-markdown-credits*
 291 Credits ~
 292
 293 The main contributors of vim-markdown are:
 294
 295 - **Ben Williams** (A.K.A. **plasticboy**). The original developer of vim-
 296   markdown. Homepage [12].
 297
 298 If you feel that your name should be on this list, please make a pull request
 299 listing your contributions.
 300
 301 ===============================================================================
 302                                                          *vim-markdown-license*
 303 License ~
 304
 305 The MIT License (MIT)
 306
 307 Copyright (c) 2012 Benjamin D. Williams
 308
 309 Permission is hereby granted, free of charge, to any person obtaining a copy of
 310 this software and associated documentation files (the "Software"), to deal in
 311 the Software without restriction, including without limitation the rights to
 312 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
 313 of the Software, and to permit persons to whom the Software is furnished to do
 314 so, subject to the following conditions:
 315
 316 The above copyright notice and this permission notice shall be included in all
 317 copies or substantial portions of the Software.
 318
 319 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 320 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 321 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 322 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 323 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 324 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 325 SOFTWARE.
 326
 327 ===============================================================================
 328                                                       *vim-markdown-references*
 329 References ~
 330
 331 [1] http://daringfireball.net/projects/markdown/
 332 [2] https://github.com/gmarik/vundle
 333 [3] https://github.com/tpope/vim-pathogen
 334 [4] http://packages.qa.debian.org/v/vim-addon-manager.html
 335 [5] https://github.com/plasticboy/vim-markdown/archive/master.tar.gz
 336 [6] https://github.com/klen/python-mode
 337 [7] https://gohugo.io/content/front-matter/
 338 [8] https://github.com/cespare/vim-toml
 339 [9] https://github.com/elzr/vim-json
 340 [10] http://www.cirosantilli.com/markdown-style-guide/#tables
 341 [11] https://github.com/godlygeek/tabular
 342 [12] http://plasticboy.com/
 343
 344 vim: ft=help