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] [![Guide to Markdown Mode for Emacs][leanpub-badge]][leanpub-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
9 [leanpub-link]: https://leanpub.com/markdown-mode
10 [leanpub-badge]: https://img.shields.io/badge/leanpub-guide-orange.svg
12 <!-- This file is autogenerated by webpage.sh from the comments at the top of
13 markdown-mode.el. Make edits there, not here. -->
15 markdown-mode is a major mode for editing [Markdown][]-formatted
16 text. The latest stable version is markdown-mode 2.2, released on
17 May 26, 2017. See the [release notes][] for details.
18 markdown-mode is free software, licensed under the GNU GPL v2.
20 ![Markdown Mode Screenshot](http://jblevins.org/projects/markdown-mode/screenshots/20160108-001.png)
22 [Markdown]: http://daringfireball.net/projects/markdown/
23 [release notes]: http://jblevins.org/projects/markdown-mode/rev-2-2
27 <a href="https://leanpub.com/markdown-mode"><img src="http://jblevins.org/projects/markdown-mode/guide-v2.2.png" align="right" height="350" width="252"></a>
29 Documentation for Markdown Mode is available below, but Emacs is also
30 a self-documenting editor. That means that the source code itself
31 contains additional documentation: each function has its own docstring
32 available via <kbd>C-h f</kbd> (`describe-function`), individual keybindings
33 can be investigated with <kbd>C-h k</kbd> (`describe-key`), and a complete list
34 of keybindings is available using <kbd>C-h m</kbd> (`describe-mode`).
36 Additionally, to celebrate Markdown Mode's 10th birthday the package
37 creator is writing a [Guide to Markdown Mode for Emacs][guide]. This
38 ebook will supplement the existing documentation with in-depth
39 discussion of advanced movement and editing commands, configuration
40 examples, tips and tricks, and a survey of other packages that work
41 with Markdown Mode. It will be [published at Leanpub][guide] and
42 possibly available through other channels. Please visit
43 the [book homepage][guide] to sign up to be notified when it is ready
44 and to help determine the price.
46 [guide]: https://leanpub.com/markdown-mode
50 The recommended way to install markdown-mode is to install the package
51 from [MELPA Stable](https://stable.melpa.org/#/markdown-mode)
52 using `package.el`. First, configure `package.el` and the MELPA Stable
53 repository by adding the following to your `.emacs`, `init.el`,
54 or equivalent startup file:
58 (add-to-list 'package-archives
59 '("melpa-stable" . "https://stable.melpa.org/packages/"))
63 Then, after restarting Emacs or evaluating the above statements, issue
64 the following command: <kbd>M-x package-install RET markdown-mode RET</kbd>.
65 When installed this way, the major modes `markdown-mode` and `gfm-mode`
66 will be autoloaded and `markdown-mode` will be used for file names
67 ending in either `.md` or `.markdown`.
69 Alternatively, if you manage loading packages with [use-package][]
70 then you can automatically install and configure `markdown-mode` by
71 adding a declaration such as this one to your init file (as an
72 example; adjust settings as desired):
75 (use-package markdown-mode
77 :commands (markdown-mode gfm-mode)
78 :mode (("README\\.md\\'" . gfm-mode)
79 ("\\.md\\'" . markdown-mode)
80 ("\\.markdown\\'" . markdown-mode))
81 :init (setq markdown-command "multimarkdown"))
84 [MELPA Stable]: http://stable.melpa.org/
85 [use-package]: https://github.com/jwiegley/use-package
89 Alternatively you can manually download and install markdown-mode.
90 First, download the [latest stable version][markdown-mode.el] and
91 save the file where Emacs can find it (i.e., a directory in your
92 `load-path`). You can then configure `markdown-mode` and `gfm-mode`
93 to load automatically by adding the following to your init file:
96 (autoload 'markdown-mode "markdown-mode"
97 "Major mode for editing Markdown files" t)
98 (add-to-list 'auto-mode-alist '("\\.markdown\\'" . markdown-mode))
99 (add-to-list 'auto-mode-alist '("\\.md\\'" . markdown-mode))
101 (autoload 'gfm-mode "markdown-mode"
102 "Major mode for editing GitHub Flavored Markdown files" t)
103 (add-to-list 'auto-mode-alist '("README\\.md\\'" . gfm-mode))
106 [markdown-mode.el]: http://jblevins.org/projects/markdown-mode/markdown-mode.el
108 **Development Version**
110 To follow or contribute to markdown-mode development, you can
111 browse or clone the Git repository
112 [on GitHub](https://github.com/jrblevin/markdown-mode):
115 git clone https://github.com/jrblevin/markdown-mode.git
118 If you prefer to install and use the development version, which may
119 become unstable at some times, you can either clone the Git
120 repository as above or install markdown-mode from
121 [MELPA](https://melpa.org/#/markdown-mode).
123 If you clone the repository directly, then make sure that Emacs can
124 find it by adding the following line to your startup file:
127 (add-to-list 'load-path "/path/to/markdown-mode/repository")
130 **Packaged Installation**
132 markdown-mode is also available in several package managers. You
133 may want to confirm that the package you install contains the
134 latest stable version first (and please notify the package
137 * Debian Linux: [elpa-markdown-mode][] and [emacs-goodies-el][]
138 * Ubuntu Linux: [elpa-markdown-mode][elpa-ubuntu] and [emacs-goodies-el][emacs-goodies-el-ubuntu]
139 * RedHat and Fedora Linux: [emacs-goodies][]
140 * NetBSD: [textproc/markdown-mode][]
141 * MacPorts: [markdown-mode.el][macports-package] ([pending][macports-ticket])
142 * FreeBSD: [textproc/markdown-mode.el][freebsd-port]
144 [elpa-markdown-mode]: https://packages.debian.org/sid/lisp/elpa-markdown-mode
145 [elpa-ubuntu]: http://packages.ubuntu.com/search?keywords=elpa-markdown-mode
146 [emacs-goodies-el]: http://packages.debian.org/emacs-goodies-el
147 [emacs-goodies-el-ubuntu]: http://packages.ubuntu.com/search?keywords=emacs-goodies-el
148 [emacs-goodies]: https://apps.fedoraproject.org/packages/emacs-goodies
149 [textproc/markdown-mode]: http://pkgsrc.se/textproc/markdown-mode
150 [macports-package]: https://trac.macports.org/browser/trunk/dports/editors/markdown-mode.el/Portfile
151 [macports-ticket]: http://trac.macports.org/ticket/35716
152 [freebsd-port]: http://svnweb.freebsd.org/ports/head/textproc/markdown-mode.el
156 To enable editing of code blocks in indirect buffers using <kbd>C-c </kbd>`,
157 you will need to install the [`edit-indirect`][ei] package.
159 [ei]: https://github.com/Fanael/edit-indirect/
163 Keybindings are grouped by prefixes based on their function. For
164 example, the commands for styling text are grouped under <kbd>C-c C-s</kbd>
165 and commands dealing with headings begin with <kbd>C-c C-t</kbd> (mnemonic:
166 titling). The primary commands in each group will are described
167 below. You can obtain a list of all keybindings by pressing `C-c
168 C-h`. Movement and shifting commands tend to be associated with
169 paired delimiters such as <kbd>M-{</kbd> and <kbd>M-}</kbd> or <kbd>C-c <</kbd> and <kbd>C-c ></kbd>.
170 Outline navigation keybindings the same as in `org-mode`. Finally,
171 commands for running Markdown or doing maintenance on an open file
172 are grouped under the <kbd>C-c C-c</kbd> prefix. The most commonly used
173 commands are described below. You can obtain a list of all
174 keybindings by pressing <kbd>C-c C-h</kbd>.
176 * Links and Images: <kbd>C-c C-l</kbd> and <kbd>C-c C-i</kbd>
178 <kbd>C-c C-l</kbd> (`markdown-insert-link`) is a general command for
179 inserting new link markup or editing existing link markup. This
180 is especially useful when markup or URL hiding is enabled, so
181 that URLs can't easily be edited directly. This command can be
182 used to insert links of any form: either inline links,
183 reference links, or plain URLs in angle brackets. The URL or
184 `[reference]` label, link text, and optional title are entered
185 through a series of interactive prompts. The type of link is
186 determined by which values are provided:
188 * If both a URL and link text are given, insert an inline link:
190 * If both a `[reference]` label and link text are given, insert
191 a reference link: `[text][reference]`.
192 * If only link text is given, insert an implicit reference link:
194 * If only a URL is given, insert a plain URL link:
197 Similarly, <kbd>C-c C-i</kbd> (`markdown-insert-image`) is a general
198 command for inserting or editing image markup. As with the link
199 insertion command, through a series interactive prompts you can
200 insert either an inline or reference image:
202 * If both a URL and alt text are given, insert an inline
203 image: `![alt text](url)`.
204 * If both a `[reference]` label and alt text are given,
205 insert a reference link: `![alt text][reference]`.
207 If there is an existing link or image at the point, these
208 command will edit the existing markup rather than inserting new
209 markup. Otherwise, if there is an active region, these commands
210 use the region as either the default URL (if it seems to be a
211 URL) or link text value otherwise. In that case, the region
212 will be deleted and replaced by the link.
214 Note that these functions can be used to convert links and
215 images from one type to another (inline, reference, or plain
216 URL) by selectively adding or removing properties via the
219 If a reference label is given that is not yet defined, you
220 will be prompted for the URL and optional title and the
221 reference will be inserted according to the value of
222 `markdown-reference-location`. If a title is given, it will be
223 added to the end of the reference definition and will be used
224 to populate the title attribute when converted to HTML.
226 Local images associated with image links may be displayed
227 inline in the buffer by pressing <kbd>C-c C-x C-i</kbd>
228 (`markdown-toggle-inline-images`). This is a toggle command, so
229 pressing this once again will remove inline images.
231 * Text Styles: <kbd>C-c C-s</kbd>
233 <kbd>C-c C-s i</kbd> inserts markup to make a region or word italic. If
234 there is an active region, make the region italic. If the point
235 is at a non-italic word, make the word italic. If the point is
236 at an italic word or phrase, remove the italic markup.
237 Otherwise, simply insert italic delimiters and place the cursor
238 in between them. Similarly, use <kbd>C-c C-s b</kbd> for bold, <kbd>C-c C-s c</kbd>
239 for inline code, and <kbd>C-c C-s k</kbd> for inserting `<kbd>` tags.
241 <kbd>C-c C-s q</kbd> inserts a blockquote using the active region, if
242 any, or starts a new blockquote. <kbd>C-c C-s Q</kbd> is a variation
243 which always operates on the region, regardless of whether it
244 is active or not (i.e., when `transient-mark-mode` is off but
245 the mark is set). The appropriate amount of indentation, if
246 any, is calculated automatically given the surrounding context,
247 but may be adjusted later using the region indentation
250 <kbd>C-c C-s p</kbd> behaves similarly for inserting preformatted code
251 blocks (with <kbd>C-c C-s P</kbd> being the region-only counterpart)
252 and <kbd>C-c C-s C</kbd> inserts a GFM style backquote fenced code block.
254 * Headings: <kbd>C-c C-s</kbd>
256 To insert or replace headings, there are two options. You can
257 insert a specific level heading directly or you can have
258 `markdown-mode` determine the level for you based on the previous
259 heading. As with the other markup commands, the heading
260 insertion commands use the text in the active region, if any,
261 as the heading text. Otherwise, if the current line is not
262 blank, they use the text on the current line. Finally, the
263 setext commands will prompt for heading text if there is no
264 active region and the current line is blank.
266 <kbd>C-c C-s h</kbd> inserts a heading with automatically chosen type and
267 level (both determined by the previous heading). <kbd>C-c C-s H</kbd>
268 behaves similarly, but uses setext (underlined) headings when
269 possible, still calculating the level automatically.
270 In cases where the automatically-determined level is not what
271 you intended, the level can be quickly promoted or demoted
272 (as described below). Alternatively, a <kbd>C-u</kbd> prefix can be
273 given to insert a heading _promoted_ (lower number) by one
274 level or a <kbd>C-u C-u</kbd> prefix can be given to insert a heading
275 demoted (higher number) by one level.
277 To insert a heading of a specific level and type, use <kbd>C-c C-s 1</kbd>
278 through <kbd>C-c C-s 6</kbd> for atx (hash mark) headings and <kbd>C-c C-s !</kbd> or
279 <kbd>C-c C-s @</kbd> for setext headings of level one or two, respectively.
280 Note that <kbd>!</kbd> is <kbd>S-1</kbd> and <kbd>@</kbd> is <kbd>S-2</kbd>.
282 If the point is at a heading, these commands will replace the
283 existing markup in order to update the level and/or type of the
284 heading. To remove the markup of the heading at the point,
285 press <kbd>C-c C-k</kbd> to kill the heading and press <kbd>C-y</kbd> to yank the
286 heading text back into the buffer.
288 * Horizontal Rules: <kbd>C-c C-s -</kbd>
290 <kbd>C-c C-s -</kbd> inserts a horizontal rule. By default, insert the
291 first string in the list `markdown-hr-strings` (the most
292 prominent rule). With a <kbd>C-u</kbd> prefix, insert the last string.
293 With a numeric prefix <kbd>N</kbd>, insert the string in position <kbd>N</kbd>
296 * Footnotes: <kbd>C-c C-s f</kbd>
298 <kbd>C-c C-s f</kbd> inserts a footnote marker at the point, inserts a
299 footnote definition below, and positions the point for
300 inserting the footnote text. Note that footnotes are an
301 extension to Markdown and are not supported by all processors.
303 * Wiki Links: <kbd>C-c C-s w</kbd>
305 <kbd>C-c C-s w</kbd> inserts a wiki link of the form `[[WikiLink]]`. If
306 there is an active region, use the region as the link text. If the
307 point is at a word, use the word as the link text. If there is
308 no active region and the point is not at word, simply insert
309 link markup. Note that wiki links are an extension to Markdown
310 and are not supported by all processors.
312 * Markdown and Maintenance Commands: <kbd>C-c C-c</kbd>
314 *Compile:* <kbd>C-c C-c m</kbd> will run Markdown on the current buffer
315 and show the output in another buffer. *Preview*: <kbd>C-c C-c p</kbd>
316 runs Markdown on the current buffer and previews, stores the
317 output in a temporary file, and displays the file in a browser.
318 *Export:* <kbd>C-c C-c e</kbd> will run Markdown on the current buffer
319 and save the result in the file `basename.html`, where
320 `basename` is the name of the Markdown file with the extension
321 removed. *Export and View:* press <kbd>C-c C-c v</kbd> to export the
322 file and view it in a browser. *Open:* <kbd>C-c C-c o</kbd> will open
323 the Markdown source file directly using `markdown-open-command`.
324 *Live Export*: Press <kbd>C-c C-c l</kbd> to turn on
325 `markdown-live-preview-mode` to view the exported output
326 side-by-side with the source Markdown. **For all export commands,
327 the output file will be overwritten without notice.**
328 `markdown-live-preview-window-function` can be customized to open
329 in a browser other than `eww`. If you want to force the
330 preview window to appear at the bottom or right, you can
331 customize `markdown-split-window-direction`.
335 - <kbd>C-c C-c m</kbd>: `markdown-command` > `*markdown-output*` buffer.
336 - <kbd>C-c C-c p</kbd>: `markdown-command` > temporary file > browser.
337 - <kbd>C-c C-c e</kbd>: `markdown-command` > `basename.html`.
338 - <kbd>C-c C-c v</kbd>: `markdown-command` > `basename.html` > browser.
339 - <kbd>C-c C-c w</kbd>: `markdown-command` > kill ring.
340 - <kbd>C-c C-c o</kbd>: `markdown-open-command`.
341 - <kbd>C-c C-c l</kbd>: `markdown-live-preview-mode` > `*eww*` buffer.
343 <kbd>C-c C-c c</kbd> will check for undefined references. If there are
344 any, a small buffer will open with a list of undefined
345 references and the line numbers on which they appear. In Emacs
346 22 and greater, selecting a reference from this list and
347 pressing <kbd>RET</kbd> will insert an empty reference definition at the
348 end of the buffer. Similarly, selecting the line number will
349 jump to the corresponding line.
351 <kbd>C-c C-c n</kbd> renumbers any ordered lists in the buffer that are
354 <kbd>C-c C-c ]</kbd> completes all headings and normalizes all horizontal
357 * Following Links: <kbd>C-c C-o</kbd>
359 Press <kbd>C-c C-o</kbd> when the point is on an inline or reference
360 link to open the URL in a browser. When the point is at a
361 wiki link, open it in another buffer (in the current window,
362 or in the other window with the <kbd>C-u</kbd> prefix). Use <kbd>M-p</kbd> and
363 <kbd>M-n</kbd> to quickly jump to the previous or next link of any type.
365 * Doing Things: <kbd>C-c C-d</kbd>
367 Use <kbd>C-c C-d</kbd> to do something sensible with the object at the point:
369 - Jumps between reference links and reference definitions.
370 If more than one link uses the same reference label, a
371 window will be shown containing clickable buttons for
372 jumping to each link. Pressing <kbd>TAB</kbd> or <kbd>S-TAB</kbd> cycles
373 between buttons in this window.
374 - Jumps between footnote markers and footnote text.
375 - Toggles the completion status of GFM task list items
378 * Promotion and Demotion: <kbd>C-c C--</kbd> and <kbd>C-c C-=</kbd>
380 Headings, horizontal rules, and list items can be promoted and
381 demoted, as well as bold and italic text. For headings,
382 "promotion" means *decreasing* the level (i.e., moving from
383 `<h2>` to `<h1>`) while "demotion" means *increasing* the
384 level. For horizontal rules, promotion and demotion means
385 moving backward or forward through the list of rule strings in
386 `markdown-hr-strings`. For bold and italic text, promotion and
387 demotion means changing the markup from underscores to asterisks.
388 Press <kbd>C-c C--</kbd> or <kbd>C-c <left></kbd> to promote the element at the point
391 To remember these commands, note that <kbd>-</kbd> is for decreasing the
392 level (promoting), and <kbd>=</kbd> (on the same key as <kbd>+</kbd>) is for
393 increasing the level (demoting). Similarly, the left and right
394 arrow keys indicate the direction that the atx heading markup
395 is moving in when promoting or demoting.
397 * Completion: <kbd>C-c C-]</kbd>
399 Complete markup is in normalized form, which means, for
400 example, that the underline portion of a setext header is the
401 same length as the heading text, or that the number of leading
402 and trailing hash marks of an atx header are equal and that
403 there is no extra whitespace in the header text. <kbd>C-c C-]</kbd>
404 completes the markup at the point, if it is determined to be
407 * Editing Lists: <kbd>M-RET</kbd>, <kbd>C-c <up></kbd>, <kbd>C-c <down></kbd>, <kbd>C-c <left></kbd>, and <kbd>C-c <right></kbd>
409 New list items can be inserted with <kbd>M-RET</kbd> or <kbd>C-c C-j</kbd>. This
410 command determines the appropriate marker (one of the possible
411 unordered list markers or the next number in sequence for an
412 ordered list) and indentation level by examining nearby list
413 items. If there is no list before or after the point, start a
414 new list. As with heading insertion, you may prefix this
415 command by <kbd>C-u</kbd> to decrease the indentation by one level.
416 Prefix this command by <kbd>C-u C-u</kbd> to increase the indentation by
419 Existing list items (and their nested sub-items) can be moved
420 up or down with <kbd>C-c <up></kbd> or <kbd>C-c <down></kbd> and indented or
421 outdented with <kbd>C-c <right></kbd> or <kbd>C-c <left></kbd>.
423 * Editing Subtrees: <kbd>C-c <up></kbd>, <kbd>C-c <down></kbd>, <kbd>C-c <left></kbd>, and <kbd>C-c <right></kbd>
425 Entire subtrees of ATX headings can be promoted and demoted
426 with <kbd>C-c <left></kbd> and <kbd>C-c <right></kbd>, which are the same keybindings
427 used for promotion and demotion of list items. If the point is in
428 a list item, the operate on the list item. Otherwise, they operate
429 on the current heading subtree. Similarly, subtrees can be
430 moved up and down with <kbd>C-c <up></kbd> and <kbd>C-c <down></kbd>.
432 These commands currently do not work properly if there are
433 Setext headings in the affected region.
435 Please note the following "boundary" behavior for promotion and
436 demotion. Any level-six headings will not be demoted further
437 (i.e., they remain at level six, since Markdown and HTML define
438 only six levels) and any level-one headings will promoted away
439 entirely (i.e., heading markup will be removed, since a
440 level-zero heading is not defined).
442 * Shifting the Region: <kbd>C-c <</kbd> and <kbd>C-c ></kbd>
444 Text in the region can be indented or outdented as a group using
445 <kbd>C-c ></kbd> to indent to the next indentation point (calculated in
446 the current context), and <kbd>C-c <</kbd> to outdent to the previous
447 indentation point. These keybindings are the same as those for
448 similar commands in `python-mode`.
450 * Killing Elements: <kbd>C-c C-k</kbd>
452 Press <kbd>C-c C-k</kbd> to kill the thing at point and add important
453 text, without markup, to the kill ring. Possible things to
454 kill include (roughly in order of precedece): inline code,
455 headings, horizonal rules, links (add link text to kill ring),
456 images (add alt text to kill ring), angle URIs, email
457 addresses, bold, italics, reference definitions (add URI to
458 kill ring), footnote markers and text (kill both marker and
459 text, add text to kill ring), and list items.
461 * 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>
463 These keys are used for hierarchical navigation in lists and
464 headings. When the point is in a list, they move between list
465 items. Otherwise, they move between headings. Use <kbd>C-c C-n</kbd> and
466 <kbd>C-c C-p</kbd> to move between the next and previous visible
467 headings or list items of any level. Similarly, <kbd>C-c C-f</kbd> and
468 <kbd>C-c C-b</kbd> move to the next and previous visible headings or
469 list items at the same level as the one at the point. Finally,
470 <kbd>C-c C-u</kbd> will move up to the parent heading or list item.
472 * Movement by Markdown paragraph: <kbd>M-{</kbd>, <kbd>M-}</kbd>, and <kbd>M-h</kbd>
474 Paragraphs in `markdown-mode` are regular paragraphs,
475 paragraphs inside blockquotes, individual list items, headings,
476 etc. These keys are usually bound to `forward-paragraph` and
477 `backward-paragraph`, but the built-in Emacs functions are
478 based on simple regular expressions that fail in Markdown
479 files. Instead, they are bound to `markdown-forward-paragraph`
480 and `markdown-backward-paragraph`. To mark a paragraph,
481 you can use <kbd>M-h</kbd> (`markdown-mark-paragraph`).
483 * Movement by Markdown block: <kbd>C-M-{</kbd>, <kbd>C-M-}</kbd>, and <kbd>C-c M-h</kbd>
485 Markdown blocks are regular paragraphs in many cases, but
486 contain many paragraphs in other cases: blocks are considered
487 to be entire lists, entire code blocks, and entire blockquotes.
488 To move backward one block use <kbd>C-M-{</kbd>
489 (`markdown-beginning-block`) and to move forward use <kbd>C-M-}</kbd>
490 (`markdown-end-of-block`). To mark a block, use <kbd>C-c M-h</kbd>
491 (`markdown-mark-block`).
493 * Movement by Defuns: <kbd>C-M-a</kbd>, <kbd>C-M-e</kbd>, and <kbd>C-M-h</kbd>
495 The usual Emacs commands can be used to move by defuns
496 (top-level major definitions). In markdown-mode, a defun is a
497 section. As usual, <kbd>C-M-a</kbd> will move the point to the
498 beginning of the current or preceding defun, <kbd>C-M-e</kbd> will move
499 to the end of the current or following defun, and <kbd>C-M-h</kbd> will
500 put the region around the entire defun.
502 * Miscellaneous Commands:
504 When the [`edit-indirect`][ei] package is installed, <kbd>C-c </kbd>`
505 (`markdown-edit-code-block`) can be used to edit a code block
506 in an indirect buffer in the native major mode. Press <kbd>C-c C-c</kbd>
507 to commit changes and return or <kbd>C-c C-k</kbd> to cancel.
509 As noted, many of the commands above behave differently depending
510 on whether Transient Mark mode is enabled or not. When it makes
511 sense, if Transient Mark mode is on and the region is active, the
512 command applies to the text in the region (e.g., <kbd>C-c C-s b</kbd> makes the
513 region bold). For users who prefer to work outside of Transient
514 Mark mode, since Emacs 22 it can be enabled temporarily by pressing
515 <kbd>C-SPC C-SPC</kbd>. When this is not the case, many commands then
516 proceed to look work with the word or line at the point.
518 When applicable, commands that specifically act on the region even
519 outside of Transient Mark mode have the same keybinding as their
520 standard counterpart, but the letter is uppercase. For example,
521 `markdown-insert-blockquote` is bound to <kbd>C-c C-s q</kbd> and only acts on
522 the region in Transient Mark mode while `markdown-blockquote-region`
523 is bound to <kbd>C-c C-s Q</kbd> and always applies to the region (when nonempty).
525 Note that these region-specific functions are useful in many
526 cases where it may not be obvious. For example, yanking text from
527 the kill ring sets the mark at the beginning of the yanked text
528 and moves the point to the end. Therefore, the (inactive) region
529 contains the yanked text. So, <kbd>C-y</kbd> followed by <kbd>C-c C-s Q</kbd> will
530 yank text and turn it into a blockquote.
532 markdown-mode attempts to be flexible in how it handles
533 indentation. When you press <kbd>TAB</kbd> repeatedly, the point will cycle
534 through several possible indentation levels corresponding to things
535 you might have in mind when you press <kbd>RET</kbd> at the end of a line or
536 <kbd>TAB</kbd>. For example, you may want to start a new list item,
537 continue a list item with hanging indentation, indent for a nested
538 pre block, and so on. Outdenting is handled similarly when backspace
539 is pressed at the beginning of the non-whitespace portion of a line.
541 markdown-mode supports outline-minor-mode as well as org-mode-style
542 visibility cycling for atx- or hash-style headings. There are two
543 types of visibility cycling: Pressing <kbd>S-TAB</kbd> cycles globally between
544 the table of contents view (headings only), outline view (top-level
545 headings only), and the full document view. Pressing <kbd>TAB</kbd> while the
546 point is at a heading will cycle through levels of visibility for the
547 subtree: completely folded, visible children, and fully visible.
548 Note that mixing hash and underline style headings will give undesired
553 Although no configuration is *necessary* there are a few things
554 that can be customized. The <kbd>M-x customize-mode</kbd> command
555 provides an interface to all of the possible customizations:
557 * `markdown-command` - the command used to run Markdown (default:
558 `markdown`). This variable may be customized to pass
559 command-line options to your Markdown processor of choice.
561 * `markdown-command-needs-filename` - set to `t` if
562 `markdown-command` does not accept standard input (default:
563 `nil`). When `nil`, `markdown-mode` will pass the Markdown
564 content to `markdown-command` using standard input (`stdin`).
565 When set to `t`, `markdown-mode` will pass the name of the file
566 as the final command-line argument to `markdown-command`. Note
567 that in the latter case, you will only be able to run
568 `markdown-command` from buffers which are visiting a file.
570 * `markdown-open-command` - the command used for calling a standalone
571 Markdown previewer which is capable of opening Markdown source files
572 directly (default: `nil`). This command will be called
573 with a single argument, the filename of the current buffer.
574 A representative program is the Mac app [Marked 2][], a
575 live-updating Markdown previewer which can be [called from a
576 simple shell script](http://jblevins.org/log/marked-2-command).
578 * `markdown-hr-strings` - list of strings to use when inserting
579 horizontal rules. Different strings will not be distinguished
580 when converted to HTML--they will all be converted to
581 `<hr/>`--but they may add visual distinction and style to plain
582 text documents. To maintain some notion of promotion and
583 demotion, keep these sorted from largest to smallest.
585 * `markdown-bold-underscore` - set to a non-nil value to use two
586 underscores when inserting bold text instead of two asterisks
589 * `markdown-italic-underscore` - set to a non-nil value to use
590 underscores when inserting italic text instead of asterisks
593 * `markdown-asymmetric-header` - set to a non-nil value to use
594 asymmetric header styling, placing header characters only on
595 the left of headers (default: `nil`).
597 * `markdown-header-scaling` - set to a non-nil value to use
598 a variable-pitch font for headings where the size corresponds
599 to the level of the heading (default: `nil`).
601 * `markdown-header-scaling-values` - list of scaling values,
602 relative to baseline, for headers of levels one through six,
603 used when `markdown-header-scaling` is non-nil
604 (default: `(2.0 1.7 1.4 1.1 1.0 1.0)`).
606 * `markdown-list-indent-width` - depth of indentation for lists
607 when inserting, promoting, and demoting list items (default: 4).
609 * `markdown-indent-function` - the function to use for automatic
610 indentation (default: `markdown-indent-line`).
612 * `markdown-indent-on-enter` - Set to a non-nil value to
613 automatically indent new lines when <kbd>RET</kbd> is pressed.
614 Set to `indent-and-new-item` to additionally continue lists
615 when <kbd>RET</kbd> is pressed (default: `t`).
617 * `markdown-enable-wiki-links` - syntax highlighting for wiki
618 links (default: `nil`). Set this to a non-nil value to turn on
619 wiki link support by default. Wiki link support can be toggled
620 later using the function `markdown-toggle-wiki-links`."
622 * `markdown-wiki-link-alias-first` - set to a non-nil value to
623 treat aliased wiki links like `[[link text|PageName]]`
624 (default: `t`). When set to nil, they will be treated as
625 `[[PageName|link text]]`.
627 * `markdown-uri-types` - a list of protocol schemes (e.g., "http")
628 for URIs that `markdown-mode` should highlight.
630 * `markdown-enable-math` - font lock for inline and display LaTeX
631 math expressions (default: `nil`). Set this to `t` to turn on
632 math support by default. Math support can be toggled
633 interactively later using <kbd>C-c C-x C-e</kbd>
634 (`markdown-toggle-math`).
636 * `markdown-css-paths` - CSS files to link to in XHTML output
639 * `markdown-content-type` - when set to a nonempty string, an
640 `http-equiv` attribute will be included in the XHTML `<head>`
641 block (default: `""`). If needed, the suggested values are
642 `application/xhtml+xml` or `text/html`. See also:
643 `markdown-coding-system`.
645 * `markdown-coding-system` - used for specifying the character
646 set identifier in the `http-equiv` attribute when included
647 (default: `nil`). See `markdown-content-type`, which must
648 be set before this variable has any effect. When set to `nil`,
649 `buffer-file-coding-system` will be used to automatically
650 determine the coding system string (falling back to
651 `iso-8859-1` when unavailable). Common settings are `utf-8`
654 * `markdown-xhtml-header-content` - additional content to include
655 in the XHTML `<head>` block (default: `""`).
657 * `markdown-xhtml-standalone-regexp` - a regular expression which
658 `markdown-mode` uses to determine whether the output of
659 `markdown-command` is a standalone XHTML document or an XHTML
660 fragment (default: `"^\\(<\\?xml\\|<!DOCTYPE\\|<html\\)"`). If
661 this regular expression not matched in the first five lines of
662 output, `markdown-mode` assumes the output is a fragment and
663 adds a header and footer.
665 * `markdown-link-space-sub-char` - a character to replace spaces
666 when mapping wiki links to filenames (default: `"_"`).
667 For example, use an underscore for compatibility with the
668 Python Markdown WikiLinks extension. In `gfm-mode`, this is
669 set to `"-"` to conform with GitHub wiki links.
671 * `markdown-reference-location` - where to insert reference
672 definitions (default: `header`). The possible locations are
673 the end of the document (`end`), after the current block
674 (`immediately`), the end of the current subtree (`subtree`),
675 or before the next header (`header`).
677 * `markdown-footnote-location` - where to insert footnote text
678 (default: `end`). The set of location options is the same as
679 for `markdown-reference-location`.
681 * `markdown-nested-imenu-heading-index` - Use nested imenu
682 heading instead of a flat index (default: `t`). A nested
683 index may provide more natural browsing from the menu, but a
684 flat list may allow for faster keyboard navigation via tab
687 * `comment-auto-fill-only-comments` - variable is made
688 buffer-local and set to `nil` by default. In programming
689 language modes, when this variable is non-nil, only comments
690 will be filled by auto-fill-mode. However, comments in
691 Markdown documents are rare and the most users probably intend
692 for the actual content of the document to be filled. Making
693 this variable buffer-local allows `markdown-mode` to override
694 the default behavior induced when the global variable is non-nil.
696 * `markdown-gfm-additional-languages`, - additional languages to
697 make available, aside from those predefined in
698 `markdown-gfm-recognized-languages`, when inserting GFM code
699 blocks (default: `nil`). Language strings must have be trimmed
700 of whitespace and not contain any curly braces. They may be of
701 arbitrary capitalization, though.
703 * `markdown-gfm-use-electric-backquote` - use
704 `markdown-electric-backquote` for interactive insertion of GFM
705 code blocks when backquote is pressed three times (default: `t`).
707 * `markdown-make-gfm-checkboxes-buttons` - Whether GitHub
708 Flavored Markdown style task lists (checkboxes) should be
709 turned into buttons that can be toggled with mouse-1 or RET. If
710 non-nil (default), then buttons are enabled. This works in
711 `markdown-mode` as well as `gfm-mode`.
713 * `markdown-hide-urls` - Determines whether URL and reference
714 labels are hidden for inline and reference links (default: `nil`).
715 When non-nil, inline links will appear in the buffer as
716 `[link](∞)` instead of
717 `[link](http://perhaps.a/very/long/url/)`. To change the
718 placeholder (composition) character used, set the variable
719 `markdown-url-compose-char`. URL hiding can be toggled
720 interactively using <kbd>C-c C-x C-l</kbd> (`markdown-toggle-url-hiding`)
721 or from the Markdown | Links & Images menu.
723 * `markdown-hide-markup` - Determines whether all possible markup
724 is hidden or otherwise beautified (default: `nil`). The actual
725 buffer text remains unchanged, but the display will be altered.
726 Brackets and URLs for links will be hidden, asterisks and
727 underscores for italic and bold text will be hidden, text
728 bullets for unordered lists will be replaced by Unicode
729 bullets, and so on. Since this includes URLs and reference
730 labels, when non-nil this setting supersedes `markdown-hide-urls`.
731 Markup hiding can be toggled using <kbd>C-c C-x C-m</kbd>
732 (`markdown-toggle-markup-hiding`) or from the Markdown | Show &
735 Unicode bullets are used to replace ASCII list item markers.
736 The list of characters used, in order of list level, can be
737 specified by setting the variable `markdown-list-item-bullets`.
738 The placeholder characters used to replace other markup can
739 be changed by customizing the corresponding variables:
740 `markdown-blockquote-display-char`,
741 `markdown-hr-display-char`, and
742 `markdown-definition-display-char`.
744 * `markdown-fontify-code-blocks-natively` - Whether to fontify
745 code in code blocks using the native major mode. This only
746 works for fenced code blocks where the language is specified
747 where we can automatically determine the appropriate mode to
748 use. The language to mode mapping may be customized by setting
749 the variable `markdown-code-lang-modes`. This can be toggled
750 interactively by pressing <kbd>C-c C-x C-f</kbd>
751 (`markdown-toggle-fontify-code-blocks-natively`).
753 Additionally, the faces used for syntax highlighting can be modified to
754 your liking by issuing <kbd>M-x customize-group RET markdown-faces</kbd>
755 or by using the "Markdown Faces" link at the bottom of the mode
756 customization screen.
758 [Marked 2]: https://itunes.apple.com/us/app/marked-2/id890031187?mt=12&uo=4&at=11l5Vs&ct=mm
762 Besides supporting the basic Markdown syntax, Markdown Mode also
763 includes syntax highlighting for `[[Wiki Links]]`. This can be
764 enabled by setting `markdown-enable-wiki-links` to a non-nil value.
765 Wiki links may be followed by pressing <kbd>C-c C-o</kbd> when the point
766 is at a wiki link. Use <kbd>M-p</kbd> and <kbd>M-n</kbd> to quickly jump to the
767 previous and next links (including links of other types).
768 Aliased or piped wiki links of the form `[[link text|PageName]]`
769 are also supported. Since some wikis reverse these components, set
770 `markdown-wiki-link-alias-first` to nil to treat them as
771 `[[PageName|link text]]`. If `markdown-wiki-link-fontify-missing`
772 is also non-nil, Markdown Mode will highlight wiki links with
773 missing target file in a different color. By default, Markdown
774 Mode only searches for target files in the current directory.
775 Search in subdirectories can be enabled by setting
776 `markdown-wiki-link-search-subdirectories` to a non-nil value.
777 Sequential parent directory search (as in [Ikiwiki][]) can be
778 enabled by setting `markdown-wiki-link-search-parent-directories`
781 [Ikiwiki]: https://ikiwiki.info
783 [SmartyPants][] support is possible by customizing `markdown-command`.
784 If you install `SmartyPants.pl` at, say, `/usr/local/bin/smartypants`,
785 then you can set `markdown-command` to `"markdown | smartypants"`.
786 You can do this either by using <kbd>M-x customize-group markdown</kbd>
787 or by placing the following in your `.emacs` file:
790 (setq markdown-command "markdown | smartypants")
793 [SmartyPants]: http://daringfireball.net/projects/smartypants/
795 Syntax highlighting for mathematical expressions written
796 in LaTeX (only expressions denoted by `$..$`, `$$..$$`, or `\[..\]`)
797 can be enabled by setting `markdown-enable-math` to a non-nil value,
798 either via customize or by placing `(setq markdown-enable-math t)`
799 in `.emacs`, and then restarting Emacs or calling
800 `markdown-reload-extensions`.
802 ## GitHub Flavored Markdown (GFM)
804 A [GitHub Flavored Markdown][GFM] mode, `gfm-mode`, is also
805 available. The GitHub implementation differs slightly from
806 standard Markdown in that it supports things like different
807 behavior for underscores inside of words, automatic linking of
808 URLs, strikethrough text, and fenced code blocks with an optional
811 The GFM-specific features above apply to `README.md` files, wiki
812 pages, and other Markdown-formatted files in repositories on
813 GitHub. GitHub also enables [additional features][GFM comments] for
814 writing on the site (for issues, pull requests, messages, etc.)
815 that are further extensions of GFM. These features include task
816 lists (checkboxes), newlines corresponding to hard line breaks,
817 auto-linked references to issues and commits, wiki links, and so
818 on. To make matters more confusing, although task lists are not
819 part of [GFM proper][GFM], [since 2014][] they are rendered (in a
820 read-only fashion) in all Markdown documents in repositories on the
821 site. These additional extensions are supported to varying degrees
822 by `markdown-mode` and `gfm-mode` as described below.
824 * **URL autolinking:** Both `markdown-mode` and `gfm-mode` support
825 highlighting of URLs without angle brackets.
827 * **Multiple underscores in words:** You must enable `gfm-mode` to
828 toggle support for underscores inside of words. In this mode
829 variable names such as `a_test_variable` will not trigger
832 * **Fenced code blocks:** Code blocks quoted with backquotes, with
833 optional programming language keywords, are highlighted in
834 both `markdown-mode` and `gfm-mode`. They can be inserted with
835 <kbd>C-c C-s C</kbd>. If there is an active region, the text in the
836 region will be placed inside the code block. You will be
837 prompted for the name of the language, but may press enter to
838 continue without naming a language.
840 * **Strikethrough:** Strikethrough text is supported in both
841 `markdown-mode` and `gfm-mode`. It can be inserted (and toggled)
842 using <kbd>C-c C-s s</kbd>.
844 * **Task lists:** GFM task lists will be rendered as checkboxes
845 (Emacs buttons) in both `markdown-mode` and `gfm-mode` when
846 `markdown-make-gfm-checkboxes-buttons` is set to a non-nil value
847 (and it is set to t by default). These checkboxes can be
848 toggled by clicking `mouse-1`, pressing <kbd>RET</kbd> over the button,
849 or by pressing <kbd>C-c C-d</kbd> (`markdown-do`) with the point anywhere
850 in the task list item.
852 * **Wiki links:** Generic wiki links are supported in
853 `markdown-mode`, but in `gfm-mode` specifically they will be
854 treated as they are on GitHub: spaces will be replaced by hyphens
855 in filenames and the first letter of the filename will be
856 capitalized. For example, `[[wiki link]]` will map to a file
857 named `Wiki-link` with the same extension as the current file.
858 If a file with this name does not exist in the current directory,
859 the first match in a subdirectory, if any, will be used instead.
861 * **Newlines:** Neither `markdown-mode` nor `gfm-mode` do anything
862 specifically with respect to newline behavior. If you use
863 `gfm-mode` mostly to write text for comments or issues on the
864 GitHub site--where newlines are significant and correspond to
865 hard line breaks--then you may want to enable `visual-line-mode`
866 for line wrapping in buffers. You can do this with a
867 `gfm-mode-hook` as follows:
870 ;; Use visual-line-mode in gfm-mode
871 (defun my-gfm-mode-hook ()
872 (visual-line-mode 1))
873 (add-hook 'gfm-mode-hook 'my-gfm-mode-hook)
876 * **Preview:** GFM-specific preview can be powered by setting
877 `markdown-command` to use [Docter][]. This may also be
878 configured to work with [Marked 2][] for `markdown-open-command`.
880 [GFM]: http://github.github.com/github-flavored-markdown/
881 [GFM comments]: https://help.github.com/articles/writing-on-github/
882 [since 2014]: https://github.com/blog/1825-task-lists-in-all-markdown-documents
883 [Docter]: https://github.com/alampros/Docter
887 markdown-mode has benefited greatly from the efforts of the many
888 volunteers who have sent patches, test cases, bug reports,
889 suggestions, helped with packaging, etc. Thank you for your
890 contributions! See the [contributors graph][contrib] for details.
892 [contrib]: https://github.com/jrblevin/markdown-mode/graphs/contributors
896 markdown-mode is developed and tested primarily for compatibility
897 with GNU Emacs 24.3 and later. If you find any bugs in
898 markdown-mode, please construct a test case or a patch and open a
899 ticket on the [GitHub issue tracker][issues].
901 [issues]: https://github.com/jrblevin/markdown-mode/issues
905 markdown-mode was written and is maintained by Jason Blevins. The
906 first version was released on May 24, 2007.
908 * 2007-05-24: [Version 1.1][]
909 * 2007-05-25: [Version 1.2][]
910 * 2007-06-05: [Version 1.3][]
911 * 2007-06-29: [Version 1.4][]
912 * 2007-10-11: [Version 1.5][]
913 * 2008-06-04: [Version 1.6][]
914 * 2009-10-01: [Version 1.7][]
915 * 2011-08-12: [Version 1.8][]
916 * 2011-08-15: [Version 1.8.1][]
917 * 2013-01-25: [Version 1.9][]
918 * 2013-03-24: [Version 2.0][]
919 * 2016-01-09: [Version 2.1][]
920 * 2017-05-26: [Version 2.2][]
922 [Version 1.1]: http://jblevins.org/projects/markdown-mode/rev-1-1
923 [Version 1.2]: http://jblevins.org/projects/markdown-mode/rev-1-2
924 [Version 1.3]: http://jblevins.org/projects/markdown-mode/rev-1-3
925 [Version 1.4]: http://jblevins.org/projects/markdown-mode/rev-1-4
926 [Version 1.5]: http://jblevins.org/projects/markdown-mode/rev-1-5
927 [Version 1.6]: http://jblevins.org/projects/markdown-mode/rev-1-6
928 [Version 1.7]: http://jblevins.org/projects/markdown-mode/rev-1-7
929 [Version 1.8]: http://jblevins.org/projects/markdown-mode/rev-1-8
930 [Version 1.8.1]: http://jblevins.org/projects/markdown-mode/rev-1-8-1
931 [Version 1.9]: http://jblevins.org/projects/markdown-mode/rev-1-9
932 [Version 2.0]: http://jblevins.org/projects/markdown-mode/rev-2-0
933 [Version 2.1]: http://jblevins.org/projects/markdown-mode/rev-2-1
934 [Version 2.2]: http://jblevins.org/projects/markdown-mode/rev-2-2