doomemacs/modules/lang/markdown/README.org

#+title:    :lang markdown
#+subtitle: Write docs for people to ignore
#+created:  February 19, 2017
#+since:    2.0.0

* Description :unfold:
This module provides Markdown support for Emacs.

#+begin_quote
Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you
to write using an easy-to-read, easy-to-write plain text format, then convert it
to structurally valid XHTML (or HTML).

Thus, “Markdown” is two things: (1) a plain text formatting syntax; and (2) a
software tool, written in Perl, that converts the plain text formatting to HTML.
See the Syntax page for details pertaining to Markdown's formatting syntax. You
can try it out, right now, using the online Dingus.

The overriding design goal for Markdown's formatting syntax is to make it as
readable as possible. The idea is that a Markdown-formatted document should be
publishable as-is, as plain text, without looking like it's been marked up with
tags or formatting instructions. While Markdown's syntax has been influenced by
several existing text-to-HTML filters, the single biggest source of inspiration
for Markdown's syntax is the format of plain text email. -- John Gruber
#+end_quote

** Maintainers
- [[doom-user:][@hlissner]]

[[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
- +grip ::
  Enable [[https://github.com/seagle0128/grip-mode][grip support]] (on [[kbd:][<localleader> p]]), to provide live github-style
  previews of your markdown (or org) files.

** Packages
- [[doom-package:][edit-indirect]]
- [[doom-package:][evil-markdown]] if [[doom-module:][:editor evil +everywhere]]
- [[doom-package:][grip-mode]] if [[doom-module:][+grip]]
- [[doom-package:][markdown-mode]]
- [[doom-package:][markdown-toc]]

** Hacks
- [[doom-package:][flyspell]] has been configured not to spell check in code blocks, links, HTML
  tags or references.

** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./

* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]

This module requires:
- A linter (requires [[doom-module:][:checkers syntax]])
- A markdown compiler, for previewing Markdown

** Linters
Out of the box, flycheck recognizes these checkers for markdown-mode and
gfm-mode:

- Markdown-specific
  - [[https://github.com/DavidAnson/markdownlint][markdownlint]] (~$ npm install markdownlint~)
  - [[https://github.com/markdownlint/markdownlint][mdl]] (~$ gem install mdl~)
- General (natural language)
  - [[http://proselint.com/][proselint]]
    - ~$ pip install proselint~
    - Or through your OS package manager
      - MacOS: ~$ brew install proselint~
      - Arch Linux: ~$ pacman -S proselint~
  - [[https://github.com/textlint/textlint][textlint]] (~$ npm install textlint~)

** Markdown compiler
This module requires a markdown compiler in order for ~markdown-preview~ to
work. It will recognize and use one of the following executables, in this order
(you only need one):

- [[https://github.com/markedjs/marked][markedjs]]: a markdown compiler "built for speed"
- [[https://github.com/jgm/pandoc][pandoc]]: the universal markup transpiler
- [[http://pell.portland.or.us/~orc/Code/discount/][markdown]]: there are various flavors of this compiler. This module will look
  for these two:
  - John Gruber's [[https://daringfireball.net/projects/markdown/][original perl script]]
  - The C implementation called [[http://pell.portland.or.us/~orc/Code/discount/][discount]], by David Parsons
- [[https://fletcher.github.io/MultiMarkdown-6/][multimarkdown]]: a compiler for a language that is a superset of Markdown, with
  additional output formats and features.

*** MarkedJS
Not to be confused with [[https://marked2app.com/][the Marked 2 app]], marked is an npm package:
#+begin_src sh
npm install -g marked
#+end_src

*** Pandoc
Pandoc is the universal markup transpiler. It should be available through your
system package manager. For example:

+ MacOS: ~$ brew install pandoc~
+ Arch Linux: ~$ pacman -S pandoc~

*** Markdown
The C implementation of Markdown.pl, called =discount=, is available through
your OS's package manager:

+ MacOS: ~$ brew install discount~
+ Arch Linux: ~$ pacman -S discount~

The original perl script that discount is inspired from can be found on [[https://daringfireball.net/projects/markdown/][John
Gruber's website]].

*** MultiMarkdown
See [[https://fletcher.github.io/MultiMarkdown-6/introduction.html][its documentation]] for details on what MultiMarkdown is. The compiler can be
installed through your OS's package manager:

+ MacOS: ~$ brew install multimarkdown~
+ Arch Linux: [[https://aur.archlinux.org/packages/multimarkdown/][multimarkdown]] is available on the AUR

* TODO Usage
#+begin_quote
 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** Markdown preview
~markdown-preview~ is bound to [[kbd:][<localleader> p]]. This will open a preview of your
compiled markdown document in your browser.

Alternatively, you can use ~grip-mode~ through [[doom-module:][+grip]].

* Configuration
#+begin_quote
 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** Changing how markdown is compiled
When ~markdown-preview~ is invoked ([[kbd:][<localleader> p]]) it consults
~markdown-command~. Its default value (~#'+markdown-compile~) will consult
~+markdown-compile-functions~: a list of functions that take three arguments:
the start and end point in the current buffer to use as input, and an output
buffer to insert the result in.

By default, the value of ~+markdown-compile-functions~ is:
#+begin_src lisp
'(+markdown-compile-marked
  +markdown-compile-pandoc
  +markdown-compile-markdown
  +markdown-compile-multimarkdown)
#+end_src

These functions will attempt to use the marked, pandoc and markdown executables,
if available. Changing this variable will control how markdown is compiled:
#+begin_src emacs-lisp
;; Add a new one
(add-hook '+markdown-compile-functions #'my-compile-function)

;; Or remove an existing one
(remove-hook '+markdown-compile-functions #'+markdown-compile-markdown)
#+end_src

Otherwise, you can change ~markdown-command~ directly:
#+begin_src emacs-lisp
(setq markdown-command "markdown | smartypants")
#+end_src

* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]

* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

* TODO Appendix
#+begin_quote
 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote