-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathguide.txt
3942 lines (3063 loc) · 156 KB
/
guide.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---
title: Guide to Markdown Mode for Emacs
author: Jason R. Blevins
date: August 2017
tags: Emacs, markdown, markdown-mode, writing, plain text
---
{mainmatter}
# Introduction {#intro}
This _Guide_ describes how to install, use, and customize
[Markdown Mode](https://jblevins.org/projects/markdown-mode/), a major mode for editing Markdown-formatted text
files in [Emacs](https://www.gnu.org/software/emacs/). It is not intended to be a replacement for the
online manual, but rather to supplement and extend the manual for
users who want to learn to use Markdown Mode more effectively.
The goal of this book is to make writing and publishing with Markdown
in Emacs more enjoyable and efficient. The hope is that through
examples and detailed descriptions of the various commands and
customizable variables, users can learn more about Emacs itself and
also improve their Markdown writing workflows.
This book covers the usual basic information about obtaining,
installing and configuring Markdown Mode, but it also addresses
advanced usage such as subtree and structure editing, defun and page
movement, marking, narrowing, region manipulation, etc. It goes
beyond the basic documentation by also discussing interaction with
other packages and systems such as Flyspell mode, CriticMarkup mode,
Pandoc mode, Deft, HTML as Markdown mode, and MathJax. Finally, it
also contains tips and tricks for custom configuration options such as
custom CSS stylesheets, using pre- and post-processors, customizing
faces, keeping notes in a local wiki, etc.
This guide is based on **Markdown Mode version 2.3**.
Markdown Mode and this guide were written by [Jason Blevins](https://jblevins.org/).
Markdown Mode is free software, licensed under the
GNU General Public License (GPL) version 3 or later,
and it may be freely obtained from the [Markdown Mode homepage](https://jblevins.org/projects/markdown-mode/).
## Quick Reference
If you are a seasoned Markdown Mode user, here is a quick reference
table including new version 2.3 features:
| Action | Keybinding |
|-----------------------------------------------------|-------------------|
| **Headings** | |
| Insert heading depending on context | `C-c C-s h` |
| Insert heading, prefer setext | `C-c C-s H` |
| Insert atx heading of level # = 1, 2, … 6 | `C-c C-s #` |
| Insert setext heading of level 1 | `C-c C-s !` |
| Insert setext heading of level 2 | `C-c C-s @` |
| **Inline Elements** | |
| Bold | `C-c C-s b` |
| Italics | `C-c C-s i` |
| Inline code | `C-c C-s c` |
| `kbd` tag | `C-c C-s k` |
| Wiki link | `C-c C-s w` |
| **Block Elements** | |
| Preformatted/code block | `C-c C-s p` |
| Preformatted/code block (region) | `C-c C-s P` |
| Blockquote | `C-c C-s q` |
| Blockquote (region) | `C-c C-s Q` |
| GFM code block | `C-c C-s C` |
| Edit code block in indirect buffer | `C-c '` |
| **Links and Images** | |
| Insert or edit link (inline, reference, or URL) | `C-c C-l` |
| Insert or edit image (inline or reference) | `C-c C-i` |
| Follow link at point | `C-c C-o` |
| Jump between reference link and definition | `C-c C-d` |
| Move to next link | `M-n` |
| Move to previous link | `M-p` |
| **Footnotes** | |
| Insert footnote | `C-c C-s f` |
| Jump between footnote and definition | `C-c C-d` |
| **List Items & List Editing** | |
| Insert new list item (same level) | `M-RET` |
| Insert new list item (same level) | `C-c C-j` |
| Insert new list item (parent level) | `C-u C-c C-j` |
| Insert new list item (child level) | `C-u C-u C-c C-j` |
| Move list item up | `C-c <up>` |
| Move list item down | `C-c <down>` |
| Outdent/promote list item | `C-c <left>` |
| Indent/demote list item | `C-c <right>` |
| Toggle GFM checkbox | `C-c C-x C-x` |
| **Horizontal Rules** | |
| Insert default horizontal rule string | `C-c C-s -` |
| **Killing and Yanking** | |
| Kill element and keep text in kill ring | `C-c C-k` |
| Yank text back into buffer | `C-y` |
| **Movement by Paragraph** | |
| Backward paragraph | `M-{` |
| Forward paragraph | `M-}` |
| Mark paragraph | `M-h` |
| **Movement by Block** | |
| Backward block | `C-M-{` |
| Forward block | `C-M-}` |
| Mark block | `C-c M-h` |
| Narrow to block | `C-x n b` |
| Widen | `C-x n w` |
| **Movement by Section (Defun)** | |
| Beginning of section | `C-M-a` |
| End of section | `C-M-e` |
| Mark section | `C-M-h` |
| Mark subtree | `C-c C-M-h` |
| Narrow to section | `C-x n d` |
| Narrow to subtree | `C-x n s` |
| Widen | `C-x n w` |
| **Outline & List Movement** | |
| Next heading or list item | `C-c C-n` |
| Previous heading or list item | `C-c C-p` |
| Next heading or list item (same level) | `C-c C-f` |
| Previous heading or list item (same level) | `C-c C-b` |
| Move up to parent heading or list item | `C-c C-u` |
| **Outline Visibility Cycling** | |
| Cycle visibility globally | `S-TAB` |
| Cycle visibility of heading at point | `TAB` |
| **Outline Subtree Editing** | |
| Move subtree up | `C-c <up>` |
| Move subtree down | `C-c <down>` |
| Promote subtree | `C-c <left>` |
| Demote subtree | `C-c <right>` |
| **Region Editing** | |
| Indent region | `C-c >` |
| Exdent region | `C-c <` |
| **Promotion and Demotion** | |
| Promote element at point | `C-c -` |
| Demote element at point | `C-c =` |
| **Markup Completion** | |
| Complete markup at point or in region | `C-c C-]` |
| Complete markup in buffer | `C-c C-c ]` |
| **Markdown & Utility Commands** | |
| Run Markdown, output to temporary buffer | `C-c C-c m` |
| Run Markdown, export to file | `C-c C-c e` |
| Run Markdown, preview in browser | `C-c C-c p` |
| Run Markdown, export, and preview | `C-c C-c v` |
| Run Markdown, save to kill ring | `C-c C-c w` |
| Toggle live preview mode | `C-c C-c l` |
| Open external previewer | `C-c C-c o` |
| Check references in buffer | `C-c C-c c` |
| Renumber ordered lists in buffer | `C-c C-c n` |
| **Toggles and Settings** | |
| Toggle markup hiding | `C-c C-x C-m` |
| Toggle URL hiding | `C-c C-x C-l` |
| Toggle native code block font lock | `C-c C-x C-f` |
| Toggle inline images | `C-c C-x C-i` |
| Toggle LaTeX math support | `C-c C-x C-e` |
| Toggle GFM checkbox | `C-c C-x C-x` |
## Markdown
[Markdown](http://daringfireball.net/projects/markdown/) is a lightweight markup language, originally created by
[John Gruber](https://daringfireball.net) in late 2003 and released in 2004. Markdown aims to be
simultaneously easy to write and easy to read. It takes many cues from
previous, similar attempts such as [atx](http://www.aaronsw.com/2002/atx/), by [Aaron Swartz](http://www.aaronsw.com),[^aaronsw]
[setext](http://docutils.sourceforge.net/mirror/setext.html), by Ian Feldman, and [Textile](https://txstyle.org), by Dean Allen, as well
as from existing conventions for marking up plain text email.
"Markdown" is also used to refer to the original Markdown processor,
also written by John Gruber, which is a Perl script that converts plain
Markdown-formatted text input to HTML output. It is distributed
under a BSD-style license and is included with, or available as a
plugin for, several content management systems. In the remainder I
will refer to the processor by its filename, Markdown.pl, to
distinguish between the Markdown syntax and the Perl script. After
the original Perl implementation, Markdown processors have been
implemented by others in a variety of programming languages.
Some examples are, in no particular order, PHP Markdown Extra, Python
Markdown, MultiMarkdown (Perl and C), Pandoc (Haskell), Discount (C),
Maruku (Ruby), RedCarpet (Ruby), Kramdown (Ruby), Showdown
(JavaScript), and CommonMark (C and JavaScript).
[^aaronsw]: John Gruber described Aaron Swartz as his "muse" while developing Markdown, due to his early enthusiasm for and feedback on the project. Aaron Swartz also wrote [html2text](http://www.aaronsw.com/2002/html2text/), a popular HTML to Markdown converter written in Python.
### Markdown Syntax Reference
For reference, below is a plain-text summary of Markdown's syntax.
Additional details about each type of element are explained in the
course of describing the Markdown Mode editing commands. See the
original [Markdown syntax page](http://daringfireball.net/projects/markdown/syntax) for complete details.
<<(examples/markdown.md)
Characters can be backslash-escaped in Markdown. That is, characters
which are ordinarily interpreted by Markdown as formatting commands
will instead be interpreted literally if preceded by a backslash. For
example, when you need to type a literal asterisk or underscore:
{lang="text"}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is *italic*, but this \*is not\*.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Markdown.pl also does not transform any text within raw block-level
HTML elements (although some other processors do). Thus it is
possible to include sections of HTML within a Markdown source
document by wrapping them in block-level HTML tags. However, with a
small number of exceptions (e.g., comments and `kbd` tags) Markdown
Mode does not explicitly support inline HTML.
### Additional Information
For additional information on Markdown syntax, you can refer to the
following links:
* [Markdown Syntax](http://daringfireball.net/projects/markdown/syntax) - Original syntax description by John Gruber
* [Markdown Dingus](http://daringfireball.net/projects/markdown/dingus) - Online converter using Markdown.pl
* [Babelmark 2](https://johnmacfarlane.net/babelmark2/) - Online converter comparing many Markdown processors
* [Wikipedia article](http://en.wikipedia.org/wiki/Markdown) - Background information on Markdown with syntax examples
* [Mastering Markdown](https://guides.github.com/features/mastering-markdown/) - Guide to Markdown and extensions by GitHub
* [Pandoc User's Guide](http://pandoc.org/MANUAL.html) - Markdown and Pandoc extensions
* [PHP Markdown Reference](https://michelf.ca/projects/php-markdown/reference/) - Markdown and PHP Markdown Extra extensions
* [Write better Markdown](http://brettterpstra.com/2015/08/24/write-better-markdown/) - Style guide by Brett Terpstra
## History
Markdown Mode was originally written and is still maintained
by [Jason Blevins](https://jblevins.org/). The initial release, version 1.1, was created
on May 24, 2007. As of this writing, the latest stable version of
Markdown Mode is version 2.3, released on August 31, 2017. For a
complete list of changes, see the [version 2.3 release notes](https://jblevins.org/projects/markdown-mode/rev-2-3)
or those for previous versions:
* 2017-05-26: [Version 2.2](https://jblevins.org/projects/markdown-mode/rev-2-2)
* 2016-01-09: [Version 2.1](https://jblevins.org/projects/markdown-mode/rev-2-1)
* 2013-03-24: [Version 2.0](https://jblevins.org/projects/markdown-mode/rev-2-0)
* 2013-01-25: [Version 1.9](https://jblevins.org/projects/markdown-mode/rev-1-9)
* 2011-08-15: [Version 1.8.1](https://jblevins.org/projects/markdown-mode/rev-1-8-1)
* 2011-08-12: [Version 1.8](https://jblevins.org/projects/markdown-mode/rev-1-8)
* 2009-10-01: [Version 1.7](https://jblevins.org/projects/markdown-mode/rev-1-7)
* 2008-06-04: [Version 1.6](https://jblevins.org/projects/markdown-mode/rev-1-6)
* 2007-10-11: [Version 1.5](https://jblevins.org/projects/markdown-mode/rev-1-5)
* 2007-06-29: [Version 1.4](https://jblevins.org/projects/markdown-mode/rev-1-4)
* 2007-06-05: [Version 1.3](https://jblevins.org/projects/markdown-mode/rev-1-3)
* 2007-05-25: [Version 1.2](https://jblevins.org/projects/markdown-mode/rev-1-2)
* 2007-05-24: [Version 1.1](https://jblevins.org/projects/markdown-mode/rev-1-1)
I> Historically, version numbering began at 1.1 because the source code
I> was originally stored in RCS (Revision Control System), which numbers
I> revisions starting at 1.1 by default. After version 1.5, the source
I> was moved to Git, where it still resides today. See the chapter
I> on [Markdown Mode Development](#devel) for instructions on how to obtain
I> the source code.
## 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! Markdown Mode is much more robust and includes many
additional features as a result of your efforts. Below is a partial
list of contributors (in alphabetical order). See the
[GitHub contributors graph](https://github.com/jrblevin/markdown-mode/graphs/contributors) and the commit log for more details.
<!--
git shortlog -s -n | awk '{ $1=""; print $0 }'
M-x sort-regexp-fields RET \(.*\) \(.*?\)$ RET 2 RET
-->
> Masayuki Ataka, Hilko Bengen, Jonas Bernoulli, Greg Bognar, Roger
> Bolsius, Daniel Brotsky, Cyril Brulebois, Daniel Burrows, Donald
> Ephraim Curtis, Julien Danjou, Werner Dittmann, Jeremiah Dodds,
> Carsten Dominik, Michael Dwyer, Dmitry Dzhus, Peter Eisentraut,
> Conal Elliott, Bryan Fink, Gunnar Franke, Samuel Freilich, Shigeru
> Fukaya, Peter S. Galbraith, Francois Gannaz, David Glasser, Matus
> Goljer, Kévin Le Gouguec, Marijn Haverbeke, Isaac Hodes, Philippe
> Ivaldi, Zhenlei Jia, Peter Jones, Antonis Kanouras, Marcin
> Kasperski, Keshav Kini, Dave Kleinschmidt, Vasily Korytov, Joost
> Kremers, Bryan Kyle, Kévin Le Gouguec, Chris Lott, Christopher
> J. Madsen, Tom May, Danny McClanahan, Matt McClure, Howard Melman,
> Eric Merritt, Nelson Minar, Stefan Monnier, Makoto Motohashi, Jon
> Mountjoy, Akinori Musha, Pierre Neidhardt, Spanti Nicola, Theresa
> O'Connor, George Ogata, Paul W. Rankin, Jose A. Ortega Ruiz, Max
> Penet, Nicolas Petton, Jorge Israel Peña, Scott Pfister, Kevin
> Porter, Steve Purcell, Alec Resnick, Christophe Rhodes, Enrico
> Scholz, Dale Sedivec, Ankit Solanki, Tyler Smith, Michael Sperber,
> Mike Sperber, Vitalie Spinu, Philipp Stephani, Moogen Tian, Vegard
> Vesterheim, Tim Visher, Ben Voui, Sebastian Wiesner, Peter Williams,
> Tianxiang Xiong, Ian Yang, Syohei Yoshida, and Google, Inc.
------------------------------------------------------------------------------
# Installation & Configuration {#install}
There are many ways to load packages in Emacs, and the following three
are covered in this section: installation using the built-in Emacs
package manager (recommended), installation using a system-wide
package manager, and manual installation.
Markdown Mode is compatible with Emacs 24.3 and later, and it has few
dependencies. To preview files and export to HTML, you will need to
install and configure a Markdown processor (e.g., Markdown.pl).
Also, to enable editing of code blocks in indirect buffers
using `C-c '` (`markdown-edit-code-block`), you will need to install
the [`edit-indirect`](https://github.com/Fanael/edit-indirect/) package.
I> This chapter covers installing the stable version of Markdown
I> Mode, but installing the development version is similar. If you would
I> like to test the development version see the [Markdown Mode Development](#devel)
I> chapter at the end.
## Installation Methods
### Emacs Package Manager
The recommended way to install Markdown Mode is to use the built-in
Emacs package manager, `package.el`, which has been included in Emacs
since version 23. Markdown Mode can be installed via the `markdown-mode`
package in the [MELPA Stable repository](https://stable.melpa.org/#/markdown-mode).[^MELPA]
First, you will need to configure the package manager to use the MELPA
Stable repository by adding the following to your `.emacs`, `init.el`,
or equivalent init file:
``` emacs-lisp
(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`.
When installing this way, the major modes `markdown-mode` and
`gfm-mode` will be autoloaded and `markdown-mode` will be invoked
automatically for file names ending in either `.md` or `.markdown`.[^extensions]
Alternatively, if you manage loading packages with [use-package](https://github.com/jwiegley/use-package)
(a practice I highly recommend) then you can
automatically install and configure `markdown-mode` by adding a
declaration such as the one below to your init file (this is an example,
so adjust the settings as needed):
``` emacs-lisp
(use-package markdown-mode
:ensure t
:commands (markdown-mode gfm-mode)
:mode (("README\\.md\\'" . gfm-mode))
:init (setq markdown-command "/usr/local/bin/multimarkdown"))
```
[^MELPA]: MELPA is Milkypostman's Emacs Lisp Package Archive at <http://melpa.org/>.
[^extensions]: See the tip on [Using Markdown Mode with Other File Extensions](#file-extensions) for instructions on how to configure Emacs to use `markdown-mode` for file extensions other than `.md` and `.markdown`.
### OS Package Manager
Markdown Mode is also available in various package managers on several
operating systems. You should confirm that the package you install
contains the latest stable version (and please notify the package
maintainer if not). These packages also typically do not byte compile
the source files or configure them to load automatically, so you may
still need to follow the [Manual Installation](#manual) instructions in the
next section.
**MacOS:** MacOS users who use Homebrew can install the
[markdown-mode formula](https://github.com/dunn/homebrew-emacs/blob/master/Formula/markdown-mode.rb), which in turn obtains the latest
stable version of Markdown Mode from GitHub.
``` text
brew tap dunn/emacs
brew install dunn/emacs/markdown-mode
```
This will install files in
`/usr/local/share/emacs/site-lisp/markdown-mode`. Depending on where
you obtained Emacs, this directory may or may not be in your
`load-path`, so you may need to add it as described in the
[Manual Installation](#manual) section that follows.
W> If you are a MacPorts user, unfortunately there does not seem to be
W> an up-to-date port. The existing [markdown-mode.el](https://trac.macports.org/browser/trunk/dports/editors/markdown-mode.el/Portfile) port
W> currently points to a Git revision from 2014. There is also a
W> [pending](http://trac.macports.org/ticket/35716) ticket for a new port, but there has been no activity.
W> Rather than installing from MacPorts, I recommend using the Emacs
W> package manager as described above.
**Debian and Ubuntu Linux:** On Debian-based distributions, Markdown
Mode can be installed via the [elpa-markdown-mode](https://packages.debian.org/sid/lisp/elpa-markdown-mode) package.
``` text
sudo apt-get install elpa-markdown-mode
```
**FreeBSD:** FreeBSD users can install
the [textproc/markdown-mode.el](http://svnweb.freebsd.org/ports/head/textproc/markdown-mode.el) port, but note that the
installed files are not byte compiled. Users who install this port
will also need to edit their init files following the Manual
Installation instructions in the next section to load Markdown Mode.
**NetBSD:** Markdown Mode is available in pkgsrc
as [textproc/markdown-mode](http://pkgsrc.se/textproc/markdown-mode), but (as of May 8, 2017) it installs and
byte-compiles an outdated version of Markdown Mode. If you use this
package, you will also need to edit your init file following the Manual
Installation instructions below, to load Markdown Mode. Rather than
installing this package, use the Emacs package manager as described
above.
``` text
pkg_add textproc/markdown-mode
```
### Manual Installation {#manual}
Alternatively, you can manually download and install Markdown Mode.
First, download the [latest stable version](https://jblevins.org/projects/markdown-mode/markdown-mode.el)[^stable] 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:
``` emacs-lisp
(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 GitHub Flavored Markdown files" t)
(add-to-list 'auto-mode-alist '("README\\.md\\'" . gfm-mode))
```
[^stable]: The latest stable version is available at <https://jblevins.org/projects/markdown-mode/markdown-mode.el>.
## Configuring Markdown {#configuring-markdown}
Although strictly speaking no configuration is _necessary_, there are
a few settings that most users will want to customize. The most
important of these is the `markdown-command` variable, which tells
Markdown Mode where to find an external program on your system for
converting Markdown to HTML. You should customize this variable so
that Markdown Mode uses your Markdown processor of choice.
`markdown-command`
: String, default: `"markdown"`.
The command used to convert Markdown to HTML, along with any
necessary command-line options. The default is to look for an
executable named `markdown` in the Emacs `exec-path`.
If you are using the customize interface, you simply need to type the
path to your Markdown script or binary in the "Markdown Command" field
in the customize interface (e.g., `/usr/local/bin/multimarkdown`). If
you know the name of the executable, say `multimarkdown`, but you are
not sure where it is located, and you are using macOS or Linux, you
can find it by typing `which multimarkdown` at the command line.
To set this variable in your init file, add a line such as the
following:
``` emacs-lisp
(setq markdown-command "/usr/local/bin/multimarkdown")
```
### Configuring Markdown on macOS with Homebrew
If you use Homebrew, then you can install Markdown.pl, Pandoc, or
MultiMarkdown by issuing one of the following commands:
``` text
brew install markdown
brew install pandoc
brew install multimarkdown
```
Then, in Emacs, type `M-x customize-mode RET markdown-mode` and set
"Markdown Command" to the path of the executable you just installed:
`/usr/local/bin/markdown`, `/usr/local/bin/pandoc`, or
`/usr/local/bin/multimarkdown`.
### Configuring Markdown on Windows
On Windows, you will need to use the full path including the drive
letter. For example, if you installed Pandoc in `C:\Utils\Console`,
then you would set `markdown-command` like this:
``` emacs-lisp
(setq markdown-command "c:/Utils/Console/pandoc.exe")
```
If you need to run Markdown as a script, with an interpreter, then
you will need to add that as well. For example, to use Markdown.pl with
Perl (both need to be installed), something like this should suffice:
``` emacs-lisp
(setq markdown-command "c:/path/to/perl.exe c:/path/to/Markdown.pl")
```
### Passing Command Line Options to Markdown
You can also customize this variable to pass any necessary
command line options to your Markdown processor. For example, to ask
MultiMarkdown to enable smart typography and footnotes, you can define
`markdown-command` as follows:
``` emacs-lisp
(setq markdown-command "/usr/local/bin/multimarkdown --smart --notes")
```
If you use Pandoc, you may want to configure it as follows:
``` emacs-lisp
(setq markdown-command
(concat
"/usr/local/bin/pandoc"
" --from=markdown --to=html"
" --standalone --mathjax --highlight-style=pygments"))
```
The command-line arguments ask Pandoc to convert Markdown to HTML, to
produce a standalone HTML document rather than a snippet, to enable
MathJax (to render LaTeX as MathML), and to use Pygments for syntax
highlighting of code blocks.
### Passing a File Name to Markdown
By default, Markdown Mode assumes that your Markdown processor accepts
input via the standard input, or `stdin`. That is, it assumes that if
you were using it from the command line, you could _pipe_ input to it
like so:
``` text
cat document.md | markdown
```
If your Markdown processor needs to be passed a file name, you will need
to set another variable: `markdown-command-needs-filename`.
When this variable is `nil` (the default), Markdown Mode will pass the
Markdown content to `markdown-command` using `stdin`. When set to
`t`, Markdown Mode will pass the name of the file as the final command
line argument to `markdown-command`. Note that in the latter case,
you will only be able to run `markdown-command` from buffers which are
visiting a file.
`markdown-command-needs-filename`
: Boolean, default: `nil`.
Set to `t` if the program specified as `markdown-command`
needs the filename to be specified as a command line argument,
rather than reading the content from the standard input (`stdin`).
### Markdown Command and `exec-path`
You can set `markdown-command` to be the full path to the executable,
as in previous examples, but a better solution is to set your
`exec-path` properly so that Emacs can find it without the full path.
You can check this in two ways. First, to see the value of
`exec-path`, issue `M-x describe-variable RET exec-path`. If you see
the directory containing your Markdown executable in the path, then
the name of the program by itself should suffice without the path
(e.g., `multimarkdown`).
Second, you can also use the `executable-find` command to see if Emacs
can find your Markdown processor. This isn't an interactive command,
but you can run it using `eval-expression` via `M-:`. For example, to
check whether Emacs can find an executable named `pandoc`, you can
issue `M-: (executable-find "pandoc")`. The return value will be
displayed in the minibuffer. If you see the path to `pandoc`, then
Emacs can find it. If you see `nil`, then `pandoc` could not be found
in your `exec-path`.
E> If you attempt to preview or export your buffer and you see an error
E> regarding the `markdown` command (which is the default value of the
E> `markdown-command` variable), then most likely you need to check
E> your `markdown-command` setting or install a Markdown processor (or
E> both). Below are some common error messages that indicate that
E> either the `markdown` binary cannot be found or `markdown-command`
E> should be customized to your system:
E>
E> {lang="text"}
E> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
E> /bin/bash: markdown: command not found
E>
E> zsh:1: command not found: markdown
E>
E> 'markdown' is not recognized as an internal or external
E> command, operable program or batch file.
E> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
T> If you are having trouble setting your `exec-path`, a simple way to
T> configure it is to install the
T> [`exec-path-from-shell`](https://github.com/purcell/exec-path-from-shell)
T> package. Its purpose is to ensure that environment variables in
T> Emacs are the same as in your shell. This allows Emacs to find any
T> commands you can also execute from the command line without
T> specifying the full path.
## Customization
{width=70%}
When in Markdown Mode, the `M-x customize-mode` command provides an
interface to all of the available customizations. If you are
using a different mode, then you will need to be more specific: `M-x
customize-mode RET markdown-mode`. Alternatively, you can customize
variables using `M-x customize-group RET markdown` (i.e., by
customizing the _group_ rather than the _mode_).
T> If you use this built-in customize interface, be sure to save your
T> changes before closing the buffer by clicking the "Apply and Save"
T> button.
{width=70%}
Additionally, the faces used for font lock (syntax highlighting)
can be modified to your liking---the font family, color,
size, and so on---by issuing `M-x customize-group RET
markdown-faces` or by using the "Markdown Faces" link at the
bottom of the mode customization screen.
------------------------------------------------------------------------------
# Movement & Editing {#editing}
This section describes the movement, insertion, and editing commands
provided by Markdown Mode. Commands pertaining to block elements are
described first: headings, paragraphs, blockquotes, lists, code blocks,
and horizontal rules. Then, commands for editing span elements are
described: emphasis, code, links, images, and comments. Finally,
miscellaneous editing commands are described for markup completion,
markup cycling, indentation, etc. Extensions, such as footnotes,
fenced code blocks, wiki links, definition lists, and checkboxes
are described in the [Extensions](#extensions) chapter that follows.
Markdown Mode keybindings are grouped by prefixes based on their
function. Like other major modes, most commands begin with `C-c`, the
`mode-specific-command-prefix`. Commands are then grouped by category
under a second-level prefix. For example, the commands for styling
text are grouped under `C-c C-s` (`markdown-mode-style-map`).
Similarly, commands for running Markdown and performing maintenance
tasks reside under `C-c C-c` (`markdown-mode-command-map`).
Movement and shifting commands tend to be associated with paired
delimiters such as `M-{` and `M-}` or `C-c <` and `C-c >`.
If you have `menu-bar-mode` on, you can also access these commands
from the Markdown menu.
We begin with a summary of Markdown Mode prefixes and mnemonics. The
commands in each group will be described in detail below. You can
obtain a list of all keybindings by pressing `C-c C-h` or `C-h m`. To
see commands under a specific prefix, add `C-h` to the end of the
prefix. For example, press `C-c C-s C-h` to list all commands under
`C-c C-s`.
| Prefix | Function |
|-----------|------------------------|
| `C-c C-s` | **S**tyles |
| `C-c C-l` | **L**inks |
| `C-c C-i` | **I**mages |
| `C-c C-c` | **C**ommands |
| `C-c C-x` | Toggles |
When you use the `C-c C-s` or `C-c C-c` prefixes, prompts will
appear in the minibuffer that provide hints for a few of the most
commonly used commands. You can control this by setting
`markdown-enable-prefix-prompts`.
`markdown-enable-prefix-prompts`
: Boolean, default: `t`.
When non-`nil`, display prompts when certain prefix keys are
pressed. Set to `nil` to disable these prompts.
T> There are several Emacs packages for providing keybinding hints,
T> such as `which-key` and `guide-key`. If you use one of these,
T> you can disable Markdown Mode's prefix prompts by setting
T> `markdown-enable-prefix-prompts` to `nil`.
The following sections describe many commands for inserting
markup---for headings, blockquotes, lists, source code, and so
on---and many of these commands behave differently depending on
whether `transient-mark-mode` is enabled or not. When it makes sense,
if `transient-mark-mode` is on and there is an active region, the
command applies to the text in the region. For example, `C-c C-s b`
(`markdown-insert-bold`) would make the region bold. When
`transient-mark-mode` is off or there is no active region, many
commands then proceed to work with either the word at the point (e.g.,
for italics) or the current line (e.g., for headings).
There are also some parallel commands that act specifically on the
region, even when `transient-mark-mode` is disabled. These commands
have the same keybindings as their standard counterparts but use an
uppercase letter instead. For example, `markdown-insert-blockquote`
is bound to `C-c C-s q` while `markdown-blockquote-region` is bound to
`C-c C-s Q`. The latter _always_ applies to the region while the former
only acts on the region when `transient-mark-mode` is on and the region
is active.
T> For users who prefer to work _without_ `transient-mark-mode`,
T> conveniently since Emacs 22 it can be enabled temporarily by pressing
T> `C-SPC C-SPC`.
## Headings
Headings in Markdown can be defined using either of two formats:
atx and setext.
Atx-style headings are lines beginning with one to six hash marks (`#`)
followed by the heading text. The number of hash marks corresponds to
the level of the heading, with one being the most prominent and six
being the least prominent (corresponding to the six levels of headings
in HTML, `<h1>` through `<h6>`). The heading text may optionally be
followed by an equal number of hash marks.
{lang="text"}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# First-level heading #
First section text. Here we close the heading with a hash mark.
## Second-level heading
Second section text. No closing hash marks here.
### Third-level heading ###
Third section text.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The second type of headings supported in Markdown are called setext
headings, for which only two levels are defined. Instead of being
surrounded by hash marks, equals signs (`=`) and hyphens (`-`) are
used to underline the heading text.
{lang="text"}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
First-level heading
==================
Second-level heading
-------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### Inserting & Replacing Headings
There are two options for inserting or replacing headings: you can
either insert a heading of a specific level and type or let Markdown
Mode determine the level and type for you. To insert a heading of a
specific level directly, simply use `C-c C-s #` where `#` is a number
`1` through `6` (`markdown-insert-header-atx-1`, …,
`markdown-insert-header-atx-6`).
To insert setext headings directly, use
`C-c C-s !` (`markdown-insert-header-setext-1`) for level one
or `C-c C-s @` (`markdown-insert-header-setext-2`) for level two.
Noting that `!` is `S-1` and `@` is `S-2` may make these commands
easier to remember.
For automatic heading insertion use `C-c C-s h`
(`markdown-insert-header-dwim`). The type and level are determined
based on the previous heading. By default, the new heading will be a
sibling (same level). A `C-u` prefix can be added to insert a heading
that is _promoted_ (lower number) by one level or a `C-u C-u` prefix
can be given to insert a heading that is _demoted_ (higher number) by
one level.
X> Suppose you are currently writing in a level-two section, as in the
X> following example, where `█` indicates the point:
X>
X> {lang="text"}
X> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
X> ## Heading ##
X>
X> Body text.
X> █
X> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
X>
X> Pressing `C-c C-s h`, for automatic heading insertion, creates a
X> new level-two sibling heading:
X>
X> {lang="text"}
X> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
X> ## Heading ##
X>
X> Body text.
X>
X> ## █##
X> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
X>
X> Using the universal prefix, as in `C-u C-c C-s h`, creates a
X> new level-one parent heading:
X>
X> {lang="text"}
X> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
X> # █#
X> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
X>
X> Using the universal prefix twice, as in `C-u C-u C-c C-s h`, creates a
X> new level-three child heading instead:
X>
X> {lang="text"}
X> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
X> ### █###
X> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To automatically insert setext-style headings, use `C-c C-s H`
(`markdown-insert-header-setext-dwim`). This command behaves
like `C-c C-c h` (`markdown-insert-header-dwim`) in that the level is
calculated automatically and it can accept the same prefix arguments,
but it uses setext (underlined) headings for levels one and two.
As with several other markup commands, if the region is active and
`transient-mark-mode` is on, the heading insertion commands use the
text in the region as the heading text. Next, if the current line is
not blank, they use the text on the current line. Otherwise, the user
is prompted to provide the heading text.
If the point is at a heading, these commands will replace the existing
markup in order to update the level or type of the heading. This
is useful, for example, when the automatically-determined heading level
is not what you wanted: the heading level can be quickly changed as needed.
X> Suppose you mistakenly insert a level-two heading and want to
X> replace it, as in the following example:
X>
X> {lang="text"}
X> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
X> ## Heading█##
X> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
X>
X> Pressing `C-c C-s 1` replaces the heading with a level-one heading:
X>
X> {lang="text"}
X> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
X> # Heading█#
X> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To remove the markup of the heading at the point, you can press `C-c C-k`
(`markdown-kill-thing-at-point`) to kill the heading and add the text
to the kill ring. Press `C-y` to yank the heading text back into the
buffer.
I> Markdown.pl and several other processors allow one to omit the
I> whitespace between the hash mark and the heading text, but some
I> processors and specifications such as CommonMark do require the
I> whitespace. To help guarantee compatibility, Markdown Mode also
I> requires whitespace. This has other advantages, for example, it
I> allows one to use #hashtags that might wrap to the beginning of the
I> line.
T> If the length of the underline characters is not exactly right,
T> Markdown Mode can help keep things tidy by "completing" the markup
T> for you after the fact. See the [Markup Completion](#completion) section of
T> this chapter for more details.
### Outline Navigation {#outline}
Markdown Mode defines keys for hierarchical navigation in headings and
lists. When the point is in a list, they move between list items.
Otherwise, they move between headings.
* Use `C-c C-n` and `C-c C-p` (`markdown-outline-previous` and
`markdown-outline-next`) to move to the next and previous visible
headings or list items _of any level_.
* Similarly, `C-c C-f` and `C-c C-b`
(`markdown-outline-previous-same-level` and `markdown-outline-next-same-level`)
move to the next and previous visible headings or list items
_at the same level_ as the one at the point.
* Finally, `C-c C-u` (`markdown-outline-up`) will move up to the
parent heading or list item.
T> The outline navigation commands in `markdown-mode` (`C-c C-n`,
T> `C-c C-p`, `C-c C-f`, `C-c C-b`, and `C-c C-u`) are the same as in
T> `org-mode`, which are in turn based on those in `outline-minor-mode`.
### Movement by Defun
The usual Emacs commands can be used to move by defuns (top-level
major definitions), but in Markdown Mode, **a defun is a section.** As
usual, `C-M-a` (`beginning-of-defun`) will move the point to the
beginning of the current or preceding defun, `C-M-e` (`end-of-defun`)
will move to the end of the current or following defun, and `C-M-h`
(`mark-defun`) will mark the current defun. To narrow
the buffer to show only the current section, use `C-x n d`
(`narrow-to-defun`) and to widen again, use `C-x n w` (`widen`) as
usual.
T> Defuns in Emacs are major top-level definitions. The name derives
T> from the Emacs Lisp `defun` macro for defining functions. The
T> defun movement and marking commands in Markdown Mode (`C-M-a`,
T> `C-M-e`, and `C-M-h`) are the same as in Emacs more generally.
T> Since Markdown has no functions, Markdown Mode considers section
T> headings to be defuns.
To include the complete subtree (including any subsections) when
marking and narrowing, Markdown Mode also defines `C-c C-M-h`
(`markdown-mark-subtree`) and `C-x n s`
(`markdown-narrow-to-subtree`).
### Movement by Page
Markdown Mode also re-defines the "page" movement and marking commands
in Emacs, since they aren't otherwise useful in Markdown documents.
Elsewhere in Emacs, pages are defined by a regular expression given in
the `page-delimiter` variable, usually `^L` (control-L, the page break
control code). Markdown Mode redefines a page to be a complete
top-level subtree, so you can navigate between top-level headings
using the standard Emacs page movement keys: `C-x [` and `C-x ]`
(`markdown-backward-page` and `markdown-forward-page`). To
mark the current top-level subtree, use `C-x C-p`
(`markdown-mark-page`). To narrow the buffer to show only the current
top-level subtree, use `C-x n p` (`markdown-narrow-to-page`) and to
widen again, use `C-x n w` (`widen`) as usual.
### Visibility Cycling
Markdown Mode supports `org-mode`-style visibility cycling for
headings and sections. There are two types of visibility cycling:
global and local.
Pressing `S-TAB` (`markdown-shifttab`) cycles _globally_ between three
levels of visibility, as shown in the screenshot below:
1. headings only (overview),
2. top-level headings only (contents),
3. all sections visible (show all).
On the other hand, pressing `TAB` (`markdown-cycle`) while the point
is at a heading will cycle through three levels of visibility
_locally_ for the current subtree:
1. all subsections and sub-headings completely folded,
2. child headings visible,
3. all subsections and sub-headings fully visible.
### Subtree Editing
Entire subtrees of ATX headings can be promoted and demoted with
`C-c <left>` and `C-c <right>` (`markdown-promote` and
`markdown-demote`). Conveniently, these are the same keybindings used
for promotion and demotion of list items. If the point is at a list
item, they operate on the list item. Otherwise, they operate on the
current heading subtree. Similarly, subtrees can be moved up and down
with `C-c <up>` and `C-c <down>` (`markdown-move-up` and
`markdown-move-down`).
W> These commands are based on functions from `outline.el` that are
W> regular-expression-based, and so they currently do not work
W> properly if there are setext headings in the region.
Note the following "boundary" behavior for promotion and demotion.
Any level-six headings will not be demoted further (i.e., they remain
at level six, since Markdown and HTML do not define more than six
levels of headings) and any level-one headings will be promoted away
entirely (i.e., the heading markup will be removed, since level-zero
headings are undefined).
### Heading Customization
Markdown Mode distinguishes between _symmetric_ and _asymmetric_ atx
heading markup. Symmetric headings have an equal number of hash marks
at the beginning and end of the line. Asymmetric headings have only
leading hash marks. Both are valid, so this is an aesthetic choice.
You can customize Markdown Mode to fit your preference by setting the
`markdown-asymmetric-header` variable.
`markdown-asymmetric-header`
: `nil` or `t`, default: `nil`.
Determines if atx heading style will be asymmetric.
When `nil`, balanced markup will be inserted at the beginning and
end of the line around the heading title.
{lang="text}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
## Heading ##
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Set to a non-`nil` value to use asymmetric heading styling, placing
heading markup only at the beginning of the line.
{lang="text}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
## Heading
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
_Example:_
``` emacs-lisp
(setq markdown-asymmetric-header t)
```
Markdown Mode also has the ability to scale the font sizes used for
headings in proportion to their importance (as in AUCTeX, for
instance). To enable this, customize `markdown-header-scaling` or set
it in your init file.