]> git.madduck.net Git - etc/vim.git/blob - doc/vim-markdown.txt

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

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