Emacs 31: An Unofficial Guide to markdown-ts-mode

By Rahul M. Juliato — August 26, 2026

Introduction

With the arrival of Emacs 31, a wave of exciting new features has landed. Among these is the markdown-ts-mode, a Tree-sitter based approach to Markdown. Currently, this mode is classified as experimental.

This guide serves as a primer to get the mode operational and answer common setup questions. Because it is experimental, you must manually opt-in; consequently, you might encounter bugs, and the developers welcome your feedback.

What does it actually do?

Despite its "experimental" label, the feature set is robust. It supports:

• The full CommonMark specification.
• The majority of GitHub Flavored Markdown (GFM).
• Code blocks for non-ts-modes (e.g., elisp).
• Table of Contents (TOC) utilities.
• Integration with external tools like gfm and pandoc.

---

Getting Started: Installation & Setup

Since this isn't enabled by default, simply opening a .md file or running M-x markdown-ts-mode won't work immediately. You need to configure your init file.

Configuration Options

Depending on your preference, you can use use-package or standard Elisp.

Option A: Using use-package

(use-package markdown-ts-mode
  :ensure nil
  :mode ("\\.md\\'" "\\.mdx\\'" "\\.markdown\\'")
  :config
  (require 'markdown-ts-mode-x))

Option B: Standard Elisp

(autoload 'markdown-ts-mode "markdown-ts-mode" nil t)
(dolist (re '("\\.md\\'" "\\.mdx\\'" "\\.markdown\\'"))
  (add-to-list 'auto-mode-alist (cons re 'markdown-ts-mode)))
(with-eval-after-load 'markdown-ts-mode
  (require 'markdown-ts-mode-x))

Pro Tip: If you want to test this without altering your main config, save the code above into a file named testing.el and load it in a fresh emacs -Q session.

Warning: Do not attempt to install this via the MELPA repository.** The old MELPA repo is archived, lacks features, and will likely fail on Emacs 31. This mode is built-in.

---

Understanding Tree-sitter Grammars

If this is your first time using a -ts-mode, be aware that Tree-sitter requires external "grammars" to understand the structure of the text.

The Installation Flow

Markdown is unique because it requires two separate grammars:

1. The primary Markdown grammar.
2. An inline parsing grammar.

Troubleshooting Checklist

If the mode isn't working, check the following:

• Is your Emacs build compiled with the tree-sitter flag?
• Do you have essential build tools installed (gcc, make, etc.)?
• Is the tree-sitter-cli package installed on your OS? (Verify with tree-sitter --version).

While some users prefer pre-compiled grammars from their Linux distribution, this guide assumes you are building them yourself via Emacs.

---

Advanced Integration & Fontification

The true power of markdown-ts-mode is its ability to collaborate with other Tree-sitter modes. For example, many Markdown files start with YAML or TOML front-matter.

Consider this header:

---
title : The Official 'markdown-ts-mode.el' Feature Test File
author : Rahul Martim Juliato
date : 2026-03-18
version : $0.1.0$
parsers needed : markdown, markdown-inline, yaml, toml, html, c, javascript, python, ruby, rust
---

If the header above isn't colorful (fontified), you are missing the corresponding grammar. To fix this for YAML, run: M-x treesit-install-language-grammar $\rightarrow$ yaml

Handling Grammar Failures

Sometimes, the automatic registration fails. If Emacs doesn't suggest a source for the grammar, you can check the source code of the mode. For instance, in yaml-ts-mode.el, the expected source is defined as:

(add-to-list 'treesit-language-source-alist '(yaml "https://github.com/tree-sitter-grammars/tree-sitter-yaml"))

By ensuring all necessary grammars are installed, you can achieve a fully integrated, multi-language editing experience within a single Markdown document.