One of the things that we Emacers hear with tiring frequency is that Emacs is moribund, old technology loved only by graybeards stuck in the last century. In fact, as actual users know, Emacs is undergoing constant development and is often the first to offer new features that the other editors copy. The most salient examples are Org mode and Magit but there are plenty of more recent examples.

But don’t take my word for it. Over at the Emacs subreddit, gonstrider has a short post relating his experience with all of this. He’s been using an unnamed editor—you’ll have no problem figuring out which one—that keeps having weekly updates that seem to make things worse each time. So he jumped in the deep end and downloaded and built Master (Emacs 32) fully expecting to find lots of broken things.

It didn’t turn out that way. He was, in fact, surprised to discover that almost everything worked well. The only problem he had was evil on Windows and he solved that by simply upgrading evil. As for the rest, he found that Emacs was super-responsive and all the functionality that seemed laggy in that other editor was snappy in Emacs.

There are two lessons here. The first is that Emacs, far from being moribund, is undergoing continuing development and introducing new features. The second point is that Emacs is, unlike some of its competitors, continuing to produce upgrades that simply work and don’t make their users crazy.

Very shortly, we should see the release of Emacs 31 but work on Emacs 32 is already ongoing and amazingly stable for what is, after all, alpha software. The next time someone tells you that Emacs is old and moribund, refer them to gonstrider’s post.

Years ago, when I started the old blog¹, I discovered Solarized.

I liked it. The colors were beautiful and worked for me, but eventually I switched to the Gotham theme in Emacs, which, if you take a look, is not much different — just a bit darker. I stayed with this theme for a long time, tweaking it a bit after a trip to New Mexico.

When I received my Mac and started working on it at home, I enjoyed its automatic switching between dark and light themes. At the same time, Prot started coming out with more of his excellent Ef Themes, and I adopted ef-reverie for my light theme and ef-night for my dark one (once again, if you look at the images, you’d see they’re not far off from Solarized, especially my choice of a light theme).

This has been the state of affairs until the beginning of this week, when I “found” Solarized again. I discovered Prot himself was heavily influenced by Solarized, and he discussed it several times on his blog. Here’s part of his background story for his project Prot16:

My starting point for developing a colour scheme was Ethan Schoonover’s Solarized. A true masterpiece. I thus settled on a method of using a 16-colour palette that consists of 8 base values and 8 accents. As with Solarized, the themes would have to be able to transition from ’light’ to ‘dark’ environments with minor alteration to the mapping of colours (though not the values themselves).

Prot’s quest is an interesting one. Like me, he enjoyed Solarized, but eventually decided the colors were not contrasting enough for his taste. His reaction was to create his well-known Modus themes, which, along with his Ef-themes and Prot16, set new theming standards for Emacs.

Meanwhile, I have had the other issue since childhood:

I’ve never liked harsh contrast for this reason. As a matter of fact, a more “gentle” contrasting theme is one of the reasons I like working in Emacs. My website and my wiki are a result of these preferences. The black text on the beige background is comfortable on my eyes. Enough contrast to read, but not enough to burn text into my vision, as many dark modes out there do.

While Prot’s ef-themes offer softer contrast (I didn’t check, but it does seem so visually) which I find excellent, I decided to try out bbatsov’s Solarized for Emacs, which I didn’t know about in the past when I first picked up this theme for Emacs — the official Emacs port is not as good in my opinion.

