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`.
282 - <kbd>C-c C-c m</kbd>: `markdown-command` > `*markdown-output*` buffer.
283 - <kbd>C-c C-c p</kbd>: `markdown-command` > temporary file > browser.
284 - <kbd>C-c C-c e</kbd>: `markdown-command` > `basename.html`.
285 - <kbd>C-c C-c v</kbd>: `markdown-command` > `basename.html` > browser.
286 - <kbd>C-c C-c w</kbd>: `markdown-command` > kill ring.
287 - <kbd>C-c C-c o</kbd>: `markdown-open-command`.
288 - <kbd>C-c C-c l</kbd>: `markdown-live-preview-mode` > `*eww*` buffer.
290 <kbd>C-c C-c c</kbd> will check for undefined references. If there are
291 any, a small buffer will open with a list of undefined
292 references and the line numbers on which they appear. In Emacs
293 22 and greater, selecting a reference from this list and
294 pressing <kbd>RET</kbd> will insert an empty reference definition at the
295 end of the buffer. Similarly, selecting the line number will
296 jump to the corresponding line.
298 <kbd>C-c C-c n</kbd> renumbers any ordered lists in the buffer that are
301 <kbd>C-c C-c ]</kbd> completes all headings and normalizes all horizontal
304 * Following Links: <kbd>C-c C-o</kbd>
306 Press <kbd>C-c C-o</kbd> when the point is on an inline or reference
307 link to open the URL in a browser. When the point is at a
308 wiki link, open it in another buffer (in the current window,
309 or in the other window with the <kbd>C-u</kbd> prefix). Use <kbd>M-p</kbd> and
310 <kbd>M-n</kbd> to quickly jump to the previous or next link of any type.
312 * Jumping: <kbd>C-c C-l</kbd>
314 Use <kbd>C-c C-l</kbd> to jump from the object at point to its counterpart
315 elsewhere in the text, when possible. Jumps between reference
316 links and definitions; between footnote markers and footnote
317 text. If more than one link uses the same reference name, a
318 new buffer will be created containing clickable buttons for jumping
319 to each link. You may press <kbd>TAB</kbd> or <kbd>S-TAB</kbd> to jump between
320 buttons in this window.
322 * Promotion and Demotion: <kbd>C-c C--</kbd> and <kbd>C-c C-=</kbd>
324 Headings, horizontal rules, and list items can be promoted and
325 demoted, as well as bold and italic text. For headings,
326 "promotion" means *decreasing* the level (i.e., moving from
327 `<h2>` to `<h1>`) while "demotion" means *increasing* the
328 level. For horizontal rules, promotion and demotion means
329 moving backward or forward through the list of rule strings in
330 `markdown-hr-strings`. For bold and italic text, promotion and
331 demotion means changing the markup from underscores to asterisks.
332 Press <kbd>C-c C--</kbd> or <kbd>M-LEFT</kbd> to promote the element at the point
335 To remember these commands, note that <kbd>-</kbd> is for decreasing the
336 level (promoting), and <kbd>=</kbd> (on the same key as <kbd>+</kbd>) is for
337 increasing the level (demoting). Similarly, the left and right
338 arrow keys indicate the direction that the atx heading markup
339 is moving in when promoting or demoting.
341 * Completion: <kbd>C-c C-]</kbd>
343 Complete markup is in normalized form, which means, for
344 example, that the underline portion of a setext header is the
345 same length as the heading text, or that the number of leading
346 and trailing hash marks of an atx header are equal and that
347 there is no extra whitespace in the header text. <kbd>C-c C-]</kbd>
348 completes the markup at the point, if it is determined to be
351 * Editing Lists: <kbd>M-RET</kbd>, <kbd>M-UP</kbd>, <kbd>M-DOWN</kbd>, <kbd>M-LEFT</kbd>, and <kbd>M-RIGHT</kbd>
353 New list items can be inserted with <kbd>M-RET</kbd> or <kbd>C-c C-j</kbd>. This
354 command determines the appropriate marker (one of the possible
355 unordered list markers or the next number in sequence for an
356 ordered list) and indentation level by examining nearby list
357 items. If there is no list before or after the point, start a
358 new list. Prefix this command by <kbd>C-u</kbd> to decrease the
359 indentation by one level. Prefix this command by <kbd>C-u C-u</kbd> to
360 increase the indentation by one level.
362 Existing list items can be moved up or down with <kbd>M-UP</kbd> or
363 <kbd>M-DOWN</kbd> and indented or exdented with <kbd>M-RIGHT</kbd> or <kbd>M-LEFT</kbd>.
365 * Editing Subtrees: <kbd>M-S-UP</kbd>, <kbd>M-S-DOWN</kbd>, <kbd>M-S-LEFT</kbd>, and <kbd>M-S-RIGHT</kbd>
367 Entire subtrees of ATX headings can be promoted and demoted
368 with <kbd>M-S-LEFT</kbd> and <kbd>M-S-RIGHT</kbd>, which mirror the bindings
369 for promotion and demotion of list items. Similarly, subtrees
370 can be moved up and down with <kbd>M-S-UP</kbd> and <kbd>M-S-DOWN</kbd>.
372 Please note the following "boundary" behavior for promotion and
373 demotion. Any level-six headings will not be demoted further
374 (i.e., they remain at level six, since Markdown and HTML define
375 only six levels) and any level-one headings will promoted away
376 entirely (i.e., heading markup will be removed, since a
377 level-zero heading is not defined).
379 * Shifting the Region: <kbd>C-c <</kbd> and <kbd>C-c ></kbd>
381 Text in the region can be indented or exdented as a group using
382 <kbd>C-c ></kbd> to indent to the next indentation point (calculated in
383 the current context), and <kbd>C-c <</kbd> to exdent to the previous
384 indentation point. These keybindings are the same as those for
385 similar commands in `python-mode`.
387 * Killing Elements: <kbd>C-c C-k</kbd>
389 Press <kbd>C-c C-k</kbd> to kill the thing at point and add important
390 text, without markup, to the kill ring. Possible things to
391 kill include (roughly in order of precedece): inline code,
392 headings, horizonal rules, links (add link text to kill ring),
393 images (add alt text to kill ring), angle URIs, email
394 addresses, bold, italics, reference definitions (add URI to
395 kill ring), footnote markers and text (kill both marker and
396 text, add text to kill ring), and list items.
398 * 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>
400 Navigation between headings is possible using `outline-mode`.
401 Use <kbd>C-c C-n</kbd> and <kbd>C-c C-p</kbd> to move between the next and previous
402 visible headings. Similarly, <kbd>C-c C-f</kbd> and <kbd>C-c C-b</kbd> move to the
403 next and previous visible headings at the same level as the one
404 at the point. Finally, <kbd>C-c C-u</kbd> will move up to a lower-level
405 (higher precedence) visible heading.
407 * Movement by Paragraph or Block: <kbd>M-{</kbd> and <kbd>M-}</kbd>
409 The definition of a "paragraph" is slightly different in
410 markdown-mode than, say, text-mode, because markdown-mode
411 supports filling for list items and respects hard line breaks,
412 both of which break paragraphs. So, markdown-mode overrides
413 the usual paragraph navigation commands <kbd>M-{</kbd> and <kbd>M-}</kbd> so that
414 with a <kbd>C-u</kbd> prefix, these commands jump to the beginning or
415 end of an entire block of text, respectively, where "blocks"
416 are separated by one or more lines.
418 * Movement by Defun: <kbd>C-M-a</kbd>, <kbd>C-M-e</kbd>, and <kbd>C-M-h</kbd>
420 The usual Emacs commands can be used to move by defuns
421 (top-level major definitions). In markdown-mode, a defun is a
422 section. As usual, <kbd>C-M-a</kbd> will move the point to the
423 beginning of the current or preceding defun, <kbd>C-M-e</kbd> will move
424 to the end of the current or following defun, and <kbd>C-M-h</kbd> will
425 put the region around the entire defun.
427 As noted, many of the commands above behave differently depending
428 on whether Transient Mark mode is enabled or not. When it makes
429 sense, if Transient Mark mode is on and the region is active, the
430 command applies to the text in the region (e.g., <kbd>C-c C-s s</kbd> makes the
431 region bold). For users who prefer to work outside of Transient
432 Mark mode, since Emacs 22 it can be enabled temporarily by pressing
433 <kbd>C-SPC C-SPC</kbd>. When this is not the case, many commands then
434 proceed to look work with the word or line at the point.
436 When applicable, commands that specifically act on the region even
437 outside of Transient Mark mode have the same keybinding as their
438 standard counterpart, but the letter is uppercase. For example,
439 `markdown-insert-blockquote` is bound to <kbd>C-c C-s b</kbd> and only acts on
440 the region in Transient Mark mode while `markdown-blockquote-region`
441 is bound to <kbd>C-c C-s B</kbd> and always applies to the region (when nonempty).
443 Note that these region-specific functions are useful in many
444 cases where it may not be obvious. For example, yanking text from
445 the kill ring sets the mark at the beginning of the yanked text
446 and moves the point to the end. Therefore, the (inactive) region
447 contains the yanked text. So, <kbd>C-y</kbd> followed by <kbd>C-c C-s C-b</kbd> will
448 yank text and turn it into a blockquote.
450 markdown-mode attempts to be flexible in how it handles
451 indentation. When you press <kbd>TAB</kbd> repeatedly, the point will cycle
452 through several possible indentation levels corresponding to things
453 you might have in mind when you press <kbd>RET</kbd> at the end of a line or
454 <kbd>TAB</kbd>. For example, you may want to start a new list item,
455 continue a list item with hanging indentation, indent for a nested
456 pre block, and so on. Exdention is handled similarly when backspace
457 is pressed at the beginning of the non-whitespace portion of a line.
459 markdown-mode supports outline-minor-mode as well as org-mode-style
460 visibility cycling for atx- or hash-style headings. There are two
461 types of visibility cycling: Pressing <kbd>S-TAB</kbd> cycles globally between
462 the table of contents view (headings only), outline view (top-level
463 headings only), and the full document view. Pressing <kbd>TAB</kbd> while the
464 point is at a heading will cycle through levels of visibility for the
465 subtree: completely folded, visible children, and fully visible.
466 Note that mixing hash and underline style headings will give undesired
471 Although no configuration is *necessary* there are a few things
472 that can be customized. The <kbd>M-x customize-mode</kbd> command
473 provides an interface to all of the possible customizations:
475 * `markdown-command` - the command used to run Markdown (default:
476 `markdown`). This variable may be customized to pass
477 command-line options to your Markdown processor of choice.
479 * `markdown-command-needs-filename` - set to <kbd>t</kbd> if
480 `markdown-command` does not accept standard input (default:
481 `nil`). When `nil`, `markdown-mode` will pass the Markdown
482 content to `markdown-command` using standard input (`stdin`).
483 When set to <kbd>t</kbd>, `markdown-mode` will pass the name of the file
484 as the final command-line argument to `markdown-command`. Note
485 that in the latter case, you will only be able to run
486 `markdown-command` from buffers which are visiting a file.
488 * `markdown-open-command` - the command used for calling a standalone
489 Markdown previewer which is capable of opening Markdown source files
490 directly (default: `nil`). This command will be called
491 with a single argument, the filename of the current buffer.
492 A representative program is the Mac app [Marked 2][], a
493 live-updating Markdown previewer which can be [called from a
494 simple shell script](http://jblevins.org/log/marked-2-command).
496 * `markdown-hr-strings` - list of strings to use when inserting
497 horizontal rules. Different strings will not be distinguished
498 when converted to HTML--they will all be converted to
499 `<hr/>`--but they may add visual distinction and style to plain
500 text documents. To maintain some notion of promotion and
501 demotion, keep these sorted from largest to smallest.
503 * `markdown-bold-underscore` - set to a non-nil value to use two
504 underscores when inserting bold text instead of two asterisks
507 * `markdown-italic-underscore` - set to a non-nil value to use
508 underscores when inserting italic text instead of asterisks
511 * `markdown-asymmetric-header` - set to a non-nil value to use
512 asymmetric header styling, placing header characters only on
513 the left of headers (default: `nil`).
515 * `markdown-header-scaling` - set to a non-nil value to use
516 a variable-pitch font for headings where the size corresponds
517 to the level of the heading (default: `nil`).
519 * `markdown-header-scaling-values` - list of scaling values,
520 relative to baseline, for headers of levels one through six,
521 used when `markdown-header-scaling` is non-nil
522 (default: `(list 1.8 1.4 1.2 1.0 1.0 1.0)`).
524 * `markdown-list-indent-width` - depth of indentation for lists
525 when inserting, promoting, and demoting list items (default: 4).
527 * `markdown-indent-function` - the function to use for automatic
528 indentation (default: `markdown-indent-line`).
530 * `markdown-indent-on-enter` - set to a non-nil value to
531 automatically indent new lines when the enter key is pressed
532 (default: <kbd>t</kbd>)
534 * `markdown-enable-wiki-links` - syntax highlighting for wiki
535 links (default: `nil`). Set this to a non-nil value to turn on
536 wiki link support by default. Wiki link support can be toggled
537 later using the function `markdown-toggle-wiki-links`."
539 * `markdown-wiki-link-alias-first` - set to a non-nil value to
540 treat aliased wiki links like `[[link text|PageName]]`
541 (default: <kbd>t</kbd>). When set to nil, they will be treated as
542 `[[PageName|link text]]`.
544 * `markdown-uri-types` - a list of protocol schemes (e.g., "http")
545 for URIs that `markdown-mode` should highlight.
547 * `markdown-enable-math` - syntax highlighting for LaTeX
548 fragments (default: `nil`). Set this to <kbd>t</kbd> to turn on math
549 support by default. Math support can be enabled, disabled, or
550 toggled later using the function `markdown-toggle-math`."
552 * `markdown-css-paths` - CSS files to link to in XHTML output
555 * `markdown-content-type` - when set to a nonempty string, an
556 `http-equiv` attribute will be included in the XHTML `<head>`
557 block (default: `""`). If needed, the suggested values are
558 `application/xhtml+xml` or `text/html`. See also:
559 `markdown-coding-system`.
561 * `markdown-coding-system` - used for specifying the character
562 set identifier in the `http-equiv` attribute when included
563 (default: `nil`). See `markdown-content-type`, which must
564 be set before this variable has any effect. When set to `nil`,
565 `buffer-file-coding-system` will be used to automatically
566 determine the coding system string (falling back to
567 `iso-8859-1` when unavailable). Common settings are `utf-8`
570 * `markdown-xhtml-header-content` - additional content to include
571 in the XHTML `<head>` block (default: `""`).
573 * `markdown-xhtml-standalone-regexp` - a regular expression which
574 `markdown-mode` uses to determine whether the output of
575 `markdown-command` is a standalone XHTML document or an XHTML
576 fragment (default: `"^\\(<\\?xml\\|<!DOCTYPE\\|<html\\)"`). If
577 this regular expression not matched in the first five lines of
578 output, `markdown-mode` assumes the output is a fragment and
579 adds a header and footer.
581 * `markdown-link-space-sub-char` - a character to replace spaces
582 when mapping wiki links to filenames (default: `"_"`).
583 For example, use an underscore for compatibility with the
584 Python Markdown WikiLinks extension. In `gfm-mode`, this is
585 set to `"-"` to conform with GitHub wiki links.
587 * `markdown-reference-location` - where to insert reference
588 definitions (default: `header`). The possible locations are
589 the end of the document (`end`), after the current block
590 (`immediately`), before the next header (`header`).
592 * `markdown-footnote-location` - where to insert footnote text
593 (default: `end`). The set of location options is the same as
594 for `markdown-reference-location`.
596 * `markdown-nested-imenu-heading-index` - Use nested imenu
597 heading instead of a flat index (default: `nil`). A nested
598 index may provide more natural browsing from the menu, but a
599 flat list may allow for faster keyboard navigation via tab
602 * `comment-auto-fill-only-comments` - variable is made
603 buffer-local and set to `nil` by default. In programming
604 language modes, when this variable is non-nil, only comments
605 will be filled by auto-fill-mode. However, comments in
606 Markdown documents are rare and the most users probably intend
607 for the actual content of the document to be filled. Making
608 this variable buffer-local allows `markdown-mode` to override
609 the default behavior induced when the global variable is non-nil.
611 * `markdown-gfm-additional-languages`, - additional languages to
612 make available, aside from those predefined in
613 `markdown-gfm-recognized-languages`, when inserting GFM code
614 blocks (default: `nil`). Language strings must have be trimmed
615 of whitespace and not contain any curly braces. They may be of
616 arbitrary capitalization, though.
618 * `markdown-gfm-use-electric-backquote` - use
619 `markdown-electric-backquote` for interactive insertion of GFM
620 code blocks when backquote is pressed three times (default: <kbd>t</kbd>).
622 * `markdown-make-gfm-checkboxes-buttons` - Whether GitHub
623 Flavored Markdown style task lists (checkboxes) should be
624 turned into buttons that can be toggled with mouse-1 or RET. If
625 non-nil (default), then buttons are enabled. This works in
626 `markdown-mode` as well as `gfm-mode`.
628 Additionally, the faces used for syntax highlighting can be modified to
629 your liking by issuing <kbd>M-x customize-group RET markdown-faces</kbd>
630 or by using the "Markdown Faces" link at the bottom of the mode
631 customization screen.
633 [Marked 2]: https://itunes.apple.com/us/app/marked-2/id890031187?mt=12&uo=4&at=11l5Vs&ct=mm
637 Besides supporting the basic Markdown syntax, Markdown Mode also
638 includes syntax highlighting for `[[Wiki Links]]`. This can be
639 enabled by setting `markdown-enable-wiki-links` to a non-nil value.
640 Wiki links may be followed by pressing <kbd>C-c C-o</kbd> when the point
641 is at a wiki link. Use <kbd>M-p</kbd> and <kbd>M-n</kbd> to quickly jump to the
642 previous and next links (including links of other types).
643 Aliased or piped wiki links of the form `[[link text|PageName]]`
644 are also supported. Since some wikis reverse these components, set
645 `markdown-wiki-link-alias-first` to nil to treat them as
646 `[[PageName|link text]]`. If `markdown-wiki-link-fontify-missing`
647 is also non-nil, Markdown Mode will highlight wiki links with
648 missing target file in a different color. By default, Markdown
649 Mode only searches for target files in the current directory.
650 Sequential parent directory search (as in [Ikiwiki][]) can be
651 enabled by setting `markdown-wiki-link-search-parent-directories`
654 [Ikiwiki]: https://ikiwiki.info
656 [SmartyPants][] support is possible by customizing `markdown-command`.
657 If you install `SmartyPants.pl` at, say, `/usr/local/bin/smartypants`,
658 then you can set `markdown-command` to `"markdown | smartypants"`.
659 You can do this either by using <kbd>M-x customize-group markdown</kbd>
660 or by placing the following in your `.emacs` file:
662 (setq markdown-command "markdown | smartypants")
664 [SmartyPants]: http://daringfireball.net/projects/smartypants/
666 Syntax highlighting for mathematical expressions written
667 in LaTeX (only expressions denoted by `$..$`, `$$..$$`, or `\[..\]`)
668 can be enabled by setting `markdown-enable-math` to a non-nil value,
669 either via customize or by placing `(setq markdown-enable-math t)`
670 in `.emacs`, and then restarting Emacs or calling
671 `markdown-reload-extensions`.
673 ## GitHub Flavored Markdown (GFM)
675 A [GitHub Flavored Markdown][GFM] mode, `gfm-mode`, is also
676 available. The GitHub implementation differs slightly from
677 standard Markdown in that it supports things like different
678 behavior for underscores inside of words, automatic linking of
679 URLs, strikethrough text, and fenced code blocks with an optional
682 The GFM-specific features above apply to `README.md` files, wiki
683 pages, and other Markdown-formatted files in repositories on
684 GitHub. GitHub also enables [additional features][GFM comments] for
685 writing on the site (for issues, pull requests, messages, etc.)
686 that are further extensions of GFM. These features include task
687 lists (checkboxes), newlines corresponding to hard line breaks,
688 auto-linked references to issues and commits, wiki links, and so
689 on. To make matters more confusing, although task lists are not
690 part of [GFM proper][GFM], [since 2014][] they are rendered (in a
691 read-only fashion) in all Markdown documents in repositories on the
692 site. These additional extensions are supported to varying degrees
693 by `markdown-mode` and `gfm-mode` as described below.
695 * **URL autolinking:** Both `markdown-mode` and `gfm-mode` support
696 highlighting of URLs without angle brackets.
698 * **Multiple underscores in words:** You must enable `gfm-mode` to
699 toggle support for underscores inside of words. In this mode
700 variable names such as `a_test_variable` will not trigger
703 * **Fenced code blocks:** Code blocks quoted with backticks, with
704 optional programming language keywords, are highlighted in
705 both `markdown-mode` and `gfm-mode`. They can be inserted with
706 <kbd>C-c C-s P</kbd>. If there is an active region, the text in the
707 region will be placed inside the code block. You will be
708 prompted for the name of the language, but may press enter to
709 continue without naming a language.
711 * **Strikethrough:** Strikethrough text is only supported in
712 `gfm-mode` and can be inserted (and toggled) using <kbd>C-c C-s d</kbd>.
713 Following the mnemonics for the other style keybindings, the
714 letter <kbd>d</kbd> coincides with the HTML tag `<del>`.
716 * **Task lists:** GFM task lists will be rendered as checkboxes
717 (Emacs buttons) in both `markdown-mode` and `gfm-mode` when
718 `markdown-make-gfm-checkboxes-buttons` is set to a non-nil value
719 (and it is set to t by default). These checkboxes can be
720 toggled by clicking `mouse-1` or pressing <kbd>RET</kbd> over the button.
722 * **Wiki links:** Generic wiki links are supported in
723 `markdown-mode`, but in `gfm-mode` specifically they will be
724 treated as they are on GitHub: spaces will be replaced by hyphens
725 in filenames and the first letter of the filename will be
726 capitalized. For example, `[[wiki link]]` will map to a file
727 named `Wiki-link` with the same extension as the current file.
729 * **Newlines:** Neither `markdown-mode` nor `gfm-mode` do anything
730 specifically with respect to newline behavior. If you use
731 `gfm-mode` mostly to write text for comments or issues on the
732 GitHub site--where newlines are significant and correspond to
733 hard line breaks--then you may want to enable `visual-line-mode`
734 for line wrapping in buffers. You can do this with a
735 `gfm-mode-hook` as follows:
737 ;; Use visual-line-mode in gfm-mode
738 (defun my-gfm-mode-hook ()
739 (visual-line-mode 1))
740 (add-hook 'gfm-mode-hook 'my-gfm-mode-hook)
742 * **Preview:** GFM-specific preview can be powered by setting
743 `markdown-command` to use [Docter][]. This may also be
744 configured to work with [Marked 2][] for `markdown-open-command`.
746 [GFM]: http://github.github.com/github-flavored-markdown/
747 [GFM comments]: https://help.github.com/articles/writing-on-github/
748 [since 2014]: https://github.com/blog/1825-task-lists-in-all-markdown-documents
749 [Docter]: https://github.com/alampros/Docter
753 markdown-mode has benefited greatly from the efforts of the many
754 volunteers who have sent patches, test cases, bug reports,
755 suggestions, helped with packaging, etc. Thank you for your
756 contributions! See the [contributors graph][contrib] for details.
758 [contrib]: https://github.com/jrblevin/markdown-mode/graphs/contributors
762 markdown-mode is developed and tested primarily for compatibility
763 with GNU Emacs 24.3 and later. If you find any bugs in
764 markdown-mode, please construct a test case or a patch and open a
765 ticket on the [GitHub issue tracker][issues].
767 [issues]: https://github.com/jrblevin/markdown-mode/issues
771 markdown-mode was written and is maintained by Jason Blevins. The
772 first version was released on May 24, 2007.
774 * 2007-05-24: [Version 1.1][]
775 * 2007-05-25: [Version 1.2][]
776 * 2007-06-05: [Version 1.3][]
777 * 2007-06-29: [Version 1.4][]
778 * 2007-10-11: [Version 1.5][]
779 * 2008-06-04: [Version 1.6][]
780 * 2009-10-01: [Version 1.7][]
781 * 2011-08-12: [Version 1.8][]
782 * 2011-08-15: [Version 1.8.1][]
783 * 2013-01-25: [Version 1.9][]
784 * 2013-03-24: [Version 2.0][]
785 * 2016-01-09: [Version 2.1][]
787 [Version 1.1]: http://jblevins.org/projects/markdown-mode/rev-1-1
788 [Version 1.2]: http://jblevins.org/projects/markdown-mode/rev-1-2
789 [Version 1.3]: http://jblevins.org/projects/markdown-mode/rev-1-3
790 [Version 1.4]: http://jblevins.org/projects/markdown-mode/rev-1-4
791 [Version 1.5]: http://jblevins.org/projects/markdown-mode/rev-1-5
792 [Version 1.6]: http://jblevins.org/projects/markdown-mode/rev-1-6
793 [Version 1.7]: http://jblevins.org/projects/markdown-mode/rev-1-7
794 [Version 1.8]: http://jblevins.org/projects/markdown-mode/rev-1-8
795 [Version 1.8.1]: http://jblevins.org/projects/markdown-mode/rev-1-8-1
796 [Version 1.9]: http://jblevins.org/projects/markdown-mode/rev-1-9
797 [Version 2.0]: http://jblevins.org/projects/markdown-mode/rev-2-0
798 [Version 2.1]: http://jblevins.org/projects/markdown-mode/rev-2-1