Markdown Soma

Live Markdown in Emacs

markdown-soma is an Emacs minor-mode which gives you live rendering of Markdown to HTML.

Based on the Vim plugin vim-markdown-composer,

Usage

To start:

M-x markdown-soma-mode

The default browser will open a tab with the rendered markdown view.

Edits and commands in your current Emacs buffer, will trigger a new markdown render in the browser. The browser view will automatically scroll so you can see what you're editing. (This could be better, suggestions on how to improve it are welcome.)

Render hooks

A new markdown render triggers by hooks in markdown-soma--render-buffer-hooks.

;; default render buffer hooks

(setq markdown-soma--render-buffer-hooks
  '(after-revert-hook
    after-save-hook
    after-change-functions
    post-command-hook))

Install

Via MELPA

M-x package-install markdown-soma

Using Doom Emacs

in ~/.doom.d/packages.el

(package! markdown-soma)

Install soma executable

The source for the soma markdown/websocket server is included the package repository. You'll need to compile it from source. If you don't have Rust on your system, use rustup to get set up.

Once rust is ready, open a terminal at the package folder.

$ cargo install --path .

# compiles:
# ⟶ ~/.cargo/bin/soma

By default, ~/.cargo/bin will be in your $PATH.

Customizing

You can select a builtin CSS theme with::

M-x markdown-soma-select-builtin-css

To persist the setting, select a theme name and add it to your Emacs init with:

(setq markdown-soma-custom-css
   (markdown-soma--css-pathname-from-builtin-name "theme name")

You can also use any other markdown aware CSS stylesheet (i.e. targets CSS selectors #markdown-preview and/or .markdown-preview as markdown content containers..)

Set a custom CSS file to use with:

M-x markdown-soma-select-css-file

Note: the CSS style will apply after restarting markdown-soma-mode.

M-x markdown-soma-restart

To persist the setting add to your Emacs init

(setq markdown-soma-custom-css "/path/to/your.css")

You can select a highlightjs theme:

M-x markdown-soma-select-highlight-theme

To persist the setting add to your Emacs init

;; Change "theme name" to the selected highlightjs theme.
(setq markdown-soma-highlightjs-theme "theme name")

Markdown support

Soma converts markdown to HTML, using pulldown-cmark. It is 100% compliant with the common-markdown spec.

Extensions

• Github flavored markdown (gfm) tables
• GFM code fences
• GFM task lists
• Strike-through

---

TeX/MathJax support thanks to KaTeX

e.g. \\sqrt{3x-1} wrapped in $ ⟶ $\\sqrt{3x-1}$ to display the expression ⟶ $\sqrt{3x-1}$

wrapping with \\(\\) e.g. \\(\\sqrt{3x-1}\\) gives the same \(\sqrt{3x-1}\) inline.

Use $$...$$ or \\[..\\]to center the expression in a presentation style.

e.g. $$\\sqrt{3x-1}$$

$$\sqrt{3x-1}$$

$$n = {A \pm \sqrt{b^4-4ac} \over 2a}$$

$$n = {A \pm \sqrt{b^4-4ac} \over 2a}$$

$$\xleftrightharpoons{abc}$$

$$\xleftrightharpoons{abc}$$

---

Technical note.

Emacs sends text from the current buffer to soma using (process-send-string BUFFER-TEXT PROCESS).

soma converts input (assumed to be markdown text) and broadcasts changes to connected clients (as HTML).

Emacs embeds a value for scrollTo, into the input with a magic comment e.g.

<!-- SOMA: {"scrollTo": 0} // scrolls to the top.  -->

In a nutshell pulldown-cmark is doing the heavy lifting. Providing the core markdown service, via aurelius. Which in turn provides the web/websocket interface. The soma executable is essentially just wrapping aurelius as a repeating stdin reader, i.e. instead of terminating at EOF it will use this as a signal to broadcast the updated content to clients.