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.0, released on March 24, 2013:

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!

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

The latest development version can be downloaded directly (markdown-mode.el) or it can be obtained from the (browsable and clonable) Git repository at http://jblevins.org/git/markdown-mode.git. The entire repository, including the full project history, can be cloned via the Git protocol by running

git clone git://jblevins.org/git/markdown-mode.git

Installation

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.

Usage

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.

Customization

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.

Extensions

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]].

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:

(defun markdown-custom ()
  "markdown-mode-hook"
  (setq markdown-command "markdown | smartypants"))
(add-hook 'markdown-mode-hook '(lambda() (markdown-custom)))

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

A GitHub Flavored Markdown (GFM) mode, gfm-mode, is also available. The GitHub implementation of differs slightly from standard Markdown. The most important differences are that newlines are significant, triggering hard line breaks, and that underscores inside of words (e.g., variable names) need not be escaped. As such, gfm-mode turns off auto-fill-mode and turns on visual-line-mode (or longlines-mode if visual-line-mode is not available). Underscores inside of words (such as test_variable) will not trigger emphasis.

Wiki links in this mode will be treated as on GitHub, with hyphens replacing spaces in filenames and where the first letter of the filename capitalized. For example, [[wiki link]] will map to a file named Wiki-link with the same extension as the current file.

GFM code blocks, with optional programming language keywords, will be highlighted. They can be inserted with C-c C-s P. If there is an active region, the text in the region will be placed inside the code block. You will be prompted for the name of the language, but may press enter to continue without naming a language.

For a more complete GitHub-flavored markdown experience, consider adding README.md to your auto-mode-alist:

(add-to-list 'auto-mode-alist '("README\\.md\\'" . gfm-mode))

For GFM preview can be powered by setting markdown-command to use Docter. This may also be configured to work with Marked 2 for markdown-open-command.

Acknowledgments

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

Bugs

Although markdown-mode is developed and tested primarily using GNU Emacs 24, compatibility with earlier Emacsen is also a priority.

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.

History

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.