#+TITLE: Markdown layer

#+TAGS: dsl|layer|markup|programming

[[file:img/markdown.png]]

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#bibtex][BibTeX]]
- [[#install][Install]]
- [[#configuration][Configuration]]
  - [[#live-preview][Live preview]]
  - [[#automatic-mmm-mode-generation][Automatic MMM-Mode Generation]]
- [[#usage][Usage]]
  - [[#generate-a-toc][Generate a TOC]]
  - [[#editing-tables][Editing tables]]
- [[#key-bindings][Key bindings]]
  - [[#element-insertion][Element insertion]]
  - [[#element-removal][Element removal]]
  - [[#table-manipulation][Table manipulation]]
  - [[#completion][Completion]]
  - [[#following-and-jumping][Following and Jumping]]
  - [[#indentation][Indentation]]
  - [[#header-navigation][Header navigation]]
  - [[#buffer-wide-commands][Buffer-wide commands]]
  - [[#list-editing][List editing]]
  - [[#movement][Movement]]
  - [[#promotion-demotion][Promotion, Demotion]]
  - [[#toggles][Toggles]]

* Description
This layer adds markdown support to Spacemacs.

** Features:
- markdown files support via [[http://jblevins.org/git/markdown-mode.git/][markdown-mode]]
- [[https://github.com/mdx-js/mdx][mdx]] file support via [[http://jblevins.org/git/markdown-mode.git/][markdown-mode]]
- Fast GitHub-flavored live preview via [[https://github.com/blak3mill3r/vmd-mode][vmd-mode]]
- TOC generation via [[https://github.com/ardumont/markdown-toc][markdown-toc]]
- Completion of Emojis using [[https://github.com/dunn/company-emoji][company-emoji]] (still needs a way of showing, either
  using the =emoji= layer or having a proper font) :clap:

* BibTeX
For more extensive support of references with BibTeX files, have a look at the
[[https://github.com/syl20bnr/spacemacs/blob/develop/layers/%2Blang/bibtex/README.org][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
A live preview can be generated when one of these executables are in path:
- =markdown=
- =pandoc=
- =markdown_py=

A well-knowned =markdown= command is from [[https://daringfireball.net/projects/markdown/]].
Or follow =pandoc= installation instructions to install pandoc into path:
[[https://pandoc.org/installing.html]]

Another choice is installing =Python-Markdown=:

#+BEGIN_SRC shell
  pip install --user Markdown
#+END_SRC

Then setup the =markdown-executable= variable to point to the executable of =Python-Markdown=:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (markdown :variables markdown-executable "~/.local/bin/markdown_py")))
#+END_SRC

Another alternative is to install the `github layer` and use `grip-mode` for live
previewing, though this only supports Github flavored markdown.

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=:

#+BEGIN_SRC emacs-lisp
  dotspacemacs-configuration-layers '(
    (markdown :variables markdown-live-preview-engine 'vmd))
#+END_SRC

And install the executable with:

#+BEGIN_SRC shell
  npm install -g vmd
#+END_SRC

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")`:

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

*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~

** Editing tables
While =markdown-mode= provides functionality to edit tables, users of =org=
layer benefit from more sophisticated =orgtbl-mode=.

In order to use =orgtabl-mode=, add =org= layer to your =~/.spacemacs=.

* 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 B~ | insert gfm checkbox                                               |
| ~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 k~ | make region <kbd> element or insert <kbd> element                 |
| ~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                                                        |
| ~SPC m x s~ | make region striked through or insert strikethrough               |

** Element removal

| Key binding | Description         |
|-------------+---------------------|
| ~SPC m k~   | kill thing at point |

** Table manipulation

| Key binding | Description             |
|-------------+-------------------------|
| ~SPC m t p~ | move row up             |
| ~SPC m t n~ | move row down           |
| ~SPC m t f~ | move column right       |
| ~SPC m t b~ | move column left        |
| ~SPC m t r~ | insert row              |
| ~SPC m t R~ | delete row              |
| ~SPC m t c~ | insert column           |
| ~SPC m t C~ | delete column           |
| ~SPC m t s~ | sort lines              |
| ~SPC m t t~ | transpose table         |
| ~SPC m t d~ | convert region to table |

** 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    |