Emacs markdown-mode
meta-description: A major mode for GNU Emacs for editing Markdown files.
meta-icon: emacs
meta-city: Durham
meta-created: May 24, 2007 23:47 GMT
meta-modified: June 4, 2008 17:04 EDT
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.
[Markdown]: http://daringfireball.net/projects/markdown/
The latest version is markdown-mode 1.6, released on June 4. 2008:
* [markdown-mode.el][]
* [Screenshot][]
* [Release notes][]
markdown-mode is also available in the Debian `emacs-goodies-el`
package (beginning with revision 27.0-1).
[markdown-mode.el]: http://code.jblevins.org/markdown-mode/markdown-mode.el
[screenshot]: http://jblevins.org/projects/markdown-mode/screenshots/20080604-001.png
[release notes]: http://jblevins.org/projects/markdown-mode/rev-1-6
## Dependencies ##
markdown-mode requires easymenu, a standard package since GNU Emacs
19 and XEmacs 19, which provides a uniform interface for creating
menus in GNU Emacs and XEmacs.
## 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` files:
(autoload 'markdown-mode "markdown-mode.el"
"Major mode for editing Markdown files" t)
(setq auto-mode-alist
(cons '("\\.text" . markdown-mode) auto-mode-alist))
There is no consensus on an official file extension so change `.text` to
`.mdwn`, `.md`, `.mdt`, or whatever you call your markdown files.
## Usage ##
Although no configuration is necessary there are a few things that can
be customized (M-x customize-mode).
Keybindings are grouped by prefixes based on their function. For
example, commands dealing with headers begin with C-c C-t. The
primary commands in each group will are described below. You can
obtain a list of all keybindings by pressing C-c C-h.
* Anchors: C-c C-a
C-c C-a l inserts inline links of the form `[text](url)`. If
there is an active region, text in the region is used for the link
text. C-c C-a w acts similarly for wiki links of the form
`[[WikiLink]]`.
* Commands: C-c C-c
C-c C-c m will run Markdown on the current buffer and preview the
output in another buffer while C-c C-c p runs Markdown on the
current buffer and previews the output in a browser.
C-c C-c c will check for undefined references. If there are any,
a small buffer will open with a list of undefined references and
the line numbers on which they appear. In Emacs 22 and greater,
selecting a reference from this list and pressing `RET` will insert
an empty reference definition at the end of the buffer. Similarly,
selecting the line number will jump to the corresponding line.
* Images: C-c C-i
C-c C-i i inserts an image, using the active region (if any) as
the alt text.
* Physical styles: C-c C-p
These commands all act on text in the active region, if any, and
insert empty markup fragments otherwise. C-c C-p b makes the
selected text bold, C-c C-p f formats the region as fixed-width
text, and C-c C-p i is used for italic text.
* Logical styles: C-c C-s
These commands all act on text in the active region, if any, and
insert empty markup fragments otherwise. Logical styles include
blockquote (C-c C-s b), preformatted (C-c C-s p), code (C-c C-s c),
emphasis (C-c C-s e), and strong (C-c C-s s).
* Headers: C-c C-t
All header commands use text in the active region, if any, as the
header text. To insert an atx or hash style level-n header, press
C-c C-t n where n is between 1 and 5. For a top-level setext or
underline style header press C-c C-t t (mnemonic: title) and for
a second-level underline-style header press C-c C-t s
(mnemonic: section).
* Other commands
C-c - inserts a horizontal rule.
Many of the commands described above behave differently depending on
whether Transient Mark mode is enabled or not. When it makes sense,
if Transient Mark mode is on and a region is active, the command
applies to the text in the region (e.g., C-c C-p b makes the region
bold). For users who prefer to work outside of Transient Mark mode,
in Emacs 22 it can be enabled temporarily by pressing C-SPC C-SPC.
When applicable, commands that specifically act on the region even
outside of Transient Mark mode have the same keybinding as the with
the exception of an additional C- prefix. 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 C-b and always applies to the region (when
nonempty).
Markdown mode supports outline-minor-mode as well as org-mode-style
visibility cycling for atx- or hash-style headers. There are two
types of visibility cycling: Pressing `S-TAB` cycles globally between
the table of contents view (headers only), outline view (top-level
headers only), and the full document view. Pressing `TAB` while the
point is at a header will cycle through levels of visibility for the
subtree: completely folded, visiable children, and fully visible.
Note that mixing hash and underline style headers will give undesired
results.
## Extensions ##
Besides supporting the basic Markdown syntax, markdown-mode also
includes syntax highlighting for `[[Wiki Links]]` by default.
[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)))
Experimental syntax highlighting for mathematical expressions written
in LaTeX (only expressions denoted by `$..$`, `$$..$$`, or `\[..\]`)
can be enabled by editing `markdown-mode.el` and changing `(defvar
markdown-enable-itex nil)` to `(defvar markdown-enable-itex t)`.
[SmartyPants]: http://daringfireball.net/projects/smartypants/
## Thanks ##
* Cyril Brulebois for Debian packaging.
* Conal Elliott for a font-lock regexp patch.
* Edward O'Connor for a font-lock regexp fix.
* Greg Bognar for menus and a patch.
* Daniel Burrows for filing Debian bug #456592.
* Peter S. Galbraith for maintaining emacs-goodies-el.
* Dmitry Dzhus for reference checking functions.
## Bugs ##
Markdown mode is developed and tested primarily using GNU Emacs 22
although compatibility with GNU Emacs 21 is also a priority.
Presently Markdown mode does not attempt to distinguish between
multiple indentation levels and preformatted text (four or more
leading spaces). I am not aware of a way to handle this using
Emacs's regexp-based font-lock facilities. Implementing a more
robust approach to syntax highlighting is a high-priority item for
future work.
If you find any bugs, such as syntax highlighting issues, please
construct a test case and email me at .
Comments and patches are welcome!