Marksman

Write Markdown with code assist and intelligence in the comfort of your favourite editor.

Marksman is a program that integrates with your editor to assist you in writing and maintaining your Markdown documents. Using LSP protocol it provides completion, goto definition, find references, rename refactoring, diagnostics, and more. In addition to regular Markdown, it also supports wiki-link-style references that enable Zettelkasten-like^{1, 2} note taking. See more about Marksman's features below.

Marksman works on MacOS, Linux, and Windows and is distributed as a self-contained binary for each OS.

The server provides assistance with:

• Markdown inline links:

  This is [inline link](/some-file.md#some-heading).
  This is an internal [anchor link](#heading).
  

• Markdown reference links:

  See [reference].
  
  [reference]: /url "Title"
  

• Wiki-links:

  Link to [[another-note]].
  Link to [[another-notes#heading]].
  Internal link to [[#a-heading]].
  

All types of links support completion, hover, goto definition/references. Additionally, Marksman provides diagnostics for wiki-links to detect broken references and duplicate/ambiguous headings.

Existing editor integrations³:

• VSCode via Marksman VSCode.

• Neovim:

  • via nvim-lsp-installer (automatic server installation),
  • via nvim-lspconfig,
  • via CoC-marksman.

• Emacs:

  • via LSP Mode (automatic server installation).

    Example config for use-package users:

    (use-package markdown-mode
      :hook (markdown-mode . lsp)
      :config
      (require 'lsp-marksman))
    

  • via Eglot, requires configuration (unless eglot#1013 gets merged); add the following to your init.el

    (add-to-list 'eglot-server-programs '(markdown-mode . ("marksman")))      
    (add-hook 'markdown-mode-hook #'eglot-ensure)
    

• Helix requires configuration (unless helix#3499 gets merged); add the following to your ~/.config/helix/languages.toml:

  [[language]]
  name = "markdown"
  scope = "source.md"
  injection-regex = "md|markdown"
  file-types = ["md"]
  roots = [".marksman.toml"]
  language-server = { command = "marksman", args=["server"] }
  indent = { tab-width = 2, unit = "  " }
  

• Sublime Text via LSP-marksman (automatic server installation).

How to install

Option 1: use pre-built binary

1. Go to Releases page: each release has pre-built binaries for Linux, MacOS, and Windows. Download the binary for your OS.
2. Rename the binary and make it executable:
   • MacOS: mv marksman-macos marksman && chmod +x marksman
   • Linux: mv marksman-linux marksman && chmod +x marksman
   • Windows: rename marksman-windows.exe to marksman.exe.
3. Place the binary somewhere in your PATH.
   • XDG recommends using $HOME/.local/bin/ (make sure this folder is in your PATH).

Option 2: build from source

0. Install Dotnet SDK for your OS.
1. Clone the repository: git clone https://github.com/artempyanykh/marksman.git
2. Inside marksman folder run make install
3. The binary will be installed under $HOME/.local/bin (make sure this folder is in your PATH).

Demo

Below is a mix of VSCode, Neovim, and Emacs screenshots. Although, not all features demonstrated for each editor, generally most features should work equaly in all editors.

• Document symbols:
• Hover preview:
• Completion:
  • 
  • 
• Find references:
• Project-wide diagnostics:
• Rename refactor for headings and reference links:

Features and plans

✅ - done; 🗓 - planned.

• ✅ Document symbols from headings.
• ✅ Workspace symbols from headings.
  • Query matching is subsequence-based, that is lsp will match both LSP and Low Seimic Profile.
• ✅ Completion for links (inline, reference, wiki).
• ✅ Hover prevew for links.
• ✅ "Go to definition" for links.
• ✅ "Find references" for headings and links.
• ✅ Diagnostics for wiki-links.
• ✅ Support multi-folder workspaces.
• ✅ Custom parser for more fine-grained note structure.
• 🗓 Code Lens with "# references" on headings.
• ✅ Rename refactor.
• 🗓 Add support for images (diagnostics, completion, goto).
• 🗓 Add "check" command for standalone workspace checking.
• 🗓 Add "build" command that rewrites all cross-references into proper relative markdown links for further embedding into a static site generator such as Jekyll or Hakyll.
• 🗓 Support for Jupyter notebooks.

Code actions

Table of Contents: Marksman has a code action to create and update a table of contents of a document.

Ignore files

Marksman by default reads ignore globs from .gitignore, .hgignore, and .ignore and doesn't scan directories matching any of the glob patterns.

NOTE: Marksman will only read top-level ignore files, or in other words ignore files at the root of your workspace folder. This is unlike Git which supports ignore files inside any project folder. If the lack of support for non top-level ignore files affects your workflow do open an issue.

Workspace folders and project roots

The LSP specification is designed to work with projects rather than individual files⁴. How a root folder of a project is found varies between editors, but usually it's either

1. a root of the version control system (applicable to all languages),
2. a folder with .marksman.toml marker file (specific to Marksman integrations).

Therefore, in case Marksman doesn't provide Markdown language assist for your files and you don't understand why, you can either:

1. check your project into version control, or
2. create a .marksman.toml at the root folder of your project, or
3. refer to your editor/LSP client documentation regarding how project root is defined.

Where's zeta-note and where's Rust?

After much deliberation, I've decided that it'd be cheaper for me to write a new from-scratch implementation of the language server in F# and add new features to it, than it is to add new features to the Rust version.

The original Rust implementation is archived in a separate repo. Further development will happen in this repository in F#.

[1]: You may have heard about Roam Research. This is a commercial implementation of the Zettelkasten method and another point of reference for what Marksman is about. However, unlike a proprietary Roam Research, Marksman is free, open-source and integrated into your favourite editor (albeit for not not as feature rich as Roam Research).

[2]: There is an excellent VSCode extension called Markdown Memo. You definitely need to check it out if you're primarily using VSCode as it has some features that are missing in Marksman and Marksman VSCode extension. However, Markdown Memo is VSCode specific while Marksman is a generic language server, so can be used with any editor that has LSP support: Emacs, Vim, Neovim, etc.

[3]: Since Marksman is a regular Language Server most of the functionality works out of the box with any LSP client.

[4]: There is an initiative to add a single-file mode to LSP but it's not a part of the spec at least until and including v3.17.