GNU bug report logs - #80127
31.0.50; Eglot: add markdown-ts-mode support to documentation

Previous Next

To reply to this bug, email your comments to 80127 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 31.0.50; Eglot: add markdown-ts-mode support to documentation
Date: Sun, 04 Jan 2026 03:20:09 -0300

[Message part 1 (text/plain, inline)]

Hi all,

I was wondering if it would be possible to get the new
`markdown-ts-mode` to render documentation provided by Eglot. This would
allow nice syntax highlighting in Emacs "out of the box".

This patch introduces a new user option, `eglot-markdown-renderers`,
which allows users to specify a list of preferred Markdown rendering
functions. Eglot will use the first renderer that is available, falling
back to plain text if none are present. I kept the current default:
`gfm-view-mode` first, `markdown-ts-mode` next. Users might want to
invert the order.

Notice that `markdown-ts-mode` is a bit more limited in what it can
render and prettify compared to `gfm-view-mode`, but it is still a nice
addition out of the box. This will probably improve over time with new
`markdown-ts-mode` options.

Additionally, `markdown-ts-mode` is only enabled when Emacs was compiled
with Tree-sitter support.

I have only tested this patch on Emacs master, but I believe it handles
older Emacs/Eglot versions gracefully by checking for `markdown-ts-mode`
availability before using it.

Please see the attached patch.

[0001-Eglot-configurable-Markdown-rendering-with-Tree-sitt.patch (text/x-patch, attachment)]

Message #8 received at 80127 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Rahul Martim Juliato <rahuljuliato <at> gmail.com>,
 João Távora <joaotavora <at> gmail.com>
Cc: 80127 <at> debbugs.gnu.org
Subject: Re: bug#80127: 31.0.50;
 Eglot: add markdown-ts-mode support to documentation
Date: Sun, 04 Jan 2026 09:05:52 +0200

> From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
> Date: Sun, 04 Jan 2026 03:20:09 -0300
> 
> I was wondering if it would be possible to get the new
> `markdown-ts-mode` to render documentation provided by Eglot. This would
> allow nice syntax highlighting in Emacs "out of the box".
> 
> This patch introduces a new user option, `eglot-markdown-renderers`,
> which allows users to specify a list of preferred Markdown rendering
> functions. Eglot will use the first renderer that is available, falling
> back to plain text if none are present. I kept the current default:
> `gfm-view-mode` first, `markdown-ts-mode` next. Users might want to
> invert the order.
> 
> Notice that `markdown-ts-mode` is a bit more limited in what it can
> render and prettify compared to `gfm-view-mode`, but it is still a nice
> addition out of the box. This will probably improve over time with new
> `markdown-ts-mode` options.
> 
> Additionally, `markdown-ts-mode` is only enabled when Emacs was compiled
> with Tree-sitter support.
> 
> I have only tested this patch on Emacs master, but I believe it handles
> older Emacs/Eglot versions gracefully by checking for `markdown-ts-mode`
> availability before using it.
> 
> Please see the attached patch.

Thanks.

However, I thought Eglot already supported markdown-mode for this
purpose?  And if it indeed does, then using major-mode-remap-alist to
redirect markdown-mode to markdown-ts-mode is all one needs to get
Eglot to use markdown-ts-mode instead of markdown-mode for rendering,
I think.

If that somehow doesn't work, could you please tell the details and
show a recipe for reproducing the problem?

Message #11 received at 80127 <at> debbugs.gnu.org (full text, mbox):

From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Rahul Martim Juliato <rahuljuliato <at> gmail.com>, 80127 <at> debbugs.gnu.org,
 João Távora <joaotavora <at> gmail.com>
Subject: Re: bug#80127: 31.0.50; Eglot: add markdown-ts-mode support to
 documentation
Date: Tue, 6 Jan 2026 20:18:25 -0300

On Sun 04 Jan 09:05, Eli Zaretskii wrote:
> > From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
> > Date: Sun, 04 Jan 2026 03:20:09 -0300
> > 
> > I was wondering if it would be possible to get the new
> > `markdown-ts-mode` to render documentation provided by Eglot. This would
> > allow nice syntax highlighting in Emacs "out of the box".
> > 
> > This patch introduces a new user option, `eglot-markdown-renderers`,
> > which allows users to specify a list of preferred Markdown rendering
> > functions. Eglot will use the first renderer that is available, falling
> > back to plain text if none are present. I kept the current default:
> > `gfm-view-mode` first, `markdown-ts-mode` next. Users might want to
> > invert the order.
> > 
> > Notice that `markdown-ts-mode` is a bit more limited in what it can
> > render and prettify compared to `gfm-view-mode`, but it is still a nice
> > addition out of the box. This will probably improve over time with new
> > `markdown-ts-mode` options.
> > 
> > Additionally, `markdown-ts-mode` is only enabled when Emacs was compiled
> > with Tree-sitter support.
> > 
> > I have only tested this patch on Emacs master, but I believe it handles
> > older Emacs/Eglot versions gracefully by checking for `markdown-ts-mode`
> > availability before using it.
> > 
> > Please see the attached patch.
> 
> Thanks.
> 
> However, I thought Eglot already supported markdown-mode for this
> purpose?  And if it indeed does, then using major-mode-remap-alist to
> redirect markdown-mode to markdown-ts-mode is all one needs to get
> Eglot to use markdown-ts-mode instead of markdown-mode for rendering,
> I think.
> 
> If that somehow doesn't work, could you please tell the details and
> show a recipe for reproducing the problem?


