Markdown Mode for Emacs

GitHub MELPA badge MELPA stable badge Travis CI Build Status Guide to Markdown Mode for Emacs

markdown-mode is a major mode for editing Markdown-formatted text. The latest stable version is markdown-mode 2.3, released on August 31, 2017. See the release notes for details. markdown-mode is free software, licensed under the GNU GPL, version 3 or later.

Markdown Mode Screenshot
Markdown Mode Screenshot

Documentation

The primary documentation for Markdown Mode is available below, and is generated from comments in the source code. For a more in-depth treatment, the Guide to Markdown Mode for Emacs covers Markdown syntax, advanced movement and editing in Emacs, extensions, configuration examples, tips and tricks, and a survey of other packages that work with Markdown Mode. Finally, Emacs is also a self-documenting editor. This means that the source code itself contains additional documentation: each function has its own docstring available via C-h f (describe-function), individual keybindings can be investigated with C-h k (describe-key), and a complete list of keybindings is available using C-h m (describe-mode).

Installation

Note: To use all of the features of markdown-mode, you’ll need to install the Emacs package itself and also have a local Markdown processor installed (e.g., Markdown.pl, MultiMarkdown, or Pandoc). The external processor is not required for editing, but will be used for rendering HTML for preview and export. After installing the Emacs package, be sure to configure markdown-command to point to the preferred Markdown executable on your system. See the Customization section below for more details.

The recommended way to install markdown-mode is to install the package from MELPA Stable using package.el. First, configure package.el and the MELPA Stable repository by adding the following to your .emacs, init.el, or equivalent startup file:

(require 'package)
(add-to-list 'package-archives
             '("melpa-stable" . "https://stable.melpa.org/packages/"))
(package-initialize)

Then, after restarting Emacs or evaluating the above statements, issue the following command: M-x package-install RET markdown-mode RET. When installed this way, the major modes markdown-mode and gfm-mode will be autoloaded and markdown-mode will be used for file names ending in either .md or .markdown.

Alternatively, if you manage loading packages with use-package then you can automatically install and configure markdown-mode by adding a declaration such as this one to your init file (as an example; adjust settings as desired):

(use-package markdown-mode
  :ensure t
  :commands (markdown-mode gfm-mode)
  :mode (("README\\.md\\'" . gfm-mode)
         ("\\.md\\'" . markdown-mode)
         ("\\.markdown\\'" . markdown-mode))
  :init (setq markdown-command "multimarkdown"))

Direct Download

Alternatively you can manually download and install markdown-mode. First, download the latest stable version and save the file where Emacs can find it (i.e., a directory in your load-path). You can then configure markdown-mode and gfm-mode to load automatically by adding the following to your init file:

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

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

Development Version

To follow or contribute to markdown-mode development, you can browse or clone the Git repository on GitHub:

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

If you prefer to install and use the development version, which may become unstable at some times, you can either clone the Git repository as above or install markdown-mode from MELPA.

If you clone the repository directly, then make sure that Emacs can find it by adding the following line to your startup file:

(add-to-list 'load-path "/path/to/markdown-mode/repository")

Packaged Installation

markdown-mode is also available in several package managers. You may want to confirm that the package you install contains the latest stable version first (and please notify the package maintainer if not).

Dependencies

To enable editing of code blocks in indirect buffers using C-c ’, you will need to install the edit-indirect package.

Usage

Keybindings are grouped by prefixes based on their function. For example, the commands for styling text are grouped under C-c C-s and toggle commands begin with C-c C-x. 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 b 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 q and only acts on the region in Transient Mark mode while markdown-blockquote-region is bound to C-c C-s Q 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 Q 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. Outdenting 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]]. This can be enabled by setting markdown-enable-wiki-links to a non-nil value. 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]]. If markdown-wiki-link-fontify-missing is also non-nil, Markdown Mode will highlight wiki links with missing target file in a different color. By default, Markdown Mode only searches for target files in the current directory. Search in subdirectories can be enabled by setting markdown-wiki-link-search-subdirectories to a non-nil value. 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.

Acknowledgments

markdown-mode has benefited greatly from the efforts of the many volunteers who have sent patches, test cases, bug reports, suggestions, helped with packaging, etc. Thank you for your contributions! See the contributors graph for details.

Bugs

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. See the contributing guidelines in CONTRIBUTING.md for details on creating pull requests.

History

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