Homepage: https://github.com/jasonm23/markdown-soma
Author: Jason Milkins
Updated:
Live preview for Markdown
# 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`][vmc],
## 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`.
```lisp
;; 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](https://melpa.org)
```
M-x package-install markdown-soma
```
Using [Doom Emacs](https://github.com/doomemacs/doomemacs)
in `~/.doom.d/packages.el`
```lisp
(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.
```shell
$ 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:
```lisp
(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
```lisp
(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
```lisp
;; 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][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.
```html
```
In a nutshell [`pulldown-cmark`][pulldown-cmark] is doing the heavy lifting.
Providing the core markdown service, via [`aurelius`][jason-aurelius]. Which in
turn provides the web/websocket interface. The `soma` executable is essentially
just wrapping [`aurelius`][jason-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.
[highlightjs]: https://highlightjs.org
[rustup]: https://rustup.rs
[pulldown-cmark]: https://github.com/raphlinus/pulldown-cmark
[katex]: https://katex.org
[aurelius]: https://github.com/euclio/aurelius
[jason-aurelius]: https://github.com/jasonm23/aurelius
[vmc]: https://github.com/euclio/vim-markdown-composer