Hi Eli,

Thanks for the reply!

You're right that Eglot already supports rendering Markdown via
`markdown-mode`, let me try to explain this a bit further and why I took
this route.

The motivation for this patch comes from a bit of history and from a
slightly different angle.

This request actually started earlier in bug#77856
(https://debbugs.gnu.org/cgi/bugreport.cgi?bug=77856), where I initially
proposed adding `markdown-ts-mode` support to Eglot's documentation
rendering. I unfortunately muddied that thread by reporting an unrelated
Flymake/Eldoc bug while experimenting with a prototype, which led to
some confusion (entirely my fault). Since that discussion never quite
got to focus cleanly on *just* Markdown rendering, I decided to open a
new bug and patch dedicated solely to this feature, consider this my
second attempt at "doing it properly".

Regarding `major-mode-remap-alist`, the specific use case I'm trying to
address is Emacs setups that do not use third-party Markdown packages at
all (or cannot, for policy or packaging reasons), and instead rely only
on what Emacs provides out of the box. I also admit it hadn't occurred
to me earlier that remapping could be leveraged here.

With `markdown-ts-mode` now built-in, Eglot documentation currently
falls back to plain text in the setups mentioned above, which is a
noticeable regression in user experience compared to having *some*
structured rendering. Even if `markdown-ts-mode` is currently less
feature-rich than `gfm-view-mode` (which usually comes with
`markdown-mode`), highlighted code blocks and basic structure are, in my
experience, a significant improvement over raw text.

Additionally, Eglot depends on `gfm-view-mode` (provided by
`markdown-mode`) being available in order to even request Markdown
formatted documentation from the LSP server, otherwise defaulting to
plain text. Since this negotiation happens before rendering, this is why
I suspect that remapping alone wouldn't work as intended in this case.

The intent of the patch is therefore not to replace existing workflows,
but to make Eglot "do the best it can" automatically:

* use `gfm-view-mode` when available,
* otherwise use `markdown-ts-mode` when Tree-sitter support exists,
* and only fall back to plain text as a last resort.

I tried to keep this conservative and backwards-compatible, with
explicit availability checks and no behavior change for users already
using `markdown-mode`.

At this point, I'd also very much welcome guidance from João on whether
this direction aligns with Eglot's design expectations, or if there's a
preferred approach I may be missing. I'm happy to adjust the patch if
there's a cleaner or more idiomatic solution.

Thanks again for taking the time to look at this, and apologies for the
earlier confusion.

-- 
Rahul Martim Juliato

Message #14 received at 80127 <at> debbugs.gnu.org (full text, mbox):

From: João Távora <joaotavora <at> gmail.com>
To: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 80127 <at> debbugs.gnu.org
Subject: Re: bug#80127: 31.0.50; Eglot: add markdown-ts-mode support to
 documentation
Date: Tue, 06 Jan 2026 23:48:49 +0000

Rahul Martim Juliato <rahuljuliato <at> gmail.com> writes:

> On Sun 04 Jan 09:05, Eli Zaretskii wrote:
>> > From: Rahul Martim Juliato <rahuljuliato <at> gmail.com>
>> > Date: Sun, 04 Jan 2026 03:20:09 -0300
>> > 
>> > I was wondering if it would be possible to get the new
>> > `markdown-ts-mode` to render documentation provided by Eglot. This would
>> > allow nice syntax highlighting in Emacs "out of the box".
>> > 
>> > This patch introduces a new user option, `eglot-markdown-renderers`,
>> > which allows users to specify a list of preferred Markdown rendering
>> > functions. Eglot will use the first renderer that is available, falling
>> > back to plain text if none are present. I kept the current default:
>> > `gfm-view-mode` first, `markdown-ts-mode` next. Users might want to
>> > invert the order.
>> > 
>> > Notice that `markdown-ts-mode` is a bit more limited in what it can
>> > render and prettify compared to `gfm-view-mode`, but it is still a nice
>> > addition out of the box. This will probably improve over time with new
>> > `markdown-ts-mode` options.
>> > 
>> > Additionally, `markdown-ts-mode` is only enabled when Emacs was compiled
>> > with Tree-sitter support.
>> > 
>> > I have only tested this patch on Emacs master, but I believe it handles
>> > older Emacs/Eglot versions gracefully by checking for `markdown-ts-mode`
>> > availability before using it.
>> > 
>> > Please see the attached patch.
>> 
>> Thanks.
>> 
>> However, I thought Eglot already supported markdown-mode for this
>> purpose?  And if it indeed does, then using major-mode-remap-alist to
>> redirect markdown-mode to markdown-ts-mode is all one needs to get
>> Eglot to use markdown-ts-mode instead of markdown-mode for rendering,
>> I think.
>> 
>> If that somehow doesn't work, could you please tell the details and
>> show a recipe for reproducing the problem?
>
>
> Hi Eli,
>
> Thanks for the reply!
>
> You're right that Eglot already supports rendering Markdown via
> `markdown-mode`, let me try to explain this a bit further and why I took
> this route.
>
> The motivation for this patch comes from a bit of history and from a
> slightly different angle.
>
> This request actually started earlier in bug#77856
> (https://debbugs.gnu.org/cgi/bugreport.cgi?bug=77856), where I initially
> proposed adding `markdown-ts-mode` support to Eglot's documentation
> rendering. I unfortunately muddied that thread by reporting an unrelated
> Flymake/Eldoc bug while experimenting with a prototype, which led to
> some confusion (entirely my fault). Since that discussion never quite
> got to focus cleanly on *just* Markdown rendering, I decided to open a
> new bug and patch dedicated solely to this feature, consider this my
> second attempt at "doing it properly".

Hi Rahul,

I've tried your code and like I said before I very much support this.
It's good if decent markdown rendering can be obtained with just Emacs
and nothing else.  Also markdown-ts-mode is a much simpler beast than
markdown.el, likely faster, and that is definitely appreciated.  See a
simpler patch at the end of my sig.

- No defcustom (we don't need it yet)

- Actually checks if the markdown grammar is available, maybe
  treesit-language-available-p would be better for this (why?), but I'm
  afraid it might be a bit too heavy to call repeatedly in tight loops.

Other than that, I put gfm-view-mode as having priority over
markdown-ts-mode (like you did) mainly markdown-ts-mode isn't quite a
"view" mode like gfm-view-mode.  That modes uses invisibility specs for
uninteresting artifacts like '```' .  Wonder if markdown-ts-mode could
grow those abilities, either with a derived mode or by binding some
variables around the call to the mode function.

João

diff --git a/lisp/progmodes/eglot.el b/lisp/progmodes/eglot.el
index 00f549937d5..2f431b5b288 100644
--- a/lisp/progmodes/eglot.el
+++ b/lisp/progmodes/eglot.el
@@ -714,8 +714,12 @@ eglot--executable-find
     (executable-find command)))
 
 (defun eglot--accepted-formats ()
-  (if (and (not eglot-prefer-plaintext) (fboundp 'gfm-view-mode))
-      ["markdown" "plaintext"] ["plaintext"]))
+  (if (and (not eglot-prefer-plaintext)
+           (or (fboundp 'gfm-view-mode)
+               (and (fboundp 'markdown-ts-mode)
+                    (treesit-grammar-location 'markdown))))
+      ["markdown" "plaintext"]
+    ["plaintext"]))
 
 (defconst eglot--uri-path-allowed-chars
   (let ((vec (copy-sequence url-path-allowed-chars)))
@@ -2092,23 +2096,30 @@ eglot--format-markup
   "Format MARKUP according to LSP's spec.
 MARKUP is either an LSP MarkedString or MarkupContent object."
   (let (string render-mode language)
-    (cond ((stringp markup)
-           (setq string markup
-                 render-mode (or mode 'gfm-view-mode)))
-          ((setq language (plist-get markup :language))
-           ;; Deprecated MarkedString
-           (setq string (concat "```" language "\n"
-                                (plist-get markup :value) "\n```")
-                 render-mode (or mode 'gfm-view-mode)))
-          (t
-           ;; MarkupContent
-           (setq string (plist-get markup :value)
-                 render-mode
-                 (or mode
-                     (pcase (plist-get markup :kind)
-                       ("markdown" 'gfm-view-mode)
-                       ("plaintext" 'text-mode)
-                       (_ major-mode))))))
+    (let ((md-renderer
+           (cond ((and (fboundp 'markdown-ts-mode)
+                       (treesit-grammar-location 'markdown))
+                  'markdown-ts-mode)
+                 ((fboundp 'gfm-view-mode)
+                  'gfm-view-mode)
+                 (t 'text-mode))))
+      (cond ((stringp markup)
+             (setq string markup
+                   render-mode (or mode md-renderer)))
+            ((setq language (plist-get markup :language))
+             ;; Deprecated MarkedString
+             (setq string (concat "```" language "\n"
+                                  (plist-get markup :value) "\n```")
+                   render-mode (or mode md-renderer)))
+            (t
+             ;; MarkupContent
+             (setq string (plist-get markup :value)
+                   render-mode
+                   (or mode
+                       (pcase (plist-get markup :kind)
+                         ("markdown" md-renderer)
+                         ("plaintext" 'text-mode)
+                         (_ major-mode)))))))
     (with-temp-buffer
       (setq-local markdown-fontify-code-blocks-natively t)
       (insert string)

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.