Skip to content

About

A Emacs major mode for Markdown, powered by tree-sitter, works on Emacs 29+

Resources

Stars

11 stars

Watchers

0 watching

Forks

Latest commit

 

History

22 Commits

Folders and files

Repository files navigation

md-ts-mode

MELPA Tests melpazoid

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.

Features

  • Syntax highlighting for headings (atx and setext), emphasis, strong emphasis, strikethrough (~~deleted~~; single tildes like ~x~ stay plain unless md-ts-strict-strikethrough is 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. Set md-ts-thematic-break-width to a positive number for a fixed width, or to 0 to 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-markup hides delimiters (#, *, ~, brackets, link destinations) so only content is visible; visible link text remains activatable.
  • Imenu and outline-minor-mode integration via headings.
  • Custom faces: md-ts-heading-1 through md-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, and md-ts-code.

Opening links

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.

Requirements

  • 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: markdown and markdown-inline from tree-sitter-markdown (version 0.4.1 or compatible).

Installation

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.

Install tree-sitter grammars

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.

Embedded code blocks

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.

Development

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.

Compatibility

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.

Acknowledgments

Based on markdown-ts-mode from GNU Emacs 31, originally written by Rahul Martim Juliato.

About

A Emacs major mode for Markdown, powered by tree-sitter, works on Emacs 29+

Resources

Stars

11 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages