Emacs org-mode
Welcome to the Emacs org-mode category.
You can subscribe to this category only via RSS!
I am working on restoring some of my related posts from my old blog, so keep checking here for new content.
Harp is org-mode medical app for Android
There’s the app for health-related records Irreal mentioned the other day, Harp. It’s an org-mode-centered app for Android (soon to be iOS though), which looks pretty basic at this point. You can create several profiles (for different people), and each one has a medical journal and documentation attached, along with some graphs as you accumulate data.
It’s a good idea to have an org-mode-based health app, with all the information you need available to you quickly, protected behind encryption. The issue specific to me is that even though I have a personal Android phone, it’s my iPhone that has my medical apps (part of the Epic suite), as this is the phone I usually carry around with me. These apps already have all my health records, doctors, appointment etc.
I’ve been playing with it a bit, and I think it’s mostly the idea of having my health records saved in org mode that makes sense, especially with the denote file convention system. My Android is also where I have signal, which I can use to share medical records with people close to me, so there’s that. It’s not ideal to carry around two phones, but I think I want to experiment for a bit.
I think I found what crashed my Emacs on macOS
For those of you following along, Emacs has been crashing on my Mac (but not on my Linux desktop) for a while, but it seemed too random to pinpoint. This led me into looking for the Darwin version in the Emacs build in Emacs for Mac OS (which was what I was using on my Mac), which was a couple of versions behind that of macOS itself.
I went ahead and attempted to use Emacs Plus from Homebrew, as most people commented. I haven’t noticed much of a difference, though personally I do prefer to use Emacs from Homebrew as I do with my other packages, so I stuck with it a bit longer.
Yesterday I encountered a stubborn crash in my journelly.org file. Journelly, which is basically a large org-file with pictures displayed in-line under some headers (you can get an idea of what Journelly is and how I use it here).
I took a picture of the snow outside with my iPhone using Journelly, which saved it to journelly.org with the image attached. On the Mac, every time I went to open the header, Emacs crashed, time after time. I just couldn’t edit that image. In a collapsed state for the header, where the image didn’t show, it was fine. On Linux, when I tried - fine. Oh, and before you ask - I tried this with emacs -Q, and yes, it crashed every single time as well.
The JPG image on my iPhone was a 7MB file with dimensions of 4284 x 5712. I knew from past experience that such large images slow down Emacs (on Linux too), so I shrunk it down to a 700kb file with dimensions of 604 x 640, and launched Emacs again. No problem. Everything was stable. I tried to load Emacs a few more times and it worked each time.
This was my hunch from the beginning - that something is up with images at least on the Mac, and this is proof enough for me. I don’t know exactly at what point Emacs crashes: is it a matter of how many images the org file has? How big are they? A combination of both? But I can tell you it seems to be more about the dimensions of the image in pixels than the file size. This is fine for me, for my journal, I don’t need large high-resolution images anyway; those are uploaded and displayed on my blog and elsewhere. It seems that some folks have encountered similar issues as well, from Reddit and elsewhere.
If you have similar issues and you’re fine with scaling down your images, a good solution is dwim-shell-commands-resize-image-in-pixels, part of the excellent dwim-shell-command package, which can quickly shrink down a large number of images from inside Emacs. I’m using it constantly.
Switched to emacs-plus to try it again for a few days. Darwin version is now up to date. Let’s see what the differences are, if there are indeed any - and of course, if things keep crashing.
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.
Lately, Emacs on my Mac has been crashing more frequently. I don’t know for sure what it is, and I can’t get much from the logs, but it seems to be somewhat related to images. Perhaps some memory issue.
My research has led me to suspect that perhaps emacs-plus from Homebrew would be better (I’ve been using Emacs for macOS), but I’m not quite sure yet.
Right now I’m too tired to tackle it, so I’m going to crawl to bed. I’ve been too tired and too busy in the evenings to do much of my personal projects, which sucks. Hope to get some stuff done this weekend, but it’s going to be a busy one.
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.