Emacs org-mode
Emacs for macOS and Darwin versions
Regarding to Emacs crashing: AI found that my Drawin version of Emacs might be the cause. I’ve been using Emacs for Mac OS which ran darwin21.6.0 - old… (current version on macOS is 25.3.0)
The question is, is this really the problem, or more like the AI making stuff up? It makes sense to me that an Emacs build is based on a slightly older Darwin version, though I’m not an expert. Another reason for this suspicion is that the AI assistant recommended emacs-plus without considering emacs for macOS. I know both are solid based on my own research, and I used Emacs-plus (available with Homebrew) for a while. I’ve been using Emacs for macOS for about a year, and it’s been fine until I believe I updated to the latest macOS, which everyone seems to hate, so I wouldn’t be surprised if it has to do with macOS 26 more than anything else.
For now, I installed the latest version of Emacs for macOS, which was built on darwin23.2 - still behind, but not as bad. If this is what’s running Emacs 30.2 for so many Mac users, it further confirms my suspicion that the Darwin version is not really the issue. But maybe I’m wrong.
I posted my question on Reddit to get some feedback, and out of curiosity, see what the Darwin version is for Emacs-plus (don’t want to install it right now). Guess we’ll see.
Denote includes the option of adding different directories, so this now makes sense:
(setq denote-directory
(if (eq system-type 'gnu/linux) ; If I'm using Linux, include the private folder.
(list (expand-file-name "~/Sync/Notes")
(expand-file-name "~/Documents/private"))
(list (expand-file-name "~/Sync/Notes")))) ; If I'm using anything else (macOS) just Notes.
(setq denote-excluded-directories-regexp "data") ; the data folder (with attachments) is excluded.
I have a private folder for Denote notes on Linux only. I used to only sync my Sync/Notes folder, which includes my informational notes and blog posts, but that means I’m missing out on Denote’s abilities in my private folder, which is slowly increasing in size. This solves this problem.
There’s no need to list the data folder (which includes my attachments, mostly in file formats that are not Denote’s format), so that’s why the exclusion is there.
Org files to beatiful docx files with Pandoc
When it comes to sharing written documents with my co-workers, I usually need to use Word or PDFs. Org-mode includes an export option to odt files, which does the job in a pinch, but it’s a bit harder to customize, especially if I want to preserve certain formatting elements. In the past, I used to create ODT files, import them into Word, make whatever changes I needed, and save them in a docx file. The problem there, besides the manual work, is consistency. If I want to make sure I use the same style for fonts, header sizes, and table formats, things get annoying fast.
About a year ago, I discovered that Pandoc can use an external Word document (docx) as a style template. As long as I have this file accessible, every org file I convert to docx will automatically (and beautifully, I may add) retain the exact style changes I need. This, of course, can be automated later inside Emacs, so the export process is basically seamless.
The problem lies in the fact that you need to work with Word and understand how its styles. Readers of this blog know I love to complain about Microsoft’s UI and its lack of consistency, and the instructions here are one fine example in my opinion. Be it as it may, I will try to keep the snarky comments in check.
Creating the default style sheet
The first thing to do is get Pandoc to create its default style reference document as a .docx. This can be done with pandoc -o custom-reference.docx --print-default-data-file reference.docx.
What you’re telling Pandoc here is to output (-o) a file named custom-reference.docx (you can call it whatever you’d like, as long as it’s a docx, since you want to work with Word). What to output goes into this file? The default reference document.
Once you do that, you will have a custom-reference.docx in the folder you ran the command from.
Now it’s time to work inside Word.
Modifying the styles
What you will see is a rather plain file listing a bunch of styles and their name. First, you will see “Title,” and it will be nice and big because it’s using the Title style in Word. Heading 1 will use the Heading 1 style, Body Text (further down) will use the Body Text style, and so on.
What you want to do is to access these styles in Word. You will be modifying them to fit to your liking.
To do that, search for the Styles Pane. In my case, Office 365 for macOS, I can find it in the ribbon under Home, but I wouldn’t be surprised if that’s a little different if you’re using Windows, or a different version of Word.
With the Style Pane open, you will see a long list of the available styles. You can navigate this way, but I find it’s easier to just look for them in the document to the left and select them; it will then show under Current style: to the right.
Now that you have a style selected, select the name of that style from the Style Pane and choose Modify Style…1. You will see the options available to you, such as the font name, text color, alignment, etc.
Make sure that you do not change the Name: of the style! You’re modifying existing default styles that Pandoc recognizes; if you create a new one (by giving it a new name), Pandoc will not know what to do with it and will ignore it. Remember, you are modifying a reference sheet of existing styles, not creating new styles. Likewise, this means that you have no reason to change anything in the document itself (the content) - Pandoc doesn’t care about that and will ignore it. You’re only touching the options in the Modify Style… window.
That’s basically all there is to it. As you will see soon, some items can get a bit more complicated as they are not available in the same way. Save the files when you’re done modifying the styles. You will probably keep going back to this document as you export docx files, tweaking things until you like them.
Using Pandoc to export from org-mode to a docx file
The next step is to tell Pandoc to convert an existing org file to a docx file using the reference sheet we just worked on. To do that, use the following command:
pandoc -s <input_file.org> -o <output_file.docx> --reference-doc custom-reference.docx.
The idea is the same as before, but we use a stationary option, -s (the reason for that is that we’re telling Pandoc to use a “full” version of a document, needed with the reference doc option, otherwise it can’t use our reference document).
Then, we’re pointing Pandoc to our org file and using the output, -o, as the doc file we want, then finally using the reference-doc option by utilizing our reference file, custom-reference.docx (unless you change the name to something else). That’s it, Pandoc will create the file in the folder you are in.
Images and Tables
For me, things get a bit more complicated. My technical documents often include screenshots, and I need those embedded in the resulting Word docx file.
The above command will embed images in the Word document, as long as org-mode can find and display your images (using the inlineimages option in org-mode). My org-mode technical notes are all written with Denote these days, which keeps everything organized, including the images, which are inside the default data subfolder. If your workflow is different, be mindful of your path to the images; you’d probably want to use an absolute path in org-mode (use C-u C-u C-c C-l when linking an image instead of the usual C-u C-c C-l for this). There’s also the option to extract media in Pandoc (see the –extract-media option). In my opinion, it’s simpler and cleaner to dedicate a folder for your org documents, completed with a subfolder for attachments.
Another issue that stumbled me was the tables.
Pandoc’s default style for tables is minimal - without borders. This might look nice if you want to hide your tables, but if you need a table with borders and perhaps some shading, you’ll run into issues.
The problem is with Word. The style for the table is not included in the Style Pane. In order to change the style for your table in the reference doc, you need to locate Table Design in your ribbon. Notice that if you work on a small screen (like in my recording), you might have to expand your options to find it. Then, you will have to extend the pane further and locate the Modify Table Style below. Once again, this is true for my case, Office 365 on macOS. If you’re using a different Office version or on Windows, this menu might be located elsewhere.
Once you have Modify Table Style open, you can change the borders and shading to your heart’s content, but as before, make sure the style name remains Table. If you create a new style, Pandoc will ignore it.
A few tricks I picked up
Under the name of the style, in the Modify Style or Modify Table Style window, you will see the Style based on option. You can change this option and browse through different colors and fonts to find something you like, and then customize further instead of starting from scratch. As long as you don’t change the name of the style, you’re OK. I found this useful when working with tables, as I was looking for a table with shading on every other row.
Speaking of tables, the border button is the little square icon in the middle. I spent a few moments trying to find it.
Bonus: use dwim-shell-command for quick export
If you’re an Emacs user, you like shortcuts, and you like to use shell commands from within Emacs. If you haven’t yet, check out dwim-shell-command.
Here’s how I have it set up. All I have to do is mark the org file(s) I want to convert to a docx, and that’s it. It doesn’t matter if I want to export only one file or fifty; it’s the same ease of use.
(defun jtr/dwim-shell-command-pandoc-org-to-docx ()
"uses pandoc to convert an org file to docx using a template docx file. The docx template file is stored in my Notes sync folder"
(interactive)
(dwim-shell-command-on-marked-files
"converting from org to docx"
"pandoc -s '<<f>>' -o '<<fne>>.docx' --reference-doc ~/Sync/Notes/Info/custom-reference.docx"
:utils "pandoc"))
Footnotes
1 : Or, another way to work is to use to select the text you want to modify, then go to Format and select Style from there; you will need to then choose Modify in the window that shows.
A bit of a teaser:
This bit of dwim-shell-command magic works nicely:
(defun jtr/dwim-shell-command-pandoc-org-to-docx ()
"uses pandoc to convert an org file to docx using a template docx file. The docx template file is stored in my synced notes folder"
(interactive)
(dwim-shell-command-on-marked-files
"converting from org to docx"
"pandoc -s '<<f>>' -o '<<fne>>.docx' --reference-doc ~/Sync/Notes/custom-reference.docx"
:utils "pandoc"))
Why I use Denote?
When I mentioned Denote again a couple of days ago, Omar commented that whenever someone mentions using Denote or org-roam, he’s curious to know if that person tried vanilla org-mode first, without additional packages.
I get it. After all, I’ve been resisting the whole Zettelkasten bandwagon and org-roam with it for a while, keeping the same opinion about org-roam Omar seems to have about Denote (I’m speculating here, of course). In general, I don’t like the idea of Doom Emacs or Spacemacs for the same reasons. Denote, for some reason, never registered this way. I liked it from day one.
As I was answering his question and he asked for more details, I thought it might make a good post. So here we are.
Not a whole lot changed for me since I first looked into Denote. I still mostly use it for my blog posts (like the one you’re reading right now) and my info notes, which mostly contain technical how-tos to myself and to a lesser degree, some records and memos, like a list of equipment in my home or who’s who at work. At this point, I also have a third, personal folder with notes only on my Linux computer as well, which mostly contain “supplemental” notes as I call them to journal entries I want to expand on in private (I use my work iPhone with Journelly, which does a fantastic job, but I don’t trust Apple or any cloud service for that matter with my private stuff).
It has been slow progress, but I’ve improved my usability with Denote, which I recently enhanced further after having the pleasure of talking to Prot 1:1 in one of his online tutoring sessions (always a pleasure, and highly recommended if you ask me).
The main philosophy behind Denote is something I’ve been in agreement with for a long time, before I started using it, or Emacs, or even got familiar with Linux: the idea of how to date and rename files. I’ve never agreed with the American way of writing dates, and I always prefer the ISO format: yyyymmdd followed by hhmm. To me, this is how things should be organized. So when Denote came around with Prot explaining that this is how he sees files should be organized - date, followed by keywords, and then a title - it just clicked.
You can extend this file-naming scheme to all your personal files if you’d like (at least all the files you visit with Dired), and I’m in the process of doing exactly that. Because the renaming function is built into Denote, it’s easy to stay concise and avoid mistakes (for example, renaming one file 20260124 something, and then another 2026124, emitting the 0 for January). While it’s true you could easily do that without Denote, to me, this core piece was like a sign that said, “Hey, look at this, this guy is building a package that is based on something that makes sense, check it out.”
Tags are another important part of Denote. Org-mode has tags built into headers, which works, but the headers, to me, are a bit too specific to need them. For the most part, I can get the level of information I need through the header itself, and I use tags to associate a certain header with a person - but even that is not useful, as I often work with too many people for the tags to really mean anything. Meanwhile, it’s the files themselves that need tags: certain workflows are similar, but are tagged to work for different operating systems (say, how to set my work VPN on Linux vs on my Mac), or maybe I have a naming convention for different departments at work, and I want to tag the relevant departments.
I didn’t always break my different workflows and notes into files. In the past, I had one org file as a wiki: a single file with many headers explaining workflows and procedures. I often had errors there. It was one big file that I often opened and edited, so I had syncing issues, headers that got mixed up, etc. The other problem I had with the wiki was logical: at times, a certain subheader would fit under two different headers, and I would have a hard time deciding where to place something. Headers work as categories, while tags work as ,well, tags. If we take the VPN example from before, I could put my VPN instructions under “networking,” “security,” or “remote work,” but not all. I don’t have this problem with Denote.
Another, more recent skill I started using with Denote is its metadata and search features. Meta notes work as an index of other files, where I can have one file with a dynamic list (updated whenever the file is loaded) of live links to other files with the same tag or other regex I use. Meanwhile, searching with Denote using denote-grep (something I learned recently) shows a list of all the files matching my search in collapsible form, making it easy to find what I need. I can use one of many denote-query forms to filter those results even further, and of course, there’s denote-consult, which, well, if you know consult, you know what it does, and it’s excellent.
Finding stuff is a central issue for anyone keeping notes, no matter what system they use. Denote supplies me with the best tools I’ve seen for this job. It’s true that many of these tools are already available in Emacs and in org-mode. Denote doesn’t alter these existing options; rather, it builds on them. In fact, that’s a big part of Denote: the way its commands are constructed borrows from what Emacs already does, so if you’re familiar with one, you intuitively know what the same thing would do inside Denote.
Another example of the above is the org files you create with Denote. You can use Denote directly with a capture template, and each file is created with file tags that make sense if you use org-mode: #-title, #+date and #+filetags, which denote changes automatically as you rename files with it. These work together with additional options I include in my notes, such as #+STARTUP: inlineimages. In a Markdown export, such as this very post you’re reading now, Emacs knows to ignore these org-mode only options, so I don’t need to clean them out when I’m ready to post. It’s a nice touch that already exists in vanilla org-mode, but with the added benefits of Denote, like having my post tagged, dated, and easily found in a search alongside the rest of my Denote files in the future.
There are definitely more features of Denote I don’t use, or use enough (blacklinks, which I believe are more of a recent introduction, is one of them), but as I stated above, this is a process. I learn more every week, and as my notes collection increases, so does my understanding of how to use Denote in a way that works for me.
Spent the last day and a half on and off figuring out how to use pandoc to make my org-mode files in pretty, readable docx files, including tables. It was a challenge, but it’s worth it. The key is to use a reference doc and to know how to use it. Need to expend on that.
Reflection on my Emacs experience
A couple of days ago I found out org-mode capture sun menus can handle additional nested menus. To recap quickly here (see more details in the link), this means that you’d have the main menu for capture templates, which will lead to additional templates menus, and that menu can keep leading to more and more menus. I am not sure how many levels of these templates we can have, but “more than enough” is a good enough answer for me.
As I was writing the post above, I went back to my old blog and reviewed two of my older, Emacs-usage-defining posts, and added them to this blog: Org-mode in files and Submenus in org-mode capture.
Those of you who enjoy reading about the Emacs experience from a user perspective (especially someone who started out without a programming background) might want to give those a read, in the order mentioned above. Beyond explaining these crucial org-mode methods (and in my opinion, crucial to use Emacs in general), these describe the struggle and the learning process of, well, how to Emacs correctly: from realizing an option exists (of course it exists, it’s Emacs), through asking the right questions, to finding the information and implementing the solution.
I’ve spent a couple of hours re-reading and revising these posts, and reached a conclusion that many of you who are reading this over their RSS feed in Emacs would probably agree with. We, Emacs users who blog, have a critical role in the Emacs ecosystem: we provide others with ideas and questions to ask, which can later be directed to official channels, the manual, and brainstorming answers.
As I mentioned a couple of times throughout the lifetime of my blog (this one and the old one): Emacs is not just a program, it’s a lifestyle.
org-mode capture: menu inside a menu
Over the weekend, I modified my org-capture templates again. I was curious to see if I could create a second-level menu in org-mode capture under my already existing menu items - and as it turns out, it’s possible, and also pretty straightforward. Here’s the start of the setting (keep in mind it’s not complete, don’t just copy-paste this):
(setq org-capture-templates
(quote (
("w" "work")
("wt" "work-ticket")
("wta" "work-ticket department A" entry
(file "~/Sync/Work/department A.org") (file "~/Sync/Templates/temp-ticket.org"):prepend t)
This will result in the following:
Select a capture template
===========================
[w]... work...
then:
Select a capture template
===========================
[wt]... work ticket...
then:
Select a capture template
===========================
[wta] work-ticket department A
I should explain this further, probably first explaining why I need such a complicated system of menus within menus, but every time I sit down to explain I run out of time. I wanted to put it out there first, and I’ll come around to explain it soon, hopefully.
I like the DU command in Dired
I had fun using the du command in Emacs this morning (that’s what I do when I don’t sleep well; judge away).
In Linux (and macOS), the DU command (I believe it stands for Disk Usage) is usually used to figure out what folders take up space on your hard drive.
While different GUI tools exist, they are not useful on encrypted drives on Linux, as they show the encrypted blocks instead of the directories, which don’t really tell you much (you could probably run those with escalated permissions, but I didn’t try).
For a gamer like me, it’s useful to see which games take up the most space. Here’s an example with a few useful flags, in the command line:
du -hs ~/.steam/steam/steamapps/common/* | sort -h
Shows me the following:
4.0K /home/jtr/.steam/steam/steamapps/common/Steam.dll
76K /home/jtr/.steam/steam/steamapps/common/Steam Controller Configs
100K /home/jtr/.steam/steam/steamapps/common/SteamLinuxRuntime
248M /home/jtr/.steam/steam/steamapps/common/Steamworks Shared
657M /home/jtr/.steam/steam/steamapps/common/SteamLinuxRuntime_soldier
776M /home/jtr/.steam/steam/steamapps/common/SteamLinuxRuntime_sniper
1.4G /home/jtr/.steam/steam/steamapps/common/Proton - Experimental
3.4G /home/jtr/.steam/steam/steamapps/common/Deep Rock Survivor
3.5G /home/jtr/.steam/steam/steamapps/common/Deep Rock Galactic
11G /home/jtr/.steam/steam/steamapps/common/Hades II
21G /home/jtr/.steam/steam/steamapps/common/Yakuza Kiwami
82G /home/jtr/.steam/steam/steamapps/common/Space Marine 2
132G /home/jtr/.steam/steam/steamapps/common/Helldivers 2
Some of the Steam-related components are not games, but… Helldivers 2 takes how much space?? Anyway.
A quick review of the options I used:
-hs for human readable (shows space in G for gigabyte and M for megabyte instead of writing in kilobytes) and summary (shows the top directory only)
~/.steam/steam/steamapps/common/* for the target path (this is where Steam stores the games in Linux, at least in Debian distros)
| to pipe the du command it into another command to read it better, in this case:
sort -h the sort command, which will sort it nicely again by order in human format. We need this last part if we want to see the directory in order, with the biggest one at the bottom.
Some places recommend using sort -hr, the additional r for reverse, which means in this case we will see the biggest directory at the top of the list. I don’t need it, because I want to see the biggest folder at the bottom, near the command line, which is where I’m going to focus next.
In Emacs, this command is easier use and works better thanks to Dired. Find a folder, mark it (m) in dired, and run dired-do-shell-command (!) and follow up with du -hs.
But since we’re in Emacs, and we might want to work with the results as text, we could use dired-do-async-shell-command (&). This will place the output in a temporary buffer we can work with (so we can save it to a text file, for example, with C-x C-w).
And here’s another thing I didn’t know: you can run these commands in Dired on multiple directories. Just mark several directories in Dired, and the resulting buffer will give you a list of all the directories you’ve marked. If you have this saved as a text buffer, it’s pretty easy to work withthe results (for example, save it as an org file and add headers telling you what you want to do with each directory).
By the way, even though it’s somewhat redundant with Dired’s default listing of files, you can also add the a option for du in this case ( for all) to display the files in the directories you’re viewing. This is useful in cases like the above, where you’re already working with the du command in Emacs and interested in looking at individual files as well, not just directories. Of course, you can just go in and list the files in Dired and open another Dired buffer with another directory listing files by size… this is Emacs, you have many ways to do whatever you want.
I think I’m going back to clocking in and out of sub-tasks, even though I said I wouldn’t. It’s easier not to, but the end result, I think, is messier, and I can’t get the clock reports right… on the other hand, it’s kind of an overkill. 🤔
Rediscovering org-clone-subtree-with-time-shift: if you have regular meetings, this is the function for you.
Create a Meeting event with everything you need (Zoom links, place for notes, tags, etc) and clone it X number of times. Emacs will ask you for the frequency. You now have X meetings ready.
Handling project in Emacs - the 2025 version
Ever since I’ve decided to move away from iCloud1, I’ve had a hard time syncing my org files with Beorg, which is how I worked with org-mode tasks on my iPhone. Frustrated, I looked into a solution that I should have revisited long ago: Plain Org.
I got Plain Org before I heard of Journelly, so it’s not just because I’m a fan of Álvaro’s work. At the time, I was just looking for an app that could read org files and lay out my projects in a nice, clear way. As it turns out, Plain Org does more than that - by doing less.
Compared to Beorg, Plain Org is very minimal. But it works with Synctrain (Syncthing for iOS), it accesses my org files on my iPhone quickly and easily, and it lets me make quick modifications when needed. For everything else, there’s Emacs. And that’s what I seem to have forgotten.
It took me a while to reconnect with the understanding that my iPhone is not the place to manage tasks and projects, despite what everyone around me seems to think, whether it’s my workplace with its Microsoft Office suite or Apple with its ever-improving Notes and Reminders. As I mentioned earlier, other apps look and work great, as long as you play by their rules. As soon as you need something customized for your needs, you’re out of luck. I can play by the rules to an extent, but not when it comes to how I think and work. I guess I had to write it out here to arrive at that conclusion again, and surprise surprise, things are working out again.
What followed was reorganizing all my org files. A deep system cleaning that was much overdue. First, I archived many of them in my archive folder. Next, I went into my projects org file itself and archived a big chunk of projects that should have been completed and/or put away a long time ago. The trick was to remind myself that archiving is not the same as throwing away something: it’s simply putting it out of sight. It’s a simple rule: if it just sits there staring me in the face for more than a week, it needs to be archived. If I need to work on it again, I can put it back: org-refile is a powerful tool. I can always go into my archive folder, which is not a part of my agenda on purpose, and search through it with occur or consult-grep.
Speaking of my org-agenda: I got rid of scheduled TODO tasks, and I’m trying to keep it this way.
The kind of work I do today is 100% projects. There’s no such thing as a simple task; if it’s simple, it gets delegated. This means each project header, which is signified by the keyword ACTIVE, has somewhere between 5 to 20 subheaders: meetings, additional tickets, purchases, notes, emails, documents attached with org-attach, you name it.
Making these subheaders into scheduled TODO items quickly overwhelms my agenda and hurts motivation. Besides, I was stuck in the habit of always having a next-action item for every single thing, so many of those TODOs just ended up being something like “Follow Up” or “Reminder.” That’s a waste. A project is already marked with “ACTIVE” for a reason, after all. I know I need to follow up on something, that’s the entire point. The other thing is that the project header (the parent header) should be the header I work with. It’s where I keep my logbook notes (C-c C-z), and where I clock in and out. I used to do this for each subtask, but then I had to think about which notes go under which task, and it made it harder to follow up later, as I had to search across different tasks containing different fragments of notes. It’s too much running in circles. Now I just look at my list of projects, pick one to work on, and start a clock (C-c C-x C-i). When I’m done, I clock out (C-c C-x C-i) and write a few notes about what I did.
I still use subheaders when I need to save something (like an email, a ticket, or meeting notes), or when I work on something that takes more than half an hour on its own.
My work environment is a hectic mess these days, and Emacs is the only thing that is flexible enough (as always) to deal with… everything. The amount of productivity and communication apps people at work around me use is staggering, but they all work in the browser, need to be online, and don’t allow to customize things.
I need to be able to organize my head in Emacs. This is so important that I’m considering enforcing a small unofficial “break” during the day when I just sit down and clean up my projects and actually do some stuff. Otherwise I’ll be stuck all day just running after emails.
Footnotes
1 Many folks use iCloud and are happy with it, so why do I make my life difficult? The two technical reasons are my Linux desktop, which I use to access some of my org files, and my Android, which is more like a backup device to capture some notes. Another reason is the lack of control of iCloud: it works most of the time, but when it doesn’t, it really messed me up. It just stays stuck and doesn’t sync for whatever reason, and in case of a conflict, iCloud “decides” which file is the right one and overwrites whatever was there before. When I lost some work because of this recently, it was the last straw. Syncthing would always create a conflict file, where I can run Diff in emacs and quickly decide what I want to keep. It also has a built-in file versioning in its folders, which has saved me a couple of times in the past.
There’s also the tinfoil hat: I’m grumpy guy who yells at clouds. To put simply, I don’t trust Apple to store my personal and private files. After viewing their transperency report I was surprised to find out they share data with law enforcement 70-80 percent of the time. I just don’t like the “think of the kids” PG approach.
If you’ve been using Emacs on macOS and iOS for a while, you probably know Álvaro Ramírez, the maker of Journelly and dwim-shell-command. I’m a fan of both.
Turns out Álvaro has a sponsorship page on GitHub. If you benefit from his work and look for a way to help out, this is it!
Emacs and mental challanges
As part of a trip to see her friend, my mom went to a show of Porsche cars last week. This is a group of enthusiastic Porsche owners from different years. One of the stories she shared was about a proud Porsche owner who drives in countries that require the driver’s seat on the right (I’m assuming the UK or Ireland?) The driver, instead of abandoning his Porsche, had his beloved car set up with an adjustable steering wheel that can shift to the right or left side of the driver’s seat.
Emacers already know where this is going. We are all, in our own way, drivers just like this guy. The difference, of course, is that we drive Emacs, not a Porsche (though I’m sure there are a few of you out there who drive both!). I find this story inspiring because the laws that dictate where the driver should sit in the car are imposed. There’s nothing the driver could do about the law itself, so they came up with their own solution to work with the law in a clever way. Again… Emacs.
Emacs is not easy to drive in 2025. It has a steep learning curve, especially if you don’t have a good computer background. The other big problem is the outside restrictions. This blog is riddled with challenges I have with Emacs and different workarounds I came up with. I think this post I wrote earlier this year summarizes it well. To recap quickly: my work environment forces me to use applications that don’t play nice with Emacs. The biggest issue I have is with emails (only Outlook is allowed), but other cloud-based software is also problematic, usually because the only interaction with it is through the browser.
There are several community solutions for these issues. One of those is Emacs Everywhere, which I need to try to play with again (the issue I have there is creating a keyboard shortcut invoking a terminal command in macOS, which proved more challenging than I thought it would be), and there are more. But there’s also a bigger issue: there are plenty of new shiny apps out there, and next to Emacs, integration is always easier and nicer. Some of those, if I go deep into the rabbit hole, survive a day or two, even a weekend - but usually I go back to Emacs gasping for air. The overall issue with other apps is that they work nice, as long as you play by their rules and restrictions. As soon as you need to customize something, you’re out of luck. They are usually also all cloud-based, which is something else I don’t like. I know I’m old-fashioned, but I like that the cloud is there as a secondary place when I need it, not forced on me to use.
Some notable examples I visited again recently are both Apple tools: Notes and Journal. Notes got a few more tweaks, making it a useful as a personal database. I love how you can scan documents directly into the App, which works seemingly with the iPhone, and I love how I can now use it on my Apple Watch to check off items when I go grocery shopping. But I would never trust Apple to store my private notes on their servers. Journal has the same issue. The app itself matured nicely, with the addition of a macOS app. It comes with useful reminders, a map to see where entries were entered, a timeline, and a surprisingly good export option to HTML, including all the entries. But it’s also a good reminder of my point above: the date format.
I don’t like the US date format, especially in my personal notes. Org-mode automatically writes dates in a yyyy-mm-dd format, which has always made more sense to me (by the way, if you know a good app that can do that for the top menu in macOS, let me know. I’m surprised Apple doesn’t include that option natively. I’ve tried to change the region and play with the clock options in the past.)
The mindset that long-time Emacs users share with the Prosche driver is what got us into Emacs in the first place. We need things working out our way. In my case, I always liked checklists and bullet points, and I used several tools to help me organize things until I discovered Orgzly, and from there, org-mode and Emacs. I mentioned several times before that I owe my current professional successes (which include promotions at work, beyond just staying sane in a pretty chaotic environment) to org-mode, but that’s not exactly true. It’s the other way around: Emacs org-mode is a tool that enables me to use my mind the way I need to use it to work out information. I believe that if there were other tools that allowed me to change things as much as I can in Emacs, I would work with those too. But, in the age of the cloud, the opposite is true. Workflows are imposed, and customization to fit personal needs usually ends up being limited to dark and light themes.
Emacs is a rare tool that allows you to do whatever you want if you just look under the hood and tweak it to your needs. There aren’t many other programs like it, and I suspect that for most people, they are not needed. But for someone like me, adjusting to other tools doesn’t work well. And it’s not a good thing. I tried to force it a couple of times; believe me, if I were happy with Outlook, OneNote, and SharePoint, my work life would be much simpler. But I get disorganized, and I can’t work without my tools. If I like tinkering with something like Emacs, it’s not just for fun: if I don’t, I’m going to “glitch” until I fix it. It’s a battle uphill, a challenge—always was, and always will be. The benefit, however, is that it keeps me on my feet, and when I get something that works for me, it really works. Better than any other easy solution offered.
I found a potentially useful package that creates a visual calendar inside Emacs. It seems to be mostly abandoned, at least in its current form. It now requires ugly workarounds in order to work.
Does anyone know something like it that works currently?
Update: From the comments, I’m learning that taking the requirements for compat seems to be the official fix. This is a pretty nice package. I’m exploring it more in depth, and I might change some workflows I have accordingly. I find it amusing that I stumbled into it by chance, as I was writing my other post.
HTML export to work with TiddlyWiki
Two weeks ago, I wrote about some of the challenges I have when working with TiddlyWiki. In a nutshell, TiddlyWiki is better when you want other people to read technical documentation you otherwise much more comfortable writing inside Emacs org-mode.
My problem is that converting org-mode to WikiText (the way TiddlyWiki works) is a friction point, and I am not willing to leave the comforts of org-mode in favor of TiddlyWiki’s UI and hotkeys. They are OK, but they do not compare to Emacs and good muscle memory.
The solution (or rather, a workaround) that I found is to export my org-mode buffer to HTML with org-mode, and then let TiddlyWiki handle the rest. I documented this process in my wiki as part of recording the workflow.
There are still a few issues, of course. Certain HTML tags still need to be converted to WikiText (as I noted in the example in the wiki article) to reflect CSS options that otherwise do not trigger with the raw HTML code yet; this is something I can probably fix down the line. The other issue is that certain TiddlyWiki functions, such as integrated macros and lists, cannot be written inside org-mode because they contain square brackets that serve as links within org-mode.
Fortunately, it’s easy enough to fix those in the exported temporary HTML buffer before pasting back into a TiddlyWiki tiddler.
It’s been fun going back to TiddlyWiki and seeing some of the recent and exciting changes they’ve introduced. I will always have a soft spot for TiddlyWiki, since it was the first personal database I tried, before I discovered Emacs org-mode.
A quick rundown about how I write instructions in org-mode
On Reddit, someone asked how to write software documentation in org-mode, and I had a lot to say. Reddit, being Reddit, however, wouldn’t let me post my long comment. That’s fine, I don’t like spreading knowledge in silos anyway.
Here’s what I said:
Hi, my job involves writing technical documentation (instructions mostly), and I use org-mode for it all the time. I polished my process over the years, and it’s a loooong answer to a lot of stuff you probably didn’t ask, but I’ll try to break down the major parts.
First, I use Denote to write all my documentation, one file per tool or procedure if possible. Denote allows me to auto-associate files with keywords (for example, instructions for macOS vs Windows) and also shows me when I wrote the file automatically (it’s in the file name), so I know how old the information is. In the org-mode file itself, I often add notes using C-c !, an inactive timestep, so if there’s an update to a part of the instructions, I know what happened when. Something I don’t use for work but in my own notes is Denote’s dynamic blocks (a block of code with dynamic links to other org files), which serve as an index to quickly view related notes.
In the org-mode file, besides the Denote options, I add options in the meta part to get rid of TOC (table of contents) and display images inline: #+STARTUP: inlineimages and #+OPTIONS: num:nil. I often use annotated images, which I embed into the org file and attach to the headers (so the images are connected to the files).
A couple of years ago, I decided to adopt and use the Microsoft Style Guide (look it up, see if it’s for you) mostly to keep consistent. I don’t like Microsoft, but they have some documentations that make sense, and my work environment is Windows-based, so they cover what I need. There are other style guides out there; whatever you find, stick with it. The style guide is what tells you what words should be in bold (UI elements and buttons) vs what gets italicized (things you want to emphasize) or why you should use “select” over “click” or “tap” (because it’s more generic and applies to more UIs). It’s up to you how crazy you want to get. I find that it helps immensely, and it’s already become an integral part of my writing.
When I write in org, I often use comments (# followed by a space and the comment) as a reminder of what I still want to cover as ideas come to me under the paragraph I’m currently writing. For example, in this long post, I had a # what about images? under what I was writing until I got to it as a reminder.
I don’t use headers right away, unless it’s something obvious from the start, like an Introduction explaining what a certain tool is (first header) and then the process to use it (second header). I prefer numbered lists and quick steps in my instructions; each line describes one action, unless it’s something simple. I use links often - and here’s another important tip: I have (setq org-export-with-broken-links t) in my settings because org-mode expects nice normal links, but Microsoft products don’t always have them, and org-mode won’t let me export with what it considers broken unless I turn it off. I validate links later, in the finished product (by the way, always use target=blank in your links so when someone selects a link, it doesn’t hijack their window but opens another window or a tab).
I don’t use in-document links (anchor links, forget what they’re called) because these don’t always work well. It’s better to tell your users something like “for uninstall instructions, see header name below,” and let them go there. Anchor links are confusing and can break when you export.
When I’m done with my lists, I see if the sections make sense. I sometimes break into sub-sections, but if I go beyond 2nd level headers, I need to consider if I should expand into another article because it tells me the instructions are getting too complex.
I got to expand a bit more about Images. Using images is almost always better, as long as they are clear and use consistent annotations (write your own style guide). I prefer arrows over circles because I find they draw the eye better, and I like using callouts with text (like in speech bubbles in comics), pointing to what I’m talking about in the images. I try to use the same text from the instructions in the images. So if step 3 in the instructions says “select submit,” I will use a bubble pointing to that button in the image, and it will say “select submit” exactly the same way. There’s more to say about images, but this goes beyond org-mode, so I’ll stop here with this.
When I export, I use pandoc . I don’t like to use Emacs HTML exporter. The reason for that is that pandoc comes with more options and the ability to have a “template” Word document that will automatically stylize your document with the right colors, font, font sizes, etc. You tweak it once in Word and it’s good forever. I don’t like to use html from org-mode because it comes with a lot of extra “fluff” you need to strip away (it’s possible, you need to find the options in the Emacs manual and specify, I just got lazy), and also everyone at my workplace uses Word or SharePoint, so it’s just easier. I love Pandoc, and I highly recommend looking into it if you’re writing a lot.
I can keep going… There are spell checkers and grammar checkers (not the same thing), and Emacs doesn’t really have a good built-in grammar check, in my opinion. I blogged about Harper not too long ago, and it’s a good tool that can be integrated into Emacs (especially if you’re on a Mac), but if you’re writing for large audiences, you might need something better. There’s more to say about videos vs images, and depending on what system you store your articles in, it affects what you want to do there (or don’t want to do there), as in if it’s a wiki or a ticketing system or some other content management system.
But it’s time to grab some dinner.
If you have specific questions, feel free to ask. I love talking about these things if it’s not obvious!
Thinking about organizing my RSS stuff
Today, I stumbled upon Moly White’s Curate your own newspaper with RSS.
To the readers of this blog, there’s nothing really new here. RSS is how we have been reading our articles for a very long time. This is true (maybe especially true) for social media; I can see if there’s anything worth logging in for on Reddit before I expose my eyeballs to pesky ads. By the way, I just learned Bluesky offers RSS too, as they should.
However, reading this article and thinking more about how I read stuff made me realize that my current state of content consumption is chaotic.
I mostly read RSS feeds on my Android, because I just happen to have it nearby whenever I’m not on the computer doing something. It’s easy to grab when I need to use the bathroom or before I go to sleep. I know I’m going to read mostly interesting things because, as Moly says, it’s my own newspaper. But I also read RSS feeds on Emacs using Elfeed, and the feeds I have there are not the same as I have on Feeder. Meanwhile, I have another database in Feedly on my iPhone, which I use less, but still.
Having different feeds on different devices is problematic enough, but there’s another somewhat related issue.
Micro.blog, where I host my blog, is a special social network and a collection of blog-related tools on top of being a place to host this website. One of those useful tools I use all the time is the platform’s “read it later” tool, which they call “Bookmarks.” Saved articles in Bookmarks are stripped of ads and annoying pop-ups for comfortable reading (similar to “reader mode” in other browsers). They are also stored automatically in the cloud, so I can get back to them much later, even years later, and it would still be there with the relevant images and everything. Though different from RSS, there’s yet more content I want to read. If RSS is the newspaper, Micro.blog’s Bookmarks are the drawers of my desk, containing clips from all kinds of news outlets, blogs, even stuff like manuals for home appliances when I’m too lazy to put them in org-mode.
My content consumption is literally all over the place(s).
This morning I was looking into some solutions in the form of an RSS server which will work well with Elfeed in Emacs. The reason integration with Emacs is important (besides the obvious answer, “duh, it’s Emacs”) is that this is also where I write my posts. Ideally, I could follow up on everything I read from inside Emacs, find my comments about it, and write a draft. And guess what! I just found out that Micro.blog offers an RSS private feed to each user’s Bookmarks page. I shouldn’t be surprised when it comes to Micro.blog, RSS is king1.
Having my devices “talk” to each other and figure out which articles I read and from where would be great, especially since I don’t necessarily have all my feeds in one place. For example, I follow Hacker News only on my iPhone, and my Android’s Feeder contains a few gems from Kagi’s small web RSS feed which I don’t have in Elfeed yet. I just need to figure out how to start organizing this mess.
Footnotes
1 : not directly related, but on the topic of RSS: Micro.blog allows you to integrate RSS feeds directly into your blog, which in my opinion is one of its killer features. I mentioned it before, but my Movies and Games categories, where I rate both, are not even written on this blog; these are posts from my letterboxd and backloggd accounts, which integrate into the blog and look like my posts.
Denote with a different root directory on Linux only
As some of you may be aware, I prefer to keep certain things private, which means I don’t use cloud services for those. So, I wanted to have a dedicated folder for private notes on my Linux desktop, which doesn’t sync to my Mac. This sounds simple enough, but my setup makes it a bit more complicated.
For my technical documentations and blog posts, I use Denote, an excellent org-mode note-taking package from Protesilaos Stavrou (AKA Prot). By design, Denote is set up to have one root folder to work from with an option for subfolders under that folder for organization, which is what I have: ~/Sync/Notes/ is the main folder, and under it I have ~/Sync/Notes/Info and ~/Sync/Notes/Blog/, which should make sense if you’re follwing along.
~/Sync/Notes/ is under my Sync folder which is synced between my devices with Syncthing. Usually this is a good idea, since I want to have my technical notes and blog posts available to me both on Linux and on the Mac - and for that matter also on the iPhone and Android, but that’s a different story.
You’re probably starting to see the problem here. Denote is using a synced folder for its root folder, so I can’t have a “just for Linux” folder under normal circumstances. I wanted that private Linux-only folder to be at ~/Documents/private on my Linux desktop, and here we have yet another problem: the Mac has a ~/Documents/ folder as well, which I’m syncing to iCloud. Again, usually this is good: some of my work files are there, and I have a few settings saved. But if this folder was synced between my Linux and the Mac, these files will quickly be uploaded to Apple’s servers. Not good.
While Denote’s documentation notes that the upcoming release will have the option to define several folders as a list for denote-directory, this is not in production yet. So my first attempt took me through Syncthing documentation.
I knew I could ask Syncthing to ignore files using ignore patterns, and these are robust enough to work on folders as well. After a few attempts, I managed to have a ~/Sync/Notes/private folder on my Linux desktop that did not sync to my other devices.
While this works, it’s a weird workaround to have an isolated folder inside a folder meant for syncing; it’s kind of counterintuitive. Another concern: if the .stignore file with the ignore pattern was to be deleted by mistake, Sycnthing would sync that folder and its contents everywhere.
Digging deeper into my old Denote configurations, I found the solution in a Denote function that could solve it:
(defun jr-private-denote ()
(interactive)
(let ((denote-directory (expand-file-name "~/Documents/private/"))
(denote-excluded-directories-regexp "data")
(denote-prompts '(title keywords))
(denote-org-front-matter "
#+title: %s
#+creator: JTR
#+date: %s
#+filetags: %s
#+identifier: %s
#+STARTUP: inlineimages
#+OPTIONS: num:nil
\n"))
(call-interactively 'denote)))
This function bypasses the regular denoate creation process (M-x denote) and changes the denote root folder to ~/Documents/private just for the purpose of this function. As well, I’ve included a few more options in the Denote front-matter, like the creator and the option to load images when the file loads. This function also excludes the /data subfolder under ~/Documents/private, which contains attachments, so I don’t create a note there by mistake.
This worked well, but it still leaves me with the problem I mentioned earlier. My configurations are stored in an org file synced inside my sync folder (so Emacs on my Linux desktop will run the same way as Emacs on my Mac, as much as possible), which means I could still run this function on the Mac, creating a private note in my Documentation folder there, and I don’t want a chance of that to happen. Besides, tweaking stuff is fun.
To fix that, I included a condition to help out:
(defun jr-private-denote ()
(interactive)
(cond
((eq system-type 'gnu/linux)
(let ((denote-directory (expand-file-name "~/Documents/private/"))
(denote-excluded-directories-regexp "data")
(denote-prompts '(title keywords))
(denote-org-front-matter "
#+title: %s
#+creator: JTR
#+date: %s
#+filetags: %s
#+identifier: %s
#+STARTUP: inlineimages
#+OPTIONS: num:nil
\n"))
(call-interactively 'denote)))
((eq system-type 'darwin)
(message "You're using your Mac"))))
Now I have the Denote org file creation process dependent on a condition that I am running on Linux: (eq system-type 'gnu/linux). In case I’m running on Mac, (eq system-type 'darwin), I will only get a reminder that I’m using my Mac, and that’s it, nothing further will happen.
In Emacs, when you press M-y, you can go through all the recent text snippets that are stored in your kill ring (aka “clipboard” in modern-day programs) via yank-pop. In two seconds, I found what I needed from yesterday, and I’m ready to go.
Emacs is just like that, once you learn to use it. Two seconds, you get what you need (for me, usually in org-mode), and you move on with your life. Everything is tailored to fit you, the user. That’s what happens when a bunch of productivity geeks sit together and build a program.
Sure, not all (and even most) programs that are open source end the same way, but Emacs is unique. It’s a shining example of what happens when different people have different needs and are provided with open tools to answer those needs. I’m not a Lisp coder, but I know that when I need to change something or tweak it, I can, and I have all the help documentation and a community behind me to help achieve what I need.