There was just one problem, and it nagged at me for years: editing AsciiDoc in Emacs was never much fun.
For years the only real option was adoc-mode, and it was showing its age. The font-locking was uneven, it predated modern Asciidoctor syntax, and it lagged far behind what markdown-mode (and org-mode) offered. So I’d catch myself reaching for Markdown in situations where AsciiDoc was clearly the better tool – not because Markdown was better, but because markdown-mode was. That always bugged me.
Eventually the itch got bad enough that I did something about it. Back in 2023 I took over maintenance of adoc-mode, which had been dormant for years, and set myself a clear goal: get it to feature parity with markdown-mode. More recently I also started a brand-new asciidoc-mode built on top of tree-sitter. The target for both is the same – AsciiDoc support in Emacs that’s on par with Markdown, and ideally not far off from Org.
Why two modes? They scratch slightly different itches:
adoc-mode is the classic, regexp-based mode. It works on any reasonably modern Emacs, has no external dependencies, and now ships a pile of interactive features (markup commands, list editing, image preview, tempo templates).asciidoc-mode is the newer, tree-sitter-based mode. It leans on a real grammar for robust, accurate highlighting and good performance in large documents. It’s leaner by design, and it needs Emacs 30.1+ with tree-sitter.1If you want the kitchen sink on any Emacs, reach for adoc-mode. If you’re on a recent Emacs and want highlighting backed by an actual parser, try asciidoc-mode. Pick whichever fits your setup – both are actively maintained.
I’ve spent a good chunk of the past month bringing both modes to a place I’m genuinely happy with, and they’re now mostly feature-complete as far as I’m concerned. Some highlights:
+text+ and ++text++ are treated as passthroughs rather than monospace, curved-quote syntax ("`text`") is recognized, the block ID shorthand [#id] is supported, checklists are highlighted, and the menus and templates dropped a bunch of deprecated AsciiDoc.py leftovers.markdown-mode and org-mode: bold renders as plain bold, emphasis as plain italic, structural markup (delimiters, list markers) fades into the background, and dedicated semantic faces cover metadata, URLs, footnotes, highlights, and roles. Switching between Markdown and AsciiDoc no longer feels jarring.xref backend over anchors, context-aware completion, and – for adoc-mode – cross-file Antora cross-reference resolution.[source,LANG] blocks in asciidoc-mode are highlighted using the language’s own major mode, just like in markdown-mode and org-mode. adoc-mode had added support for this a while back.Getting asciidoc-mode where I wanted it also meant sending a few fixes upstream to the tree-sitter-asciidoc grammar it builds on. A grammar-backed mode is only as good as its grammar, so some of the work happened a layer below Emacs. If you’re curious about that side of things, I wrote up the broader experience in building Emacs major modes with Tree-sitter.
If you’ve been avoiding AsciiDoc in Emacs because the tooling wasn’t there – I get it, that was me too. But the situation is genuinely different now. Grab adoc-mode or asciidoc-mode, point it at one of your .adoc files, and see how it feels.
And please share your feedback. Both projects are at the stage where real-world usage surfaces the rough edges I can’t see myself. Bug reports, ideas, and PRs are all very welcome on the respective issue trackers.
Together we can make AsciiDoc a first-class citizen of the Emacs ecosystem!2
That’s all from me, folks! Keep hacking!
Also, I really wanted to name something asciidoc-mode. ↩︎
Afterwards we’ll aim for world domination, of course. ↩︎
If you’ve been around Clojure long enough, you remember the chatter. Socket REPL landed in Clojure 1.8 (January 2016), prepl in Clojure 1.10 (December 2018), and for a couple of years there was a steady stream of posts, tweets, and Slack threads to the effect of “this is what we should be building tools on. nREPL is on the way out.” Some serious people put their weight behind that idea, and some of them went and built tools to prove it.
Now it’s 2026 and we can take stock.
The pitch was good. Socket REPL is just the Clojure REPL exposed on a TCP port. prepl wraps it with a structured printer so the bytes coming back are EDN-tagged maps (:ret, :out, :err, :tap) instead of a human-readable prompt. Both ship with Clojure itself. No external server library, no middleware, no third-party namespaces. You start a JVM, you bind a port, you’re done.
The intellectual case for moving off nREPL had been made by Rich Hickey himself, most clearly in a March 2015 clojure-dev post that’s worth reading in full. Rich didn’t actually attack nREPL by name in that message. What he did was argue carefully for what a REPL is: a thing that reads characters, evaluates forms, prints results, and loops, with those streams available to user code so that things like nested REPLs and debuggers compose naturally. The money line:
While framing and RPC orientation might make things easier for someone who just wants to implement an eval window, it makes the resulting service strictly less powerful than a REPL.
His proposal, in the same post, was that tools should open multiple connections to the running program: one for the human-facing stream, and dedicated channels for IDE operations. The socket REPL (which landed in 1.8 the following January) and prepl (which arrived in 1.10) were the official implementation of that worldview.
A handful of editor projects took the cue and built clients:
unrepl, propel, and friendsIt was real momentum. If you were following Clojure tooling in 2018-2020, it genuinely felt like nREPL might be the past, and the future would be some combination of socket REPL plus a thin self-installing protocol on top of it. You can find a fair number of “RIP nREPL” hot takes from that period if you go looking.
I went and surveyed each of those projects recently while working on Port. The pattern is depressingly consistent:
Tutkain started on prepl. In November 2021, its v0.11 release explicitly stopped using prepl message framing and switched to a hand-rolled EDN-RPC protocol that Tutkain boots onto the raw socket REPL by sending it a base64-encoded blob. The new protocol has request ids, op dispatch (:eval, :lookup, :completions, :test, :apropos, :interrupt, …), and server-managed thread bindings. In other words: Tutkain grew into nREPL, just spelled differently.
Chlorine never used prepl directly. It used socket REPL plus an unrepl-style upgrade blob. Its author’s successor project, Lazuli, abandoned the whole approach in favor of nREPL. The post-mortem is worth reading and is fairly blunt: tools that attempted prepl went back to nREPL because, honestly, it’s simply better.
Conjure had a prepl client in its early Rust days. The current Lua/Fennel rewrite ships only an nREPL client. The author’s reasoning in the release notes was that nREPL “has complete ecosystem adoption and brilliant ClojureScript support.”
Clojure-Sublimed technically still talks to a raw socket REPL, but only after sending it an EDN-printing prelude that upgrades the REPL to a structured protocol of tonsky’s own design. His post on the topic is one of the most thoughtful pieces I’ve read on Clojure REPL design, and his conclusion is roughly: the bare socket REPL is more useful than prepl because you can install your own protocol on top of it. Which is true. But notice that everyone who reached that conclusion ended up reinventing the same wheel: ids, ops, request/response correlation, completion support, lookup, interrupts. You know, the things nREPL has had since 2010.
So the trajectory looks roughly like this:
Pure prepl clients are nearly extinct in the wild. The one I found that qualifies is propel by Oliver Caldwell (of Conjure fame), which is delightful, about 70 lines of Clojure, and explicitly synchronous (one outstanding eval at a time). That works! But it’s not a foundation for the kind of feature set people expect from an editor.
Here’s where I land. Rich isn’t wrong that prepl is closer to a “real” REPL in the strict sense. prepl genuinely is a more faithful encoding of read-eval-print: each form goes in, each result comes out, and the semantics match what you’d get at the standard REPL prompt.
The thing is, “real REPL” is not the property you optimize for when you’re building editor tooling. The properties editor tooling actually needs are:
nREPL was explicitly designed for those properties. The ops, middleware, and transport abstractions exist precisely because the people building it knew the consumers are not humans typing at a prompt, they’re programs negotiating a session.
Calling nREPL “not a real REPL” is technically defensible and practically beside the point. Nobody on the consuming end is confused about what nREPL is for.
I wrote about nREPL’s revival in 2018. At that point I had just finished migrating the project out of Clojure Contrib, and the goal was to give it a real home and a working development process. It was a lot of work, but in hindsight things played out pretty well.
Looking at where things ended up:
bb and you get an nREPL server, no extra dependencies. That’s how a lot of people use nREPL in scripting contexts today, and it’s been a hit.cider-nrepl, refactor-nrepl, piggieback, sayid, drawbridge, …) is alive, well, and continues to add features.Meanwhile prepl is, as best as I can tell, mostly a curiosity. It got me a side project I had fun with. It did not displace nREPL.
The history of tooling protocols is full of cases where “purer”, “simpler”, or “more elegant” lost to “shipped, documented, and battle-tested.” LSP beat fifteen ad-hoc language protocols. DAP beat the same fifteen debuggers. nREPL beat prepl in the (Clojure) editor space.
It’s not that the simpler thing is bad. prepl is a fine, elegant little protocol, and there’s a real case for embedding it in CI scripts, ops automation, deployment pipelines, or anywhere you want to drive a Clojure VM programmatically without pulling in a server library. Use it there.
But for editor tooling? The Clojure community made an enormous, multi-year, multi-tool investment in nREPL. We have the protocol, the middleware, the manual, the books, the conference talks. nREPL works, it’s actively maintained, it’s increasingly portable across Clojure dialects, and the design decisions that Rich called out as un-REPL-like are the exact ones that make it a good substrate for editors.
So I’ll say what I felt awkward saying back in 2018: nREPL forever. It’s the right abstraction for the job, and it’s not going anywhere.
One more thing. After finishing Port I got curious what a minimal nREPL client would look like by comparison, so I went and built one. As you can imagine, it turned out to be significantly simpler. If that sounds interesting, take a look at neat, a small, language-agnostic nREPL client for Emacs.
Keep hacking!
]]>I think I’ll take my REPL neat
My parens black and my bed at three
CIDER’s too sweet for me…
– Bozier
Last week I announced Port, a small prepl client for Emacs. Today I’m following it up with another small Emacs package. Meet neat, a tiny, deliberately language-agnostic nREPL client.
For years I’ve been hearing some version of the same request: “could CIDER work with my non-Clojure nREPL server?”. Babashka, Basilisp, nREPL-CLR, even some homegrown servers people built on top of nREPL for languages I’d never heard of.1 The answer was always the same kind of squishy “sort of, in theory, with caveats”, because while bare nREPL is genuinely language-agnostic, CIDER is not. CIDER was built for Clojure and assumes Clojure pretty much everywhere.
I always thought the right answer was “let’s gradually make CIDER more language-agnostic.” That’s the kind of plan that sounds reasonable until you actually try it.
The thing that pushed me over the edge was, oddly enough, building Port. Port is small, focused, and doesn’t try to be CIDER. Working on it for a couple of weeks reminded me how (deceptively) productive it is to start from a clean slate when the new requirements don’t match the assumptions baked into a mature codebase. Trying to retrofit CIDER into a language-agnostic shape would have meant fighting with every helper that ever assumed clojure.repl exists, every middleware contract cider-nrepl defines, every project-type heuristic that knows about deps.edn and project.clj and nothing else. A whole lot of “is the server Clojure, or is it the other thing?” branches. The Port experience reaffirmed that the right move for a genuinely different client is a new project, not a thousand cuts to an existing one.
So neat was born. The name is short, says what it does (it’s neat, both in the small-and-tidy sense and in the “no deps, no special assumptions, just the protocol” sense), and conveniently leaves room for puns I haven’t fully committed to yet. I might land on a backronym one day. For now it’s just “neat”.
neat is a small Emacs nREPL client. The code is split across four files:
neat-bencode.el: bencode encode/decode.neat-client.el: TCP connections, request dispatch, the standard nREPL ops.neat-repl.el: a comint-derived REPL buffer.neat.el: the entry point, customization group, and neat-mode minor mode for source buffers.It only uses Emacs builtins. There are no external runtime dependencies, not even on clojure-mode, because neat doesn’t assume Clojure on the other end. If you write clojure-mode, fennel-mode, hy-mode, or anything else that talks nREPL, you turn on neat-mode in that buffer and it just works.
The connection routing is also intentionally library-friendly. There’s a buffer-local neat-current-connection override so downstream packages can implement their own routing logic, plus a global default for the simple “one server at a time” case that most people will want.
Capability discovery is done at connect time via the nREPL describe op. neat doesn’t hardcode “this server has completions, this one doesn’t” assumptions. If the server reports a completions op, the CAPF backend lights up (with type annotations next to each candidate, when the server provides them). If it reports lookup, eldoc starts working and M-. jumps to definitions via an xref backend. If neither is there, you still get a perfectly serviceable raw REPL.
Start an nREPL server. Anything that speaks the protocol will do. For a Clojure server:
1
2
3
4
5
clj -M:nrepl
# or
bb nrepl-server :port 7888
# or
lein repl :headless :port 7888
Then in Emacs:
class="highlight">1
M-x neat RET localhost RET 7888 RET
A REPL buffer pops up, the prompt follows the server’s reported namespace, and you can type expressions at it. Multi-line input works because RET only submits when the form parses as balanced under neat-repl-input-syntax-table (Emacs Lisp syntax by default, which is close enough for any Lisp). Input history is persisted across sessions.
If there’s a .nrepl-port file in the project, the prompt defaults to its contents, so M-x neat RET RET is enough to connect.
To evaluate from a source buffer, turn on the minor mode:
class="highlight">1
M-x neat-mode
The familiar bindings are there, intentionally compatible with what CIDER users expect:
Key Command C-c C-eneat-eval-last-sexpC-c C-cneat-eval-defunC-c C-rneat-eval-regionC-c C-bneat-eval-bufferC-c C-lneat-load-buffer-fileC-c C-zneat-switch-to-replC-c C-kneat-interrupt-evalC-c M-nneat-set-nsC-c C-d C-dneat-show-doc-at-pointM-.xref-find-definitionsM-,xref-go-back
neat-eval-buffer ships the buffer contents as an eval op; neat-load-buffer-file uses the standard load-file op instead, so the server can attribute file and line numbers to errors. Use the latter when you’re actually loading a file from disk and care about good diagnostics.
neat-set-ns sets the buffer-local neat-ns, which gets sent as the ns field on every eval op from that buffer. For languages where the namespace is declared in the source (Clojure’s (ns foo.bar), etc.), swap in a parser via neat-buffer-ns-function.
For juggling multiple connections, M-x neat-list-connections opens a tabulated-list buffer with one row per live connection, where you can set the default or disconnect interactively.
That’s roughly the whole user-facing surface today. There’s no jack-in command, no inspector, no debugger, no test runner. Likely there will never be, but if you need those you should probably be using CIDER anyways…
Should you use it?
If you write Clojure and CIDER works for you, keep using CIDER. It’s mature, full-featured, and supported, and I’m going to keep working on it for as long as people use it. Nothing about neat changes that.
But if you find yourself in one of these situations:
- you write a non-Clojure language whose runtime ships an nREPL server, and you’ve been muddling through with a half-supported CIDER setup,
- you write Clojure but you value minimalism and don’t need the full CIDER feature set,
- you’re building an Emacs package that needs to talk nREPL and you want a small, dependency-free library to build on,2
then neat might be a better fit. It’s small enough that you can read the whole thing in an afternoon, and the library/UI split (neat-bencode and neat-client are perfectly usable from other packages) is genuinely designed for downstream consumers.
The bigger picture
neat is part of a broader push I’ve been chewing on for a while now: making nREPL a healthy multi-language ecosystem rather than a Clojure-only protocol. That push has three legs:
- An actual nREPL specification. The spec.nrepl.org draft is (will be) the formal version of what today is “whatever nREPL the project does”.
- Reference clients. neat is one. The point of building a deliberately Clojure-free client is that it stress-tests the spec. Anywhere neat ends up needing to special-case the server, the spec has a gap.
- A compatibility test suite. The parameterised integration suite in neat already runs the same assertions against multiple servers and surfaces real divergences (Clojure batching
(println "hi") into a single out message where Basilisp emits two, for example). I’d like to grow this into a portable suite that any nREPL server can self-check against.
This is also why I keep teasing a “reference CLI client” in conversations. An editor client is one thing, but a small command-line nREPL client written in a non-Lisp language would be a much sharper test of how language-agnostic the protocol really is. neat is plausibly a precursor to that. Time will tell how far I push this; for now I just wanted to get the Emacs side moving.
Thanks
As always, big thanks to Clojurists Together and everyone supporting my open source work. You make it possible for me to keep tweaking and improving CIDER, nREPL, clj-refactor, and friends, and occasionally try something “neat” on the side. neat isn’t replacing any of the existing Clojure tooling for Emacs. It’s just another tool in the box for the people who want it.
Feedback, ideas, and contributions are most welcome over at the issue tracker.
Keep hacking!
https://github.com/clojure-emacs/cider/issues/3905 ↩︎
For a long time I planned to extract CIDER’s nREPL client code into a reusable package, but now that we have neat I probably will finally abandon this idea. ↩︎
]]> bbatsov I think I’ll take my REPL neat My parens black and my bed at three CIDER’s too sweet for me… – Bozier Last week I announced Port, a small prepl client for Emacs. Today I’m following it up with another small Emacs package. Meet neat, a tiny, deliberately language-agnostic nREPL client. Why? For years I’ve been hearing some version of the same request: “could CIDER work with my non-Cloju... Port: a minimalist prepl client for Emacs 2026-05-12T09:00:00+03:00 2026-05-12T09:00:00+03:00 https://batsov.com/articles/2026/05/12/port-a-minimalist-prepl-client-for-emacs/ For ages I’ve had “add prepl support to CIDER” sitting somewhere in the back of my head. CIDER is built firmly around nREPL, but prepl ships with Clojure itself, and the appeal of dropping the external REPL server requirement is obvious. Recently, as part of a broader internals cleanup “mini-project” in CIDER, I finally sat down and put a prototype together: cider#3899.The good news is that the prototype sort of worked. The bad news is that the more I poked at it, the more I kept running into the same pattern. CIDER assumes ops, sessions, request ids, and a whole structured protocol that prepl simply doesn’t have. The amount of CIDER code that would need to grow “is this nREPL or prepl?” branches added up quickly, and I’d be papering over prepl’s limitations in dozens of subtle places. The exercise was fun, but it ended up reaffirming my long-standing belief that nREPL is a much better fit for editor tooling than prepl is.
The exercise did leave me thinking though. What if, instead of bolting prepl onto CIDER, I built a small standalone client in the spirit of inf-clojure and monroe? Something tiny and focused that doesn’t have to pretend to be CIDER, and where prepl’s quirks would be the design rather than something to work around.
Conveniently, I was on vacation in Portugal at the time, where I spent a few days in Porto, and the name pretty much picked itself. Port was born. It kept us firmly in the land of fun, drink-inspired Clojure-on-editor names: CIDER, Calva (after Calvados, the apple brandy), and now Port (the famous fortified wine). The protocol Port talks to is prepl, over a TCP port, so the pun was hard to pass up.
This time around I didn’t manage to land on a backronym I love (at least not yet). The contenders so far:
- prepl omnipotent repl toolkit (my favorite so far)
- prepl-operated repl toolkit
- peak optimized repl toolkit
Naming is hard. I remain open to better suggestions. :D
Scope, or what Port isn’t
Port is a side project. I don’t plan to invest serious time in it past the point I consider it feature-complete, which won’t be far beyond what’s already there. The deliberate goal is to keep it simple and focused, and its feature set will stay close to inf-clojure and monroe. Port is not competing with CIDER. If you want the full feature set (debugger, inspector, test runner, profiler, structured stacktraces, refactor support), CIDER + cider-nrepl is, and will remain, the way.
What Port gives you today is a small, dependable Clojure REPL that you can hook into Emacs without any external dependencies, just a stock Clojure JVM with a prepl listening on a port.
A few architectural notes
If you’re up for the long version, doc/design.md goes deep. Here’s the short version of what prepl gives you compared to nREPL:
- No bencode. prepl emits EDN-tagged maps, one per line. This might be a feature or a problem, depending on your perspective.
- No middleware. Whatever the server prints is what you get. No interception, no extension surface.
- No sessions. There’s one thread per TCP connection.
- No ops. You send a Clojure form, the server evaluates it, and prints back tagged messages:
:ret, :out, :err, :tap, plus an :exception true flag on errors. - No request id. This is the main issue. Tags identify the kind of message, not which request produced it.
That last point is the central design constraint. If you want to issue a request and reliably read back its result without accidentally consuming output from an unrelated background future or tap>, you need to layer correlation on top of the protocol. Port does this with two tricks:
- Two sockets per session. A user socket drives the REPL buffer with raw streaming output, and a separate tool socket carries helper-command requests. Background prints from
future/agent on the user thread don’t bleed into the tool channel. - A bootstrap form. On connect, the tool socket evaluates a one-shot form that defines a
port.tooling/-eval wrapper. Every subsequent helper call goes through it, which captures *out* / *err* and returns a tagged map containing the request id. The client matches the id against a pending-callback registry.
This is what nREPL provides via sessions and ops, just reinvented at the TCP layer. It’s a fair amount of work for something nREPL gives you for free, which only strengthens my view that nREPL is the better protocol for editor tooling. Still, it was an interesting and educational exercise.
Zero dependencies
One thing I’m fairly proud of: Port has no hard dependencies. You’ll want either clojure-mode or clojure-ts-mode installed for the source-buffer side of things, but Port itself only soft-depends on them via runtime fboundp checks. Hook it onto whichever one(s) you actually use. I intend to keep it that way. Dependency creep is a real problem in the Emacs (every?) ecosystem, and a small package should stay small.
What’s there in 0.1
I tagged v0.1.0 yesterday. It’s small but already perfectly usable:
M-x port “jacks in” (bootstraps) (auto-detects deps.edn / project.clj / bb.edn, starts a server and connects to it)- single-buffer REPL with persistent input history, completion, and eldoc at the prompt
- interactive evaluation from source buffers with pretty-printed results
- structured stacktrace buffer with cause chain and navigable frames
M-. find-definition that follows into jar sources- doc/source/apropos/macroexpand helpers
MELPA submission is queued up next. After that, expect Port to be in burst-driven maintenance mode like most of my smaller projects.
Feedback, ideas, and contributions are most welcome. The issue tracker is the right place.
Closing thoughts
Funny thing, I’d never actually written any code against prepl until I started this project. It was fun to spend some quality time with the “competition” of my beloved nREPL. Working with a different protocol always teaches you something about the one you’re used to, and I came away from this with a renewed appreciation for both: prepl is genuinely elegant for what it is, and nREPL is genuinely well-designed for what we use it for.
Big thanks to Clojurists Together and everyone else who supports my OSS Clojure work. You rock! Now if you’ll excuse me, I have new releases of CIDER, clj-refactor, and refactor-nrepl to get back to.
Keep hacking!
]]> bbatsov For ages I’ve had “add prepl support to CIDER” sitting somewhere in the back of my head. CIDER is built firmly around nREPL, but prepl ships with Clojure itself, and the appeal of dropping the external REPL server requirement is obvious. Recently, as part of a broader internals cleanup “mini-project” in CIDER, I finally sat down and put a prototype together: cider#3899. The good news is that ... Batppuccin: My Take on Catppuccin for Emacs 2026-03-29T10:00:00+03:00 2026-03-29T10:00:00+03:00 https://batsov.com/articles/2026/03/29/batppuccin-my-take-on-catppuccin-for-emacs/ I promised I’d take a break from building Tree-sitter major modes, and I meant it. So what better way to relax than to build… color themes? Yeah, I know. My idea of chilling is weird, but I genuinely enjoy working on random Emacs packages. Most of the time at least…Some Background
For a very long time my go-to Emacs themes were Zenburn and Solarized – both of which I maintain popular Emacs ports for. Zenburn was actually one of my very first open source projects (created way back in 2010, when Emacs 24 was brand new). It served me well for years.
But at some point I got bored. You know the feeling – you’ve been staring at the same color palette for so long that you stop seeing it. My experiments with other editors (Helix, Zed, VS Code) introduced me to Tokyo Night and Catppuccin, and they’ve been my daily drivers since then.
Eventually, I ended up creating my own Emacs ports of both. I’ve already published Tokyo Night for Emacs, and I’ll write more about that one down the road. Today is all about Catppuccin. (and by this I totally mean Batppuccin!)
Why Another Catppuccin Port?
There’s already an official Catppuccin theme for Emacs, and it works. So why build another one? A few reasons.
The official port registers a single catppuccin theme and switches between flavors (Mocha, Macchiato, Frappe, Latte) via a global variable and a reload function. This is unusual by Emacs standards and breaks the normal load-theme workflow – theme-switching packages like circadian.el need custom glue code to work with it. It also loads color definitions from an external file in a way that fails when Emacs hasn’t marked the theme as safe yet, which means some users can’t load the theme at all.
Beyond the architecture, there are style guide issues. font-lock-variable-name-face is set to the default text color, making variables invisible. All outline-* levels use the same blue, so org-mode headings are flat. org-block forces green on all unstyled code. Several faces still ship with #ff00ff magenta placeholder colors. And there’s no support for popular packages like vertico, marginalia, transient, flycheck, or cider.
I think some of this comes from the official port trying to match the structure of the Neovim version, which makes sense for their cross-editor tooling but doesn’t sit well with how Emacs does things.1
Meet Batppuccin
Batppuccin is my opinionated take on Catppuccin for Emacs. The name is a play on my last name (Batsov) + Catppuccin.2 I guess you can think of this as @bbatsov’s Catppuccin… or perhaps Batman’s Catppuccin?
The key differences from the official port:
Four proper themes. batppuccin-mocha, batppuccin-macchiato, batppuccin-frappe, and batppuccin-latte are all separate themes that work with load-theme out of the box. No special reload dance needed.
Faithful to the style guide. Mauve for keywords, green for strings, blue for functions, peach for constants, sky for operators, yellow for types, overlay2 for comments, rosewater for the cursor. The rainbow heading cycle (red, peach, yellow, green, sapphire, lavender) makes org-mode and outline headings actually distinguishable.
Broad face coverage. Built-in Emacs faces plus magit, vertico, corfu, marginalia, embark, orderless, consult, transient, flycheck, cider, company, doom-modeline, treemacs, web-mode, and more. No placeholder colors.
Clean architecture. Shared infrastructure in batppuccin-themes.el, thin wrapper files for each flavor, color override mechanism, configurable heading scaling. The same pattern I use in Zenburn and Tokyo Night.
I didn’t really re-invent anything here - I just created a theme in a way I’m comfortable with.
I’m not going to bother with screenshots here – it looks like Catppuccin, because it is Catppuccin. There are small visual differences if you know where to look (headings, variables, a few face tweaks), but most people wouldn’t notice them side by side. If you’ve seen Catppuccin, you know what to expect.
Installation
The easiest way to install it right now:
class="highlight">1
2
3
4
(use-package batppuccin
:vc (:url "https://github.com/bbatsov/batppuccin-emacs" :rev :newest)
:config
(load-theme 'batppuccin-mocha t))
Replace mocha with macchiato, frappe, or latte for the other flavors. You can also switch interactively with M-x batppuccin-select.
There Can Never Be Enough Theme Ports
I remember when Solarized was the hot new thing and there were something like five competing Emacs ports of it. People had strong opinions about which one got the colors right, which one had better org-mode support, which one worked with their favorite completion framework. And that was fine! Different ports serve different needs and different tastes.
The same applies here. The official Catppuccin port is perfectly usable for a lot of people. Batppuccin is for people who want something more idiomatic to Emacs, with broader face coverage and stricter adherence to the upstream style guide. Both can coexist happily.
I’ve said many times that for me the best aspect of Emacs is that you can tweak it infinitely to make it your own, so as far as I’m concerned having a theme that you’re the only user of is perfectly fine. That being said, I hope a few of you will appreciate my take on Catppuccin as well.
Wrapping Up
This is an early release and there’s plenty of room for improvement. I’m sure there are faces I’ve missed, colors that could be tweaked, and packages that deserve better support. If you try it out and something looks off, please open an issue or send a PR.
I’m also curious – what are your favorite Emacs themes these days? Still rocking Zenburn? Converted to modus-themes? Something else entirely? I’d love to hear about it.
That’s all from me, folks! Keep hacking!
The official port uses Catppuccin’s Whiskers template tool to generate the Elisp from a .tera template, which is cool for keeping ports in sync across editors but means the generated code doesn’t follow Emacs conventions. ↩︎
Naming is hard, but it should also be fun! Also – I’m a huge fan of Batman. ↩︎
]]> bbatsov I promised I’d take a break from building Tree-sitter major modes, and I meant it. So what better way to relax than to build… color themes? Yeah, I know. My idea of chilling is weird, but I genuinely enjoy working on random Emacs packages. Most of the time at least… Some Background For a very long time my go-to Emacs themes were Zenburn and Solarized – both of which I maintain popular Emacs p...