I’ve learned a couple of things I wasn’t aware of. For starters, you can have many variations of this theme, even though the main 16 colors are still preserved. It makes sense when you think about it: one person can choose Solarized’s red (#dc322f in hex) as an emphasis, while another can select its yellow (#b58900) or orange (#cb4b16), for example. Webpages and Emacs take it a step further, as certain texts can be bold or italicized, with solid underlines or dashed ones, etc. All of those changes take place without touching the colors themselves.

Solarized also helps me with a certain itch I’ve had for a couple of months: a dark theme for my blog. I know most of you read my posts in your RSS reader, hopefully with a theme you enjoy, so this won’t matter much. For me, how my site looks and is styled is important, and getting there is fun.

Being a PhD student within a research group entails some structure to tracking your progress as you proceed with research. Within the current team that I'm in, we have weekly group meetings where each member presents the tasks that they've completed during the previous week and discusses any issues they might've faced (if any), to our supervisor.

Usually before the meeting, I jot down things that I've finished with pen and paper. But since I'm in the spirit of integrating my workflow with emacs and orgmode, I thought why don't I try implementing this part of my routine also into orgmode.

Enter org-agenda

All my todo items are tracked with org-agenda where I capture every task I need to finish with org-capture¹.

I have a custom org-agenda view just for viewing my daily and weekly TODO items, events/meetings scheduled at a certain time and tasks that have a deadline associated with them. Suffice to say, this workflow has replaced all my needs for having a calendar over the cloud, be it Google, Outlook, what have you². The only downside that I haven't figured out (yet) is to incorporate calendar invites that I receive via email, into my org-agenda automatically instead of manually capturing an event into the agenda view.

With this custom agenda view, as I finish tasks and mark them DONE, they disappear from the current view. This is by design. I figured I could just review my completed tasks by visiting the relevant files (tasks.org, meetings.org, etc. in my case). But who wants to sift through all the completed tasks and filter them manually to only note down the tasks completed during the previous week? Why not automate this with the power of emacs?

Elisp snippet that implements this weekly review

The idea is fairly simple. I'd like to look at the tasks that I've completed since the last group meeting. This assumes I review these tasks on the day of the group meeting (which I do currently³).

We simply then instruct orgmode to filter out the DONE items from the last 7 days. The org-agenda-custom-commands variable is what we'll use to define this custom org-agenda view.

(setq org-agenda-custom-commands
      '(("w" "Finished tasks from last week" tags "CLOSED>=\"<-7d>\""
         ((org-agenda-overriding-header "Finished tasks from last week")
         (org-agenda-archives-mode t)
         (org-agenda-tag-filter-preset '("-emacs" "-personal" "-email"))
         (org-agenda-prefix-format '((tags . " ")))
         (org-agenda-remove-tags nil)))))

Let's go over the various config options one by one:

• The first line defines the keybinding in the primary org-agenda dashboard and the associated title for the keybinding.
• tags "CLOSED>=\"<-7d>\"" is pretty self-explanatory. We filter for items that were completed in the last 7 days.
• org-agenda-overriding-header: Simply defines the title of the agenda view.
• org-agenda-archives-mode: This is set to t (True) meaning to also look at the archived entries from last week. I typically archive my entries frequently so this is helpful.
• org-agenda-tag-filter-preset: I don't want personal tasks appearing in this view, so I remove any items that have the relevant tags.
• org-agenda-prefix-format: By default, the agenda view contains information about which file the entries belong to (in my case, it's tasks.org). This appears as tasks: per entry in the agenda which unnecessarily clutters the view.
• org-agenda-remove-tags: I don't want to remove the tags of the various entries (they are useful to me) that appear in the right margin. Hence this variable is set to nil (False).

To invoke the view, we can simply run M-x org-agenda and hit w to get into the view. My org-agenda dashboard looks like this:

All the above keys are present in the default view, except my custom views (depicted by j and w keys).

Invoking custom org-agenda views (slightly) faster

For my workflow, I mostly deal with just the two org-agenda views (represented by j and w). It's a good idea to have a global keybinding to quickly invoke these views. Let's define the function and keybinding for it.

(defun pani/done-items-prev-week-org-agenda ()
  "Custom function to immediately jump to my custom org-agenda view."
  (interactive)
  (org-agenda nil "w"))

To invoke the function, we define the keybinding like via a use-package macro:

(use-package org-agenda
  :ensure nil
  ;; Don't need to go through org-agenda template for custom agenda
  :bind (:map global-map
	      ("C-c w" . pani/done-items-prev-week-org-agenda)))

I can then just hit CTRL c w to bring up this new agenda view.

That's it! This should make things easier for me during our group's weekly meetings.

Marcin Borkowski (mbork) does a lot of writing and, of course, uses Org mode for most of it. The hard part, he says, is not the writing but the editing. In particular, he’s talking about the emphasis markup. If he wants to write a word or region in bold, that’s easy. He merely starts and end it text with a star. Making a word or region bold after the fact—in the editing phase—is more difficult. You have to locate the beginning of the text, add a star, move to the end of the text, and add another star.

Mbork, of course, soon discovered the solution: org-emphjasize. All you need to do is highlight the text and specify the markup character. The problem is that the binding for org-emphasize, Ctrl+c Ctrl+x Ctrl+f, is difficult to type. Mbork solved that writing a function to call org-emphasize with an argument * to cover his most common use. But then he bound it to Ctrl+c Ctrl+x Ctrl+8, which strikes me as just as bad, although you don’t have to specify the *.

My solution for this is to use surround.el that I wrote about here and Bozhidar Batsov wrote about here. I have it bound to Hyper+’ so it’s easy to call. I suppose you could even do as mbork did and write a specialized function for a heavily applied use case.

One thing for sure, mbork is right about markup being harder to deal with when editing.

The topic of this month's Emacs Carnival interests me, even though I "dump ... notes into a directory and simply grep for information ...."⁰ Org does not work the way my brain works,¹ or rather, my brain doesn't work the way Org works.

I do use Org. At first I created a few Org files (work.org and home.org, and maybe todo.org) thinking I could rigidly dedicate all my topics to them.

Over time I had about dozen files, one for nearly every major facet of my life until I gave up. Why? Because it really doesn't matter where I put Org TODOs and their notes. When I need to locate something, Org provides a way to search entries for a regular expression, which is what grep does, sans all that Unixy CLI stuff.

So faced with the task of paying one of my wife's medical bills, I could agonize over whether to put the task into wife.org or bills.org or medical.org.² Or I could just:

• establish the task somewhere,
• act on it
• link to a receipt
• mark it done³

I created a special template for org-capture, which places these one-off tasks into todo.org. And it clocks into the task, too.

A topic with even greater complexity is "education." I'm a lifelong learner; my edu.org file has (only) 29 headings, all of which have at least a few subheadings. If I learn about an Emacs feature, I might want to write about it, so I'll put a task into blog.org that links to it.

Occasionally a post will span multiple topics in edu.org, topics such as Emacs, Vivaldi, LibreOffice, HTML or LaTeX. In a year from now, which file should I look for it in? The keystroke C-c a s comes to the rescue.⁴ I might search for "Sacha" because all I remember is that I discovered an Emacs feature on Sacha's website.⁵ Incidentally, I get 13 hits when I search for "Sacha," one of which was the one I had in mind.

The question I think all Emacs users face is, "At what point does tweaking Emacs (and self-quantifying tools in general) tip the scales from aiding our progress to impeding it?" I dread going down a Knowledge Management rabbit hole,⁶ but I'm sure I'll enjoy the leap.

⁰ Charlie Holland's Search for Knowledge

¹ A tree works like your brain.

² Don't even get me started on insurance.

³ All of this occurs while clocked in to the task.

⁴ In this case, C-c a is bound to org-agenda.

⁵ Sacha Chua's blog

⁶ Can one gain knowledge of Knowledge Management Systems without having a Knowledge Management System in which to record that knowledge? That may be a Zen koan for someone.

Protesilaos Stavrou (Prot) has another nice video on something that I was vaguely aware of but had never used: conditional abbreviations. As most Emacers know, you can define abbreviations that will expand into another, usually longer or more complicated, string. It can save a lot of time and you can set them to fire automatically or when Tab is pressed right after the abbreviation.

What’s less well known is that these abbreviations can have properties and one of those properties is to specify a function that will tell Emacs whether or not it should expand the abbreviation. Prot gives a few examples of this. In one example, he wants “Welcome” to expand to a French greeting but only if he is using one of the French input methods. Another example expands an abbreviation only if he’s in a certain directory or one of its subdirectories. A third example expands an abbreviation only if a certain minor mode is active.

Those examples might seem like they’d be complicated but they are, in fact, simple, almost trivial. In the call to define-abbrev, you simply give the name of the deciding function in the :enable-function clause. Check out Prot’s video for the details.

I use several abbreviation systems—including abbrev—but this capability in abbrev is especially nice. It’s easy to use and you can make the firing condition as simple or complex as you need it to be.

Prot’s video is 14 minutes, 33 seconds so it should be easy to find time for it. As with all of Prot’s videos, it’s worth the time.

The Navigation category has a couple of interesting window configuration tips this week in case you prefer to work with just one window or have multiple windows with some of them dedicated to specific buffers.

• Upcoming events (iCal file, Org):
  • London Emacs (in person): Emacs London meetup https://www.meetup.com/london-emacs-hacking/events/315859503/ Tue Aug 11 1800 Europe/London
  • Emacs Berlin: In-Person-Only Emacs-Berlin Stammtisch https://emacs-berlin.org/ Tue Aug 11 1900 Europe/Berlin
  • OrgMeetup (virtual) https://orgmode.org/worg/orgmeetup.html Wed Aug 12 0900 America/Vancouver - 1100 America/Chicago - 1200 America/Toronto - 1600 Etc/UTC - 1800 Europe/Berlin - 2130 Asia/Kolkata – Thu Aug 13 0000 Asia/Singapore
  • Atelier Emacs Montpellier (in person) https://lebib.org/date/atelier-emacs Fri Aug 14 1800 Europe/Paris
  • OrgDevMeetup https://bbb.emacsverse.org/rooms/orgdevmeetup Sat Aug 15 0900 America/Vancouver - 1100 America/Chicago - 1200 America/Toronto - 1600 Etc/UTC - 1800 Europe/Berlin - 2130 Asia/Kolkata – Sun Aug 16 0000 Asia/Singapore
  • M-x Research: TBA https://m-x-research.github.io/ Wed Aug 19 0800 America/Vancouver - 1000 America/Chicago - 1100 America/Toronto - 1500 Etc/UTC - 1700 Europe/Berlin - 2030 Asia/Kolkata - 2300 Asia/Singapore
  • Emacs APAC: Emacs APAC meetup (virtual) https://emacs-apac.gitlab.io/announcements/ Sat Aug 22 0130 America/Vancouver - 0330 America/Chicago - 0430 America/Toronto - 0830 Etc/UTC - 1030 Europe/Berlin - 1400 Asia/Kolkata - 1630 Asia/Singapore
• Beginner:
  • How to learn Emacs, like, for real
  • Emacs for NvChads
  • Emacs for Life [Leanpub PDF/iPad/Kindle]​ ($20+)
• Emacs configuration:
  • Emacs Package Management with package-quickstart - DEV Community (JP, @gemmaro)
  • Tip about setting file-precious-flag by location with my-maybe-mark-file-precious (@tennoseremel@gts.skobk.in)
  • Emacs Config Gems - Part 3 - Melpa, UI, help, and many more
  • Emacs Config Gems - Part 4 - recycle bin, frame size, backups, autosave, autorevert, recentf
  • User Interface to Computer Applications Demonstrated in GNU Emacs (02:09:31) also available as separate videos, see video description
  • Dotfiles Season 1 Episode 4: Emacs Configuration (14:31)
  • Rate my Emacs config! (Reddit)
  • myn-macs (MY miNimal eMACS IDE setup for the lazy terminal wizard) (Reddit)
• Emacs Lisp:
  • Charlie Holland: Gödel, Escher, Elisp: The Beauty of Macros (Reddit)
  • [ANN] TextUI is now public: responsive Flex/Grid layout for widget.el interfaces (Reddit)
• Appearance:
  • Raymond Zeitler: Display Active Clock in Emacs Frame Title (Irreal)
  • paniash/modus-vague: The vague theme for emacs, built on top of modus themes. · GitHub (@paniash@mas.to)
• Navigation:
  • Protesilaos: Emacs: the ‘speedbar’ built-in file explorer (Emacs 31) (YouTube 15:40, Reddit, Reddit, Irreal)
  • Chris Maiorana: Using ffap to jump to file includes in Emacs (YouTube 07:04)
  • Raymond Zeitler: Dedicate an Emacs Window to Its Buffer
  • James Cherti: single-window.el – Always Open Emacs Buffers in the Current Active Window (GitHub, Reddit)
  • Srijan Choudhary: Emacs: desktop-save-mode without the automatic restore (Irreal)
  • My Emacs workflow with project.el and tab-bar.el project-x.el (30:39)
• TRAMP:
  • Runbox.el - for shell/compile/eglot over TRAMP in local buffers (emacs-tangents, Reddit, @cidra@mastodon.uno)
• Dired:
  • Dave's blog: Run the file in Emacs’ dired - path
  • dired-z: zoxide-style directory jumping inside Dired (Reddit)
• Writing:
  • Efficient Note-taking in Emacs with Howm (@qnnnp)
  • Reversible transpose-chars and transpose-words, and a dwim that transposes around "and" or "or" (@jameshowell@fediscience.org)
  • Protesilaos: Emacs: conditionally expand abbrev-mode definitions (YouTube 14:34, Reddit)
  • Using remark to strip words in backtick quotes before write-good analysis (@howard@pdx.social)
  • How Prot Organizes Knowledge, Projects, and Tasks in Emacs (37:53)
  • benleis1/wikimode · GitHub (YouTube, Reddit, @benleis@mathstodon.xyz) - navigate Markdown and Org files like a wiki
• Org Mode:
  • Reviewing finished tasks from last week in org-agenda and emacs (Irreal)
  • Read a .docx in Emacs with its tracked changes and comments intact, as org-mode (Reddit)
  • How to Generate PDFs from Org Mode using ox-odt (26:03)
  • rlridenour/ox-rlr-slipshow: Emacs Org mode exporter to create Slipshow Markdown files. · GitHub (@randyridenour@zirk.us)
  • Org development:
    • ox: New hook that runs after include keywords, but before macros/babel
    • org: Rename statistics scope options
• Coding:
  • Managing Changes with ediff — Alex Carney (@alcarney)
  • Tip about using diff-hl-set-reference-rev (@glyph)
  • [[https://utcc.utoronto.ca/~cks/space/blog/programming/EmacsGitBlameOverTime][Chris's Wiki :: blog/programming/EmacsGitBlameOverTime]] (lobste.rs)
  • The Emacs Cat: Debugging in Emacs
  • Xah Talk Show Ep811. Emacs: CSS toggle px rem (30:21)
• Math:
  • r-ts-mode now on Melpa
• Shells:
  • Eshell shared history (Reddit)
  • Zoxide in eshell (Reddit)
• Web:
  • Andros Fenollosa: EWW, the Emacs browser you underestimate (HN)
• Mail, news, and chat:
  • martianh/mastodon.el 2.1.0: collections (@mousebot@todon.nl)
• Evil mode:
  • Disable mouse drag selection in evil mode (@aud@fire.asta.lgbt)
• Multimedia:
  • Charles Choi: Announcing now-playing.el, an Emacs interface for the macOS Music app (Reddit)
  • Sacha Chua: Replace YouTube captions from Emacs Lisp
• LLMs:
  • kriyative / elisp-agent · GitLab (@kriyative@functional.cafe)
  • blog.fidelramos.net – Supply-chain hygiene for Emacs: LLM review of package upgrades (ES)
  • AGENTS.md - discussion about whether to include AGENTS.md in Emacs source code (HN)
• Community:
  • Sacha Chua: Emacs Chat avec Richard Bonichon en français (YouTube, 01:57:39)
• Other:
  • How to Count Words In Emacs (01:09)
  • Emacs Arbitrary Code Execution Returns (Reddit)
  • bible-gateway package update: touch-typing verse memorisation, reading plans, transient menu, and more (Reddit)
  • graph-fa2 0.2.3 now available on MELPA - graph visualization
• Emacs development:
  • emacs-devel:
    • Re: [PATCH] emoji on TUI emacs - Stefan Monnier via Emacs development discussions. Possible workaround for different composition widths?
    • Re: Discussion about why GNU/Linux system upgrades cause old programs to break - Eli Zaretskii Issues with compiling older versions
  • Show-all values for speedbar user options for hiding
  • Add `outline-occur' command and `display-buffer-default-alist' variable
• New packages:
  • bitbucket-devops: Bitbucket Cloud DevOps workflows (MELPA)
  • denote-smart-sluggify-title: Denoise denote titles to save filename length (MELPA)
  • graph-fa2: ForceAtlas2 pure-elisp background-cached engine (MELPA)
  • pimacs: Emacs Client for Pi (MELPA)
  • ronny-theme: A dark colorscheme inspired by Monokai (MELPA)

Links from reddit.com/r/emacs, r/orgmode, r/spacemacs, Mastodon #emacs, Bluesky #emacs, Hacker News, lobste.rs, programming.dev, lemmy.world, lemmy.ml, planet.emacslife.com, YouTube, the Emacs NEWS file, Emacs Calendar, and emacs-devel. Thanks to Andrés Ramírez for emacs-devel links. Do you have an Emacs-related link or announcement? Please e-mail me at sacha@sachachua.com. Thank you!

You can e-mail me at sacha@sachachua.com.

This is a purely-for-fun exercise: a guide to web design for terminal browsers. Starting from the text browsers people actually use, I am going to pull out a set of rules in case you ever decide to build a site meant to read and look its best in a terminal. It is not an alternative to Gemini, Gopher or a smallweb attempt, but a set of best practices so your site reads well in a terminal browser, and even so you can build Web Apps for the terminal.

Five engines, one test

The first step is to install the five text engines people actually use and feed them the same test pages, isolating one feature at a time.

• w3m (0.5.6): the most capable with tables, and it even draws images in terminals that allow it.
• lynx (2.9.3): the patriarch, the lowest common denominator since 1992.
• links (2.30): fast, with a little bit of CSS.
• elinks (0.20.0): the cousin with bigger ambitions, it even has an optional CSS engine.
• EWW: the Emacs one.

Now we look for the compatibility crossovers. You test HTML and CSS features and see how each engine interprets them.

The results:

From this we draw some general conclusions:

• JavaScript does not exist. In any of them. It is not slow or partial. There simply is no interpreter.
• CSS is almost a mirage. Stylesheets, whether <style> or <link>, are ignored in all of them except elinks, which applies a few things like text-align. Four out of five engines do not read your CSS. Design as if it were not there.
• display:none is a trap. If you hide something with a class (class="hidden" and .hidden{display:none} in your sheet), all five engines show it. Every one. Because they do not read the sheet: do not hide anything important with CSS. If it should not be seen, do not put it in the HTML.
• Images are text. Only EWW (and w3m in some terminals) actually draws the image. In the rest, the image is its alt attribute. All five fall back to alt when the image is broken, and an image with no alt leaves you a [hero] with the file name, or nothing at all. alt is not accessibility for others, it is your content.
• <details> does not fold. None of the five make it interactive. The summary and the body always show, one after the other.
• HTML5 semantic tags are invisible. article, section, nav, header, footer, main, aside: they are transparent containers. They do not add a single line break. Their value is semantic, not visual.

With that, we can lay down a few design lines and best practices.

8 rules for publishing to the terminal

1. DOM order rules

There is no float, no flex, no grid, no order. Whatever you put first in the HTML comes first on screen. So place the content right after opening the <body> and send the long navigation and the footer to the end. A reader who opens your article does not want to tab through thirty menu links before reaching the first sentence.

2. Mark structure with tags, not styles

Real headings <h1>..<h6> for the hierarchy, never a <div class="big-title">. Lists with <ul>/<ol>, definitions with <dl>. Quotes with <blockquote>, which all of them indent. Code with <pre> and <code>. Each engine gives them its own treatment: use them for what they mean.

3. Your page must read with CSS turned off

This is the touchstone. If you disable CSS and your page becomes unreadable, it is not the terminal browser's problem, it is your HTML's problem. Spacing (margin, padding, line-height) does not exist: the separation comes from paragraphs. Structure with real <p>, not with loose <br>.

4. Do not convey information with color alone

A "required field in red" or a "green = correct" evaporate. Inline color is the most fragile thing in the table: it depends on the terminal and its configuration, and in many cases it does not even show. Always pair color with text or a symbol. An "Error:" in front, an asterisk, anything.

5. Tables for data only, never for layout

EWW and w3m draw a surprisingly good ASCII grid, colspan and rowspan included. But a layout table produces an absurd, unreadable grid. Watch the width: if the columns add up to more than the terminal's, the experience degrades. Fewer columns and short cells win.

6. Images with a descriptive alt and srcset

alt is what you see in four out of five engines. Make it a sentence, not an image1.png. And if the image is pure decoration, give it an explicit alt="": that way the reader ignores it instead of reading you the file name. A missing alt and an empty one are not the same thing. Offer srcset with several resolutions, and the engine that can show images will pick the right one. And do not rely on an image to communicate anything critical, because in most engines they do not load at all.

7. Real forms

No JavaScript submissions. A <form> with its action and its method (GET or POST), and an <input type="submit"> or a <button>. Put a name on every field: the engines collect by name, and a field without one is lost. Associate a <label> with each one.

8. Headers that do count

<title> always, descriptive: lynx and links center it at the top, and all of them use it to identify the page. <meta charset> in UTF-8 as an encoding fallback. <base> if you use relative links, which all of them respect. And serve over HTTPS, since several engines flag the certificate status.

TerminalSpeed Insights

A guide you cannot run is a list of good intentions. So I wrote a prototype. It is a Python script that reads an HTML file, or a URL, and gives you back a readability score with the specific warnings. The number is a heuristic, not a science. I hand out the points by eye, an error weighs more than a warning and that is that. What really matters is the list of warnings, not the scoreboard.

You can download it from its repository, TerminalSpeed Insights, and run it against any page:

python3 terminalspeed.py https://your-site.dev/

Running it over a few popular sites, the ones leaning more on content than design, I get some numbers:

At the top are the wikis, the docs, the text sites and the ones that fly the minimalism flag. At the bottom, curiously, two of the sites most loved by people who read in the terminal. It is no coincidence: the ones that score high serve the content first and lean on the tags, not on CSS. EmacsWiki, for instance, is almost plain HTML, and that is why it reads on anything that can show text.

Still, these are numbers not every browser shares. Open Hacker News in w3m and you will see the front page perfectly readable, with its numbered list of headlines, despite that 55. w3m draws tables so well that it survives. The validator is not wrong to penalize it, it flags real friction, but friction is not always a death sentence. Take the score as a guide, not a verdict: a 100 almost guarantees it reads well, a low number tells you where to look.

Not just documents: a Terminal Web App

So far I have talked about documents: articles, cards, docs pages. We still have to squeeze the forms: GET and POST work in all five engines. And a form that works is, no more and no less, an application.

Let me show you with a coffee shop:

<form action="/order" method="post">
  <p><label>Your name <input type="text" name="name"></label></p>
  <p><label>Quantity <input type="number" name="qty" value="1"></label></p>
  <p><label><input type="checkbox" name="no_milk" value="yes"> No milk</label></p>
  <p><button type="submit">Order coffee</button></p>
</form>

And this is how it looks in EWW, the Emacs browser. The fields are edited with the keyboard; here I have already filled in the name, the quantity and checked "No milk":

You hit submit and the <form> does a POST. The server responds with a redirect (the good old Post/Redirect/Get pattern) and the browser paints the confirmation, all without leaving the keyboard or touching the mouse:

Look at the detail: heading in bold, the link colored, the quantity and the no-milk option collected correctly. It is a stateful app, interactive, with no JavaScript and without a single kilobyte of framework. And yes, it scores 100 with the validator.

It is a real application: it lives in the text browser, but it looks just as good in Chrome or Firefox, because underneath there is only HTML. You get a terminal interface without touching ncurses or any TUI library. Your toolkit is HTML, your renderer is the browser and your logic lives on the server. The same app, a language you already know, and it works everywhere.

Conclusion

It has been a fun investigation. Almost nobody designs their sites for the terminal, it is a minority and, even so, it is an audience that exists. And there is no shortage of reasons: these are visitors who want accessibility or speed, who are on low resolutions or who work with pipes. More than once I have found myself doing quick searches in EWW, or reading an article there for the visual comfort.

You can take it as a curious article or as another approach to web design. I, at least, will start looking at my pages with different eyes.

I hope you enjoyed this other point of view on web design.

Help me keep writing Every coffee gives me a push toward the next article. Sure, it's on me!

Send an email to comment+article-70d817e8@andros.dev to leave a comment. The subject will be ignored.

Part four of Emacs Config Gems is about basic file operations and save functions. I realized as I was working on this that I have the frame configuration here, which is the wrong place for it. I will change it after posting. Alright, here we go.

When deleting a file in Emacs, we should use the system’s trash (or recycle bin) instead of deleting the file permanently, giving us a chance to restore the file in case we’ve made a mistake.

In addition, since we have this turned on, we can also tell Emacs to always delete non-empty directories (because they’ll go to the trash) instead of prompting. It’s just faster.

(setq delete-by-moving-to-trash t)
(setq dired-recursive-deletes 'always)

Let’s set the frame Emacs starts with to be a bit bigger. In Emacs, these measurements are in lines and columns (character width), so we’re basically saying: “make the default frame 100 characters wide and 55 lines high.”¹

(setq default-frame-alist
   '((width . 100)
     (height . 55))
    )

We might want to move Emacs’ backup files and temp files (those are the ones with ~ and #)² to a different dedicated folder (emacs-bks) instead of the main Emacs folder. Since Emacs won’t just create the directory for us, let’s ask it to do so³. It won’t throw an error if we already have it.

(make-directory "~/emacs-bks" t)
(setq backup-directory-alist
      `((".*" . "~/emacs-bks")))
(setq auto-save-file-name-transforms
      `((".*" "~/emacs-bks" t)))

Now, let’s turn on the option to automatically save files we are working on inside Emacs, and set how long Emacs needs to be idle before auto-save kicks in. In my case, 300 seconds (= 5 minutes) is good enough for idle time. Importantly, I want to emphasize again, idle time. It will not auto-save the file as long as you type, so if you type non-stop for an hour and suddenly lose power, this will not save you, since Emacs didn’t get the chance to be idle for 5 minutes (or even 30 seconds, which is the default). For this, we have auto-save-interval, which auto-saves every 300 characters (globally in Emacs) by default. In my case, I’m lowering it here to 100, since I write plenty of quick notes (using org-add-note, C-c C-z), and it’s common for me to keep using Emacs between those without hitting the 300 mark. Both of those are described in the manual under auto-saving.

(auto-save-visited-mode t)
(setq auto-save-visited-interval 300)
(setq auto-save-interval 100)

Auto-revert checks the buffer we’re visiting against the saved file itself. If the buffer has no changes, but the saved file does have changes, it loads those changes into the buffer silently. However, if the buffer has changes (meaning, we’re writing something into the file and we haven’t saved yet), it won’t do a thing and won’t say anything. Since my particular setup means that all of my org files are inside a folder synced by Syncthing, this is ideal: if I save changes to a file on my Mac, when I switch to my Linux desktop I’ll have the file and the buffer visiting it refreshed and ready to go, provided of course that Syncthing is working and the sync is complete⁴.

(global-auto-revert-mode t)

Activate recentf mode, so Emacs has a list of the recent files we worked on last time, up to 30 by my config. 10 is too little; 50 starts to feel more like “everything I opened this month,” which defeats the purpose. Useful when we don’t want to navigate to the same file each time, and we don’t want to have a bookmark. Note: since I’m using consult, recent files are integrated and show under the file header in the consult minibuffer, and can be quickly viewed with f while visiting the consult minibuffer.

(recentf-mode t)
(setq recentf-max-saved-items 30)

I installed Donovan Ratefison's brand-new Vakana app¹ on my Android device this morning. After following the tutorial, I exported the thread as an Org-mode-compatible package in a ZIP and emailed it to myself in order to transfer it to my desktop.

After opening the Org file that Vakana generated, I exported the entire buffer to HTML. The result is shown below. The only change I wanted to make was to scale the bead of each heading 25%.²

It's fortuitous that Donovan Ratefison released Vakana in a month whose Emacs Carnival theme is "The Search for Knowledge," because Vakana provides a unique way to manage one's knowledge. I'll need to become proficient in it before adding it to my workflow. So my eventual Emacs Carnival submission will be more pedestrian.

¹ Learn about Vakana here or download here.

² The images used for beads are SVG files. However this blogging platform does not support that file type, so I converted them to GIF for this post. This should explain why they don't look awesome.

Your first thread

Your first thread
A 90-second tour. Walk it bead by bead, then make it yours — delete it, or reload it anytime from Settings → Pro Tips.

Table of Contents

• 1. The thread
• 2. Start here · a 90-second tour
• 3. 1/5 · Tap the bead
• 4. 2/5 · Open the thread
• 5. 3/5 · Comment — swipe me right
  • 5.1. Comments
    • 5.1.1. Comment — [2026-08-09 Sun 18:50]
• 6. 4/5 · Long-press a bead in the list
  • 6.1. Comments
    • 6.1.1. Comment — [2026-08-09 Sun 18:22]
    • 6.1.2. Comment — [2026-08-09 Sun 19:14]
• 7. 5/5 · Close it, then make it yours

1. The thread

2. Start here · a 90-second tour

[2026-08-09 Sun]

Welcome — and if this is all new, that’s perfectly fine. We’ll go gently.

Vakana is the Malagasy word for beads — there’s no other word for them in the language, and it’s where this app takes its name. The idea is old and simple: you turn a moment into a small bead — a little coloured token — and beads you keep together form a thread you can walk back along, like beads on a string. (These six notes are already a thread — “Your first thread.”)

That’s the whole shape of it. What a bead means is always yours — the app never decides that for you.

This is a short, hands-on tour: five steps, each one a thing you try yourself.

Next → 1/5 · Tap the bead.

3. 1/5 · Tap the bead

[2026-08-08 Sat]

,*Tap the bead* at the top of this note — the composer opens. That’s where you pick a bead’s shape, pattern, mood-colour and a tiny glyph (this one’s is the number 1️⃣).

Eight shapes, eight patterns, eight moods — small enough to learn, wide enough for anything. There’s no legend: a circle isn’t “an encounter” unless you decide it is.

How does the user navigate the beads? Now I see "< Prev" and "Next >" so it's obvious.

Next → 2/5 · Open the thread.

4. 2/5 · Open the thread

[2026-08-07 Fri]

You’re on a thread right now — a chain of beads strung together on purpose. Open “Your first thread” (tap its chip here, or find it in the Threads view) and you’ll see all six beads in a row you can walk, bead by bead.

The app also keeps a quiet thread for every day you write, under Days in the Threads view — built for you, no effort.

Next → 3/5 · Comment.

5. 3/5 · Comment — swipe me right

[2026-08-06 Thu]

Some thoughts arrive after the moment. Instead of rewriting a note, leave a comment in its margin.

Try it: tap the 💬 at the top of this note — or, back in your list, swipe this row to the right. Either opens the margin, where you can jot a thought or even set it to remind you later.

(The next bead, 4️⃣, already has a comment — spot the 💬 on its row.)

Next → 4/5 · Long-press the bead.

5.1. Comments

5.1.1. Comment — [2026-08-09 Sun 18:50]

The tutorial shows an icon for comment as a white-filled rectangular balloon with three dots. However the actual icon is a balloon that's an empty circle

6. 4/5 · Long-press a bead in the list

[2026-08-05 Wed]

Beads repeat, and you’ll want to find a bead’s kin. This is a thing you do from your list, not from inside a note — so head back to the list first.

There, press and hold any bead: the list instantly filters to every bead like it. (Long-press is the move most people miss.)

Want finer control? Tap the funnel at the top of the list to filter by shape, mood, pattern or glyph, then gather the results into a brand-new thread.

Next → 5/5 · Make it yours.

6.1. Comments

6.1.1. Comment — [2026-08-09 Sun 18:22]

I keep coming back to this one — long-pressing a bead is the move most people miss.

6.1.2. Comment — [2026-08-09 Sun 19:14]

The alarm clock icon next to the note field is for a reminder, not a timestamp. It puts it on the next business day at 9:00 a.m., perhaps. I pressed it at 3:00 p.m. on Sunday August 9th, and then entered the reminder for the next day at 9:00 a.m..

7. 5/5 · Close it, then make it yours

[2026-08-04 Tue]

This thread is closed — notice the clasp. Closing marks a loop that finished; you can reopen it anytime.

A finished thread can leave the app: open it and Export to turn it into a web page or a slide deck.

That’s the whole grammar — bead, thread, comment, close, export. Now make it yours:

• Delete this tour — swipe any note left, or remove it in one tap from Settings → Pro Tips → Interactive tutorial. • Want it back later? Reload from the same place.

Now write your first real moment, and bead it however you like.

Created: 2026-08-09 Sun 16:42

Validate

Lord knows I have trouble finding files sometimes. Over the years I’ve tried lots of schemes in Org Mode and elsewhere for the sole purpose of keeping track of stray items. Using includes in Org Mode has been helpful, but I didn’t have a way of jumping to those included files for quick access. Until now! Read on.

In this article, we’ll look at:

Let’s get into it.

Using ffap to jump to files

However, you may have noticed, these include lines don’t resolve as hyperlinks. So you cannot simply click an included file and jump to it.

This is where you can make use of the ffap (find file at point) command. It’s an interactive function that does exactly what it says: finds the file at your point.

If the filepath under your point resolves cleanly to a file, absolutely or relatively, you will have the option to open that file presented to you in the minibuffer.

The post Using ffap to jump to file includes in Emacs appeared first on Chris Maiorana.

Srijan Choudhary likes desktop-save-mode but he wants a slightly different behavior. He likes having his session configuration saved but he usually doesn’t want it restored. He wants to restore it only when he closed it by mistake or forget do something in the last session. Then, he wants to restore it by hand.

He could, of course, do this by disabling desktop-save-mode and calling the save and restore functions manually. The problem with that solution is that like most of us Choudhary would forget to do the save.

But this is Emacs so Choudhary was able to roll his own solution. That solution does the automatic save, as usual, but the restore function is disabled at system startup. Instead, the last save is added to a list of the last 5 saves. When he wants to restore a session, he’s presented with the list and can choose the save that he wants.

This is another great example of how Emacs lets you have it your way. His code is a little complex but there are a lot of desktop save peculiarities to account for. If you’re like me, you probably aren’t interested in this capability but that’s the point: even if you’re the only one who wants some functionality, Emacs will let you have it. This capability is something no developer is likely to anticipate so it provides another example of the superiority of Emacs’ method over the typical extension system provided by other editors.

Update [2026-08-10 Mon 10:52]: Added link to Choudhary’s post.

I’ve been cleaning out the loft, and I found this in a box. What kind of exciting pictures could lurk within!

Heh heh.

Right… during the 90s, while doing Gnus development, I sold a whole bunch of merchandise. These must be the mugs for Pterodactyl Gnus?

Man, so many shots, and almost all of them out of focus. I’m a master photographer, me.

Hey, that one’s in focus… kinda impressive height, eh?

Right, I didn’t “blog” about this until 2001, and by that time I’d bought a digital camera.

And I’ve still got a couple of mugs, almost three decades later. Quality!

The first batch had non-metallic non-dishwasher-safe printing (it turned out), so those degraded fast, but the second batch, with silver inks, is still going strong.

(Here’s a link to the other Gnus stuff I did back then… The 90s were fun.)

I want to be able to easily update YouTube captions from my VTT files. Adding a comment like this:

NOTE
#+YOUTUBE_URL: https://youtu.be/sxqsIgXYkVw
#+LANGUAGE: en

to the first subtitle in my VTT file lets me programmatically replace the captions for the specified language without needing to click through the YouTube interface, saving me at least 9 clicks, a slight delay, and the selection of the file. Now I can just bind it to C-c C-c when I'm working on correcting or translating captions.

;;;###autoload
(defun sacha-youtube-replace-captions (url language vtt-file)
  "Replace captions for URL in LANGUAGE with VTT-FILE."
  (interactive
   (let ((params (and (derived-mode-p 'subed-vtt-mode)
                      (sacha-subed-record-youtube-params))))
     (list
      (or (plist-get params :url)
          (read-string "YouTube URL: "))
      (or (plist-get params :language)
          (read-string "Language (ex: fr): "))
      (if (derived-mode-p 'subed-vtt-mode)
          (buffer-file-name)
        (read-file-name "VTT file: ")))))
  (let* ((video-id (sacha-org-yt-id url))
         (existing-captions (sacha-youtube-get-captions video-id))
         (boundary "---------------------------sacha_yt_caption_boundary"))
    (dolist (item existing-captions)
      (let ((snippet (alist-get 'snippet item)))
        (when (string= (alist-get 'language snippet) language)
          (sacha-youtube-delete-caption (alist-get 'id item)))))
    (let* ((metadata (json-encode `((snippet . ((videoId . ,video-id)
                                                (language . ,language)
                                                (name . ,language))))))
           (text (with-temp-buffer
                   (insert-file-contents vtt-file)
                   (buffer-string)))
           (body (concat "--" boundary "\r\n"
                         "Content-Type: application/json; charset=UTF-8\r\n\r\n"
                         metadata "\r\n"
                         "--" boundary "\r\n"
                         "Content-Type: text/vtt\r\n\r\n"
                         (encode-coding-string text 'utf-8) "\r\n"
                         "--" boundary "--\r\n"))
           (response (request-response-data
                      (request "https://www.googleapis.com/upload/youtube/v3/captions?uploadType=multipart&part=snippet"
                        :type "POST"
                        :headers `(("Authorization" . ,(format "Bearer %s" (sacha-google-access-token)))
                                   ("Content-Type" . ,(format "multipart/related; boundary=%s" boundary))
                                   ("Accept" . "application/json"))
                        :data body
                        :sync t
                        :parser #'json-read))))
      (message "Uploaded.")
      response)))

(defun sacha-youtube-get-captions (video-id)
  "Return the list of existing caption tracks for VIDEO-ID."
  (let ((response (request-response-data
                   (request (format "https://www.googleapis.com/youtube/v3/captions?part=snippet&videoId=%s" video-id)
                            :headers `(("Authorization" . ,(format "Bearer %s" (sacha-google-access-token))))
                            :sync t
                            :parser #'json-read))))
    (alist-get 'items response)))

(defun sacha-youtube-delete-caption (caption-id)
  "Delete the caption track identified by CAPTION-ID."
  (request (format "https://www.googleapis.com/youtube/v3/captions?id=%s" caption-id)
           :type "DELETE"
           :headers `(("Authorization" . ,(format "Bearer %s" (sacha-google-access-token))))
           :sync t))

(defun sacha-subed-record-youtube-params ()
  "Return directives related to YouTube."
  (save-excursion
    (goto-char (point-min))
    (unless (subed-subtitle-msecs-start) (subed-forward-subtitle-start-pos))
    (list
     :url (subed-record-get-directive "#+YOUTUBE_URL")
     :language (or (subed-record-get-directive "#+LANGUAGE")
                   (progn (goto-char (point-min))
                          (when (re-search-forward "^Language: \\(.+\\)\n" (or (save-excursion (re-search-forward "\n\n" nil t))
                                                                               (point-max)))
                            (match-string 1)))))))

The code uses some functions defined elsewhere in my configuration:

• Calculate an Org timestamp's offset into a YouTube stream: sacha-google-access-token and the gcloud auth command-line to get the https://www.googleapis.com/auth/youtube and https://www.googleapis.com/auth/youtube.force-ssl scopes
• YouTube: sacha-org-yt-id

You can e-mail me at sacha@sachachua.com.

After months of cooking, I am happy to announce that the mobile app is now
available for download at https://vakana.mg.

Some highlights

1. Fully offline. No ads, no data held hostage. Your data, your rules.
2. Flexible exports: Export your threads and beads to HTML (from
   templates), Markdown format (e.g., Obsidian), or rich Org files for Emacs
   users.
3. Built-in inspiration: Includes a list of use cases and possibilities.
   Find one that fits you.

Feel free to explore and share with friends.

Raw link: https://www.youtube.com/watch?v=QzhU6fklc4o

In this ~15-minute video I show how to add conditions to abbrev-mode abbreviations that you define. The idea is to have those abbrevs expand only in certain cases. I use three examples, which I think cover the common needs.

Code samples

(defun my-french-p ()
  "Return non-nil if `current-input-method' is French."
  (and current-input-method
       (string-match-p "french" current-input-method)))

(define-abbrev global-abbrev-table "welcome" "je t'en prie" nil :enable-function #'my-french-p)


(defvar my-notes-directory (expand-file-name "~/.emacs.d/abbrev-test/")
  "Directory where my notes are.")

(defun my-notes-directory-p ()
  "Return non-nil if we are in `my-notes-directory' or its subdirectories."
  (let ((current-directory (expand-file-name default-directory)))
    (string-prefix-p my-notes-directory current-directory)))

(define-abbrev global-abbrev-table "prot" "p’rǒt" nil :enable-function #'my-notes-directory-p)


(defun my-notes-keycast-mode-p ()
  "Return non-nil if `keycast-mode-line-mode' is enabled."
  (bound-and-true-p keycast-mode-line-mode))

(define-abbrev global-abbrev-table "prot" "Protesilaos, also known as Prot" nil :enable-function #'my-notes-keycast-mode-p)

Ashish Panigrahi has an interesting post on customizing his agenda view. He’s a graduate student, apparently in the sciences, and has to keep track of his tasks and their statuses. The natural solution for us Emacsers is to use Org mode and the agenda view to track these things.

There’s nothing exciting about that, of course, but what makes his post interesting is that he shows how to create a custom agenda view. It’s easy to make a custom view and I have a lot of them but they’re pretty simple. Panigrahi views are more complex and he demonstrates how to specify more intricate criteria for the view.

For his main view, he wants to show tasks that he’s completed since his last group meeting. That means he wants to filter for tasks completed in the last 7 days that aren’t personal items. He also wants to keep tags, so he makes sure they aren’t removed.

Finally, since he often consults this view, he has a function that calls it with a simple Ctrl+c w rather than having to go through the agenda dispatch menu.

As I said, you probably won’t care about his particular view but it’s instructive to see how he defined it as a jumping off place for your own views.

Protesilaos Stavrou (Prot) has another excellent video. This time it’s on it’s on the Emacs speedbar and its Emacs 31 upgrade. The TL;DR is that as of Emacs 31, you can configure the speedbar to be displayed in a separate window instead of a separate frame. The video is 15 minutes, 39 seconds so it should be easy to find time for it.

The placement of the speedbar matters a lot to Prot. He found the speedbar to be unusable when it was displayed in a separate frame because it was difficult to deal with the two related frames. It’s absolutely impossible for me to deal with because I run Emacs as a full screen app so the speedbar is in another workspace and I have to switch to that workspace to see it.

Now that the speedbar can be displayed in the same frame, Prot finds that it can be useful when dealing with large projects with many files. His video is mostly concerned with showing how the speedbar works and what you can do with it.

Lots of people love speedbar-like applications and swear by them. I, however, have never been able to warm up to them. These days, I don’t work with large projects and perhaps I’d feel differently if I did but mostly they just seem like noise to me. Even Prot says he doesn’t use speedbar for his smaller personal projects but that it can be useful for larger, multi-file projects.

My recommendation is that if you don’t already strong opinions on the matter, give the speedbar a try when Emacs 31 comes out and see if it works for you. There are plenty of informed opinions on both sides of the issue so there’s no right answer, just what works for you. As always, Emacs will let you have it your way.

I started going through the The Rust Programming Language to learn rust. I’m using the rustic package to edit files, run cargo, etc.

Having run cargo build in the sample hello_cargo project, I wanted to run the executable file from within Dired. I realized there’s no obvious way to do this in Dired or Dired-X, and that’s probably a good thing. If it was easy I can imagine all sorts of havoc with people accidentally, or intentionally, runnning files out of Dired. Too easy.

But it occurred to me that bash has command to run the next word in the command line as a command. I tried ! command in Dired, but since the directory isn’t in the path, it told me

/bin/bash: line 1: hello_cargo: command not found

Okay, update PATH before running command: ! PATH=.:$PATH command. This actually works, but decades of training give me a queasy feeling about adding . to PATH. How about $PWD instead? ! PATH=$PWD:$PATH command. Yep, that works too.

But of course, with rustic, I can use C-c C-p r to run cargo run to run the command. But trying to run the file on the line in Dired was an interesting diversion!

Prot et moi avons parlé en direct avec Richard Bonichon (emacs.d, GitHub) d'Emacs, d'OCaml, de ses flux de travail, de sa configuration et d'autres sujets en français.

J'ai raté le début de la diffusion en direct. Je suis vraiment désolée ! Heureusement, j'ai enregistré toute la conversation localement. Voici la vidéo complète :

J'ai essayé de corriger la transcription (voici le fichier VTT), mais je crois qu'il y a encore beaucoup d'erreurs, donc n'hésitez pas à m'envoyer un message.

Merci beaucoup à Richard, à Prot, et à tous les auditeurs ! À la semaine prochaine pour le 13 août : Emacs Chat avec Fabrice Niessen !

Si vous voulez parler d'Emacs avec Prot et moi en français, n'hésitez pas à me contacter!

You can e-mail me at sacha@sachachua.com.

Before I start writing in Org, I dedicate the window. This "protects" the content, preventing it from being replaced by something else. It ensures I can stay focused on my writing no matter what other buffers Emacs opens.

My usual workflow is to display help on the functions I write about. Emacs opens the help buffer in another window. That's good. But then if I click on the link to the source code that help references, that file will open in my writing window, and I lose focus. Dedicating the window prevents this.

I could dedicate a window manually by invoking toggle-window-dedicated (bound to C-x w d) every time I start writing. But because I clock in to anything I'm serious about, I let org-clock-in-hook to do it for me as shown below. Note that the hook calls set-window-dedicated-p rather than toggle-window-dedicated because the latter will un-dedicate a window that's already dedicated. I could configure org-clock-out-hook to un-dedicate the window; I'm debating whether it's necessary.

(add-hook 'org-clock-in-hook (lambda () (set-window-dedicated-p nil t)))

Interestingly, while I was writing this, JTR published his "Gems" article in which he writes about setting help-window-keep-selected to true "to keep help in its own dedicated window, so it won’t open in a separate window once we follow a link."¹ Perhaps that’s his approach to the same issue.

¹ Emacs Config Gems - Part 3

Over at Ray on Emacs, Raymond Zeitler has an interesting post on displaying the Org clocked in status. The default is to display it in the mode line but Zeitler wanted to display it in the title bar too. It turns out you can turn it off, display it in the mode line, display it in the title bar, or display it in both the mode line and title bar. These choices are controlled by the org-clock-clocked-in-display variable.

If you regularly clock in your tasks, having flexibility in where the status is displayed could be useful. The problem is I couldn’t find any reference to this variable in the help system or in timeclock.el, which handles the seemingly related timeclock-mode-line-display.

I updated my packages to make sure I had the latest Org Mode (I’m on Org 9.8.8) but I got the same results. I’m guessing that Zeitler is using one of the Emacs 31 prereleases, which implements this. If you’re interested in this feature and are on Emacs 31Try it on your system and see what happens. If it works for you, leave a comment.

Emacs has a built-in way to save and restore sessions: the desktop.el library.

As the Emacs manual says, putting this in the init file enables automatic save and restore of sessions:

(desktop-save-mode 1)

But, I wanted a different behavior:

• Automatically save the session
• But don't restore it automatically

I wanted to only use the session feature to restore sessions that I closed by mistake, or where I forgot to finish something before quitting Emacs. By default, I wanted a fresh session every time.

But this also means that some session history has to be maintained; otherwise, a fresh session will start to write to the desktop file and then I will not be able to recover the old session.

By default, the way to do this is to not set desktop-save-mode, but manually call desktop-save when needed, and then call desktop-read when needed. But, if I forget to save, I cannot restore.

This elisp is what I came up with to make it work the way I want:

(defvar my/desktop-snapshot-keep 5
  "How many previous sessions to keep desktop snapshots for.")

(defun my/desktop--snapshots ()
  (nreverse (directory-files desktop-dirname t
                             (concat "\\`" (regexp-quote desktop-base-file-name)
                                     "\\.[0-9]\\{8\\}T[0-9]\\{6\\}\\'"))))

(defun my/desktop--take-snapshot ()
  (let ((live (desktop-full-file-name)))
    (when (file-exists-p live)
      (let ((dest (concat live (format-time-string
                                ".%Y%m%dT%H%M%S"
                                (file-attribute-modification-time
                                 (file-attributes live))))))
        (unless (file-exists-p dest)
          (copy-file live dest t t)))))
  (dolist (old (nthcdr my/desktop-snapshot-keep (my/desktop--snapshots)))
    (delete-file old)))

(defun my/desktop--label (file)
  (format "%s   %d buffers"
          (format-time-string "%Y-%m-%d %H:%M:%S"
                              (file-attribute-modification-time
                               (file-attributes file)))
          (with-temp-buffer
            (insert-file-contents file)
            (how-many "^(desktop-\\(?:create-buffer\\|append-buffer-args\\) "
                      (point-min) (point-max)))))

(add-hook 'emacs-startup-hook
          (lambda ()
            (require 'desktop)
            (setq desktop-dirname (expand-file-name user-emacs-directory))
            (my/desktop--take-snapshot)
            (desktop--get-file-modtime)
            (let ((owner (desktop-owner)))
              (unless (and owner (desktop--emacs-pid-running-p owner))
                (desktop-claim-lock)))
            (desktop-save-mode 1)))

(defun my/desktop-restore (file)
  "Restore the desktop snapshot FILE, prompting for one interactively."
  (interactive
   (progn
     (require 'desktop)
     (let* ((snapshots (or (my/desktop--snapshots)
                           (user-error "No desktop snapshots in %s"
                                       desktop-dirname)))
            (choices (mapcar (lambda (f) (cons (my/desktop--label f) f))
                             snapshots)))
       (list (cdr (assoc (completing-read "Restore desktop session: "
                                          choices nil t)
                         choices))))))
  (desktop-release-lock)
  (let ((desktop-base-file-name (file-name-nondirectory file)))
    (desktop-read (file-name-directory file)))
  (desktop--get-file-modtime))

Note that desktop-save-mode must not be enabled before after-init-hook fires, because that's where desktop.el decides to automatically restore. So, I enable it in emacs-startup-hook, which runs later. Other things inside my emacs-startup-hook lambda are workarounds for how desktop.el works, so they can be fragile if there are major changes to it.

The lock check avoids a stale lock from a crashed Emacs silently disabling auto-save, and naming snapshots after the desktop file's mtime means restarting without saving anything doesn't use up one of the five slots.

Here's what it looks like when I call my/desktop-restore:

Of course, this can be made better by showing more information per session (like number of projects, names of last edited files or last visited buffers). Vertico/marginalia can show it nicely. Also maybe a section in emacs-dashboard to show recent sessions and click/enter to restore. Something for another day.

I thought it would be helpful to modify the title of the Emacs frame to display the Org task I'm clocked in to. It turns out to be a lot easier than it sounds -- just change one Org variable in Customize.

The variable is org-clock-clocked-in-display. Its default value is mode-line. This means that the active clock displays only in the mode line. But it can have one of three other values: nil, frame title, both.

I've set it to both. Now the clocked task displays in both the mode line and the frame title. It shows the clock duration in square brackets followed by the task heading in parentheses, as shown below.

This simple update has improved my productivity significantly. The prominent display of the clocked task reminds me of what I started to do before I went down yet another rabbit. Not that rabbit holes are all bad -- I was in a rabbit hole yesterday when I found org-clock-clocked-in-display.

Try it out!

My actual configs start with pretty usual stuff you’d see across many other Emacs configs. As I was going through these however, I started to wonder how things work and why they ended up the way we have them today. In turn, that led to reading about the intention behind those, which led to more options I didn’t think about. Also, it’s kind of fun. I’ve made two more passes for this part alone in the last couple of weeks, and I could probably go for a third. When reading this post, if you want the good stuff (in my opinion), get lost in the footnotes as I did. There’s a lot to explore. I just scratched the surface.

Load Melpa

Melpa is where many Emacs packages live. The story behind it (from what I can tell) revolves around one of Emacs’ maintainers, Bozhidar Batsov, who pointed to Melpa at some point in 2012, when Emacs’s then go-to third-party package repository went offline. He is not its creator — Melpa has been around before this post — but this seems to be the turning point where Emacs package maintainers started to really use it. I don’t have good coder/repository maintainer knowledge, but from what I read, it’s built on the same idea as Homebrew (for Mac), which was familiar to many of the Emacs folks at the time.

So let’s get Melpa:

(require 'package)
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)

UI and Fundamental Emacs tweaks:

Most Emacs folks with a config file like this like to kill the toolbar, scrollbar, and menu bar. I find that the menu bar makes Emacs look more like the other programs, especially in macOS¹. Besides, it’s nice to look every now and then and be reminded of good Emacs kung-fu I forgot exists (org-sort, I’m sorry my friend, I’ll keep saying hi more often).

This is why the menu-bar is commented out in my config; I want it, but I also want to remember I could turn it off if I wanted:

(tool-bar-mode -1)
(scroll-bar-mode -1)
;; (menu-bar-mode -1) 

By default, help commands² display the help buffer in a new window without selecting it. I find this annoying: if I bring up the help window, it’s usually because I want to scroll down to find something or copy (yank) something. On the other hand, if I just want to skim quickly in the help buffer, it’s helpful that the marker is on it for a quick q for quit.

In addition, we want to be able to navigate help menus as Emacs intended if we follow the links in a help buffer. help-window-keep-selected allows us to keep help in its own dedicated window, so it won’t open in a separate window once we follow a link. Going back to the original is the same as we do in other browser-like buffers in Emacs, with l (like in Eww, for example). Likewise, we can go forward with r. I should also expand here on various help options; they definitely deserve a mention, but this is another huge topic (you can get an idea from the footer) that will take a couple of weeks. I will come back to this someday.

(setq help-window-select t)
(setq help-window-keep-selected t)

Lisp is full of parentheses, and it’s easy to lose track. Turning show-paren-mode on means that standing on an open or closed parentheses highlights its matching counterpart, which is handy.

In addition, while we’re here: when we stand on an expression that is only showing a portion of an expression (meaning, we need to scroll down to see the rest) Emacs can highlight the expression for us to make sure we don’t get confused — this is the mixed option below for show-paren-style. If you want to see the whole expression highlighted every time you’re on it, there’s the option expression, which I’m leaving here for reference for myself. For now, I think it’s too much visual noise, especially since we’re using org-edit-special, which also highlights what we’re working on.

  (show-paren-mode t)
  (setq show-paren-style 'mixed)
;; (setq show-paren-style 'expression)

And now, a true Emacs classic. I don’t think I’ve seen a config without it: shortening “yes” or “no,” answer to “y” or “n” like any other program known to mankind. use-short-answers was introduced in Emacs 28.1, which is a more graceful way to do this, intended exactly for this purpose. Before that, back when I started to use Emacs, it was done with (fset 'yes-or-no-p 'y-or-n-p). If you have an older Emacs version, you’d need it.

;;  (fset 'yes-or-no-p 'y-or-n-p)
(setq use-short-answers t)

This one was annoying until I learned this option exists from someone else’s config years ago: “Emacs, please stop asking me if I want to kill process when exiting Emacs (Shell, etc.), just do it!” Yep.

(setq confirm-kill-processes nil)

Emacs has two annoying keyboard shortcuts that I should have disabled as soon as I started using it: C-x C-c (exit Emacs) and C-z (minimize Emacs). Both of them are too easy to press by mistake, especially C-z, which is undo in many other programs. If I had a penny for each time I minimized Emacs by mistake… When we want to minimize Emacs (and why would you want to do that? Emacs deserves a prominent space on your screen), we can just do it by clicking the minimize window itself, shamefully using our mouse, as we do with other apps. And Exiting Emacs? With a shortcut that seems like it fits somewhere in org-mode? No thanks. Let’s disable those:

(global-unset-key (kbd "C-x C-c"))
(global-unset-key (kbd "C-z"))

Turn off the annoying error beep, which I first discovered in SUSE Linux by turning on a visual warning (a flash) instead. This will flash the top and bottom lines of our window instead of going “beep!”

(setq visible-bell t)

Turn on visual line mode so text lines “wrap” inside the frame and don’t continue beyond the window’s edge. This is essential; I can’t read in Emacs without it. And a newcomer I discovered recently: since Emacs 30, we also have global-visual-wrap-prefix-mode, which preserves indentation on wrapped lines. For example, in a list in org-mode (made of dashes one under the other), a long line of text that wraps will align under its starting point (dash) in the list instead of jumping back to column 0 (the start of the window, to the most left). This has been a huge pet peeve. Finally!

(global-visual-line-mode t)
(global-visual-wrap-prefix-mode t)

Winner mode (included in Emacs) is sort of “undo” for changes in windows’ layout in Emacs. C-c ← goes back to our previous setting, and C-c → will “redo” the layout we just left. I use it all the time as in “oops, I closed the wrong window”³.

(winner-mode t)

Saw this over at https://emacsredux.com/blog/2026/04/07/stealing-from-the-best-emacs-configs/. This is a nice little trick, and it requires a bit of reading to understand what exactly it does: preventing Emacs from deleting whatever we have in the system’s clipboard when we kill a line, so it’s still in the kill ring. Here’s an example to help you grasp the idea and why it’s useful:

1. We’re visiting a website with our default browser and copy its URL because we want to write about it in Emacs
2. We go to Emacs, and we kill the line we’re on because we need some space
3. Crap! Now we lost our paste in the clipboard, and we have to go back to the browser and grab that URL again!
4. Wait, which tab was it? Did we close it? Should we look in our browsing history? Ugh!

Not anymore! With this little guy, when we kill the line (step 2 above), Emacs “injects” it into the kill ring. Now, when we yank with C-y, we will still get the last line we killed, yes, butlook up the kill ring with M-y and voilà! Your URL is there. No need to go find that URL again:

(setq save-interprogram-paste-before-kill t)

You know how for years Emacs “jumped” when you scrolled down large embedded images in your org buffers? Let’s turn on pixel-scroll-precision-mode for pixel scrolling instead of the default line scrolling to fix this. It’s pretty much what it reads: the default old way would “scroll” (it’s actually not scrolling at all) by a line of text at a time. Since our image of, say, 600px in height is treated as a single line of text, it will jump to the end of it. With this option turned on, Emacs would read the pixels from your mouse wheels as you scroll, and we get the smooth scrolling we’re used to.

Interesting to know: moving up and down the line without a mouse (arrows, or C-p and C-n) is moving by text lines, utilizing auto-windows-vscroll and line-move, which basically does in Emacs what arrow movement seems to be doing in modern applications: these apply this principle from the other direction — they natively work with pixels, so they treat these arrow movements as a fixed number of pixel movements, which is approximately a line of text. So, when you move up and down a large image (or say a PDF) in a browser, the browser thinks “ok, the user is moving up one line of text, which is.. hm.. let’s see… ah, it says it’s exactly 40 pixels, so let me show that”.

(pixel-scroll-precision-mode t)

test break

“Emacs is the editor of tinkerers and artisans; those who are eternally dissatisfied with all other tools because of their adamantine rigidity. Crafting, or shaping, your tools to meet your exacting needs is what Emacs excels at. Because of that, Emacs is – much to the chagrin of everyone who picks it up for the first time – squarely aimed at people who already know Emacs.”

In fact, if you’re curious about help and Emacs help, I suggest you head over there now and read that post. It expands on how to approach Emacs help by how to think Emacs, which is something that experienced Emacs users struggle to explain to newcomers.

As for the history of help in Emacs, I think it’s pretty safe to say it’s been there since the start, or at least since Emacs became intended for public use, sometime around the 1980s. By that point, most of the core help parts we know today (the tutorial, C-h t; the Emacs Manual, C-h R; as well as the framework itself) were already in place. The help system was there before GNU Emacs, back in the days of TECO Emacs that RMS worked on at MIT in the 1970s. You could browse the original code from then (preserved by MIT) and see how Stallman explained what certain commands do in emacs.doc inside that repository. Another interesting find about Emacs itself (and the help system that comes with it) is the EMACS paper written by RMS back in 1981. For the help system, take a look at page 17: “6. Self-Documentation and Extensibility” and the following chapter in page 18: “7. History”. Fascinating stuff.

Raw link: https://www.youtube.com/watch?v=Crn6x3RmmyQ

In this video I demonstrate the built-in ‘speedbar’ command. This is the file explorer that Emacs ships with. Starting with Emacs 31, the ‘speedbar’ can be configured to appear on the side of the frame. Whereas the default is to show up in a separate frame. To me, the default is impractical, whereas the new option turns ‘speedbar’ into a very useful piece of functionality.

The first time I opened a web page inside Emacs I thought it was a trick, a hack, a toy... studying it in depth I saw I was wrong. EWW is a browser written 100% in Emacs Lisp, with no external engine behind it (no WebKit, Blink or Gecko). It is absurdly lightweight, intelligently designed and, almost without meaning to, it hands you a platform to do scraping or automate web tasks in a few lines. A tool with enormous potential that many people don't know about, even within the Emacs community itself.

And the best part is that you already have it installed. It ships with Emacs by default. To launch it just run M-x eww and type a URL or a search term (it will open DuckDuckGo).

Is it a replacement for Chrome or Firefox? No, and it doesn't try to be. It plays in a different league.

Two pieces: EWW and SHR

What we call "the Emacs browser" is really two pieces working together.

• EWW (eww.el) is the browser layer: URLs, history, bookmarks, forms, cookies, downloads and sessions.
• SHR, or Simple HTML Renderer (shr.el), is the engine that turns HTML into text inside a buffer. And EWW is not the only one using it: Gnus for mail, elfeed for feeds, and quite a few other packages share it too.

Here's the key: SHR doesn't draw a page, it translates it. It takes the HTML and paints it as Emacs text, with its faces and its properties. What does it understand along the way? Quite a bit more than you'd imagine:

• Rich text: b, i, em, strong, u, s, code, tt, mark, ins, del, sup, sub, abbr, bdo/bdi.
• Structure: h1..h6, p, div, blockquote, pre, hr, ul/ol/li, dl/dt/dd.
• Links and tables.
• Images: it understands data: URIs (base64), srcset (it picks the resolution), cid: (mail), scaling with shr-max-image-proportion, animation and zoom. And if a src is broken, it falls back to its alt text, as it should.
• MathML: it keeps the TeX annotation, it does not render the formula.

Forms are a curious case: SHR doesn't add them, EWW layers them on top via shr-external-rendering-functions. Thanks to that you can submit GET and POST forms, and even multipart/form-data to upload files.

Two things are missing from the list: JavaScript and CSS.

What EWW doesn't do (and why that's fine)

EWW is not meant to run modern web applications. Its limitations aren't an oversight, they are the reason it's so fast and so lightweight. But you'd better be clear about them before you get frustrated.

No JavaScript. This rules out, in one stroke, any SPA (React, Vue, Angular), infinite scroll, content that arrives via fetch or XHR, and most of today's web. If a page needs JS to paint itself, in EWW you'll see little or nothing.

No CSS. The code itself confesses it in its header: "It does not do CSS, JavaScript or anything advanced". In practice:

• <style> sheets and <link rel=stylesheet> are ignored completely. Only the inline style attribute is read, and only if it contains color, display (specifically none) or border-collapse. Everything else (font-size, margin, padding, float, flex, grid, text-align...) is thrown in the bin.
• Colors require (display-color-cells) >= 88. And the contrast system is surprisingly serious: it converts to CIE Lab and uses CIE DE2000 distance to make sure the text is readable.
• There are no class or id selectors, no cascade, no specificity. Nothing.

The parser is not HTML5-conformant. It uses libxml2, which is tolerant but does not follow the HTML5 parsing algorithm to the letter. Manual patches are applied to plug the holes.

EWW is not for SPAs, online banking, JS dashboards, dynamic forms, anything that throws a "enable JavaScript to continue" at you, embedded video or audio, or layouts that are only legible thanks to CSS. It's not its turf, and forcing it is a waste of time.

Scraping out of the box

EWW leans on libxml-parse-html-region, which gives you back the DOM as an S-expression. And Emacs includes dom.el to walk it. That makes scraping trivial, and you don't even need to open EWW.

Look at this script. It extracts the headlines from the Hacker News front page:

(require 'dom)
(require 'url)
(require 'cl-lib)

(defun demo-scrape (url)
  "Download URL and return the Hacker News headlines as a list of conses.
Each element is (TITLE . HREF)."
  (with-current-buffer (url-retrieve-synchronously url t t 30)
    (goto-char (point-min))
    ;; Skip HTTP headers until the first blank line.
    (re-search-forward "\r?\n\r?\n" nil t)
    (let* ((dom (libxml-parse-html-region (point) (point-max)))
           ;; On HN each headline is <span class="titleline"><a>...</a>.
           (titles (dom-by-class dom "titleline")))
      (mapcar (lambda (node)
                (let ((a (dom-child-by-tag node 'a)))
                  (cons (string-trim (dom-texts a))   ; link text
                        (dom-attr a 'href))))          ; destination
              titles))))

(defun demo-scrape-hn ()
  "Download the Hacker News front page and show the headlines in a buffer."
  (interactive)
  (let ((items (demo-scrape "https://news.ycombinator.com/")))
    (with-output-to-temp-buffer "*HN headlines*"
      (princ (format "Headlines found: %d\n\n" (length items)))
      (cl-loop for (title . href) in items
               for i from 1
               do (princ (format "%2d. %s\n    %s\n\n" i title href))))))

;; Evaluating the buffer (M-x eval-buffer) runs it directly:
(demo-scrape-hn)

Evaluate it with M-x eval-buffer and a temporary buffer will pop up with the list of headlines and their links. No external libraries, nothing to install.

This is possible because dom.el gives you a handful of functions that do the heavy lifting: dom-by-tag, dom-by-class, dom-by-id, dom-child-by-tag, dom-attr, dom-text and dom-texts. And if instead of the raw HTML you want the already-rendered text (for example, to index the "readable" version of a page), you can run the DOM through shr-insert-document in a temporary buffer and keep buffer-string. This is, literally, the foundation on which elfeed or mu4e are built.

Designing "for EWW" is designing well

Let me switch perspective. So far we've talked about EWW as a reader. But what if you're the one publishing? What if you want your site to look flawless in there?

The good news is that designing for EWW isn't learning some weird dialect. It's going back to the principles of semantic HTML, the ones that should never have been abandoned. EWW renders HTML as a structured document, not as a canvas painted with CSS. Follow these ideas and, as a bonus, your site will be more accessible everywhere.

DOM order is on-screen order

SHR walks the tree in document order and inserts the text just as it finds it. There is no CSS reordering: float, flex, grid, order and position don't exist. Whatever you put first in the HTML appears first.

So place the main content as early as possible in the DOM, or at least right after opening the <body>. Long <nav> blocks and footers go at the end.

Mark up structure with tags, not with styles

SHR gives its own faces to h1..h6, b/strong, i/em, u, code, pre, blockquote, lists, mark and del/ins. Use them for what they mean, not for how they look:

• Real headings <h1>..<h6> for hierarchy. Never a <div class="big">.
• <ul>/<ol>/<li> for lists and <dl>/<dt>/<dd> for definitions.
• <blockquote> for quotes (it indents) and <pre> for preformatted blocks or ASCII art (it disables reflow).
• <code> for inline code (fixed-width face).

Watch out for the HTML5 semantic elements (article, section, nav, header, footer, main, aside, figure): they have no render of their own. They're treated as transparent containers and only contribute their textual content. They're fine for giving meaning to the document, but don't expect them to "show".

Don't rely on CSS for anything essential

You already know: only the inline style attribute is read, and only color, background-color, display and border-collapse. The rest is ignored. From that come three rules worth tattooing on yourself:

• Your page must be legible with CSS completely disabled. If it isn't, that's not an EWW problem, it's an HTML problem.
• Don't hide content with a display:none class. SHR won't apply it and that content will show up anyway. If you really need to hide something it would have to be style="display:none" inline, but that's bad practice. Better not to put that content in at all.
• Don't convey information with color alone. Even though inline color works, it demands enough contrast (that strict CIE DE2000 filter) and on poor terminals it isn't applied at all. A "required field in red" or a "green = correct" vanishes. Always back it up with text or symbols.

And a consequence that sneaks in: spacing (margin, padding, line-height) doesn't exist. Separation comes from paragraph breaks. Structure with real <p> tags, not with stray <br> or empty divs.

Tables: for data only, never for layout

SHR draws <table> as a surprisingly good ASCII grid: it measures columns, distributes widths and even emulates colspan and rowspan. But it has its rules:

• Use them only for real data. A layout table produces an absurd, illegible grid.
• Watch the width. If the sum of the columns exceeds the frame, EWW just turns on truncate-lines and the experience degrades. Fewer columns and short cells fare much better.
• Images inside cells aren't embedded in the cell (a buffer limitation): they're inserted after the table. If order matters, avoid images in there.

Images with alt and srcset

Yes, Emacs shows images in graphical buffers. But don't get cocky:

• Always give a descriptive alt. It's what shows if the image is blocked, broken or if the user browses without images. In many EWW flows, the alt is the content.
• srcset is supported: EWW picks the right resolution for the frame width, so offer it several.
• Images load asynchronously over a placeholder, they don't block the text render. Don't rely on an image to communicate anything critical.
• data: URIs (base64 included) work, handy for small embedded icons.

Forms that actually work

Forms are fine if they're pure HTML with action and method (GET or POST, including multipart/form-data for files):

• No JavaScript submissions (onclick, fetch). Use a real <form> with its <input type="submit"> or <button>.
• Put name on every field and value for the defaults. EWW collects by name.
• The recognized text types (text, password, email, number, date, color and textarea itself...) are painted as editable fields. The rest degrade to text. checkbox, radio and select work.
• Associate a <label> with each field: keyboard navigation will thank you.

Help the readable mode

If you want your article to look perfect with eww-readable, know your enemy. Its heuristic scores each node by word count, penalizes links (it subtracts their words), rewards images, and keeps the node with more than 100 words and the highest score.

The practical takeaway? Wrap the body of the article in a single container with lots of continuous text and don't chop it up into a thousand tiny divs full of links. An <article> or a <main> with long paragraphs wins. A tangle of <div> with navigation loses.

Headers and metadata that do count

Four small details that make a difference:

• <title>: shown in EWW's header line. Always set it and make it descriptive.
• <meta charset>: EWW uses it as an encoding fallback. Declare UTF-8.
• <base>: respected, useful for resolving relative links.
• HTTPS with a valid certificate: EWW colors the header-line title according to the TLS status. Serve your site over HTTPS.

So, what is it good for?

EWW is an excellent HTML document reader and a deliberately incomplete web browser. And once you accept that duality, it fits like a glove in a handful of scenarios:

• Reading without leaving Emacs: documentation, blogs, articles, wikis, HTML man pages... with all your usual keys and with isearch.
• Focused reading: the readable mode, with its word-density scoring, leaves the text and nothing else. No noise.
• Low bandwidth and zero distractions: no ads, no JS, no pop-ups, no telemetry. Accessibility out of the box.
• Feeds and mail with HTML: remember that SHR is what Gnus, elfeed and mu4e use underneath.
• A single flow: search and open links from Emacs itself, with bookmarks, history, multiple buffers or tabs and sessions.
• Scriptable: you parse the DOM from libxml-parse-html-region directly and automate whatever you want.

Its philosophy is the opposite of a modern browser. Instead of emulating a graphical rendering engine, it translates semantic HTML into Emacs text. Anything that is a "document" works very well and very fast. Anything that is a "web application" doesn't work at all. And that's the beauty of it: it won't pass the Acid3 test, but not out of deficiency, out of design.

Help me keep writing Every coffee gives me a push toward the next article. Sure, it's on me!

Send an email to comment+article-e0e00b4b@andros.dev to leave a comment. The subject will be ignored.

Introduction

In my years of using Emacs, I’ve noticed a common pattern: developers who are highly proficient at editing source code in Emacs switch to a “normal IDE” (as they call it)—such as CLion or Visual Studio—when they need to debug their code. They usually explain this by saying that Emacs feels a bit weird for the task.

However, I’d much rather not leave Emacs if something can be done inside it.

In this post, I’ll try to show that debugging in Emacs is both simple and effective, especially after a few small adjustments to the default settings.

Debugging in Emacs revolves around two key components:

1. GDB (GNU Debugger), the most popular and powerful debugger for C, C++, and other languages.
2. GUD (Grand Unified Debugger), Emacs’ built-in interface since at least v19 that turns GDB into a well-integrated debugging environment inside Emacs, allowing you to debug your code without leaving the editor.

A Sample Debug Session

Below is an example of a typical debug session of mine.

In Emacs, I open a source code file (timepoint.c in this example) and run M-x gdb. GDB then prompts in the minibuffer for the path to the corresponding executable, as shown below.

After you enter the path to the executable—assuming it was built with the -g flag (i.e., compiled with debug information)—and press Enter , GDB prints some initial output and may ask whether it should automatically download missing debugging information from trusted online servers.

Because I don’t intend to debug system or third-party libraries, I simply press n to skip this step, which can occasionally freeze Emacs for a while.

The GUD dashboard appears. It usually consists of 6 windows.

• Debugger, the GUD interaction buffer (or GDB shell);
• C/*, the source code buffer;
• Frames, the stack buffer, a list of stack frames of the program being debugged;
• Locals, the local variables/registers buffer;
• Inferior I/O, the input/output buffer (usually associated with stdin/stdout);
• Breakpoints, the breakpoints/threads list.

In my usual workflow, I type break main (or simply b main) in the GUD interaction buffer (Debugger) to set a breakpoint at the start of my program.

The new breakpoint shows up right away: as a red fringe marker next to the line in the source buffer (color varies by theme) and as an entry in the breakpoints list.

Now you can type run in the GUD interaction buffer. Execution will then stop at the first breakpoint (line 20 in this example).

GUD Keybindings

Frankly, I find the default GUD keybindings somewhat complex. For example, C-x C-a C-n is the globally defined key chord for gud-next — one of the most frequently used debugging commands. Having to type three keys while holding the Ctrl key feels excessive to me, so I prefer a single keystroke for this operation.

So, in my ~/.emacs, I’ve rebound the most frequently used GUD commands to F6 and its derivatives.

(global-set-key [(f6)] #'gud-next) ;; Execute the next single line.
(global-set-key [(control f6)] #'gud-step) ;; Enter the called function.
(global-set-key [(shift f6)] #'gud-cont) ;; Continue execution until hitting a breakpoint.
(global-set-key [(control shift f6)] #'gud-print) ;; Evaluate the expression at point.

I’ve kept the default keybindings for the less frequently used commands, such as setting a breakpoint (gud-break, C-x C-a C-b), continuing execution to the current line (gud-until, C-x C-a C-u), and so on.

Additionally, I’ve added a new keybinding for gud-watch (C-x C-a C-w), which watches the expression at point. This command has no default keybinding in GUD, at least in Emacs 29.3.

(global-set-key (kbd "C-x C-a C-w") #'gud-watch) ;; Watch the expression at point.

Debugging

Let’s continue with our sample debugging session.

We stopped at line 20, the first breakpoint in my program. Now I want to step through the function print_timepoint line by line. In the source code buffer, I move the cursor to line 9 and set a new breakpoint with C-x C-a C-b (gud-break). Then I continue execution with Shift + F6 (gud-cont) until the new breakpoint is hit.

After stepping through the function line by line with F6 (gud-next) until the end (line 16), I get the following output:

In the Locals buffer, you can see all local variables and their current values. The Inferior I/O buffer shows the program output. Everything looks correct: the tpoint variable has the value 0, which corresponds to the beginning of the Unix epoch (January 1, 1970).

Indeed, we could have inspected the print_timepoint function by simply stepping into it (gud-step, Ctrl + F6) directly from the first line of main, where the initial breakpoint was set. I used this example to demonstrate more GUD commands in action.

Now we can quit the debugging session by typing quit (or simply q) in the GUD interaction buffer (Debugger).

Of course, there’s no way to cover all the functions and commands available in GDB/Emacs GUD in one short post but I hope it provides a helpful introduction to using Emacs GUD for debugging your code.

You can find more information in the Running Debuggers Under Emacs manual; the GDB Cheat Sheet (PDF) is also worth having on hand.

Happy debugging in Emacs!

— The Emacs Cat.

For me, listening to music whenever I’m working on a computer is a commonplace, daresay essential activity. Much of my work is done using Emacs, so the idea of having it control music playback to mitigate an app switch seemed reasonable. Such was the motivation for my latest project, now-playing.el, a Transient interface for the macOS Music (nee iTunes) app.

now-playing.el takes inspiration from the many mini-client interfaces provided by Apple to control the Music app. The idea was to have a compact and simple interface:

• Show what is currently playing (song, artist, album)
• Offer basic controls (play/pause, next/previous track, volume control)
• Optionally log what was played.

now-playing.el takes advantage of AppleScript support in the Music app, providing the needed controllability and observability of it from Emacs. The sequence diagram below illustrates how these programs relate to each other by showing a request/response transaction between Emacs and the Music app using the osascript command line tool.

If Emacs is built with NextStep (NS) support, then Emacs can send a direct AppleScript message to the Music app via ns-do-applescript to avoid making a shell call to osascript.

State synchronization for now-playing.el is fairly simple, with client updates done in a pull fashion. More details about what now-playing.el can do can be found in the now-playing.el User Guide.

Closing Thoughts

It is not coincidental that writing this mini-client for the Music app works into my recent explorations and musings on malleable computing with Emacs. As of this writing, now-playing.el weighs in at 326 lines of code (cloc measured), taking full advantage of Elisp libraries to construct the following client subsystems:

• UI: Transient for menu, cus-edit.el for customization UI
• Client Edge: shell-command-to-string to osascript, ns-do-applescript
• Local Database: Elisp variables

now-playing.el explores integration with AppleScript, itself a mechanism to allow for orchestration between Cocoa applications. Expect some future posts documenting my explorations in this area, particularly with the more contemporary Apple Shortcuts and Intents.

now-playing.el v1.0 is now available on MELPA.

Irreal, as you all know, is an em-dash friendly site. Irreal has always liked them and now we like them even more because it puts a thumb in the eye of those mentally challenged folks who claim, erroneously, that “real people” don’t use em-dashes and their presence in a document is a sure sign of AI generated text.

It turns out that JTR over at The Art Of Not Asking Why is also an em-dash aficionado and has been struggling with how to enter them, especially when using Emacs. His final solution involves expand-abbrev but seems to me overly complicated. He types --- then immediately calls expand-abbrev by typing Ctrl+x `.

We here at Irreal have the same problem, of course, but solved it in what seems to me a much simpler way:

(defun jcs-insert-em-dash ()
  "Insert an em-dash at point"
  (interactive)
  (insert 8212))

and

(global-set-key (kbd "H--") #'jcs-insert-em-dash)

I have Hyper bound to the right ⌘ Cmd key so it’s really easy to invoke it: thumb on Hyper and index finger on - and it inserts an em-dash directly into the source exactly as JTR wanted.

I don’t claim my solution is better than JTR’s, only that it suits me better. It’s just another example of Emacs letting you have it your way.

Still working on Emacs Config Gems part 3. Fell into a deep rabbit hole and got lost for a couple of days, then climbed out just to discover another one I have to explore next. I wanted to crunch the first few tweaks of my Emacs config in one post, but there’s too much to explore. I’m getting there!

I particularly enjoyed the tweaks for EWW (Emacs Web Wowser) in this edition. Could be fun to take whatever page you're looking at in a different application and open it within Emacs, with syntax highlighting and maybe even the ability to copy or execute bits of code more easily. Could be handy during your search for knowledge, which is incidentally the Emacs Carnival theme for August. Enjoy!

• Help wanted:
  • pkal is looking for feedback from package maintainers on how to annotate changelog entries with release info (@pkal@social.sdfeu.org)
  • Ihor Radchenko's looking for insights from maintainers on reviewing large feature branches (@yantar92@fosstodon.org)
  • Testing patches for input methods:
    • [patch] GNU emacs bug#68339 (w32 ime font size)
    • [Patch] Implement preedit text rendering for Windows
• Upcoming events (iCal file, Org):
  • Emacs.si (in person): Emacs.si meetup #8 2026 (v #živo) https://dogodki.kompot.si/events/3944ee8f-6da1-4720-b086-b9217e4f5c7b Mon Aug 3 1900 CET
  • EmacsATX: Emacs Social https://www.meetup.com/emacsatx/events/315091679/ Thu Aug 6 1600 America/Vancouver - 1800 America/Chicago - 1900 America/Toronto - 2300 Etc/UTC – Fri Aug 7 0100 Europe/Berlin - 0430 Asia/Kolkata - 0700 Asia/Singapore
  • M-x Research: TBA https://m-x-research.github.io/ Fri Aug 7 0800 America/Vancouver - 1000 America/Chicago - 1100 America/Toronto - 1500 Etc/UTC - 1700 Europe/Berlin - 2030 Asia/Kolkata - 2300 Asia/Singapore
  • London Emacs (in person): Emacs London meetup https://www.meetup.com/london-emacs-hacking/events/315859503/ Tue Aug 11 1800 Europe/London
  • Emacs Berlin: In-Person-Only Emacs-Berlin Stammtisch https://emacs-berlin.org/ Tue Aug 11 1900 Europe/Berlin
  • OrgMeetup (virtual) https://orgmode.org/worg/orgmeetup.html Wed Aug 12 0900 America/Vancouver - 1100 America/Chicago - 1200 America/Toronto - 1600 Etc/UTC - 1800 Europe/Berlin - 2130 Asia/Kolkata – Thu Aug 13 0000 Asia/Singapore
  • Atelier Emacs Montpellier (in person) https://lebib.org/date/atelier-emacs Fri Aug 14 1800 Europe/Paris
  • OrgDevMeetup https://bbb.emacsverse.org/rooms/orgdevmeetup Sat Aug 15 0100 America/Vancouver - 0300 America/Chicago - 0400 America/Toronto - 0800 Etc/UTC - 1000 Europe/Berlin - 1330 Asia/Kolkata - 1600 Asia/Singapore
• Beginner:
  • How to Cancel a Command in Emacs (01:28)
• Emacs configuration:
  • Customize: hook to focus search field after entering customize mode (@SpaceCadet@chaos.social)
  • Handling environment variables in Emacs on OSX and Linux • Ben Mezger
  • Kakoune recipe using hel-mode https://github.com/helheim-emacs/hel/ (Reddit)
  • My Dotfiles Are an Org File | Dotfile Management with Emacs (02:38)
  • Rewriting my Emacs config (03:39:31)
• Appearance:
  • Marcin Borkowski: A fancier splash screen in terminal Emacs
  • Nice GTK tooltips for Flycheck. Works on GTK builds (Linux: Wayland/X11). (Reddit)
  • tjammer/modukai-sun-theme: Monokai Pro Light Sun based on modus-themes - Codeberg.org (@tjammer@mastodon.gamedev.place)
• Navigation:
  • Marcin Borkowski: Outlining in programs (Irreal)
  • Tip about using helm-multi-swoop-projectile for large-scale renaming in localization files (@ArneBab@rollenspiel.social)
  • Project-x now on Melpa! (+ window layouts and tabs) (Reddit)
  • I decided to customize imenu-list a bit more (Reddit)
  • Flash.nvim For Emacs (16:07) - jump to locations with search labels
• Hyperbole:
  • Hyperbole Question: What do you need to better capture and navigate your knowledge base?
  • Hyperbole Implicit Buttons: Build your Hyperverse (YouTube 34:21, (Reddit)
• Dired:
  • dired configuration similar to yazi keymaps. This is my dired config, share yours please:D (Reddit)
• Writing:
  • How to Turn on Word Wrap in Emacs (01:28)
  • Bicycle for Your Mind: Much Ado About Emacs 015 (Irreal) tabs, newlines, two-space shortcut
  • Raymond Zeitler: One Space or Two?
  • md-mode 0.2 — Add LaTeX, Mermaid, PlantUML and Graphviz rendering support (Reddit)
• Org Mode:
  • Org Mode requests: [FR] Simpler file ID links in HTML export
  • Emacs with Prot: Org Mode Basics Before Projects and Capture (21:16, Protesilaos)
  • I made an Org Mode Advanced Concepts Tutorial, please check it out (Reddit)
  • TAONAW - Emacs and Org Mode: Style & Emacs Config: A Semantic HTML Reckoning
  • grid-table 0.3.0: editable tables with horizontal and vertical merged cells for Emacs and Org (Reddit, Reddit)
  • Notes from [EVENT] #31 bbb:OrgMeetup on Wed, June 10, 19:00 UTC+3 (@yantar92@fosstodon.org)
  • Org development:
    • org-agenda-todo: Add more visual feedback on repeating tasks
    • LaTeX export: New option org-latex-fontspec-config
• Completion:
  • The Completions Buffer Is Now Enough (Reddit)
  • Protesilaos: Emacs: default minibuffer completions overview (Emacs 31) (YouTube, 30:56)
  • TAONAW - Emacs and Org Mode: Em Dashes in org-mode and the Nuances of Abbrev (Irreal)
• Coding:
  • Tip about using magit-commit-extend or magit-commit-instant-fixup (@kickingvegas@sfba.social)
  • Emacs Redux: Flycheck 38: Might & Magic (GitHub, Reddit, lobste.rs)
  • 4coder like scope hint implementation (Reddit)
  • Repeat-mode config for easier indent/dedent in Python (@jap@mastodon.nl)
  • Meta Redux: Leveling Up CIDER’s ClojureScript Support
  • tusharhero: Guix shell now inside Emacs! (HN, lobste.rs)
• Shells:
  • Using nix-shell in eshell (Reddit)
• Web:
  • Irreal: A Quick EWW Hack - retrieve URL from Safari, open in EWW
  • Is there a way to highlight code blocks in eww mode? - shr-tag-pre-highlight package
• Fun:
  • Raymond Zeitler: Emacs Smiley Functions
• LLMs:
  • Ram Krishnan / elisp-agent · GitLab (@kriyative@functional.cafe) - uses eval as its sole tool
  • New package: agent-shell-hq (Reddit)
  • Vibe-coded a simple vterm wrapper to make pairing AI agent sessions to projects easier (Reddit)
• Community:
  • Fortnightly Tips, Tricks, and Questions — 2026-07-28 / week 30
  • The Prot Effect (Reddit)
  • 0015 | New Keyboards, Emacs, Neovim, Catching up (02:11:56)
• Other:
  • Protesilaos: Emacs: tmr version 1.4.0
  • andros/lirve.el: Learn irregular verbs in English with Emacs - lirve.el - Andros's repositories (@andros@activity.andros.dev)
  • chmouel/komga-sync.el: Emacs mode to sync nov-mode reading progress with a Komga server · GitHub (@chmouel@fosstodon.org)
  • tnalpgge/org-hamlog: Log amateur radio contacts with Org tables - Codeberg.org (@nasunasu@bsd.network)
  • adif-mode: Major mode for viewing and editing amateur radio ADIF log files
  • linkarzu's videos:
    • Cashmere’s Emacs Workflow: Denote, Org, and Terminal Emacs (19:17)
    • [03] Emacs Projects, Org Capture, and My Workflow with Prot (02:00:05)
    • What I Need From Emacs: A Video for Prot (16:48)
      • Protesilaos: Reply to @linkarzu about ‘What I Need From Emacs’
• Emacs development:
  • emacs-devel:
    • Looking for reasons to keep letf considering symbol-function
    • Re: eglot-tests fail for emacs-31 branch - Stefan Monnier note about needing to ensure different package managers (ex: apt, npm, package.el) interoperate correctly
  • Canvas patch resubmitted to bug tracker after lots of polishing (@divyaranjan@mathstodon.xyz)
  • Don't immediately show *​Completions* for icomplete-in-buffer
  • * lisp/cus-start.el (completion-ignore-case): Make customizable.
  • ; * etc/NEWS: Announce support of Kmscon. (Bug#81428)
  • Merge remote-tracking branch 'origin/scratch/intern-without-shorthands'
  • New variable comment-start-line-regexp (bug#80837)
• New packages:
  • now-playing: Interface for the macOS Music app (MELPA)
  • nu-ts-mode: Major mode for Nushell scripts, powered by treesitter (MELPA)
  • ob-agent-shell: Org-babel backend for agent-shell (MELPA)
  • promptu: Compose LLM prompts from building blocks (MELPA)
  • r-ts-mode: R treesitter mode (MELPA)

Links from reddit.com/r/emacs, r/orgmode, r/spacemacs, Mastodon #emacs, Bluesky #emacs, Hacker News, lobste.rs, programming.dev, lemmy.world, lemmy.ml, planet.emacslife.com, YouTube, the Emacs NEWS file, Emacs Calendar, and emacs-devel. Thanks to Andrés Ramírez for emacs-devel links. Do you have an Emacs-related link or announcement? Please e-mail me at sacha@sachachua.com. Thank you!

You can e-mail me at sacha@sachachua.com.

Since I confessed my enjoyment of em dash in my writing last week, I started using them more freely. On a Mac, it’s Option Shift Hyphen, as Sasha would tell you. In Linux, it’s a bit more involved: Ctrl Shift U to bring up a search for Unicode number reference, and then the number for em dash: 2014.

This is all good and well, but what about Emacs, where I write most of my text?

Emacs comes with abbrev-mode, a powerful text-expanding option that automatically converts something like “om” to “org-mode”, or even “fox” to “The quick brown fox jumps over the lazy dog” if I wanted to. But the em dash is a bit more tricky. I could, if I wanted, create an abbreviation like “em” to simply expand to “—”. But this doesn’t make much sense.

When converting org-mode to markdown (as I do when I post something), the built-in solution for Emacs’ markdown exporter is to convert --- (three dashes) to —, em dash — but this presents two annoyances. First, the built-in exporter would convert those to their character reference, as we just saw: ߞ. I explained this more in-depth previously. Second, even after I fixed this issue by using pandoc, I still see --- in org-mode, not —. This looks like the kind of thing abbrev-mode was made for, right?

But it’s a bit more complicated. abbrev-mode triggers only when you type a space after a letter. So, “em” to — would work, but - to — would not, because a dash is not part of a word¹.

The solution was simpler than I thought: expand-abbrev, which “Expands the abbrev before point, if there is an abbrev there. Effective when explicitly called even when ‘abbrev-mode’ is nil.” In other words, it calls expand-abbrev without needing to trigger it the usual way. We simply call the abbrev replacement directly.

Now whenever I want an em dash, I type --- first, and then I make sure the marker is right after the last dash, and call expand-abbrev, which in my config is tied to C-x ‘. I then get an em dash in Emacs, and the exporter in Emacs (or pandoc, in my case) leaves it alone.

HTML enforces the use of a single space to separate sentences. If you want to add another space, you need to use  . I still remember how annoyed I was about that. Back in the century in which I took my technical writing course, two spaces were required. Of course, we weren't using computers very often; hand-written sentences needed to appear more separated than the words within.

I'm definitely not here to convince anyone to switch. Instead, I just want to share that I paid close attention to this detail when I was formulating my style guide for this blog. Should I continue with my out-of-date two-space habit? Or should I adopt the current convention?

I turned to Emacs itself for guidance. It turns out that the individuals who wrote Emacs comments, docstrings and help text used two spaces. Although many times they started each sentence on a new line.

It turns out that the content here mostly is one-space. I start out using two spaces in Org where most of this originates. But when I export to HTML, that second space vaporizes. That would seem like a bug to me.

The only place where you'll see evidence of my two-space style is in the comments and docstrings of my source code.

Am I the only person who nit picks about such details?

Thanks to Irreal for highlighting a customization from macosguru

Emacs Smiley Functions

Here's what my Emacs Tip of the Day dug up: smiley-buffer

Raw link: https://www.youtube.com/watch?v=WQbXKvBT8HY

In about 40 minutes from now I will do a live stream with Christian Arzu from the @linkarzu channel on YouTube. The video will be recorded.

The topic of our meeting revolves around how Christian uses NeoVim and Kitty to handle sessions and write fleeting thoughts. Then we will try to do something along those lines using built-in Emacs functionality.

Christian did a video a couple of days ago about this topic and here is my extensive commentary on it, with points that are useful in general: https://protesilaos.com/codelog/2026-07-31-re-linkarzu-what-i-need-from-emacs/.

Having to deal with Microsoft's outlook has been a growing pain with my computing needs. Of course, this is pertinent only for work email. For personal email, I use Migadu which has good standards for email unlike Microsoft's.

At work, I can only use either the official Outlook webmail or Thunderbird since those are the only clients that are whitelisted by the IT department at my university. Thunderbird is slightly better (it has a few problems of its own but I digress) but I would like to have an offline copy of all my emails, fully searchable with an indexed database provided by notmuch, which uses the excellent Xapian library for indexing. Notmuch is shipped as an emacs package in the form of notmuch.el, which is exactly what I like given that I'm moving most of my computing needs into emacs¹.

I've taken inspiration from Fergus' excellent blogpost which implements the same in neomutt. The initial setup process is identical to Fergus' blogpost.

It should be noted that notmuch is only a mail indexer. It does not fetch mail, nor does it send mail. Those are handled by isync and msmtp, which are commandline programs.

Access authentication with O365

Since Thunderbird is still allowed to access O365's authentication, we will use the client ID provided from it (this is publicly available from Thunderbird's source code)². For authentication for IMAP and SMTP, we will use XOAUTH, which is a simple authentication and security layer (SASL) more suited for email clients.

Tools like isync rely on SASL for authentication, for which we'll require an XOAUTH SASL plugin: https://github.com/moriyoshi/cyrus-sasl-xoauth2.

If you're on Arch, then this plugin is installable from the AUR:

paru -S cyrus-sasl-xoauth2-git

If not, then we can build it from source:

git clone https://github.com/moriyoshi/cyrus-sasl-xoauth2
cd cyrus-sasl-xoauth2/
./autogen.sh   # checks for requirements
./configure    # configure (here we use the defaults)
make           # compile
sudo make install     # install for root user

Token generation for OAuth

Microsoft has conditionally allowed API access to clients and the only way to get access for any client is to register the application in the Microsot Application portal, which is something only my org's IT department can do³. Fortunately, we can use Thunderbird's credentials to generate an access token for our purposes.

Another issue that comes up is the finite lifetime of these access tokens (typically an hour or two), which is cumbersome to generate each time one needs to download email. Fortunately, mutt comes with mutt_oauth2.py, a script to help in the automatic renewal of this token. This script helps in decrypting the token file and renewing it everytime it is invoked.

Fetching the initial token is fairly simple but before we do it, there are certain changes that we need to do to mutt_oauth2.py.

Look into the ENCRYPTION_PIPE variable (line 48) and make sure to specify your gpg key. If you don't have one, then generate one:

gpg --full-generate-key

Select the default options (ed25519 cypher if it allows) and make sure that the expiration of the key is set to 0 (no expiration). This makes your life easier but of course for security reasons, this is not a good practice.

Bring up your public key:

gpg --list-keys

Copy the second line (after the pub line) and paste it into mutt_oauth2.py

ENCRYPTION_PIPE = ['gpg', '--encrypt', '--recipient', 'YOUR-GPG-KEY']

After this, look at line 79. This includes a client_id for microsoft. For Thunderbird, the client id is 9e5f94bc-e8a4-4e73-b8be-63364c29d753. Leave the client_secret value as is. It should look like so:

'client_id': '9e5f94bc-e8a4-4e73-b8be-63364c29d753',
'client_secret': '',

Now we are ready to generate the access token. Simply run:

./mutt_oauth2.py OUTPUT_TOKEN_FILE --verbose --authorize

A series of prompts should appear. Select microsoft, localhostauthcode (or authcode), followed by your email address, after which you should automatically be redirected to a browser for adding your credentials for authentication. Doing so, should reveal the access token in your terminal. No need to copy it, it is present in your OUTPUT_TOKEN_FILE which is encrypted. To obtain the decrypted token, we run the script again with just the file name as an argument

./mutt_oauth2.py OUTPUT_TOKEN_FILE

A nice thing is that running this script with the token file also checks for expiry and renews it if necessary. This can be done multiple times without worry.

UPDATE (2026-06-19): About 20 days after I set this up, for whatever reason the token file expired on my personal laptop. I'm not entirely sure what happened but the fix for now was to regenerate the token again. I'll need to debug the exact cause to prevent it from happening again.

UPDATE (2026-07-29): It looks like this problem only appears on my personal laptop as it's not an authorized device and as such, 14 days is the maximum duration before which the token needs to be reauthorized. My office PC is within this "authorized" devices whitelist and thus doesn't need reauthentication after the initial setup.

Offline email setup

Now that we are done with the difficult part, we move onto setting up isync (the binary is called mbsync) which is available in most distributions. This program basically downloads your emails offline and synchronizes it with your email's remote IMAP servers. It supports multiple accounts too. The program is configurable with a ~/.mbsyncrc file⁴. I highly recommend reading the manual for it via man mbsync. Here's a starting template:

# -- Global defaults
# These will be applied to all accounts

# Create new mail in either location, so if the remote or local has mail
# and the other does not, then create it
Create Both
# never remote mail from either side
Remove None
# Remove messages marked for deletion from the local side on the
# remote. Do not ever delete local if marked for deletion in the
# remote. Prevents admins from deleting one's local mail
Expunge Far
Sync All
SyncState *
CopyArrivalDate yes
# No maximum number of messages
MaxMessages 0

# -- First email account
IMAPAccount university
Host outlook.office365.com
Port 993
User my-username@university.edu
AuthMechs XOAUTH2
PassCmd "~/.local/bin/mutt_oauth2.py ~/.local/bin/TOKEN"
# Use TLS
TLSType IMAPS
SystemCertificates yes
Timeout 10

# A store defines a collection of mailboxes, so we associate the
# remote IMAP mailbox with the account we just configured
IMAPStore university-remote
# Associate the store with our account
Account university

# Where are we going to keep the mail associated with this account
MaildirStore university-local
SubFolders Verbatim
Path ~/.local/share/mail/university/
Inbox ~/.local/share/mail/university/INBOX

# Channel to synchronize everything except "Sent" email
Channel uni-main
Far :university-remote:
Near :university-local:
# Which directories to synchronize
Patterns INBOX "Deleted Items" "Drafts"

# Channel to synchronize "Sent" email
Channel uni-sent
Far :university-remote:"Sent Items"
Near :university-local:Sent

# Group the two channels and sync everything with `mbsync NAME`
Group university
Channel uni-main
Channel uni-sent

# -- Second email account
IMAPAccount personal
...

Once you have everything configured, we can start downloading all our email by running:

mbsync university

The first time mbsync is run, it will take a fair amount of time, since you'll be downloading a lot of email (assuming you've been using your account for a long time). The subsequent runs would be just incremental downloads, so it's much faster.

After navigating to your local Maildir directory (~/.local/share/mail/university in my case), you should see all your emails downloaded and categorized into inbox, drafts, sent, and deleted-items folders.

A way to automate this to run a script periodically. I use systemd-timers where I have a script which is periodically run every 15 mins and notifies me if there's new email (I'll cover this later in the blogpost).

Sending mail via SMTP

Sending email is done via msmtp. It is configured by editing ~/.msmtprc⁵.

defaults
auth on
tls on
tls_trust_file system
logfile ~/.cache/msmtp.log
timeout 10

# -- First account
account university
tls_starttls on
host smtp.office365.com
port 587
auth xoauth2
user my-username@university.edu
passwordeval "~/.local/bin/mutt_oauth2.py ~/.local/bin/TOKEN"
from my-username@university.edu

# -- Second account
account personal

This is fairly self-explanatory. One thing to note is that tls_starttls should be on for this to work. I'm not very familiar with email security protocols like TLS and STARTTLS but from my understanding, STARTTLS is an automatic upgrade (if supported) from the more insecure TLS protocol. TLS however needs to be enabled for any email service, otherwise it won't work.

Now, we can test our configuration by sending email directly from the commandline. Save the contents of a file called example-mail as follows:

From: my-username@university.edu
To: user@example.com
Subject: Hello World

This is a test for msmtp.

And send the email by running:

cat example-mail | msmtp -t -a university

Indexing email offline with notmuch

We have receiving and sending email configured. How about reading and "using" email via an email client. In more technical terms, an email client is called a mail user agent (MUA), which is typically seen in email headers. This includes clients like Thunderbird, Apple mail, neomutt, etc. We will configure notmuch which indexes email and provides an interface for emacs natively with notmuch.el.

Notmuch is entirely tag based. Basic tags exist like unread, inbox, draft, sent but you can customize it with more tags to filter out emails from a particular email address, from a particular range of date, etc. Tags are heavily used and it's a different paradigm of handling email compared to your typical webmail interface. I won't go over the details of tagging in notmuch here for the sake of brevity (to be covered in another blogpost).

When first setting up notmuch, simply run:

notmuch setup

This will prompt you for basic information like your name, email address, Maildir directory, etc. Once this is done, notmuch needs to index your Maildir. Run the following:

notmuch new

This should be fairly fast, even if your Maildir is big. Notmuch is quick like that.

Now you can search an email entry via notmuch search. For example, I can search emails from a particular sender like so:

notmuch search 'from:friend@university.edu'

I would again advise you to go through the man pages (man notmuch-search) for more details.

Emacs setup for notmuch

Simply running M-x notmuch should give you a hello screen, where you can then select tags like inbox, unread to view their respective email. I have a fairly customized config for notmuch.el but below I provide a fairly good starting point for a more minimal notmuch interface⁶:

;; Notmuch for email
(use-package notmuch
  :load-path "/usr/share/emacs/site-lisp/"
  :ensure nil
  :defer t
  :commands (notmuch notmuch-mua-new-mail)
  :init
  ;; Search
  (setq notmuch-search-oldest-first nil)
  :config
  ; General UI
  (setq notmuch-show-logo nil
	notmuch-column-control 1.0
	notmuch-hello-auto-refresh t
	notmuch-hello-recent-searches-max 20
	notmuch-hello-thousands-separator ""
	notmuch-hello-sections '(notmuch-hello-insert-saved-searches)
	notmuch-show-all-tags-list t)

  ; Search
  (setq notmuch-search-result-format
        '(("date" . "%12s  ")
          ("count" . "%-7s  ")
          ("authors" . "%-20s  ")
          ("subject" . "%-80s  ")
          ("tags" . "(%s)")))
  (setq notmuch-tree-result-format
        '(("date" . "%12s  ")
          ("authors" . "%-20s  ")
          ((("tree" . "%s")
            ("subject" . "%s"))
           . " %-80s  ")
          ("tags" . "(%s)")))
  (setq notmuch-show-empty-saved-searches t)

  ; Tags
  (setq notmuch-archive-tags nil ; I don't archive email
	notmuch-message-replied-tags '("+replied")
	notmuch-message-forwarded-tags '("+forwarded")
	notmuch-show-mark-read-tags '("-unread")
	notmuch-draft-tags '("+draft")
	notmuch-draft-folder "university/Drafts"
	notmuch-draft-save-plaintext 'ask)

  ; Email composition
  (setq notmuch-mua-compose-in 'new-window)
  (setq notmuch-mua-hidden-headers nil)
  (setq notmuch-address-command 'internal)
  (setq notmuch-address-use-company nil)
  (setq notmuch-always-prompt-for-sender t)
  (setq notmuch-mua-cite-function
	'message-cite-original-without-signature)
  (setq notmuch-mua-user-agent-function nil)

  (setq notmuch-show-relative-dates t)
  (setq notmuch-show-all-multipart/alternative-parts nil)
  (setq notmuch-show-indent-messages-width 0)
  (setq notmuch-show-indent-multipart nil)
  (setq notmuch-show-part-button-default-action 'notmuch-show-view-part)
  (setq notmuch-wash-wrap-lines-length 120)
  (setq notmuch-unthreaded-show-out nil)
  (setq notmuch-message-headers '("To" "Cc" "Subject" "Date"))
  (setq notmuch-message-headers-visible t)

  :bind
  ( :map global-map
    ("C-c m m" . notmuch)
    ("C-x m" . notmuch-mua-new-mail) ; override `compose-mail'
    :map notmuch-search-mode-map
    ("/" . notmuch-search-filter) ; alias for l
    ("r" . notmuch-search-reply-to-thread) ; easier to reply to all by default
    ("R" . notmuch-search-reply-to-thread-sender)
    :map notmuch-show-mode-map
    ("r" . notmuch-show-reply) ; easier to reply to all by default
    ("R" . notmuch-show-reply-sender)
    :map notmuch-hello-mode-map
    ("J" . notmuch-jump-search)))

You're free to look at my init.el for my own customization for notmuch.el.

Automating email synchronization with systemd timers

Let's automate the email sync to happen every 15 mins (or whatever frequency you prefer). First we create a shell-script to download email via mbsync and also index the email with notmuch. Let's name it it syncmail.sh and place it in $HOME/.local/bin/.

#!/bin/sh
set -eu

# Set environment variable for notmuch config file
export NOTMUCH_CONFIG="$HOME/.config/notmuch/notmuch-config"

mbsync university

before=$(notmuch count --lastmod '*' | cut -f3)
notmuch new > /dev/null

query="lastmod:$((before + 1)).. and path:university/**"
count=$(notmuch count "$query")

if [ "$count" -gt 0 ]; then
    body=$(notmuch search --format=json --limit=5 "$query" \
	       | jq -r '.[] | "\(.authors): \(.subject)"')
    notify-send "New mail: $count" "$body"
fi

In addition to downloading email and indexing, the script also notifies through notify-send if there's new email along with a sender and subject in the notification. Make sure to make the script executable with

chmod +x ./syncmail.sh

Then we write the systemd script to run this script periodically. First we create a syncmail.service file in $HOME/.config/systemd/user/:

[Unit]
Description=Sync mail with mbsync and index with notmuch

[Service]
Type=oneshot
ExecStart=%h/.local/bin/syncmail.sh

Then we create a timer file (make sure it is named syncmail.timer) for actually running the script every n minutes.

[Unit]
Description=Run syncmail every 15 minutes

[Timer]
OnBootSec=2m
OnUnitActiveSec=15m
Persistent=true

[Install]
WantedBy=timers.target

The advantage over cronjobs is that if your system is asleep or shutdown, then booting up accomodates accordingly and runs the script after m minutes (2 minutes in my case).

Finally we enable the script with systemctl:

systemctl --user daemon-reload
systemctl --user enable --now syncmail.timer

Concluding remarks

Now you should have a working setup for using offline email for Microsoft's O365. This is fairly minimal but if you'd like to have encrypted emails, addressbooks, etc., please take a look at the original blogpost from Fergus.

A basic emailing etiquette I like to follow is to use plaintext as opposed to html. Read more on why this is better.