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 The definition of a "paragraph" is slightly different in
412 markdown-mode than, say, text-mode, because markdown-mode
413 supports filling for list items and respects hard line breaks,
414 both of which break paragraphs. So, markdown-mode overrides
415 the usual paragraph navigation commands <kbd>M-{</kbd> and <kbd>M-}</kbd> so that
416 with a <kbd>C-u</kbd> prefix, these commands jump to the beginning or
417 end of an entire block of text, respectively, where "blocks"
418 are separated by one or more lines.
420 * Movement by Defun: <kbd>C-M-a</kbd>, <kbd>C-M-e</kbd>, and <kbd>C-M-h</kbd>
422 The usual Emacs commands can be used to move by defuns
423 (top-level major definitions). In markdown-mode, a defun is a
424 section. As usual, <kbd>C-M-a</kbd> will move the point to the
425 beginning of the current or preceding defun, <kbd>C-M-e</kbd> will move
426 to the end of the current or following defun, and <kbd>C-M-h</kbd> will
427 put the region around the entire defun.
429 As noted, many of the commands above behave differently depending
430 on whether Transient Mark mode is enabled or not. When it makes
431 sense, if Transient Mark mode is on and the region is active, the
432 command applies to the text in the region (e.g., <kbd>C-c C-s s</kbd> makes the
433 region bold). For users who prefer to work outside of Transient
434 Mark mode, since Emacs 22 it can be enabled temporarily by pressing
435 <kbd>C-SPC C-SPC</kbd>. When this is not the case, many commands then
436 proceed to look work with the word or line at the point.
438 When applicable, commands that specifically act on the region even
439 outside of Transient Mark mode have the same keybinding as their
440 standard counterpart, but the letter is uppercase. For example,
441 `markdown-insert-blockquote` is bound to <kbd>C-c C-s b</kbd> and only acts on
442 the region in Transient Mark mode while `markdown-blockquote-region`
443 is bound to <kbd>C-c C-s B</kbd> and always applies to the region (when nonempty).
445 Note that these region-specific functions are useful in many
446 cases where it may not be obvious. For example, yanking text from
447 the kill ring sets the mark at the beginning of the yanked text
448 and moves the point to the end. Therefore, the (inactive) region
449 contains the yanked text. So, <kbd>C-y</kbd> followed by <kbd>C-c C-s C-b</kbd> will
450 yank text and turn it into a blockquote.
452 markdown-mode attempts to be flexible in how it handles
453 indentation. When you press <kbd>TAB</kbd> repeatedly, the point will cycle
454 through several possible indentation levels corresponding to things
455 you might have in mind when you press <kbd>RET</kbd> at the end of a line or
456 <kbd>TAB</kbd>. For example, you may want to start a new list item,
457 continue a list item with hanging indentation, indent for a nested
458 pre block, and so on. Exdention is handled similarly when backspace
459 is pressed at the beginning of the non-whitespace portion of a line.
461 markdown-mode supports outline-minor-mode as well as org-mode-style
462 visibility cycling for atx- or hash-style headings. There are two
463 types of visibility cycling: Pressing <kbd>S-TAB</kbd> cycles globally between
464 the table of contents view (headings only), outline view (top-level
465 headings only), and the full document view. Pressing <kbd>TAB</kbd> while the
466 point is at a heading will cycle through levels of visibility for the
467 subtree: completely folded, visible children, and fully visible.
468 Note that mixing hash and underline style headings will give undesired
473 Although no configuration is *necessary* there are a few things
474 that can be customized. The <kbd>M-x customize-mode</kbd> command
475 provides an interface to all of the possible customizations:
477 * `markdown-command` - the command used to run Markdown (default:
478 `markdown`). This variable may be customized to pass
479 command-line options to your Markdown processor of choice.
481 * `markdown-command-needs-filename` - set to <kbd>t</kbd> if
482 `markdown-command` does not accept standard input (default:
483 `nil`). When `nil`, `markdown-mode` will pass the Markdown
484 content to `markdown-command` using standard input (`stdin`).
485 When set to <kbd>t</kbd>, `markdown-mode` will pass the name of the file
486 as the final command-line argument to `markdown-command`. Note
487 that in the latter case, you will only be able to run
488 `markdown-command` from buffers which are visiting a file.
490 * `markdown-open-command` - the command used for calling a standalone
491 Markdown previewer which is capable of opening Markdown source files
492 directly (default: `nil`). This command will be called
493 with a single argument, the filename of the current buffer.
494 A representative program is the Mac app [Marked 2][], a
495 live-updating Markdown previewer which can be [called from a
496 simple shell script](http://jblevins.org/log/marked-2-command).
498 * `markdown-hr-strings` - list of strings to use when inserting
499 horizontal rules. Different strings will not be distinguished
500 when converted to HTML--they will all be converted to
501 `<hr/>`--but they may add visual distinction and style to plain
502 text documents. To maintain some notion of promotion and
503 demotion, keep these sorted from largest to smallest.
505 * `markdown-bold-underscore` - set to a non-nil value to use two
506 underscores when inserting bold text instead of two asterisks
509 * `markdown-italic-underscore` - set to a non-nil value to use
510 underscores when inserting italic text instead of asterisks
513 * `markdown-asymmetric-header` - set to a non-nil value to use
514 asymmetric header styling, placing header characters only on
515 the left of headers (default: `nil`).
517 * `markdown-header-scaling` - set to a non-nil value to use
518 a variable-pitch font for headings where the size corresponds
519 to the level of the heading (default: `nil`).
521 * `markdown-header-scaling-values` - list of scaling values,
522 relative to baseline, for headers of levels one through six,
523 used when `markdown-header-scaling` is non-nil
524 (default: `(list 1.8 1.4 1.2 1.0 1.0 1.0)`).
526 * `markdown-list-indent-width` - depth of indentation for lists
527 when inserting, promoting, and demoting list items (default: 4).
529 * `markdown-indent-function` - the function to use for automatic
530 indentation (default: `markdown-indent-line`).
532 * `markdown-indent-on-enter` - set to a non-nil value to
533 automatically indent new lines and/or continue lists when the
534 enter key is pressed (default: <kbd>t</kbd>)
536 * `markdown-enable-wiki-links` - syntax highlighting for wiki
537 links (default: `nil`). Set this to a non-nil value to turn on
538 wiki link support by default. Wiki link support can be toggled
539 later using the function `markdown-toggle-wiki-links`."
541 * `markdown-wiki-link-alias-first` - set to a non-nil value to
542 treat aliased wiki links like `[[link text|PageName]]`
543 (default: <kbd>t</kbd>). When set to nil, they will be treated as
544 `[[PageName|link text]]`.
546 * `markdown-uri-types` - a list of protocol schemes (e.g., "http")
547 for URIs that `markdown-mode` should highlight.
549 * `markdown-enable-math` - syntax highlighting for LaTeX
550 fragments (default: `nil`). Set this to <kbd>t</kbd> to turn on math
551 support by default. Math support can be enabled, disabled, or
552 toggled later using the function `markdown-toggle-math`."
554 * `markdown-css-paths` - CSS files to link to in XHTML output
557 * `markdown-content-type` - when set to a nonempty string, an
558 `http-equiv` attribute will be included in the XHTML `<head>`
559 block (default: `""`). If needed, the suggested values are
560 `application/xhtml+xml` or `text/html`. See also:
561 `markdown-coding-system`.
563 * `markdown-coding-system` - used for specifying the character
564 set identifier in the `http-equiv` attribute when included
565 (default: `nil`). See `markdown-content-type`, which must
566 be set before this variable has any effect. When set to `nil`,
567 `buffer-file-coding-system` will be used to automatically
568 determine the coding system string (falling back to
569 `iso-8859-1` when unavailable). Common settings are `utf-8`
572 * `markdown-xhtml-header-content` - additional content to include
573 in the XHTML `<head>` block (default: `""`).
575 * `markdown-xhtml-standalone-regexp` - a regular expression which
576 `markdown-mode` uses to determine whether the output of
577 `markdown-command` is a standalone XHTML document or an XHTML
578 fragment (default: `"^\\(<\\?xml\\|<!DOCTYPE\\|<html\\)"`). If
579 this regular expression not matched in the first five lines of
580 output, `markdown-mode` assumes the output is a fragment and
581 adds a header and footer.
583 * `markdown-link-space-sub-char` - a character to replace spaces
584 when mapping wiki links to filenames (default: `"_"`).
585 For example, use an underscore for compatibility with the
586 Python Markdown WikiLinks extension. In `gfm-mode`, this is
587 set to `"-"` to conform with GitHub wiki links.
589 * `markdown-reference-location` - where to insert reference
590 definitions (default: `header`). The possible locations are
591 the end of the document (`end`), after the current block
592 (`immediately`), before the next header (`header`).
594 * `markdown-footnote-location` - where to insert footnote text
595 (default: `end`). The set of location options is the same as
596 for `markdown-reference-location`.
598 * `markdown-nested-imenu-heading-index` - Use nested imenu
599 heading instead of a flat index (default: `nil`). A nested
600 index may provide more natural browsing from the menu, but a
601 flat list may allow for faster keyboard navigation via tab
604 * `comment-auto-fill-only-comments` - variable is made
605 buffer-local and set to `nil` by default. In programming
606 language modes, when this variable is non-nil, only comments
607 will be filled by auto-fill-mode. However, comments in
608 Markdown documents are rare and the most users probably intend
609 for the actual content of the document to be filled. Making
610 this variable buffer-local allows `markdown-mode` to override
611 the default behavior induced when the global variable is non-nil.
613 * `markdown-gfm-additional-languages`, - additional languages to
614 make available, aside from those predefined in
615 `markdown-gfm-recognized-languages`, when inserting GFM code
616 blocks (default: `nil`). Language strings must have be trimmed
617 of whitespace and not contain any curly braces. They may be of
618 arbitrary capitalization, though.
620 * `markdown-gfm-use-electric-backquote` - use
621 `markdown-electric-backquote` for interactive insertion of GFM
622 code blocks when backquote is pressed three times (default: <kbd>t</kbd>).
624 * `markdown-make-gfm-checkboxes-buttons` - Whether GitHub
625 Flavored Markdown style task lists (checkboxes) should be
626 turned into buttons that can be toggled with mouse-1 or RET. If
627 non-nil (default), then buttons are enabled. This works in
628 `markdown-mode` as well as `gfm-mode`.
630 Additionally, the faces used for syntax highlighting can be modified to
631 your liking by issuing <kbd>M-x customize-group RET markdown-faces</kbd>
632 or by using the "Markdown Faces" link at the bottom of the mode
633 customization screen.
635 [Marked 2]: https://itunes.apple.com/us/app/marked-2/id890031187?mt=12&uo=4&at=11l5Vs&ct=mm
639 Besides supporting the basic Markdown syntax, Markdown Mode also
640 includes syntax highlighting for `[[Wiki Links]]`. This can be
641 enabled by setting `markdown-enable-wiki-links` to a non-nil value.
642 Wiki links may be followed by pressing <kbd>C-c C-o</kbd> when the point
643 is at a wiki link. Use <kbd>M-p</kbd> and <kbd>M-n</kbd> to quickly jump to the
644 previous and next links (including links of other types).
645 Aliased or piped wiki links of the form `[[link text|PageName]]`
646 are also supported. Since some wikis reverse these components, set
647 `markdown-wiki-link-alias-first` to nil to treat them as
648 `[[PageName|link text]]`. If `markdown-wiki-link-fontify-missing`
649 is also non-nil, Markdown Mode will highlight wiki links with
650 missing target file in a different color. By default, Markdown
651 Mode only searches for target files in the current directory.
652 Search in subdirectories can be enabled by setting
653 `markdown-wiki-link-search-subdirectories` to a non-nil value.
654 Sequential parent directory search (as in [Ikiwiki][]) can be
655 enabled by setting `markdown-wiki-link-search-parent-directories`
658 [Ikiwiki]: https://ikiwiki.info
660 [SmartyPants][] support is possible by customizing `markdown-command`.
661 If you install `SmartyPants.pl` at, say, `/usr/local/bin/smartypants`,
662 then you can set `markdown-command` to `"markdown | smartypants"`.
663 You can do this either by using <kbd>M-x customize-group markdown</kbd>
664 or by placing the following in your `.emacs` file:
666 (setq markdown-command "markdown | smartypants")
668 [SmartyPants]: http://daringfireball.net/projects/smartypants/
670 Syntax highlighting for mathematical expressions written
671 in LaTeX (only expressions denoted by `$..$`, `$$..$$`, or `\[..\]`)
672 can be enabled by setting `markdown-enable-math` to a non-nil value,
673 either via customize or by placing `(setq markdown-enable-math t)`
674 in `.emacs`, and then restarting Emacs or calling
675 `markdown-reload-extensions`.
677 ## GitHub Flavored Markdown (GFM)
679 A [GitHub Flavored Markdown][GFM] mode, `gfm-mode`, is also
680 available. The GitHub implementation differs slightly from
681 standard Markdown in that it supports things like different
682 behavior for underscores inside of words, automatic linking of
683 URLs, strikethrough text, and fenced code blocks with an optional
686 The GFM-specific features above apply to `README.md` files, wiki
687 pages, and other Markdown-formatted files in repositories on
688 GitHub. GitHub also enables [additional features][GFM comments] for
689 writing on the site (for issues, pull requests, messages, etc.)
690 that are further extensions of GFM. These features include task
691 lists (checkboxes), newlines corresponding to hard line breaks,
692 auto-linked references to issues and commits, wiki links, and so
693 on. To make matters more confusing, although task lists are not
694 part of [GFM proper][GFM], [since 2014][] they are rendered (in a
695 read-only fashion) in all Markdown documents in repositories on the
696 site. These additional extensions are supported to varying degrees
697 by `markdown-mode` and `gfm-mode` as described below.
699 * **URL autolinking:** Both `markdown-mode` and `gfm-mode` support
700 highlighting of URLs without angle brackets.
702 * **Multiple underscores in words:** You must enable `gfm-mode` to
703 toggle support for underscores inside of words. In this mode
704 variable names such as `a_test_variable` will not trigger
707 * **Fenced code blocks:** Code blocks quoted with backticks, with
708 optional programming language keywords, are highlighted in
709 both `markdown-mode` and `gfm-mode`. They can be inserted with
710 <kbd>C-c C-s P</kbd>. If there is an active region, the text in the
711 region will be placed inside the code block. You will be
712 prompted for the name of the language, but may press enter to
713 continue without naming a language.
715 * **Strikethrough:** Strikethrough text is only supported in
716 `gfm-mode` and can be inserted (and toggled) using <kbd>C-c C-s d</kbd>.
717 Following the mnemonics for the other style keybindings, the
718 letter <kbd>d</kbd> coincides with the HTML tag `<del>`.
720 * **Task lists:** GFM task lists will be rendered as checkboxes
721 (Emacs buttons) in both `markdown-mode` and `gfm-mode` when
722 `markdown-make-gfm-checkboxes-buttons` is set to a non-nil value
723 (and it is set to t by default). These checkboxes can be
724 toggled by clicking `mouse-1`, pressing <kbd>RET</kbd> over the button,
725 or by pressing <kbd>C-c C-x C-x</kbd> with the point anywhere in the task
728 * **Wiki links:** Generic wiki links are supported in
729 `markdown-mode`, but in `gfm-mode` specifically they will be
730 treated as they are on GitHub: spaces will be replaced by hyphens
731 in filenames and the first letter of the filename will be
732 capitalized. For example, `[[wiki link]]` will map to a file
733 named `Wiki-link` with the same extension as the current file.
734 If a file with this name does not exist in the current directory,
735 the first match in a subdirectory, if any, will be used instead.
737 * **Newlines:** Neither `markdown-mode` nor `gfm-mode` do anything
738 specifically with respect to newline behavior. If you use
739 `gfm-mode` mostly to write text for comments or issues on the
740 GitHub site--where newlines are significant and correspond to
741 hard line breaks--then you may want to enable `visual-line-mode`
742 for line wrapping in buffers. You can do this with a
743 `gfm-mode-hook` as follows:
745 ;; Use visual-line-mode in gfm-mode
746 (defun my-gfm-mode-hook ()
747 (visual-line-mode 1))
748 (add-hook 'gfm-mode-hook 'my-gfm-mode-hook)
750 * **Preview:** GFM-specific preview can be powered by setting
751 `markdown-command` to use [Docter][]. This may also be
752 configured to work with [Marked 2][] for `markdown-open-command`.
754 [GFM]: http://github.github.com/github-flavored-markdown/
755 [GFM comments]: https://help.github.com/articles/writing-on-github/
756 [since 2014]: https://github.com/blog/1825-task-lists-in-all-markdown-documents
757 [Docter]: https://github.com/alampros/Docter
761 markdown-mode has benefited greatly from the efforts of the many
762 volunteers who have sent patches, test cases, bug reports,
763 suggestions, helped with packaging, etc. Thank you for your
764 contributions! See the [contributors graph][contrib] for details.
766 [contrib]: https://github.com/jrblevin/markdown-mode/graphs/contributors
770 markdown-mode is developed and tested primarily for compatibility
771 with GNU Emacs 24.3 and later. If you find any bugs in
772 markdown-mode, please construct a test case or a patch and open a
773 ticket on the [GitHub issue tracker][issues].
775 [issues]: https://github.com/jrblevin/markdown-mode/issues
779 markdown-mode was written and is maintained by Jason Blevins. The
780 first version was released on May 24, 2007.
782 * 2007-05-24: [Version 1.1][]
783 * 2007-05-25: [Version 1.2][]
784 * 2007-06-05: [Version 1.3][]
785 * 2007-06-29: [Version 1.4][]
786 * 2007-10-11: [Version 1.5][]
787 * 2008-06-04: [Version 1.6][]
788 * 2009-10-01: [Version 1.7][]
789 * 2011-08-12: [Version 1.8][]
790 * 2011-08-15: [Version 1.8.1][]
791 * 2013-01-25: [Version 1.9][]
792 * 2013-03-24: [Version 2.0][]
793 * 2016-01-09: [Version 2.1][]
795 [Version 1.1]: http://jblevins.org/projects/markdown-mode/rev-1-1
796 [Version 1.2]: http://jblevins.org/projects/markdown-mode/rev-1-2
797 [Version 1.3]: http://jblevins.org/projects/markdown-mode/rev-1-3
798 [Version 1.4]: http://jblevins.org/projects/markdown-mode/rev-1-4
799 [Version 1.5]: http://jblevins.org/projects/markdown-mode/rev-1-5
800 [Version 1.6]: http://jblevins.org/projects/markdown-mode/rev-1-6
801 [Version 1.7]: http://jblevins.org/projects/markdown-mode/rev-1-7
802 [Version 1.8]: http://jblevins.org/projects/markdown-mode/rev-1-8
803 [Version 1.8.1]: http://jblevins.org/projects/markdown-mode/rev-1-8-1
804 [Version 1.9]: http://jblevins.org/projects/markdown-mode/rev-1-9
805 [Version 2.0]: http://jblevins.org/projects/markdown-mode/rev-2-0
806 [Version 2.1]: http://jblevins.org/projects/markdown-mode/rev-2-1