]> 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:

Add bash for fenced code block syntax #93
[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. 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