HN Debrief

Emacs 31: An unofficial guide to Markdown-ts-mode

  • Developer Tools
  • Programming
  • Open Source
  • AI

The post is an unofficial guide to `markdown-ts-mode`, the new built-in Markdown mode in Emacs 31. It explains how to enable it, what “ts” means, and why the mode is interesting at all: it uses tree-sitter for parsing, supports CommonMark and GitHub Flavored Markdown out of the box, and adds quality-of-life features without needing an external package. A small correction came up immediately: in Emacs 31, some people report Markdown files already opening in the new mode automatically, so parts of the opt-in setup may already be obsolete depending on how your install is configured.

If you run Emacs 31, it is worth testing `markdown-ts-mode` now because built-in Markdown support is getting good enough for everyday editing. But if your workflow depends on Org-style metadata, agendas, or structured outlines, treat Markdown as an interchange format, not a drop-in replacement.

Discussion mood

Positive about the new mode and about Emacs 31 making tree-sitter more usable, but mixed on vanilla Emacs defaults. The sharpest skepticism was reserved for the idea that Markdown can absorb Org mode’s job without turning into an incompatible pseudo-standard.

Key insights

  1. 01

    Org features need semantic structure

    Markdown can mimic Org only at the surface level. Org operates on a real tree with heading-level metadata, inherited properties, scheduling, subtree edits, and other semantics that CommonMark does not define, so any attempt to bolt those features onto Markdown ends up inventing a custom dialect like Logseq or Obsidian’s field conventions. That changes the file from portable Markdown into tool-specific markup with worse guarantees than Org inside Emacs.

    If you need agendas, refiling, subtree operations, or rich metadata, keep Org as the source of truth and export when needed. Building those semantics directly on Markdown will lock you into a house style anyway.

      Attribution:
    • iLemming #1 #2 #3
  2. 02

    Emacs 31 fixes much of the tree-sitter pain

    The stale complaint that users must manually chase down grammar repositories is no longer broadly true for Emacs 31. People report that grammar installation now defaults to asking before install, and that related built-in tooling like Eglot often works with zero config once a standard server such as `clangd` or `rust-analyzer` is on the machine. The rough edges are shifting from impossible setup to policy choices about how much Emacs should automate.

    Re-evaluate any opinion you formed on tree-sitter from Emacs 29 or 30. For team docs or internal setup guides, split advice by Emacs version because 31 materially changes the onboarding story.

      Attribution:
    • femiagbabiaka #1
    • tpmoney #1
    • chroma_zone #1
    • mplanchard #1
  3. 03

    Vanilla Emacs refuses to be an IDE distro

    The resistance to more automation is not just conservatism. It comes from a clear product boundary. Language servers, parser grammars, package registries, version managers, and OS-specific binaries all move on different schedules, and commenters argue that shipping a polished default for all of that would effectively turn Emacs into a distro that owns cross-platform dependency management. Vanilla Emacs deliberately stops short and leaves opinionated defaults to Doom Emacs, Spacemacs, and user configs.

    If you want a team-standard editor experience, start from an Emacs distribution or an internal starter config, not stock Emacs. Vanilla is a toolkit, so treating it like a preassembled IDE will create avoidable support work.

      Attribution:
    • BeetleB #1 #2 #3
    • KallDrexx #1
  4. 04

    AI coding workflows center on Magit review

    The concrete workflow people actually use is straightforward. Let an agent write code through Agent Shell, gptel, Ghostel, or a terminal session running Claude Code, then review and accept changes in Magit like a pull request. The key advantage is not that Emacs has one killer AI package. It is that code generation can plug into an editor with strong diffing, staging, and context-passing commands.

    When evaluating AI integrations in Emacs, optimize for review flow and file-change visibility first. Package choice matters less if the output lands in a Magit-centered approval loop.

      Attribution:
    • remedan #1
    • banjomonster #1
    • jwr #1
    • bryanlarsen #1
    • internet_points #1

