Intro So, Emacs 31 has been released, and a lot of shiny new stuff is there, ready for us to play with. You probably heard of this new markdown-ts-mode and decided to check it out. And guess what? On Emacs version 31, this is marked as an experimental mode.

What does this mean? Should you use it or not? Is this ready? Is this just a sketch of a mode? Treat this post as a quick guide to getting this mode up and running and helping yourself find answers to these questions. Where is it in terms of features? This is an experimental mode, right? You need to opt in, so probably not everything will work flawlessly yet, and it needs more testing and feedback. That said, don't let this title mislead you.

This does not mean the mode is premature in terms of features. As you will see, this is a very feature-rich mode. This mode already covers all of the commonmark.org spec, as well as most of github.github.com/gfm/, with some extras like code blocks even for non-ts-modes, like elisp, table of contents utilities, and interfaces with external converters, such as pandoc and gfm.

Before deep diving into it yourself, you may need some help simply turning this mode on. Tree-sitter is tricky. It might even be your first time with tree-sitter, so a quick install guide is on our agenda.

Where is it? Do I need to install the mode? Experimental means Emacs does not enable the mode by default so it is not there waiting for you to simply open a .md file or call it with M-x markdown-ts-mode RET. You need to load this library. As always on Emacs, there's more than one way of doing everything, I am a big fan of use-package so I tend to use it to organize my init file.

Here is my suggested initial setup: (use-package markdown-ts-mode:ensure nil:mode ("\.md\'" "\.mdx\'" "\.markdown\'"):config(require 'markdown-ts-mode-x)) Or if you keep use-package out of your tool belt: (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)) Now both the mode and the x (nice extra goodies) libraries are loaded, and you can simply visit your Markdown files using it. If you want to experiment with it without touching your own configuration, do the following: Save the above content in a file like testing.el. Call emacs with emacs -Q --load 'testing.el'.

And there you have it, a bare Emacs session with your testing ground set up. This is what I will use for the rest of this guide. IMPORTANT: there's NO NEED to download or add this package to your package manager.

The (now very old and archived) MELPA Repository will refuse to install on Emacs version 31 onward and is very, very poor in terms of features. If you are using this, you're not using the new built-in markdown-ts-mode. Right? Let's continue.

Opening our first markdown file In order for you to see what I see, we need some pictures. If it is the first time you're using a tree-sitter-based mode, let me warn you: although tree-sitter is wonderful, fast, and feature-rich, it comes with its own set of tasks to complete and perhaps debugging skills if it needs help. I will try to cover some here; I will forget others for sure.

For this guide, I will be using this test file. The repository where it is hosted is our laboratory. No code lies there, remember, all code is in Emacs itself.

Now go ahead and open the test.md file. IMPORTANT: At this point, many things can happen. If you have the grammar for markdown installed in your system, the file is already opened.

You could, though, be prompted, as I am here, with this: It means Emacs hasn't found a grammar for markdown in my system, in this case in ~/.emacs.d/tree-sitter/ (which is the default when I start Emacs with emacs -Q ...). Emacs will offer to install it, which means downloading and compiling it from a repository already defined in markdown-ts-mode's source code. Let's install it with y.

Emacs will clone the g...