spacemacs/layers/+lang/markdown/README.org

Markdown layer

• Description
  • Features:
• BibTeX
• Install
• Configuration
  • Live preview
  • Automatic MMM-Mode Generation
• Usage
  • Generate a TOC
• Key bindings
  • Element insertion
  • Element removal
  • Completion
  • Following and Jumping
  • Indentation
  • Header navigation
  • Buffer-wide commands
  • List editing
  • Movement
  • Promotion, Demotion
  • Toggles

Description

This layer adds markdown support to Spacemacs.

Features:

• markdown files support via markdown-mode
• Fast Github-flavored live preview via vmd-mode
• TOC generation via markdown-toc
• Completion of Emojis using company-emoji (still needs a way of showing, either using the emoji layer or having a proper font) 👏

BibTeX

For more extensive support of references with BibTeX files, have a look at the BibTeX layer.

Install

To use this configuration layer, add it to your ~/.spacemacs. You will need to add markdown to the existing dotspacemacs-configuration-layers list in this file.

Configuration

Live preview

By default the built-in Emacs web browser is used to live preview a markdown buffer.

To use vmd (Github-flavored live preview) instead set the value of the variable markdown-live-preview-engine to vmd:

  dotspacemacs-configuration-layers '(
    (markdown :variables markdown-live-preview-engine 'vmd))

And install the executable with:

  npm install -g vmd

Additionally there is flymd package in chrome layer that allows to preview markdown buffer in Chrome. Please refer to chrome layer documentation for more information.

Automatic MMM-Mode Generation

To generate MMM-Modes for languages set the value of the variable markdown-mmm-auto-modes to a list of the languages. For languages where the mode name directly relates to the language name, use a string. Otherwise, use a list of `("language" "mode")`:

  dotspacemacs-configuration-layers '(
    (markdown :variables markdown-mmm-auto-modes '("c" "c++" "python" "scala" ("elisp" "emacs-lisp"))

Note: Spacemacs already defines the variable markdown-mmm-auto-modes to a bunch of languages. Consider opening a PR on the Spacemacs repository to add new languages instead of overriding the variable in your dotfile.

Usage

Generate a TOC

To generate a table of contents type on top of the buffer: SPC SPC markdown-toc-generate-toc RET

Key bindings

Element insertion

Key binding	Description
SPC m -	insert horizontal line
SPC m h i	insert header dwim
SPC m h I	insert header setext dwim
SPC m h 1	insert header atx 1
SPC m h 2	insert header atx 2
SPC m h 3	insert header atx 3
SPC m h 4	insert header atx 4
SPC m h 5	insert header atx 5
SPC m h 6	insert header atx 6
SPC m h !	insert header setext 1
SPC m h @	insert header setext 2
SPC m i l	insert link
SPC m i u	insert uri
SPC m i f	insert footnote
SPC m i w	insert wiki link
SPC m i i	insert image
SPC m i t	insert Table of Contents (toc)
SPC m x b	make region bold or insert bold
SPC m x i	make region italic or insert italic
SPC m x c	make region code or insert code
SPC m x C	make region code or insert code (Github Flavored Markdown format)
SPC m x q	make region blockquote or insert blockquote
SPC m x Q	blockquote region
SPC m x p	make region or insert pre
SPC m x P	pre region

Element removal

Key binding	Description
SPC m k	kill thing at point

Completion

Key binding	Description
SPC m ]	complete

Following and Jumping

Key binding	Description
SPC m o	follow thing at point
RET	jump (markdown-do)

Indentation

Key binding	Description
SPC m \>	indent region
SPC m \<	outdent region

Header navigation

Key binding	Description
gj	outline forward same level
gk	outline backward same level
gh	outline up one level
gl	outline next visible heading

Buffer-wide commands

Key binding	Description
SPC m c ]	complete buffer
SPC m c m	other window
SPC m c p	preview
SPC m c P	live preview using engine defined with layer variable markdown-live-preview-engine
SPC m c e	export
SPC m c v	export and preview
SPC m c o	open
SPC m c w	kill ring save
SPC m c c	check refs
SPC m c n	cleanup list numbers
SPC m c r	render buffer

List editing

Key binding	Description
SPC m l i	insert list item

Movement

Key binding	Description
SPC m {	backward paragraph
SPC m }	forward paragraph
SPC m N	next link
SPC m P	previous link

Promotion, Demotion

Key binding	Command
M-k or M-up	markdown-move-up
M-j or M-down	markdown-move-down
M-h or M-left	markdown-promote
M-l or M-right	markdown-demote

Toggles

Key binding	Description
SPC m t i	toggle inline images
SPC m t l	toggle hidden urls
SPC m t m	toggle markup hiding
SPC m t t	toggle checkbox
SPC m t w	toggle wiki links