Against the grain

  1. 01

    Rendered Markdown still beats syntax editing

    For people who mostly read Markdown, a richer parser is beside the point. A commenter said they stick with `markdown-modern` plus an Obsidian-style renderer because the win comes from better visual presentation, not from tree-sitter internals or editing commands.

    If your team consumes more Markdown than it authors, benchmark reader-focused packages and preview workflows before standardizing on parser-backed editing modes.

      Attribution:
    • rjprins #1
  2. 02

    Inline Markdown may already be faster

    One commenter questioned the whole premise of mode-assisted formatting for simple Markdown. If adding emphasis by typing literal markers takes fewer keystrokes than invoking editor commands, then the mode has to justify itself with folding, parsing, navigation, or rendering rather than with text insertion shortcuts.

    Do not sell `markdown-ts-mode` as a faster way to type `**bold**`. Its value is structural editing and correctness, so evaluate it on those terms.

      Attribution:
    • ggm #1
  3. 03

    Better plumbing does not fix Emacs onboarding

    A longtime user argued that even if tree-sitter setup improved in Emacs 31, the deeper problem remains unchanged. Too many shipped features still require hidden configuration knowledge, and that keeps Emacs hard to recommend to newcomers regardless of how good individual modes become.

    If you introduce Emacs to new hires, pair it with a curated setup and explicit onboarding docs. Pointing people at vanilla defaults will still lose many of them.

      Attribution:
    • dleslie #1

In plain english

Agent Shell ↩
An Emacs package for working with coding agents from within the editor, mentioned here as a front end for Claude Code.
clangd ↩
A language server that provides C and C++ code intelligence, usually backed by the Clang compiler tools.
Claude Code ↩
Anthropic’s coding-focused command-line agent tool, used here through Emacs integrations or terminal sessions.
CommonMark ↩
A formalized specification for Markdown intended to reduce differences between Markdown implementations.
Doom Emacs ↩
A curated Emacs distribution that ships with opinionated defaults, package choices, and configuration structure.
Eglot ↩
The built-in Emacs client for the Language Server Protocol, used to connect the editor to external language servers.
Ghostel ↩
An Emacs package mentioned as another interface for working with Claude Code or similar AI tools.
gptel ↩
An Emacs package for interacting with large language models from buffers and commands.
Logseq ↩
A note-taking and knowledge management tool that stores notes in plain text files, often using Markdown with extra conventions.
Magit ↩
A widely used Emacs interface for Git that makes reviewing, staging, and managing changes easier.
markdown-ts-mode ↩
A built-in Emacs 31 major mode for editing Markdown that uses tree-sitter for parsing and syntax-aware features.
Obsidian ↩
A Markdown-based note-taking application that stores notes as local files and supports plugins and custom metadata conventions.
Org mode ↩
An Emacs mode and document system for notes, outlines, tasks, scheduling, code blocks, and structured documents.
rust-analyzer ↩
A language server and tooling project for the Rust programming language.
Spacemacs ↩
An Emacs distribution that provides a preconfigured, feature-rich setup with its own conventions and defaults.
tree-sitter ↩
A parser generator and incremental parsing library used by editors to understand code or markup structure efficiently as you type.
ts ↩
Short for tree-sitter, a parsing system that builds syntax trees for source text so editors can provide more accurate highlighting and structural editing.

Reference links

Emacs tree-sitter and setup references

Markdown and Org interoperability

Markdown rendering tools

  • markdown-modern
    Mentioned as a preferred package for reading Markdown with better rendering, independent of tree-sitter.

AI coding in Emacs

  • agent-shell
    Frequently recommended as an Emacs interface for coding agents and local Claude Code workflows.
  • ghostel
    Suggested as an Emacs-based way to run Claude Code or similar tools through a terminal-like workflow.
  • ai-code-interface.el
    The package the questioner originally tried, which others said is not the common choice for Emacs AI coding workflows.

General reference

  • EMac
    Linked in a side conversation about iPhone autocorrect changing Emacs to eMacs.