md-ts-mode is a tree-sitter-based major mode for editing Markdown.
It is derived from markdown-ts-mode in GNU Emacs 31 and works on
Emacs 29, 30, and 31.
- Syntax highlighting for headings (atx and setext), emphasis, strong
emphasis, strikethrough (
~~deleted~~; single tildes like~x~stay plain unlessmd-ts-strict-strikethroughis nil), code spans, links (inline, full reference, collapsed reference, shortcut), images, block quotes, list markers, and indented code blocks. - Task list markers (
[ ],[x]) rendered as checkbox glyphs (☐, ☑). - Thematic breaks (
---,***,___) rendered as horizontal rules sized to the narrowest visible window showing the same text. Setmd-ts-thematic-break-widthto a positive number for a fixed width, or to0to leave the Markdown characters visible. - Pipe tables with bold headers, subdued delimiter rows, and inline markup (emphasis, code, links) fontified inside cells.
- HTML blocks highlighted with
font-lock-doc-face. - Fenced code blocks fontified by the corresponding language grammar when available.
- YAML and TOML front matter fontified when their grammars are available.
- Hide-markup mode:
md-ts-toggle-hide-markuphides delimiters (#,*,~, brackets, link destinations) so only content is visible; visible link text remains activatable. - Imenu and
outline-minor-modeintegration via headings. - Custom faces:
md-ts-heading-1throughmd-ts-heading-6,md-ts-delimiter,md-ts-list-marker,md-ts-block-quote,md-ts-strikethrough,md-ts-language-keyword,md-ts-task-list-marker,md-ts-bare-link, andmd-ts-code.
md-ts-mode buttonizes supported Markdown links and images, resolved
reference links, reference-definition labels with destinations, URI
autolinks, email autolinks, and bare prose URLs, email addresses, and
supported mailto: forms.
Bare-link detection is prose-only and skips code, HTML tags/attributes
and HTML blocks, YAML/TOML front matter metadata, parsed-link/autolink,
and reference-definition contexts.
Use C-c C-o
(md-ts-open-link-at-point) to open the link at point; standard Emacs
button mouse/help-echo behavior applies.
Local and relative paths open with find-file, mailto: targets use
Emacs’ mailto handler, and other URI schemes use browse-url.
URI fragments in targets opened by browse-url are passed through.
Local/same-buffer fragment navigation is deferred: local paths such as
file.md#heading open only file.md, and fragment-only links such as
#heading are unsupported and signal an error for now. Escaped hashes
such as a\#b.md are literal filename characters.
- GNU Emacs 29.1 or later, built with tree-sitter support.
- A supported Emacs/libtree-sitter runtime combination:
- Emacs 29/30 with libtree-sitter 0.25.x.
- Emacs 31/development snapshots with libtree-sitter 0.25.x or 0.26.x.
Older distro runtimes such as 0.22 are not supported because they mis-handle disjoint parser ranges; Emacs 29/30 with libtree-sitter 0.26+ is not currently supported.
- Tree-sitter grammars:
markdownandmarkdown-inlinefrom tree-sitter-markdown (version 0.4.1 or compatible).
Install from MELPA:
M-x package-install RET md-ts-mode RET
Or with use-package:
(use-package md-ts-mode
:ensure t)If you do not already have MELPA configured, add this to your init file:
(require 'package)
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
(package-initialize)Installing or loading md-ts-mode does not change how Markdown files
are chosen globally. If you want md-ts-mode to handle Markdown
explicitly, add:
(md-ts-mode-enable-global)The helper is autoloaded and idempotent. On Emacs 31 it also prefers
md-ts-mode over the built-in markdown-ts-mode.
After loading md-ts-mode once, install the Markdown grammars:
M-x treesit-install-language-grammar RET markdown RET M-x treesit-install-language-grammar RET markdown-inline RET
If only part of a file is highlighted, one of the grammars is probably missing.
Fenced code blocks with a language tag (e.g., ```python) are
parsed and fontified by the corresponding language grammar.
Install the grammar for any language you want highlighted:
M-x treesit-install-language-grammar RET python RET
The variable md-ts-code-block-source-mode-map maps language
symbols to their tree-sitter major modes. The mode must be
installed and its grammar available for highlighting to work.
Run make check before sending changes. Test and smoke targets first
verify that the selected EMACS uses a supported libtree-sitter runtime when
ldd or otool -L can identify it; if a distro Emacs links to an older
runtime such as 0.22, use scripts/setup-tree-sitter-runtime.sh as shown by
the failure message. The runtime detector supports direct EMACS executables
and simple env VAR=... emacs forms; wrapper commands such as
EMACS="timeout 30 emacs" fail closed unless EMACS_BIN=/path/to/emacs
identifies the binary to inspect. Non-Linux setups that cannot be detected are
warned and allowed to continue. To bypass the preflight knowingly, set
SKIP_RUNTIME_CHECK=1 (or MD_TS_SKIP_RUNTIME_CHECK=1). make perf runs
advisory link fontification benchmarks; compare RESULT lines from runs on
the same machine rather than treating them as pass/fail thresholds. Benchmark
RESULT lines include tracked dirty/untracked state and link-artifact counts.
make perf-smoke validates the local grammar and link-artifact path only; CI,
not this smoke target, covers the supported runtime matrix.
The compatibility shims in md-ts-mode.el backport Emacs 31
tree-sitter range infrastructure to Emacs 29 and 30. This
includes replacements for treesit-range-fn-exclude-children,
treesit-query-range (with RANGE-FN argument),
treesit-range-rules (with :range-fn keyword and function-form
:embed), treesit-update-ranges, and
treesit--update-ranges-local.
On Emacs 29, additional shims provide treesit-node-children,
derived-mode-add-parents, and wrappers for C functions whose
signatures changed in Emacs 30 (treesit-parser-create,
treesit-parser-list).
On Emacs 31 all guards are false and no shims are defined.
Supported combinations are Emacs 29/30 with libtree-sitter 0.25.x, and
Emacs 31/development snapshots with libtree-sitter 0.25.x or 0.26.x.
CI probes libtree-sitter 0.25.10 on Emacs 29.4, 30.2, and snapshot, and
also probes libtree-sitter 0.26 on snapshot. CI intentionally does not
run against the GitHub image’s default tree-sitter runtime when it is
older than the 0.25 minimum. Emacs 29/30 with libtree-sitter 0.26+ is
not currently a supported combination for md-ts-mode, because upstream
Emacs only gained that runtime compatibility later.
Based on markdown-ts-mode from GNU Emacs 31, originally written
by Rahul Martim Juliato.