Markdown Preview Language Server

Built using GLSP and Goldmark,
and heavily inspired by mdpls
Overview
Markdown Preview Language Server (mpls) is a language server designed to
enhance your Markdown editing experience. With live preview in the browser,
mpls allows you to see your Markdown content rendered in real-time. Whether
you're writing documentation or creating notes, mpls provides a seamless and
interactive environment.
Built with terminal editors in mind, such as (Neo)vim and Helix, which do not have
built-in Markdown rendering, mpls bridges the gap by providing a live preview
feature that works alongside these editors. Additionally, mpls is compatible
with any editor that supports the Language Server Protocol (LSP), making it a
versatile tool for Markdown editing across various platforms.
Features
- Live Preview: Instantly see your Markdown changes reflected in the browser.
Built with Goldmark
mpls is built using Goldmark, a Markdown
parser written in Go. Goldmark is known for its extensibility and performance,
making it an ideal choice for mpls.
Goldmark extensions
mpls utilizes several of Goldmark's extensions to enhance the Markdown rendering
experience:
- Github Flavored Markdown: Goldmark's built in GFM extension ensures Table,
Strikethrough, Linkify and TaskList elements are displayed correctly.
- Syntax highlighting: The
highlighting extension adds
syntax-highlighting to the fenced code blocks.
- Image Rendering: The img64
extension allows for seamless integration of images within your Markdown
files.
- Math Rendering: The katex
extension enables the rendering of LaTeX-style mathematical expressions using
KaTeX, providing a clear and professional presentation of equations.
Mermaid
mpls supports the display of diagrams and flowcharts by integrating
Mermaid.js, a powerful JavaScript library for
generating diagrams from text definitions.
Install
The easiest way to install mpls is to download one of the prebuilt
release binaries. You can find the latest releases on the Releases
page.
mpls uses CGO, which complicates cross-compiling. Therefore, for now, there
are only prebuilt binaries available for Linux/amd64.
-
Download the appropriate tar.gz file for your operating system.
-
Extract the contents of the tar.gz file. You can do this using the following
command in your terminal:
tar -xzf mpls_<version>_linux_amd64.tar.gz
(Replace <version> with the actual version of the release.)
-
Copy the extracted binary to a directory that is in your system's PATH. For example:
sudo cp mpls /usr/local/bin/
Build From Source
If you prefer to build from source or if no prebuilt binaries are available for
your architecture, follow these steps:
-
Clone the repository:
git clone https://github.com/mhersson/mpls.git
cd mpls
-
Build the project:
You can build the project using the following command:
make build
This will compile the source code and create an executable.
-
Install the executable:
You have two options to install the executable:
-
Option 1: Copy the executable to your PATH:
After building, you can manually copy the executable to a directory that is in your system's PATH. For example:
sudo cp mpls /usr/local/bin/
-
Option 2: Use make install if you are using GOPATH:
If the GOPATH is in your PATH, you can run:
make install
This will install the executable to your $GOPATH/bin directory.
Verify the installation:
After installation, you can verify that mpls is installed correctly by running:
mpls --version
This should display the version of the mpls executable.
Command-Line Options
The following options can be used when starting mpls:
| Flag |
Description |
--no-auto |
Don't open preview automatically |
--code-style |
Sets the style for syntax highlighting in fenced code blocks. (1) |
--full-sync |
Sync the entire document for every change being made. (2) |
--version |
Displays the mpls version. |
--help |
Displays help information about the available options. |
- The goldmark-highlighting extension use
Chroma as the syntax highlighter, so
all available styles in Chroma are available here. Default style is
catppuccin-mocha.
- Has a small impact on performance, but makes sure that commands like
reflow in Helix, does not impact the accuracy of the preview.
Additionally, it disables mpls' efforts to scroll to the closest section
header when editing.
Configuration examples
Helix
languages.toml
# Configured to run alongside marksman.
[[language]]
auto-format = true
language-servers = ["marksman", "mpls"]
name = "markdown"
[language-server.mpls]
command = "mpls"
Neovim (LazyVim)
lua/plugins/mpls.lua
return {
{
"neovim/nvim-lspconfig",
opts = {
servers = {
mpls = {},
},
setup = {
mpls = function(_, opts)
local lspconfig = require("lspconfig")
local configs = require("lspconfig.configs")
local util = require("lspconfig.util")
if not configs.mpls then
configs.mpls = {
default_config = {
cmd = {"mpls"},
filetypes = {"markdown"},
single_file_support = true,
root_dir = require("lspconfig").util.find_git_ancestor,
settings = {},
},
docs = {
description = [[https://github.com/mhersson/mpls
Markdown Preview Language Server (MPLS) is a language server that provides
live preview of markdown files in your browser while you edit them in your favorite editor.
]],
},
}
end
lspconfig.mpls.setup(opts)
end,
},
},
},
}
Doom-Emacs with lsp-mode
config.el
(after! markdown-mode
;; Auto start
(add-hook 'markdown-mode-local-vars-hook #'lsp!))
(after! lsp-mode
(defgroup lsp-mpls nil
"Settings for the mpls language server client."
:group 'lsp-mode
:link '(url-link "https://github.com/mhersson/mpls"))
(defcustom lsp-mpls-server-command "mpls"
"The binary (or full path to binary) which executes the server."
:type 'string
:group 'lsp-mpls)
(lsp-register-client
(make-lsp-client :new-connection (lsp-stdio-connection
(lambda ()
(or (executable-find lsp-mpls-server-command)
(lsp-package-path 'mpls)
"mpls")
))
:activation-fn (lsp-activate-on "markdown")
:initialized-fn (lambda (workspace)
(with-lsp-workspace workspace
(lsp--set-configuration
(lsp-configuration-section "mpls"))
))
;; Priority and add-on? are not needed,
;; but makes mpls work alongside other lsp servers like marksman
:priority 1
:add-on? t
:server-id 'mpls)))