doomemacs/modules/lang/markdown/README.org

:lang markdown

• Description
  • Maintainers
  • Module flags
  • Packages
  • Hacks
  • Changelog
• Installation
  • Linters
  • Markdown compiler
    • MarkedJS
    • Pandoc
    • Markdown
    • MultiMarkdown
  • Formatter
• Usage
  • Markdown preview
• Configuration
  • Changing how markdown is compiled
• Troubleshooting
• Frequently asked questions
• Appendix

Description   unfold

This module provides Markdown support for Emacs.

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

Maintainers

• @hlissner

Become a maintainer?

Module flags

+grip

Enable grip support (on <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 module does not have a changelog yet.

Installation

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

  • markdownlint ($ npm install markdownlint)
  • mdl ($ gem install mdl)

• General (natural language)

  • proselint

    • $ pip install proselint

    • Or through your OS package manager

      • MacOS: $ brew install proselint
      • Arch Linux: proselint in AUR
      • Debian & Ubuntu: $ apt-get install python3-proselint
      • Fedora: $ dnf install proselint
  • 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):

• markedjs: a markdown compiler "built for speed"
• pandoc: the universal markup transpiler

• markdown: there are various flavors of this compiler. This module will look for these two:

  • John Gruber's original perl script
  • The C implementation called discount, by David Parsons
• multimarkdown: a compiler for a language that is a superset of Markdown, with additional output formats and features.

MarkedJS

Not to be confused with the Marked 2 app, marked is an npm package:

npm install -g marked

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 John Gruber's website.

MultiMarkdown

See 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: multimarkdown is available on the AUR

Formatter

Formatting is handled using the doom-module::editor format module via prettier.

TODO Usage

󱌣 This module's usage documentation is incomplete. Complete it?

Markdown preview

markdown-preview is bound to <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

󱌣 This module's configuration documentation is incomplete. Complete it?

Changing how markdown is compiled

When markdown-preview is invoked (<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:

'(+markdown-compile-marked
  +markdown-compile-pandoc
  +markdown-compile-markdown
  +markdown-compile-multimarkdown)

These functions will attempt to use the marked, pandoc and markdown executables, if available. Changing this variable will control how markdown is compiled:

;; 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)

Otherwise, you can change markdown-command directly:

(setq markdown-command "markdown | smartypants")

Troubleshooting

There are no known problems with this module. Report one?

Frequently asked questions

This module has no FAQs yet. Ask one?

TODO Appendix

󱌣 This module has no appendix yet. Write one?