Emacs Markdown Mode

markdown-mode is a major mode for editing Markdown-formatted text files in GNU Emacs. markdown-mode is free software, licensed under the GNU GPL.

The latest stable version is markdown-mode 2.1, released on January 9, 2016:

Although markdown-mode is free, it is the result of many years of work. If you use it regularly and it has made your life or work easier or more enjoyable, then you can say thanks by supporting markdown-mode!

The latest development version can be obtained from the Git repository at http://jblevins.org/git/markdown-mode.git or from GitHub:

git clone git://jblevins.org/git/markdown-mode.git
git clone https://github.com/jrblevin/markdown-mode.git

Build Status

markdown-mode is also available in several package managers, including:


Make sure to place markdown-mode.el somewhere in the load-path and add the following lines to your .emacs file to associate markdown-mode with .text, .markdown, and .md files:

(autoload 'markdown-mode "markdown-mode"
   "Major mode for editing Markdown files" t)
(add-to-list 'auto-mode-alist '("\\.text\\'" . markdown-mode))
(add-to-list 'auto-mode-alist '("\\.markdown\\'" . markdown-mode))
(add-to-list 'auto-mode-alist '("\\.md\\'" . markdown-mode))

There is no official Markdown file extension, nor is there even a de facto standard, so you can easily add, change, or remove any of the file extensions above as needed.

markdown-mode depends on cl-lib, which has been bundled with GNU Emacs since 24.3. Users of GNU Emacs 24.1 and 24.2 can install cl-lib with package.el.


Keybindings are grouped by prefixes based on their function. For example, the commands for inserting links are grouped under C-c C-a, where the C-a is a mnemonic for the HTML <a> tag. In other cases, the connection to HTML is not direct. For example, commands dealing with headings begin with C-c C-t (mnemonic: titling). The primary commands in each group will are described below. You can obtain a list of all keybindings by pressing C-c C-h. Movement and shifting commands tend to be associated with paired delimiters such as M-{ and M-} or C-c < and C-c >. Outline navigation keybindings the same as in org-mode. Finally, commands for running Markdown or doing maintenance on an open file are grouped under the C-c C-c prefix. The most commonly used commands are described below. You can obtain a list of all keybindings by pressing C-c C-h.

As noted, many of the commands above behave differently depending on whether Transient Mark mode is enabled or not. When it makes sense, if Transient Mark mode is on and the region is active, the command applies to the text in the region (e.g., C-c C-s s makes the region bold). For users who prefer to work outside of Transient Mark mode, since Emacs 22 it can be enabled temporarily by pressing C-SPC C-SPC. When this is not the case, many commands then proceed to look work with the word or line at the point.

When applicable, commands that specifically act on the region even outside of Transient Mark mode have the same keybinding as their standard counterpart, but the letter is uppercase. For example, markdown-insert-blockquote is bound to C-c C-s b and only acts on the region in Transient Mark mode while markdown-blockquote-region is bound to C-c C-s B and always applies to the region (when nonempty).

Note that these region-specific functions are useful in many cases where it may not be obvious. For example, yanking text from the kill ring sets the mark at the beginning of the yanked text and moves the point to the end. Therefore, the (inactive) region contains the yanked text. So, C-y followed by C-c C-s C-b will yank text and turn it into a blockquote.

markdown-mode attempts to be flexible in how it handles indentation. When you press TAB repeatedly, the point will cycle through several possible indentation levels corresponding to things you might have in mind when you press RET at the end of a line or TAB. For example, you may want to start a new list item, continue a list item with hanging indentation, indent for a nested pre block, and so on. Exdention is handled similarly when backspace is pressed at the beginning of the non-whitespace portion of a line.

markdown-mode supports outline-minor-mode as well as org-mode-style visibility cycling for atx- or hash-style headings. There are two types of visibility cycling: Pressing S-TAB cycles globally between the table of contents view (headings only), outline view (top-level headings only), and the full document view. Pressing TAB while the point is at a heading will cycle through levels of visibility for the subtree: completely folded, visible children, and fully visible. Note that mixing hash and underline style headings will give undesired results.


Although no configuration is necessary there are a few things that can be customized. The M-x customize-mode command provides an interface to all of the possible customizations:

Additionally, the faces used for syntax highlighting can be modified to your liking by issuing M-x customize-group RET markdown-faces or by using the “Markdown Faces” link at the bottom of the mode customization screen.


Besides supporting the basic Markdown syntax, markdown-mode also includes syntax highlighting for [[Wiki Links]] by default. Wiki links may be followed by pressing C-c C-o when the point is at a wiki link. Use M-p and M-n to quickly jump to the previous and next links (including links of other types). Aliased or piped wiki links of the form [[link text|PageName]] are also supported. Since some wikis reverse these components, set markdown-wiki-link-alias-first to nil to treat them as [[PageName|link text]]. By default, Markdown Mode only searches for target files in the current directory. Sequential parent directory search (as in Ikiwiki) can be enabled by setting markdown-wiki-link-search-parent-directories to a non-nil value.

SmartyPants support is possible by customizing markdown-command. If you install SmartyPants.pl at, say, /usr/local/bin/smartypants, then you can set markdown-command to "markdown | smartypants". You can do this either by using M-x customize-group markdown or by placing the following in your .emacs file:

(setq markdown-command "markdown | smartypants")

Syntax highlighting for mathematical expressions written in LaTeX (only expressions denoted by $..$, $$..$$, or \[..\]) can be enabled by setting markdown-enable-math to a non-nil value, either via customize or by placing (setq markdown-enable-math t) in .emacs, and then restarting Emacs or calling markdown-reload-extensions.

GitHub Flavored Markdown (GFM)

A GitHub Flavored Markdown mode, gfm-mode, is also available. The GitHub implementation differs slightly from standard Markdown in that it supports things like different behavior for underscores inside of words, automatic linking of URLs, strikethrough text, and fenced code blocks with an optional language keyword.

The GFM-specific features above apply to README.md files, wiki pages, and other Markdown-formatted files in repositories on GitHub. GitHub also enables additional features for writing on the site (for issues, pull requests, messages, etc.) that are further extensions of GFM. These features include task lists (checkboxes), newlines corresponding to hard line breaks, auto-linked references to issues and commits, wiki links, and so on. To make matters more confusing, although task lists are not part of GFM proper, since 2014 they are rendered (in a read-only fashion) in all Markdown documents in repositories on the site. These additional extensions are supported to varying degrees by markdown-mode and gfm-mode as described below.


markdown-mode has benefited greatly from the efforts of the following people:


markdown-mode is developed and tested primarily for compatibility with GNU Emacs 24.3 and later. If you find any bugs in markdown-mode, please construct a test case or a patch and open a ticket on the GitHub issue tracker.


markdown-mode was written and is maintained by Jason Blevins. The first version was released on May 24, 2007.

  1. The theme used in the screenshot is color-theme-twilight.