markdown-xwidget

An Emacs minor mode to preview markdown files using xwidget-webkit. Features:

Render markdown using GitHub styles
Mermaid diagrams
Syntax highlighting
Mathjax

Light	Dark

These are just two examples. There's a lot of room to customize the theme.

Prerequisites

This package will not work without the following prerequisites.

Emacs xwidget support

This package displays rendered markdown in an xwidget (an embedded browser), which only works if your Emacs was compiled --with-xwidgets. If you don't have xwidget support, you're missing out!

To check whether your Emacs supports xwidgets, evaluate this in your *scratch* buffer:
```
(featurep 'xwidget-internal)
;; => t     ; you have xwidgets
;; => nil   ; you don't have xwidgets
```
To install Emacs with xwidget support on MacOS, check out homebrew-emacs-plus:
```
brew tap d12frosted/emacs-plus
brew install emacs-plus --with-xwidgets
```
pandoc, multimarkdown, or similar

pandoc and multimarkdown are CLI programs that can create HTML from markdown. You need a program like this installed. Note: there is currently an issue with pandoc and mermaid.

Installation

Here are some examples of installing and configuring markdown-xwidget.

This package is not yet on ELPA/MELPA.

[!WARNING] In all examples below, it's important to specify the :files directive! Without it, the non-elisp files (CSS and HTML) won't be copied to the right place.

elpaca

(use-package markdown-xwidget
  :after markdown-mode
  :elpaca (markdown-xwidget
           :host github
           :repo "cfclrk/markdown-xwidget"
           :files (:defaults "resources")))

doom

(package! markdown-xwidget
  :recipe (:host github
           :repo "cfclrk/markdown-xwidget"
           :files (:defaults "resources")))

straight

(use-package markdown-xwidget
  :after markdown-mode
  :straight (markdown-xwidget
             :type git
             :host github
             :repo "cfclrk/markdown-xwidget"
             :files (:defaults "resources")))

For a fully-working example, see: straight/init.el.

quelpa

For a fully-working example, see: quelpa/init.el.

Usage

Open a markdown file and then run M-x markdown-xwidget-preview-mode to toggle the live-preview on or off.

It's handy to bind this to x in markdown-mode-command-map, as shown below. Then, you can start the markdown preview using C-c C-c x.

(use-package markdown-xwidget
  :after markdown-mode
  :elpaca (markdown-xwidget
           :host github
           :repo "cfclrk/markdown-xwidget"
           :files (:defaults "resources"))
  :bind (:map markdown-mode-command-map
              ("x" . markdown-xwidget-preview-mode)))

Configuration

The following variables can be customized, and are shown here along with their default values:

(setq markdown-xwidget-command nil
      markdown-xwidget-github-theme "light"
      markdown-xwidget-mermaid-theme "default"
      markdown-xwidget-code-block-theme "default")

markdown-xwidget-command

An executable that can turn markdown into HTML. If nil, the value of markdown-command is used (which defaults to the command "markdown"). Some suitable values are "pandoc", "markdown", and "multimarkdown", assuming you have those tools installed. Note: there is currently an issue with pandoc and mermaid.

Default value: nil

markdown-xwidget-github-theme

The CSS theme used to stylize markdown elements. Valid values are: light, light-colorblind, light-high-contrast, light-tritanopia, dark, dark-dimmed, dark-colorblind, dark-high-contrast, dark-tritanopia.

Default value: "light"

markdown-xwidget-mermaid-theme

The mermaid theme to use when rendering mermaid diagrams. These themes are documented in mermaid's Deployable Themes. Valid values are: forest, dark, default, neutral.

Default value: "default"'

markdown-xwidget-code-block-theme

Theme to apply to fenced code blocks. A valid value is any filename in highlight.js/src/styles (without the .css extension).

Default value: "default"

Development

Update highlight.js, mermaid, and mathjax

To update the included versions of highlight.js, mermaid, and mathjax, run:

./scripts/fetch_resources.sh

Update GitHub CSS

[!NOTE] I haven't automated this because I'm hoping find somewhere else to obtain these CSS files. Someone else must create and maintain files like these! I just haven't found them.

The github CSS files in the resources/github_css directory are slightly modified versions of what can be generated from the github-markdown-css project. To generate the CSS, run the gen_github_css.js script for every theme:

node ./scripts/gen_github_css.js

Each run results in a file with two themes. Browsers automatically choose one of the two themes, using the prefers-color-scheme media query.

I manually split each generated file into two files -- one for each theme -- by removing the media query and putting the color variables in a :root binding.

cfclrk / markdown-xwidget

readme