1 # Emacs Markdown Mode [![MELPA badge][melpa-badge]][melpa-link] [![MELPA stable badge][melpa-stable-badge]][melpa-stable-link] [![Travis CI Build Status][travis-badge]][travis-link]
3 [melpa-link]: https://melpa.org/#/markdown-mode
4 [melpa-stable-link]: https://stable.melpa.org/#/markdown-mode
5 [melpa-badge]: https://melpa.org/packages/markdown-mode-badge.svg
6 [melpa-stable-badge]: https://stable.melpa.org/packages/markdown-mode-badge.svg
7 [travis-link]: https://travis-ci.org/jrblevin/markdown-mode
8 [travis-badge]: https://travis-ci.org/jrblevin/markdown-mode.svg?branch=master
10 <!-- This file is autogenerated by webpage.sh from the comments at the top of
11 markdown-mode.el. Make edits there, not here. -->
13 markdown-mode is a major mode for editing [Markdown][]-formatted
14 text. The latest stable version is markdown-mode 2.1, released on
15 January 9, 2016. See the [release notes][] for details.
16 markdown-mode is free software, licensed under the GNU GPL.
18 ![Markdown Mode Screenshot](http://jblevins.org/projects/markdown-mode/screenshots/20160108-001.png)
20 [Markdown]: http://daringfireball.net/projects/markdown/
21 [release notes]: http://jblevins.org/projects/markdown-mode/rev-2-1
25 The recommended way to install markdown-mode is to install the package
26 from [MELPA Stable](https://stable.melpa.org/#/markdown-mode)
27 using `package.el`. First, configure `package.el` and the MELPA Stable
28 repository by adding the following to your `.emacs`, `init.el`,
29 or equivalent startup file:
32 (add-to-list 'package-archives
33 '("melpa-stable" . "https://stable.melpa.org/packages/"))
36 Then, after restarting Emacs or evaluating the above statements, issue
37 the following command: <kbd>M-x package-install RET markdown-mode RET</kbd>.
38 When installed this way, the major modes `markdown-mode` and `gfm-mode`
39 will be autoloaded and `markdown-mode` will be used for file names
40 ending in either `.md` or `.markdown`.
42 Alternatively, if you manage loading packages with [use-package][]
43 then you can automatically install and configure `markdown-mode` by
44 adding a declaration such as this one to your init file (as an
45 example; adjust settings as desired):
47 (use-package markdown-mode
49 :commands (markdown-mode gfm-mode)
50 :mode (("README\\.md\\'" . gfm-mode)
51 ("\\.md\\'" . markdown-mode)
52 ("\\.markdown\\'" . markdown-mode))
53 :init (setq markdown-command "multimarkdown"))
55 [MELPA Stable]: http://stable.melpa.org/
56 [use-package]: https://github.com/jwiegley/use-package
60 Alternatively you can manually download and install markdown-mode.
61 First, download the [latest stable version][markdown-mode.el] and
62 save the file where Emacs can find it (i.e., a directory in your
63 `load-path`). You can then configure `markdown-mode` and `gfm-mode`
64 to load automatically by adding the following to your init file:
66 (autoload 'markdown-mode "markdown-mode"
67 "Major mode for editing Markdown files" t)
68 (add-to-list 'auto-mode-alist '("\\.markdown\\'" . markdown-mode))
69 (add-to-list 'auto-mode-alist '("\\.md\\'" . markdown-mode))
71 (autoload 'gfm-mode "markdown-mode"
72 "Major mode for editing GitHub Flavored Markdown files" t)
73 (add-to-list 'auto-mode-alist '("README\\.md\\'" . gfm-mode))
75 [markdown-mode.el]: http://jblevins.org/projects/markdown-mode/markdown-mode.el
77 **Development Version**
79 To follow or contribute to markdown-mode development, you can
80 browse or clone the Git repository
81 [on GitHub](https://github.com/jrblevin/markdown-mode):
83 git clone https://github.com/jrblevin/markdown-mode.git
85 If you prefer to install and use the development version, which may
86 become unstable at some times, you can either clone the Git
87 repository as above or install markdown-mode from
88 [MELPA](https://melpa.org/#/markdown-mode).
90 If you clone the repository directly, then make sure that Emacs can
91 find it by adding the following line to your startup file:
93 (add-to-list 'load-path "/path/to/markdown-mode/repository")
95 **Packaged Installation**
97 markdown-mode is also available in several package managers. You
98 may want to confirm that the package you install contains the
99 latest stable version first (and please notify the package
102 * Debian Linux: [elpa-markdown-mode][] and [emacs-goodies-el][]
103 * Ubuntu Linux: [elpa-markdown-mode][elpa-ubuntu] and [emacs-goodies-el][emacs-goodies-el-ubuntu]
104 * RedHat and Fedora Linux: [emacs-goodies][]
105 * NetBSD: [textproc/markdown-mode][]
106 * MacPorts: [markdown-mode.el][macports-package] ([pending][macports-ticket])
107 * FreeBSD: [textproc/markdown-mode.el][freebsd-port]
109 [elpa-markdown-mode]: https://packages.debian.org/sid/lisp/elpa-markdown-mode
110 [elpa-ubuntu]: http://packages.ubuntu.com/search?keywords=elpa-markdown-mode
111 [emacs-goodies-el]: http://packages.debian.org/emacs-goodies-el
112 [emacs-goodies-el-ubuntu]: http://packages.ubuntu.com/search?keywords=emacs-goodies-el
113 [emacs-goodies]: https://apps.fedoraproject.org/packages/emacs-goodies
114 [textproc/markdown-mode]: http://pkgsrc.se/textproc/markdown-mode
115 [macports-package]: https://trac.macports.org/browser/trunk/dports/editors/markdown-mode.el/Portfile
116 [macports-ticket]: http://trac.macports.org/ticket/35716
117 [freebsd-port]: http://svnweb.freebsd.org/ports/head/textproc/markdown-mode.el
121 `markdown-mode` depends on `cl-lib`, which has been bundled with
122 GNU Emacs since 24.3. Users of GNU Emacs 24.1 and 24.2 can install
123 `cl-lib` with `package.el`.
127 Keybindings are grouped by prefixes based on their function. For
128 example, the commands for inserting links are grouped under `C-c
129 C-a`, where the <kbd>C-a</kbd> is a mnemonic for the HTML `<a>` tag. In
130 other cases, the connection to HTML is not direct. For example,
131 commands dealing with headings begin with <kbd>C-c C-t</kbd> (mnemonic:
132 titling). The primary commands in each group will are described
133 below. You can obtain a list of all keybindings by pressing `C-c
134 C-h`. Movement and shifting commands tend to be associated with
135 paired delimiters such as <kbd>M-{</kbd> and <kbd>M-}</kbd> or <kbd>C-c <</kbd> and <kbd>C-c ></kbd>.
136 Outline navigation keybindings the same as in `org-mode`. Finally,
137 commands for running Markdown or doing maintenance on an open file
138 are grouped under the <kbd>C-c C-c</kbd> prefix. The most commonly used
139 commands are described below. You can obtain a list of all
140 keybindings by pressing <kbd>C-c C-h</kbd>.
142 * Hyperlinks: <kbd>C-c C-a</kbd>
144 In this group, <kbd>C-c C-a l</kbd> inserts an inline link of the form
145 `[text](url)`. The link text is determined as follows. First,
146 if there is an active region (i.e., when transient mark mode is
147 on and the mark is active), use it as the link text. Second,
148 if the point is at a word, use that word as the link text. In
149 these two cases, the original text will be replaced with the
150 link and point will be left at the position for inserting a
151 URL. Otherwise, insert empty link markup and place the point
152 for inserting the link text.
154 <kbd>C-c C-a L</kbd> inserts a reference link of the form `[text][label]`
155 and, optionally, a corresponding reference label definition.
156 The link text is determined in the same way as with an inline
157 link (using the region, when active, or the word at the point),
158 but instead of inserting empty markup as a last resort, the
159 link text will be read from the minibuffer. The reference
160 label will be read from the minibuffer in both cases, with
161 completion from the set of currently defined references. To
162 create an implicit reference link, press <kbd>RET</kbd> to accept the
163 default, an empty label. If the entered referenced label is
164 not defined, additionally prompt for the URL and (optional)
165 title. If a URL is provided, a reference definition will be
166 inserted in accordance with `markdown-reference-location`.
167 If a title is given, it will be added to the end of the
168 reference definition and will be used to populate the title
169 attribute when converted to XHTML.
171 <kbd>C-c C-a u</kbd> inserts a bare url, delimited by angle brackets. When
172 there is an active region, the text in the region is used as the
173 URL. If the point is at a URL, that url is used. Otherwise,
174 insert angle brackets and position the point in between them
175 for inserting the URL.
177 <kbd>C-c C-a f</kbd> inserts a footnote marker at the point, inserts a
178 footnote definition below, and positions the point for
179 inserting the footnote text. Note that footnotes are an
180 extension to Markdown and are not supported by all processors.
182 <kbd>C-c C-a w</kbd> behaves much like the inline link insertion command
183 and inserts a wiki link of the form `[[WikiLink]]`. If there
184 is an active region, use the region as the link text. If the
185 point is at a word, use the word as the link text. If there is
186 no active region and the point is not at word, simply insert
187 link markup. Note that wiki links are an extension to Markdown
188 and are not supported by all processors.
190 * Images: <kbd>C-c C-i</kbd>
192 <kbd>C-c C-i i</kbd> inserts markup for an inline image, using the
193 active region or the word at point, if any, as the alt text.
194 <kbd>C-c C-i I</kbd> behaves similarly and inserts a reference-style
197 Local images associated with image links may be displayed
198 inline in the buffer by pressing <kbd>C-c C-i C-t</kbd>
199 (`markdown-toggle-inline-images`). This is a toggle command, so
200 pressing this once again will remove inline images.
202 * Styles: <kbd>C-c C-s</kbd>
204 <kbd>C-c C-s e</kbd> inserts markup to make a region or word italic (<kbd>e</kbd>
205 for `<em>` or emphasis). If there is an active region, make
206 the region italic. If the point is at a non-italic word, make
207 the word italic. If the point is at an italic word or phrase,
208 remove the italic markup. Otherwise, simply insert italic
209 delimiters and place the cursor in between them. Similarly,
210 use <kbd>C-c C-s s</kbd> for bold (`<strong>`), <kbd>C-c C-s c</kbd> for
211 inline code (`<code>`), and <kbd>C-c C-s k</kbd> for inserting `<kbd>`
214 <kbd>C-c C-s b</kbd> inserts a blockquote using the active region, if any,
215 or starts a new blockquote. <kbd>C-c C-s C-b</kbd> is a variation which
216 always operates on the region, regardless of whether it is
217 active or not. The appropriate amount of indentation, if any,
218 is calculated automatically given the surrounding context, but
219 may be adjusted later using the region indentation commands.
221 <kbd>C-c C-s p</kbd> behaves similarly for inserting preformatted code
222 blocks, with <kbd>C-c C-s C-p</kbd> being the region-only counterpart.
224 * Headings: <kbd>C-c C-t</kbd>
226 All heading insertion commands use the text in the active
227 region, if any, as the heading text. Otherwise, if the current
228 line is not blank, they use the text on the current line.
229 Finally, the setext commands will prompt for heading text if
230 there is no active region and the current line is blank.
232 <kbd>C-c C-t h</kbd> inserts a heading with automatically chosen type and
233 level (both determined by the previous heading). <kbd>C-c C-t H</kbd>
234 behaves similarly, but uses setext (underlined) headings when
235 possible, still calculating the level automatically.
236 In cases where the automatically-determined level is not what
237 you intended, the level can be quickly promoted or demoted
238 (as described below). Alternatively, a <kbd>C-u</kbd> prefix can be
239 given to insert a heading promoted by one level or a <kbd>C-u C-u</kbd>
240 prefix can be given to insert a heading demoted by one level.
242 To insert a heading of a specific level and type, use <kbd>C-c C-t 1</kbd>
243 through <kbd>C-c C-t 6</kbd> for atx (hash mark) headings and <kbd>C-c C-t !</kbd> or
244 <kbd>C-c C-t @</kbd> for setext headings of level one or two, respectively.
245 Note that <kbd>!</kbd> is <kbd>S-1</kbd> and <kbd>@</kbd> is <kbd>S-2</kbd>.
247 If the point is at a heading, these commands will replace the
248 existing markup in order to update the level and/or type of the
249 heading. To remove the markup of the heading at the point,
250 press <kbd>C-c C-k</kbd> to kill the heading and press <kbd>C-y</kbd> to yank the
251 heading text back into the buffer.
253 * Horizontal Rules: <kbd>C-c -</kbd>
255 <kbd>C-c -</kbd> inserts a horizontal rule. By default, insert the
256 first string in the list `markdown-hr-strings` (the most
257 prominent rule). With a <kbd>C-u</kbd> prefix, insert the last string.
258 With a numeric prefix <kbd>N</kbd>, insert the string in position <kbd>N</kbd>
261 * Markdown and Maintenance Commands: <kbd>C-c C-c</kbd>
263 *Compile:* <kbd>C-c C-c m</kbd> will run Markdown on the current buffer
264 and show the output in another buffer. *Preview*: <kbd>C-c C-c p</kbd>
265 runs Markdown on the current buffer and previews, stores the
266 output in a temporary file, and displays the file in a browser.
267 *Export:* <kbd>C-c C-c e</kbd> will run Markdown on the current buffer
268 and save the result in the file `basename.html`, where
269 `basename` is the name of the Markdown file with the extension
270 removed. *Export and View:* press <kbd>C-c C-c v</kbd> to export the
271 file and view it in a browser. *Open:* <kbd>C-c C-c o</kbd> will open
272 the Markdown source file directly using `markdown-open-command`.
273 *Live Export*: Press <kbd>C-c C-c l</kbd> to turn on
274 `markdown-live-preview-mode` to view the exported output
275 side-by-side with the source Markdown. **For all export commands,
276 the output file will be overwritten without notice.**
277 `markdown-live-preview-window-function` can be customized to open
278 in a browser other than `eww`. If you want to force the
279 preview window to appear at the bottom or right, you can
280 customize `markdown-split-window-direction`.
284 - <kbd>C-c C-c m</kbd>: `markdown-command` > `*markdown-output*` buffer.
285 - <kbd>C-c C-c p</kbd>: `markdown-command` > temporary file > browser.
286 - <kbd>C-c C-c e</kbd>: `markdown-command` > `basename.html`.
287 - <kbd>C-c C-c v</kbd>: `markdown-command` > `basename.html` > browser.
288 - <kbd>C-c C-c w</kbd>: `markdown-command` > kill ring.
289 - <kbd>C-c C-c o</kbd>: `markdown-open-command`.
290 - <kbd>C-c C-c l</kbd>: `markdown-live-preview-mode` > `*eww*` buffer.
292 <kbd>C-c C-c c</kbd> will check for undefined references. If there are
293 any, a small buffer will open with a list of undefined
294 references and the line numbers on which they appear. In Emacs
295 22 and greater, selecting a reference from this list and
296 pressing <kbd>RET</kbd> will insert an empty reference definition at the
297 end of the buffer. Similarly, selecting the line number will
298 jump to the corresponding line.
300 <kbd>C-c C-c n</kbd> renumbers any ordered lists in the buffer that are
303 <kbd>C-c C-c ]</kbd> completes all headings and normalizes all horizontal
306 * Following Links: <kbd>C-c C-o</kbd>
308 Press <kbd>C-c C-o</kbd> when the point is on an inline or reference
309 link to open the URL in a browser. When the point is at a
310 wiki link, open it in another buffer (in the current window,
311 or in the other window with the <kbd>C-u</kbd> prefix). Use <kbd>M-p</kbd> and
312 <kbd>M-n</kbd> to quickly jump to the previous or next link of any type.
314 * Jumping: <kbd>C-c C-l</kbd>
316 Use <kbd>C-c C-l</kbd> to jump from the object at point to its counterpart
317 elsewhere in the text, when possible. Jumps between reference
318 links and definitions; between footnote markers and footnote
319 text. If more than one link uses the same reference name, a
320 new buffer will be created containing clickable buttons for jumping
321 to each link. You may press <kbd>TAB</kbd> or <kbd>S-TAB</kbd> to jump between
322 buttons in this window.
324 * Promotion and Demotion: <kbd>C-c C--</kbd> and <kbd>C-c C-=</kbd>
326 Headings, horizontal rules, and list items can be promoted and
327 demoted, as well as bold and italic text. For headings,
328 "promotion" means *decreasing* the level (i.e., moving from
329 `<h2>` to `<h1>`) while "demotion" means *increasing* the
330 level. For horizontal rules, promotion and demotion means
331 moving backward or forward through the list of rule strings in
332 `markdown-hr-strings`. For bold and italic text, promotion and
333 demotion means changing the markup from underscores to asterisks.
334 Press <kbd>C-c C--</kbd> or <kbd>M-LEFT</kbd> to promote the element at the point
337 To remember these commands, note that <kbd>-</kbd> is for decreasing the
338 level (promoting), and <kbd>=</kbd> (on the same key as <kbd>+</kbd>) is for
339 increasing the level (demoting). Similarly, the left and right
340 arrow keys indicate the direction that the atx heading markup
341 is moving in when promoting or demoting.
343 * Completion: <kbd>C-c C-]</kbd>
345 Complete markup is in normalized form, which means, for
346 example, that the underline portion of a setext header is the
347 same length as the heading text, or that the number of leading
348 and trailing hash marks of an atx header are equal and that
349 there is no extra whitespace in the header text. <kbd>C-c C-]</kbd>
350 completes the markup at the point, if it is determined to be
353 * Editing Lists: <kbd>M-RET</kbd>, <kbd>M-UP</kbd>, <kbd>M-DOWN</kbd>, <kbd>M-LEFT</kbd>, and <kbd>M-RIGHT</kbd>
355 New list items can be inserted with <kbd>M-RET</kbd> or <kbd>C-c C-j</kbd>. This
356 command determines the appropriate marker (one of the possible
357 unordered list markers or the next number in sequence for an
358 ordered list) and indentation level by examining nearby list
359 items. If there is no list before or after the point, start a
360 new list. Prefix this command by <kbd>C-u</kbd> to decrease the
361 indentation by one level. Prefix this command by <kbd>C-u C-u</kbd> to
362 increase the indentation by one level.
364 Existing list items can be moved up or down with <kbd>M-UP</kbd> or
365 <kbd>M-DOWN</kbd> and indented or exdented with <kbd>M-RIGHT</kbd> or <kbd>M-LEFT</kbd>.
367 * Editing Subtrees: <kbd>M-S-UP</kbd>, <kbd>M-S-DOWN</kbd>, <kbd>M-S-LEFT</kbd>, and <kbd>M-S-RIGHT</kbd>
369 Entire subtrees of ATX headings can be promoted and demoted
370 with <kbd>M-S-LEFT</kbd> and <kbd>M-S-RIGHT</kbd>, which mirror the bindings
371 for promotion and demotion of list items. Similarly, subtrees
372 can be moved up and down with <kbd>M-S-UP</kbd> and <kbd>M-S-DOWN</kbd>.
374 Please note the following "boundary" behavior for promotion and
375 demotion. Any level-six headings will not be demoted further
376 (i.e., they remain at level six, since Markdown and HTML define
377 only six levels) and any level-one headings will promoted away
378 entirely (i.e., heading markup will be removed, since a
379 level-zero heading is not defined).
381 * Shifting the Region: <kbd>C-c <</kbd> and <kbd>C-c ></kbd>
383 Text in the region can be indented or exdented as a group using
384 <kbd>C-c ></kbd> to indent to the next indentation point (calculated in
385 the current context), and <kbd>C-c <</kbd> to exdent to the previous
386 indentation point. These keybindings are the same as those for
387 similar commands in `python-mode`.
389 * Killing Elements: <kbd>C-c C-k</kbd>
391 Press <kbd>C-c C-k</kbd> to kill the thing at point and add important
392 text, without markup, to the kill ring. Possible things to
393 kill include (roughly in order of precedece): inline code,
394 headings, horizonal rules, links (add link text to kill ring),
395 images (add alt text to kill ring), angle URIs, email
396 addresses, bold, italics, reference definitions (add URI to
397 kill ring), footnote markers and text (kill both marker and
398 text, add text to kill ring), and list items.
400 * Outline Navigation: <kbd>C-c C-n</kbd>, <kbd>C-c C-p</kbd>, <kbd>C-c C-f</kbd>, <kbd>C-c C-b</kbd>, and <kbd>C-c C-u</kbd>
402 Navigation between headings is possible using `outline-mode`.
403 Use <kbd>C-c C-n</kbd> and <kbd>C-c C-p</kbd> to move between the next and previous
404 visible headings. Similarly, <kbd>C-c C-f</kbd> and <kbd>C-c C-b</kbd> move to the
405 next and previous visible headings at the same level as the one
406 at the point. Finally, <kbd>C-c C-u</kbd> will move up to a lower-level
407 (higher precedence) visible heading.
409 * Movement by Paragraph or Block: <kbd>M-{</kbd> and <kbd>M-}</kbd>
411 These keys are usually bound to `forward-paragraph` and
412 `backward-paragraph`, but those built-in Emacs functions are
413 based on simple regular expressions and can fail in Markdown.
414 Instead, they are bound to `markdown-forward-block` and
415 `markdown-backward-block`.
417 * Movement by Defun: <kbd>C-M-a</kbd>, <kbd>C-M-e</kbd>, and <kbd>C-M-h</kbd>
419 The usual Emacs commands can be used to move by defuns
420 (top-level major definitions). In markdown-mode, a defun is a
421 section. As usual, <kbd>C-M-a</kbd> will move the point to the
422 beginning of the current or preceding defun, <kbd>C-M-e</kbd> will move
423 to the end of the current or following defun, and <kbd>C-M-h</kbd> will
424 put the region around the entire defun.
426 As noted, many of the commands above behave differently depending
427 on whether Transient Mark mode is enabled or not. When it makes
428 sense, if Transient Mark mode is on and the region is active, the
429 command applies to the text in the region (e.g., <kbd>C-c C-s s</kbd> makes the
430 region bold). For users who prefer to work outside of Transient
431 Mark mode, since Emacs 22 it can be enabled temporarily by pressing
432 <kbd>C-SPC C-SPC</kbd>. When this is not the case, many commands then
433 proceed to look work with the word or line at the point.
435 When applicable, commands that specifically act on the region even
436 outside of Transient Mark mode have the same keybinding as their
437 standard counterpart, but the letter is uppercase. For example,
438 `markdown-insert-blockquote` is bound to <kbd>C-c C-s b</kbd> and only acts on
439 the region in Transient Mark mode while `markdown-blockquote-region`
440 is bound to <kbd>C-c C-s B</kbd> and always applies to the region (when nonempty).
442 Note that these region-specific functions are useful in many
443 cases where it may not be obvious. For example, yanking text from
444 the kill ring sets the mark at the beginning of the yanked text
445 and moves the point to the end. Therefore, the (inactive) region
446 contains the yanked text. So, <kbd>C-y</kbd> followed by <kbd>C-c C-s C-b</kbd> will
447 yank text and turn it into a blockquote.
449 markdown-mode attempts to be flexible in how it handles
450 indentation. When you press <kbd>TAB</kbd> repeatedly, the point will cycle
451 through several possible indentation levels corresponding to things
452 you might have in mind when you press <kbd>RET</kbd> at the end of a line or
453 <kbd>TAB</kbd>. For example, you may want to start a new list item,
454 continue a list item with hanging indentation, indent for a nested
455 pre block, and so on. Exdention is handled similarly when backspace
456 is pressed at the beginning of the non-whitespace portion of a line.
458 markdown-mode supports outline-minor-mode as well as org-mode-style
459 visibility cycling for atx- or hash-style headings. There are two
460 types of visibility cycling: Pressing <kbd>S-TAB</kbd> cycles globally between
461 the table of contents view (headings only), outline view (top-level
462 headings only), and the full document view. Pressing <kbd>TAB</kbd> while the
463 point is at a heading will cycle through levels of visibility for the
464 subtree: completely folded, visible children, and fully visible.
465 Note that mixing hash and underline style headings will give undesired
470 Although no configuration is *necessary* there are a few things
471 that can be customized. The <kbd>M-x customize-mode</kbd> command
472 provides an interface to all of the possible customizations:
474 * `markdown-command` - the command used to run Markdown (default:
475 `markdown`). This variable may be customized to pass
476 command-line options to your Markdown processor of choice.
478 * `markdown-command-needs-filename` - set to <kbd>t</kbd> if
479 `markdown-command` does not accept standard input (default:
480 `nil`). When `nil`, `markdown-mode` will pass the Markdown
481 content to `markdown-command` using standard input (`stdin`).
482 When set to <kbd>t</kbd>, `markdown-mode` will pass the name of the file
483 as the final command-line argument to `markdown-command`. Note
484 that in the latter case, you will only be able to run
485 `markdown-command` from buffers which are visiting a file.
487 * `markdown-open-command` - the command used for calling a standalone
488 Markdown previewer which is capable of opening Markdown source files
489 directly (default: `nil`). This command will be called
490 with a single argument, the filename of the current buffer.
491 A representative program is the Mac app [Marked 2][], a
492 live-updating Markdown previewer which can be [called from a
493 simple shell script](http://jblevins.org/log/marked-2-command).
495 * `markdown-hr-strings` - list of strings to use when inserting
496 horizontal rules. Different strings will not be distinguished
497 when converted to HTML--they will all be converted to
498 `<hr/>`--but they may add visual distinction and style to plain
499 text documents. To maintain some notion of promotion and
500 demotion, keep these sorted from largest to smallest.
502 * `markdown-bold-underscore` - set to a non-nil value to use two
503 underscores when inserting bold text instead of two asterisks
506 * `markdown-italic-underscore` - set to a non-nil value to use
507 underscores when inserting italic text instead of asterisks
510 * `markdown-asymmetric-header` - set to a non-nil value to use
511 asymmetric header styling, placing header characters only on
512 the left of headers (default: `nil`).
514 * `markdown-header-scaling` - set to a non-nil value to use
515 a variable-pitch font for headings where the size corresponds
516 to the level of the heading (default: `nil`).
518 * `markdown-header-scaling-values` - list of scaling values,
519 relative to baseline, for headers of levels one through six,
520 used when `markdown-header-scaling` is non-nil
521 (default: `(list 1.8 1.4 1.2 1.0 1.0 1.0)`).
523 * `markdown-list-indent-width` - depth of indentation for lists
524 when inserting, promoting, and demoting list items (default: 4).
526 * `markdown-indent-function` - the function to use for automatic
527 indentation (default: `markdown-indent-line`).
529 * `markdown-indent-on-enter` - set to a non-nil value to
530 automatically indent new lines and/or continue lists when the
531 enter key is pressed (default: <kbd>t</kbd>)
533 * `markdown-enable-wiki-links` - syntax highlighting for wiki
534 links (default: `nil`). Set this to a non-nil value to turn on
535 wiki link support by default. Wiki link support can be toggled
536 later using the function `markdown-toggle-wiki-links`."
538 * `markdown-wiki-link-alias-first` - set to a non-nil value to
539 treat aliased wiki links like `[[link text|PageName]]`
540 (default: <kbd>t</kbd>). When set to nil, they will be treated as
541 `[[PageName|link text]]`.
543 * `markdown-uri-types` - a list of protocol schemes (e.g., "http")
544 for URIs that `markdown-mode` should highlight.
546 * `markdown-enable-math` - syntax highlighting for LaTeX
547 fragments (default: `nil`). Set this to <kbd>t</kbd> to turn on math
548 support by default. Math support can be enabled, disabled, or
549 toggled later using the function `markdown-toggle-math`."
551 * `markdown-css-paths` - CSS files to link to in XHTML output
554 * `markdown-content-type` - when set to a nonempty string, an
555 `http-equiv` attribute will be included in the XHTML `<head>`
556 block (default: `""`). If needed, the suggested values are
557 `application/xhtml+xml` or `text/html`. See also:
558 `markdown-coding-system`.
560 * `markdown-coding-system` - used for specifying the character
561 set identifier in the `http-equiv` attribute when included
562 (default: `nil`). See `markdown-content-type`, which must
563 be set before this variable has any effect. When set to `nil`,
564 `buffer-file-coding-system` will be used to automatically
565 determine the coding system string (falling back to
566 `iso-8859-1` when unavailable). Common settings are `utf-8`
569 * `markdown-xhtml-header-content` - additional content to include
570 in the XHTML `<head>` block (default: `""`).
572 * `markdown-xhtml-standalone-regexp` - a regular expression which
573 `markdown-mode` uses to determine whether the output of
574 `markdown-command` is a standalone XHTML document or an XHTML
575 fragment (default: `"^\\(<\\?xml\\|<!DOCTYPE\\|<html\\)"`). If
576 this regular expression not matched in the first five lines of
577 output, `markdown-mode` assumes the output is a fragment and
578 adds a header and footer.
580 * `markdown-link-space-sub-char` - a character to replace spaces
581 when mapping wiki links to filenames (default: `"_"`).
582 For example, use an underscore for compatibility with the
583 Python Markdown WikiLinks extension. In `gfm-mode`, this is
584 set to `"-"` to conform with GitHub wiki links.
586 * `markdown-reference-location` - where to insert reference
587 definitions (default: `header`). The possible locations are
588 the end of the document (`end`), after the current block
589 (`immediately`), before the next header (`header`).
591 * `markdown-footnote-location` - where to insert footnote text
592 (default: `end`). The set of location options is the same as
593 for `markdown-reference-location`.
595 * `markdown-nested-imenu-heading-index` - Use nested imenu
596 heading instead of a flat index (default: `nil`). A nested
597 index may provide more natural browsing from the menu, but a
598 flat list may allow for faster keyboard navigation via tab
601 * `comment-auto-fill-only-comments` - variable is made
602 buffer-local and set to `nil` by default. In programming
603 language modes, when this variable is non-nil, only comments
604 will be filled by auto-fill-mode. However, comments in
605 Markdown documents are rare and the most users probably intend
606 for the actual content of the document to be filled. Making
607 this variable buffer-local allows `markdown-mode` to override
608 the default behavior induced when the global variable is non-nil.
610 * `markdown-gfm-additional-languages`, - additional languages to
611 make available, aside from those predefined in
612 `markdown-gfm-recognized-languages`, when inserting GFM code
613 blocks (default: `nil`). Language strings must have be trimmed
614 of whitespace and not contain any curly braces. They may be of
615 arbitrary capitalization, though.
617 * `markdown-gfm-use-electric-backquote` - use
618 `markdown-electric-backquote` for interactive insertion of GFM
619 code blocks when backquote is pressed three times (default: <kbd>t</kbd>).
621 * `markdown-make-gfm-checkboxes-buttons` - Whether GitHub
622 Flavored Markdown style task lists (checkboxes) should be
623 turned into buttons that can be toggled with mouse-1 or RET. If
624 non-nil (default), then buttons are enabled. This works in
625 `markdown-mode` as well as `gfm-mode`.
627 Additionally, the faces used for syntax highlighting can be modified to
628 your liking by issuing <kbd>M-x customize-group RET markdown-faces</kbd>
629 or by using the "Markdown Faces" link at the bottom of the mode
630 customization screen.
632 [Marked 2]: https://itunes.apple.com/us/app/marked-2/id890031187?mt=12&uo=4&at=11l5Vs&ct=mm
636 Besides supporting the basic Markdown syntax, Markdown Mode also
637 includes syntax highlighting for `[[Wiki Links]]`. This can be
638 enabled by setting `markdown-enable-wiki-links` to a non-nil value.
639 Wiki links may be followed by pressing <kbd>C-c C-o</kbd> when the point
640 is at a wiki link. Use <kbd>M-p</kbd> and <kbd>M-n</kbd> to quickly jump to the
641 previous and next links (including links of other types).
642 Aliased or piped wiki links of the form `[[link text|PageName]]`
643 are also supported. Since some wikis reverse these components, set
644 `markdown-wiki-link-alias-first` to nil to treat them as
645 `[[PageName|link text]]`. If `markdown-wiki-link-fontify-missing`
646 is also non-nil, Markdown Mode will highlight wiki links with
647 missing target file in a different color. By default, Markdown
648 Mode only searches for target files in the current directory.
649 Search in subdirectories can be enabled by setting
650 `markdown-wiki-link-search-subdirectories` to a non-nil value.
651 Sequential parent directory search (as in [Ikiwiki][]) can be
652 enabled by setting `markdown-wiki-link-search-parent-directories`
655 [Ikiwiki]: https://ikiwiki.info
657 [SmartyPants][] support is possible by customizing `markdown-command`.
658 If you install `SmartyPants.pl` at, say, `/usr/local/bin/smartypants`,
659 then you can set `markdown-command` to `"markdown | smartypants"`.
660 You can do this either by using <kbd>M-x customize-group markdown</kbd>
661 or by placing the following in your `.emacs` file:
663 (setq markdown-command "markdown | smartypants")
665 [SmartyPants]: http://daringfireball.net/projects/smartypants/
667 Syntax highlighting for mathematical expressions written
668 in LaTeX (only expressions denoted by `$..$`, `$$..$$`, or `\[..\]`)
669 can be enabled by setting `markdown-enable-math` to a non-nil value,
670 either via customize or by placing `(setq markdown-enable-math t)`
671 in `.emacs`, and then restarting Emacs or calling
672 `markdown-reload-extensions`.
674 ## GitHub Flavored Markdown (GFM)
676 A [GitHub Flavored Markdown][GFM] mode, `gfm-mode`, is also
677 available. The GitHub implementation differs slightly from
678 standard Markdown in that it supports things like different
679 behavior for underscores inside of words, automatic linking of
680 URLs, strikethrough text, and fenced code blocks with an optional
683 The GFM-specific features above apply to `README.md` files, wiki
684 pages, and other Markdown-formatted files in repositories on
685 GitHub. GitHub also enables [additional features][GFM comments] for
686 writing on the site (for issues, pull requests, messages, etc.)
687 that are further extensions of GFM. These features include task
688 lists (checkboxes), newlines corresponding to hard line breaks,
689 auto-linked references to issues and commits, wiki links, and so
690 on. To make matters more confusing, although task lists are not
691 part of [GFM proper][GFM], [since 2014][] they are rendered (in a
692 read-only fashion) in all Markdown documents in repositories on the
693 site. These additional extensions are supported to varying degrees
694 by `markdown-mode` and `gfm-mode` as described below.
696 * **URL autolinking:** Both `markdown-mode` and `gfm-mode` support
697 highlighting of URLs without angle brackets.
699 * **Multiple underscores in words:** You must enable `gfm-mode` to
700 toggle support for underscores inside of words. In this mode
701 variable names such as `a_test_variable` will not trigger
704 * **Fenced code blocks:** Code blocks quoted with backquotes, with
705 optional programming language keywords, are highlighted in
706 both `markdown-mode` and `gfm-mode`. They can be inserted with
707 <kbd>C-c C-s P</kbd>. If there is an active region, the text in the
708 region will be placed inside the code block. You will be
709 prompted for the name of the language, but may press enter to
710 continue without naming a language.
712 * **Strikethrough:** Strikethrough text is only supported in
713 `gfm-mode` and can be inserted (and toggled) using <kbd>C-c C-s d</kbd>.
714 Following the mnemonics for the other style keybindings, the
715 letter <kbd>d</kbd> coincides with the HTML tag `<del>`.
717 * **Task lists:** GFM task lists will be rendered as checkboxes
718 (Emacs buttons) in both `markdown-mode` and `gfm-mode` when
719 `markdown-make-gfm-checkboxes-buttons` is set to a non-nil value
720 (and it is set to t by default). These checkboxes can be
721 toggled by clicking `mouse-1`, pressing <kbd>RET</kbd> over the button,
722 or by pressing <kbd>C-c C-x C-x</kbd> with the point anywhere in the task
725 * **Wiki links:** Generic wiki links are supported in
726 `markdown-mode`, but in `gfm-mode` specifically they will be
727 treated as they are on GitHub: spaces will be replaced by hyphens
728 in filenames and the first letter of the filename will be
729 capitalized. For example, `[[wiki link]]` will map to a file
730 named `Wiki-link` with the same extension as the current file.
731 If a file with this name does not exist in the current directory,
732 the first match in a subdirectory, if any, will be used instead.
734 * **Newlines:** Neither `markdown-mode` nor `gfm-mode` do anything
735 specifically with respect to newline behavior. If you use
736 `gfm-mode` mostly to write text for comments or issues on the
737 GitHub site--where newlines are significant and correspond to
738 hard line breaks--then you may want to enable `visual-line-mode`
739 for line wrapping in buffers. You can do this with a
740 `gfm-mode-hook` as follows:
742 ;; Use visual-line-mode in gfm-mode
743 (defun my-gfm-mode-hook ()
744 (visual-line-mode 1))
745 (add-hook 'gfm-mode-hook 'my-gfm-mode-hook)
747 * **Preview:** GFM-specific preview can be powered by setting
748 `markdown-command` to use [Docter][]. This may also be
749 configured to work with [Marked 2][] for `markdown-open-command`.
751 [GFM]: http://github.github.com/github-flavored-markdown/
752 [GFM comments]: https://help.github.com/articles/writing-on-github/
753 [since 2014]: https://github.com/blog/1825-task-lists-in-all-markdown-documents
754 [Docter]: https://github.com/alampros/Docter
758 markdown-mode has benefited greatly from the efforts of the many
759 volunteers who have sent patches, test cases, bug reports,
760 suggestions, helped with packaging, etc. Thank you for your
761 contributions! See the [contributors graph][contrib] for details.
763 [contrib]: https://github.com/jrblevin/markdown-mode/graphs/contributors
767 markdown-mode is developed and tested primarily for compatibility
768 with GNU Emacs 24.3 and later. If you find any bugs in
769 markdown-mode, please construct a test case or a patch and open a
770 ticket on the [GitHub issue tracker][issues].
772 [issues]: https://github.com/jrblevin/markdown-mode/issues
776 markdown-mode was written and is maintained by Jason Blevins. The
777 first version was released on May 24, 2007.
779 * 2007-05-24: [Version 1.1][]
780 * 2007-05-25: [Version 1.2][]
781 * 2007-06-05: [Version 1.3][]
782 * 2007-06-29: [Version 1.4][]
783 * 2007-10-11: [Version 1.5][]
784 * 2008-06-04: [Version 1.6][]
785 * 2009-10-01: [Version 1.7][]
786 * 2011-08-12: [Version 1.8][]
787 * 2011-08-15: [Version 1.8.1][]
788 * 2013-01-25: [Version 1.9][]
789 * 2013-03-24: [Version 2.0][]
790 * 2016-01-09: [Version 2.1][]
792 [Version 1.1]: http://jblevins.org/projects/markdown-mode/rev-1-1
793 [Version 1.2]: http://jblevins.org/projects/markdown-mode/rev-1-2
794 [Version 1.3]: http://jblevins.org/projects/markdown-mode/rev-1-3
795 [Version 1.4]: http://jblevins.org/projects/markdown-mode/rev-1-4
796 [Version 1.5]: http://jblevins.org/projects/markdown-mode/rev-1-5
797 [Version 1.6]: http://jblevins.org/projects/markdown-mode/rev-1-6
798 [Version 1.7]: http://jblevins.org/projects/markdown-mode/rev-1-7
799 [Version 1.8]: http://jblevins.org/projects/markdown-mode/rev-1-8
800 [Version 1.8.1]: http://jblevins.org/projects/markdown-mode/rev-1-8-1
801 [Version 1.9]: http://jblevins.org/projects/markdown-mode/rev-1-9
802 [Version 2.0]: http://jblevins.org/projects/markdown-mode/rev-2-0
803 [Version 2.1]: http://jblevins.org/projects/markdown-mode/rev-2-1