Emacs on Jiewawa's blog

Overriding keybindings with Meow

Fri, 01 May 2026 00:00:00 +0000

I previously wrote about useful Emacs commands for reading. This allowed me to use j and k to scroll the window up and down instead of going forward or backward a line.

I am now using meow for my modal editing needs and have been really happy with it. Meow allows for custom states to be defined, but I have been using a different method recently that takes advantage of the built-in normal and motion states.

Meow has a very clever design choice in that when a key is pressed it can translate it to the default emacs binding and call it via a macro. Below is an example of the function meow-next, which I have bound to j. It essentially just executes the key-binding that is stored as the value of meow--kbd-forward-line which happens to be C-n.

(defun meow-next (arg)
  "Move to the next line.

Will cancel all other selection, except char selection.

Use with universal argument to move to the last line of buffer.
Use with numeric argument to move multiple lines at once."
  (interactive "P")
  (unless (equal (meow--selection-type) '(expand . char))
    (meow--cancel-selection))
  (cond
   ((meow--with-universal-argument-p arg)
    (goto-char (point-max)))
   (t
    (setq this-command #'next-line)
    (meow--execute-kbd-macro meow--kbd-forward-line))))

(defvar meow--kbd-forward-line "C-n"
"KBD macro for command `forward-line'.")

Because meow’s keyboard macro commands are all stored as variables, it is easy for us to overwrite them locally. In the following example I will show how I made a minor mode that lets me have a more enjoyable reading experience.

Firstly, we need to bind the new functions to some obscure key combination. I chose to add these to the global keymap in this case as I want them available across a variety of major-modes.

Then I wrote functions to toggle between the original values of the meow–kbd variables and their overrides.

Finally, I defined a minor mode that can be added to a major-mode’s hook.

(keymap-global-set "M-s-j" 'scroll-up-line)
(keymap-global-set "M-s-k" 'scroll-down-line)

(defvar meow-reading-originals
  '((meow--kbd-backward-line . "C-p")
    (meow--kbd-forward-line . "C-n")))

(defvar meow-reading-overwrites
  '((meow--kbd-backward-line . "M-s-k")
    (meow--kbd-forward-line . "M-s-j")))

(defun meow-reading-restore-directions ()
  "Restore Meow's direction variables locally."
  (dolist (binding meow-reading-originals)
    (set (make-local-variable (car binding)) (cdr binding))))

(defun meow-reading-overwrite-directions ()
  "Overwrite Meow's direction variables locally."
  (dolist (binding meow-reading-overwrites)
    (set (make-local-variable (car binding)) (cdr binding))))

(define-minor-mode meow-reading-mode
  "Adjust some bindings to make `meow-normal-mode' a better experience for reading modes."
  :lighter " reading"
  (if meow-reading-mode
      (progn
        (meow-reading-overwrite-directions)
        (setq-local meow-cursor-type-motion nil)
        (meow--update-cursor-motion))
    (progn (meow-reading-restore-directions)
           (kill-local-variable meow-cursor-type-motion)
           (meow--update-cursor-motion))))

Here is an example of how you can have the minor mode be loaded for all buffers of a given major mode.

(use-package elfeed
  :hook
  (elfeed-show-mode . meow-reading-mode))

The reason that I prefer this to making a whole new “reading-state” is that this is still using meow’s default motion-state. I get to take advantage of all of the default key-bindings. One of the reasons that I moved from evil to meow was that I was getting tired of having to bind so many functions myself. With this method, I can essentially say “I want this mode to behave the same as all of the others, just with one or two changes”.

I am also working on a minor mode for lisp modes that takes advantage of smartparens to hopefully create a lispy like environment, but that is still a work in progress.

Tools for Studying Chinese with Emacs

Fri, 21 Nov 2025 00:00:00 +0000

In my 20 years of studying Chinese, I have tried countless tools for helping me learn efficiently.

Recently, I have seen a growing overlap between Chinese learners and Emacs users. Therefore I want to share some of the tools that I have found or developed since switching to our beloved editor.

On AI/LLMs

It’s probably quite shocking to find no AI packages on this list. While I don’t fundamentally have any issue with people using AI for language learning, I find that many people now automatically reach to LLMs as their first port of call.

LLMs need to be considered a tool, and for my particular use case there are better tools for the job.

Paw

Paw by Damon Chan is one of the most impressive packages I have seen. I think that for language learners and knowledge workers, it has the potential to be considered in the same vein as Org-Mode and Magit as a killer Emacs package.

Paw manages to combine many Emacs packages and command line applications into a cohesive environment. It can manage known words and annotations, it can access online and offline dictionaries and it can be used as a front-end to LLMs for your language learning needs.

The author primarily developed it to work with English and Japanese, but I have worked on adding basic Chinese support. There is still work to be done, as the package is being actively developed. There are some new features such as live annotation that I haven’t even tried yet.

jieba

Any Chinese learner should use a tool that segments text into words, rather than just breaking it down character by character. There are emt for Mac, ewt-rs for Windows, emacs-chinese-word-segmentation, but I settled on the cross platform emacs-jieba as the rust implementation of jieba is both fast and actively developed.

CC-CEDICT

CC-CEDICT is a Creative Commons licensed Chinese to English dictionary that is built into many popular Chinese dictionary applications such as Pleco. I have added a few words over the years, but it’s definitely something that I want to contribute more to in the future.

It is really useful having a dictionary that is so thorough and has such consistent formatting in a plain text format. In fact I use the Emacs package cc-cedict.el as the base for many of my own functions in which I need the pinyin or definition of a given word.

pinyin-convert

I have been using pinyin-convert to convert between pinyin written with tone numbers and diacritics. I mostly use it in conjunction with cc-cedict.el as that dictionary uses tone numbers like zhong1guo2. Running pinyin-convert--string-to-tone-mark will convert it to zhōngguó. This is a small package but it works really well. It’s definitely worth trying out.

Typing Chinese

Before I switched to Emacs, I was using fcitx5 and rime for typing in Chinese, so naturally emacs-rime was a logical choice as my input method editor. It works really well and I like how it allows regular keys to be used in normal mode for both evil and meow. Nowadays, this is the only way that I type Chinese on my computer. If I want to type in another application, I do it via an pop-up Emacs buffer.

For systems where librime is not available, pyim is another alternative. I have never needed any alternative to emacs-rime so haven’t tried it out. The user TomoeMami reached out to me to suggest sis for using OS-native input sources and Emacs-native input sources.

zh-utils

I wrote the zh-utils package to collect all the Chinese related functionality I have written over the years. It is easier for me to manage now that I am treating it as a package instead of various functions in my init.el, and other learners can take advantage of it.

As of now it is capable of the following:

Convert Chinese characters to Pinyin
Check if a string is Chinese or not
Return the most likely Chinese word at point using segmentation
Return which part of speech a given string belongs to

Check out the readme for more details.

Tone Colours

Pleco is definitely the best Chinese dictionary on mobile, and one feature that I didn’t realise was so useful when I started using it all those years ago is having characters coloured based on the tone associated with it.

I found that when I think of a character, I quite often would picture it in red, green, blue, purple or grey depending on its tone. My zh-utils package includes some code that utilises org-mode links to achieve the desired result.

For example [[t3:][我]] would be rendered with the correct colour. I even wrote a tool that converts a CC-CEDICT dictionary file to make use of this format.

The code below is for having nicer colours with Modus themes, and in fact I have even changed the Pleco app to use the same colours as well.

(defun my-modus-themes-custom-faces (&rest _)
  (modus-themes-with-colors
    (custom-set-faces
     `(t1-face ((t :height 1.9 :foreground ,red-intense)))
     `(t2-face ((t :height 1.9 :foreground ,green-intense)))
     `(t3-face ((t :height 1.9 :foreground ,blue-intense)))
     `(t4-face ((t :height 1.9 :foreground ,magenta-warmer)))
     `(t5-face ((t :height 1.9 :foreground ,comment))))))

(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces)

Anki

I have known about the power of Anki for a long time, and I have kept up the habit of making and reviewing flashcards on and off over the years.

Previously, I had been using simple Front/Back flashcards. Now having watched Daniel Evensen’s recent video explaining how he sets up Anki for language learning, it really clicked to me that I should be using my own note layout with multiple fields to generate different types of cards based on the same note.

In the images below, you can see an example Anki note, and a preview of a card based on said note.

I wrote an org-capture template that calls a function I wrote for making a flashcard with a single key stroke. It automatically generates audio for the word, and fills in all the fields for the note type. It uses several of the zh-utils functions and is able to guess what word I want based on context.

(defun my/create-flashcard (word)
  (let* ((cc (cc-cedict word))
         (pinyin (pinyin-convert--string-to-tone-mark
                  (cc-cedict-entry-pinyin cc)))
         (definition (string-join (cc-cedict-entry-english cc) ", "))
         (sound (format "[sound:%s.mp3]" word))
         (level (zh-utils--get-hsk-level word))
         (grammar (zh-utils--get-word-grammar word))
         (coloured (zh-utils-tonify-word word)))
    (zh-utils-tts-make-audio
     "zh-CN-YunyangNeural"
     (format "%s %s" word word)
     word)
    (format
     (concat "* %s %s\n"
             ":PROPERTIES:\n"
             ":ANKI_DECK: Chinese::New\n"
             ":ANKI_NOTE_TYPE: Jack Chinese\n"
             ":END:\n"
             "** Chinese\n%s\n"
             "** Pinyin\n%s\n"
             "** Definition\n%s\n"
             "** Grammar\n%s\n"
             "** Sound\n%s\n"
             "** Coloured Characters\n%s\n")
     word
     (if level (format ":%s:" level) "")
     word pinyin definition grammar sound coloured)))


(defun my/create-flashcard-from-context ()
  "Create flashcard using context-aware word selection."
  (let ((word (zh-utils--org-capture-flashcard-get-word)))
    (when word
      (my/create-flashcard word))))

(push '("c" "Chinese Flashcard" entry
      (file "~/notes/new-flashcards.org")
      (function my/create-flashcard-from-context))
    org-capture-templates)

To make the coloured characters in Anki match the colours of Modus Themes, I add the following CSS to the card’s styling.

.t1 {color: #e30000;}
.t2 {color: #01b31c;}
.t3 {color: #150ff0;}
.t4 {color: #8800bf;}
.t5 {color: #777777;}

.nightMode .t1 {color: #ff8080;}
.nightMode .t2 {color: #80ff80;}
.nightMode .t3 {color: #8080ff;}
.nightMode .t4 {color: #df80ff;}
.nightMode .t5 {color: #c6c6c6;}

Fonts

The two Chinese fonts I like to use in Emacs are Adobe Fangsong and Sarasa Gothic. I often toggle between the two of these, but I didn’t think that this was worth including in my zh-utils package. You may find it useful as a starting point.

(defun my/set-han-font-fangsong ()
  (set-fontset-font "fontset-default" 'han
                    (font-spec :family "Adobe Fangsong Std"))
  (setq my/han-font "fangsong"))

(defun my/set-han-font-sarasa ()
  (set-fontset-font "fontset-default" 'han
                    (font-spec :family "Sarasa Mono SC"))
  (setq my/han-font "sarasa"))

(defun my/toggle-han-font ()
  (interactive)
  (if (equal my/han-font "sarasa")
      (my/set-han-font-fangsong)
    (my/set-han-font-sarasa)))

(set-fontset-font "fontset-default" 'han
                  (font-spec :family "Sarasa Mono SC"))
(setq my/han-font "sarasa")

Trying to do the last 20%

Tue, 21 Oct 2025 00:00:00 +0000

For the last few years, I have been using Emacs for almost all of my daily computing needs. In that time, I have also become fairly proficient at elisp. Across many files in my user-emacs-directory, I have hundreds of functions and snippets of code that I have written myself.

However, one area that I would like to improve is what I am calling “the last 20%”. These functions mostly work for me, but if I ever wanted to share these functions with others, then there is a lot of work that needs doing to get them into a ready state.

I previously wrote one set of code that could be packaged into a minor-mode and it was really rewarding when I once someone else using that code in their configuration.

Going forward, I want to tidy up and organise many of the functions into their own small packages so that I can maintain them better for myself. Below I will list some of the packages for which I have already written most of the logic, and are simply missing “the last 20%”.

Org-workout

This is a tool for tracking, analysing, planning and plotting workout data which are stored in human readable org files. This project is already on Codeberg.

Koreader-import

A tool for converting highlights from Koreader and importing them into the emacs highlight manager of your choice such as org-remark or paw.

eww-filters

A follow on to my eww-rdrview integration. Filters for web pages based on the URL. I chose to modify the HTML before emacs converts it to SXML, so that theoretically filters could be shared with other text based browsers. It already mostly works with w3m-filters

meow-paren

Create a lispy-like experience with meow. Overwrite meow vars in normal mode instead of making a new mode. I went into this tool with the idea of packaging it, so the conventions are good, but some logic is still missing.

Chinese Helpers

I realised that the file containing all my functions regarding learning Chinese and using it in emacs was about 800 lines long. I think some of these can be removed now, but I think other users could get some use out of some parts.

Conclusion

Recently, I have found myself having a bit more free time and have been enjoying hacking on emacs lisp. One of the things that makes emacs so amazing is the community, and I now want to give something back and this post will hopefully keep me accountable.

Useful Emacs commands for reading

Fri, 04 Oct 2024 00:00:00 +0000

Since I started using Emacs, I’ve written hundreds of functions that I only used once and then were left to rot in the depths of my init.el.

Today I would like to share some simple commands that I wrote when I was just starting off with Emacs that I had forgotten that I had written and assumed that this was the default behaviour as it now seems to natural to me. A very small amount of the code here will be specific to evil-mode, but it shouldn’t be too difficult to adapt it to work without.

Removing visual fluff

I like to have a clean, distraction free reading experiences in major-modes such as elfeed, eww, and nov.

I achieve this by:

Centring the text in a column and increasing padding.
Hiding the mode-line
Hiding the cursor

Centring text

I use olivetti for centring text and have no complaints. It works seamlessly for my needs. In fact, I also enable this in Org-Mode and Markdown-Mode.

(defun my/centre-visual-fill-on ()
  ;; Centre the text in one column
  (visual-line-mode 1)
  (setq olivetti-body-width 100)
  (olivetti-mode 1))

(defun my/centre-visual-fill-off ()
  (visual-line-mode 0)
  (kill-local-variable 'olivetti-body-width)
  (olivetti-mode 0))

Hiding mode-line

I’ve seen lots of people do this one and it is useful when wanting to focus. Unlike the previous commands, this is something that I sometimes toggle so I made an interactive function too.

(defun my/kill-modeline ()
  (setq-local mode-line-format nil))

(defun my/restore-modeline ()
    (kill-local-variable 'mode-line-format))

(defun my/toggle-modeline ()
  (interactive)
  (if (null mode-line-format)
      (my/restore-modeline)
    (my/kill-modeline)))

Hiding the cursor

This is one that I don’t remember seeing anybody else do, but it’s a game changer. When I’m reading, I’m following with my eyes and I don’t care where the cursor is unless I decide that I want to highlight some text. Again, I want to be able to toggle this quickly so I wrote an interactive function too.

(defun my/hide-cursor-evil ()
  (setq-local evil-default-cursor '(ignore))
  (setq-local cursor-type nil))

(defun my/show-cursor-evil ()
  (kill-local-variable 'evil-default-cursor)
  (kill-local-variable 'cursor-type))

(defun my/toggle-cursor ()
  (interactive)
  (if (null cursor-type)
      (my/show-cursor-evil)
    (my/hide-cursor-evil)))

I combine these three ideas into a simple hook that gets ran whenever I open a new buffer in one of my reading modes.

(defun my/reading-mode-hook ()
  (my/centre-visual-fill-on)
  (my/hide-cursor-evil)
  (my/kill-modeline))

Figure 1: Screenshot showing Org Mode on the left and eww with cursor hidden on the right

Navigating

I’ve seen takes on the previous ideas many times while reading other Emacs users’ blogs, but I haven’t seen many users describe how they move around buffers that are primarily meant to be read.

Initially I tried using a form of paging, but I found it tedious to have to scan for where I left off before I scrolled down.

Ultimately, I settled on the following logic, which was very simple to implement:

If the cursor is visible, move the cursor up or down one line
If the cursor is not visible, scroll the buffer up or down one line

(defun my-view-down ()
  (interactive)
  (if (null cursor-type)
      (scroll-up-line)
    (next-line)))

(defun my-view-up ()
  (interactive)
  (if (null cursor-type)
      (scroll-down-line)
    (previous-line)))

Tying it all together

I could have come up with a minor mode for enabling this in each major mode, but I like how this reminds me of a time when I didn’t spend so long dicking about with functions that I only use once.

Here is a simple example configuration of how I have elfeed set up.

(use-package elfeed
  :hook
  (elfeed-show-mode . my/reading-mode-hook))

(evil-define-key 'normal elfeed-show-mode-map (kbd "j") 'my-view-down)
(evil-define-key 'normal elfeed-show-mode-map (kbd "k") 'my-view-up)

Another Way of integrating Mozilla Readability in Emacs EWW

Wed, 10 Apr 2024 00:00:00 +0000

I was browsing Planet Emacslife yesterday when I came across Anand Tamariya’s post Mozilla Readability in GNU Emacs. I recently wrote a minor mode that had achieves the same thing, but Anand and I took very different approaches to get the same results.

Anand used the official Mozilla Readability package, but I use rdrview which is a port of Mozilla’s original program written in C. The developer claims that “the code is closely adapted from the Firefox version and the output is expected to be mostly equivalent.”

He also modified the source code of eww.el, whereas my approach was to use the eww-retrieve-command variable which was added in Emacs 28.1. The following is enough to get started, but I wasn’t entirely happy with the results.

(setq eww-retrieve-command '("rdrview" "-H"))

Since Emacs 29.1, EWW buffers can be automatically renames to give more descriptive names I typically like it to display the title of the web page. The following code can be used to accomplish it.

(defun my-eww-rename-buffer ()
  (when (eq major-mode 'eww-mode)
    (when-let ((string (or (plist-get eww-data :title)
                           (plist-get eww-data :url))))
      (format "%s *eww*" string))))

(setq eww-auto-rename-buffer 'my-eww-rename-buffer)

However, the way that rdrview works is that it only displays the main content of a web page and that does not include the <head> or <title> tags. I often have many EWW buffers open, so it is very important that I can quickly distinguish each of them without having to opening them.

By changing the flags provided to the rdrview command, I could prepend the web page with the title. Then, I simply had to write a function that updates the title in eww-data, and add the function to eww-after-render-hook.

(define-minor-mode eww-rdrview-mode
  "Toggle whether to use `rdrview' to make eww buffers more readable."
  :lighter " rdrview"
  (if eww-rdrview-mode
      (progn
        (setq eww-retrieve-command '("rdrview" "-T" "title,sitename,body" "-H"))
        (add-hook 'eww-after-render-hook #'eww-rdrview-update-title))
    (progn
      (setq eww-retrieve-command nil)
      (remove-hook 'eww-after-render-hook #'eww-rdrview-update-title))))

(defun eww-rdrview-update-title ()
  "Change title key in `eww-data' with first line of buffer.
It should be the title of the web page as returned by `rdrview'"
  (save-excursion
    (goto-char (point-min))
    (plist-put eww-data :title (string-trim (thing-at-point 'line t))))
  (eww--after-page-change))

That’s all you really need to use this minor mode, but my preferred entry point is toggling it on and off from within EWW. The regular eww-readable function is bound to a single key press, and I wanted to also have a function that can be called the same way.

(defun eww-rdrview-toggle-and-reload ()
  "Toggle `eww-rdrview-mode' and reload page in current eww buffer."
  (interactive)
  (if eww-rdrview-mode (eww-rdrview-mode -1)
    (eww-rdrview-mode 1))
  (eww-reload))

Generally eww-readable is good enough at getting rid of the distracting parts of a web page, but there are still times when it doesn’t work exactly as I want it to. There are also times when rdrview doesn’t work as I’d hoped it to either.

Since writing the above code, I find that I have been using both methods for removing clutter from web pages. I’ll try one and if I’m not satisfied, then I’ll use the other.

Blogging with Denote and Hugo

Tue, 26 Mar 2024 00:00:00 +0000

A few months ago, I replaced Org-Roam with Prot’s Denote package and have been using it for a while now. I have mostly been using it to manage my collection of personal notes, but I also want the option to publish any note as a blog post quickly and easily.

Since starting to use Denote, I am trying to think of notes and public blog posts not as two separate entities, but as a part of a larger knowledge base. Unless I’m writing something specific like notes on a book, which would go in the /books subdirectory, most notes start their life in the root of my denote-directory before being moved to a relevant subdirectory. Blog posts are moved to the /blog subdirectory.

With ox-hugo, you can write all posts in a single Org file, or like I do, you can have a single file for each post. ox-hugo also provides a really useful feature for auto-exporting on save. I enabled it by adding the following in the .dir-locals.el file in the /blog subdirectory.

((org-mode . ((eval . (org-hugo-auto-export-mode))
              (org-hugo-section . "blog"))))

The three stages of a blog post

I make use of Denote’s file-naming scheme to easily distinguish between each of the following states that a note can be in:

Private note: Located in the root of my denote-directory
Draft blog post: Located in the /blog subdirectory, with the keyword draft
Published blog post: Located in the /blog subdirectory, without the keyword draft

Below is truncated tree view of my denote-directory:

├── 20230708T141810--books__metanote.org
├── ........
├── blog
│   ├── ........
│   ├── 20231104T134226--a-dwim-fullscreen-function-for-emacs-and-sway__emacs_linux.org
│   └── 20240323T143034--hacking-on-denote-and-hugo__blogging_denote_draft_emacs.org

Linking

Prot introduced a new set of link parameters specifically for Denote. The file’s Denote identifier is used to refer to the file you want to link to [[denote:20230708T141810][Books]] and the title of the file is the description. I have seen some Emacs users complain that these links are not portable, but for me they are very useful as the links continue to work even when I move files to different subdirectories.

I modified the included denote-link-ol-export so that links to private notes or drafts are not exported, but links to public notes are exported as Hugo relative links. There is only one change from the original function, in which I use my/denote-markdown-export to determine which type of note the link refers to and format it accordingly.

(defun my/denote-link-ol-export (link description format)
  " Modified version of `denote-link-ol-export'.
Replace markdown export with `my/denote-markdown-export'

Original docstring below:
Export a `denote:' link from Org files.
The LINK, DESCRIPTION, and FORMAT are handled by the export
backend."
  (let* ((path-id (denote-link--ol-resolve-link-to-target link :path-id))
           (path (file-relative-name (car path-id)))
           (p (file-name-sans-extension path))
           (id (cdr path-id))
           (desc (or description (concat "denote:" id))))
    (cond
     ((eq format 'html) (format "<a href=\"%s.html\">%s</a>" p desc))
     ((eq format 'latex) (format "\\href{%s}{%s}" (replace-regexp-in-string "[\\{}$%&_#~^]" "\\\\\\&" path) desc))
     ((eq format 'texinfo) (format "@uref{%s,%s}" path desc))
     ((eq format 'ascii) (format "[%s] <denote:%s>" desc path)) ; NOTE 2022-06-16: May be tweaked further
     ((eq format 'md) (my/denote-markdown-export link desc))
     (t path))))

(defun my/denote-markdown-export (link desc)
  "Format the way Denote links are exported to markdown.
  If LINK is considered private or a draft, return DESC.
  If LINK is considered a public note, format it as a Hugo relative link. "
  (let ((path (denote-get-path-by-id link)))
    (if (not (string-match "/blog" path))
          (format "%s" desc)
        (if (string-match "_draft" path)
            (format "%s" desc)
          (format "[%s]({{< relref \"%s\" >}})"
                  desc
                  (denote-sluggify-title
                   (denote-retrieve-filename-title path)))))))

(org-link-set-parameters "denote" :export #'my/denote-link-ol-export)

With that, I am able to covert the following Org-Mode links:

This is a private note: [[denote:20230708T141810][Books]]
This is a draft blog post: [[denote:20240323T143034][Hacking on Denote and Hugo]]
This is a published blog post: [[denote:20231104T134226][A DWIM fullscreen function for Emacs and Sway]]

Into this Markdown in which only public notes are exported:

This is a private note: Books
This is a draft blog post: Hacking on Denote and Hugo
This is a published blog post: [A DWIM fullscreen function for Emacs and Sway]({{< relref "a-dwim-fullscreen-function-for-emacs-and-sway" >}})

Moving between the three stages

The following code requires Denote version 2.3.0 as my/insert-hugo-export-file-name makes use of the denote-sluggify-title, if you are using an earlier version of Denote, you can replace that function with denote-sluggify.

Changing a note from a draft is quite simple. my/denote-convert-note-to-blog-post is a wrapper for simple functions that do the following:

Move file to /blog subdirectory
Add Denote keyword draft
Add #+hugo_draft: t to file metadata
Sluggify Denote title and add #+export_file_name to file metadata

(defun my/insert-hugo-draft-status ()
  "Add metadata to current org-mode file marking it as a Hugo draft."
  (save-excursion
    (goto-char 0)
    (search-forward "filetags")
    (end-of-line)
    (insert "\n#+hugo_draft: t ")))

(defun my/insert-hugo-export-file-name ()
  "Add metadata to current org-mode file containing export file name.
  Export File Name is returned by `denote-retrieve-title-value'."
  (save-excursion
    (goto-char 0)
    (search-forward "filetags")
    (end-of-line)
    (insert (format
               "\n#+export_file_name: %s.md"
               (denote-sluggify-title
                (denote-retrieve-title-value buffer-file-name 'org))))))

(defun my/move-current-buffer-file-to-subdirectory (subdirectory)
  "Move file of current buffer to SUBDIRECTORY seamlessy.
  There should be no discernable difference in the buffer's appearance."
  (let ((input-file (buffer-file-name))
          (output-file (concat (denote-directory)
                               subdirectory
                               (file-relative-name (buffer-file-name))))
          (window-pos (window-start))
          (cursor-pos (point)))
    (save-buffer)
    (rename-file input-file output-file)
    (find-file output-file)
    (set-window-start (selected-window) window-pos)
    (goto-char cursor-pos)
    (kill-buffer (get-file-buffer input-file))))

(defun my/denote-convert-note-to-blog-post ()
  "Mark file of current Denote buffer to be marked as a draft blog post."
  (interactive)
  (my/move-current-buffer-file-to-subdirectory "blog/")
  (denote-keywords-add '("draft"))
  (my/insert-hugo-draft-status)
  (my/insert-hugo-export-file-name))

To change a note from a draft to a public note, my/denote-publish-hugo-post is another wrapper around simple functions that do the following:

Format current date and add #+hugo_publishdate to file metadata
Remove Org-Mode draft tag
Remove #+hugo_draft: t from file metadata
Rename file and remove draft from Denote keywords

  (defun my/insert-hugo-published-date ()
    "Format the current date and add it to Org-Mode metadata."
    (save-excursion
      (goto-char 0)
      (search-forward "filetags")
      (end-of-line)
      (insert (concat "\n#+hugo_publishdate: "(format-time-string  "%Y-%m-%d")))))

(defun my/denote-remove-draft-tag-from-metadata ()
  "Remove \"draft\" tag from Org-Mode metadata."
  (save-excursion
    (goto-char 0)
    (search-forward "filetags")
    (when (search-forward-regexp ":draft\\|draft:" (line-end-position) t)
      (replace-match "")
      (when (and (looking-at ":$\\|: ") (looking-back " "))
        (delete-char 1)))))

(defun my/denote-remove-hugo-draft-status ()
  "Remove Hugo draft entry from Org-Mode metadata."
  (save-excursion
    (goto-char 0)
    (when (search-forward "#+hugo_draft: t")
      (beginning-of-line)
      (kill-line)
      (kill-line))))

(defun my/denote-remove-keyword-from-filename (keyword)
  "Remove Denote keyword \"draft\" from filename of current file."
  (denote-rename-file buffer-file-name
                      (denote-retrieve-filename-title buffer-file-name)
                      (delete keyword
                              (denote-retrieve-keywords-value
                               buffer-file-name 'org))
                      nil))

(defun my/denote-publish-hugo-post ()
  "Mark file of current `denote' buffer to be published as a blog post."
  (interactive)
  (my/insert-hugo-published-date)
  (my/denote-remove-hugo-draft-status)
  (my/denote-remove-draft-tag-from-metadata)
  (my/denote-remove-keyword-from-filename "draft"))

Conclusion

Are these tweaks going to make me a prolific blogger? Probably not, but they gave me a good opportunity to craft a comfy setup while also practising some Emacs Lisp.

Update - 2026/04/03

An update to Denote broke my my/denote-convert-note-to-blog-post and my/denote-publish-hugo-post functions. Here is an updated version. Everything else should work the same.

(defun my/insert-hugo-draft-status ()
  "Add metadata to current org-mode file marking it as a Hugo draft."
  (save-excursion
    (goto-char 0)
    (search-forward "filetags")
    (end-of-line)
    (insert "\n#+hugo_draft: t ")))

(defun my/insert-hugo-export-file-name ()
  "Add metadata to current org-mode file containing export file name.
Export File Name is returned by `denote-retrieve-title-value'."
  (save-excursion
    (goto-char 0)
    (search-forward "filetags")
    (end-of-line)
    (insert (concat
             "\n#+export_file_name: "
             (denote-sluggify-title
              (denote-retrieve-title-value buffer-file-name 'org))
             ".md"))))

(defun my/move-current-buffer-file-to-subdirectory (subdirectory)
  "Move file of current buffer to SUBDIRECTORY seamlessy.
There should be no discernable difference in the buffer's appearance."
  (let ((input-file (buffer-file-name))
        (output-file (concat (denote-directory)
                             subdirectory
                             (file-relative-name (buffer-file-name))))
        (window-pos (window-start))
        (cursor-pos (point)))
    (save-buffer)
    (rename-file input-file output-file)
    (find-file output-file)
    (set-window-start (selected-window) window-pos)
    (goto-char cursor-pos)
    (kill-buffer (get-file-buffer input-file))))

(defun my/move-denote-file-to-blog-subdirectory ()
  (my/move-current-buffer-file-to-subdirectory "blog/"))

(defun my/insert-hugo-published-date ()
  "Format the current date and add it to Org-Mode metadata."
  (save-excursion
    (goto-char 0)
    (search-forward "filetags")
    (end-of-line)
    (insert (concat "\n#+hugo_publishdate: "(format-time-string  "%Y-%m-%d")))))

(defun my/denote-remove-draft-tag-from-metadata ()
  "Remove \"draft\" tag from Org-Mode metadata."
  (save-excursion
    (goto-char 0)
    (search-forward "filetags")
    (when (search-forward-regexp ":draft\\|draft:" (line-end-position) t)
      (replace-match "")
      (when (and (looking-at ":$\\|: ") (looking-back " "))
        (delete-char 1)))))

(defun my/denote-remove-hugo-draft-status ()
  "Remove Hugo draft entry from Org-Mode metadata."
  (save-excursion
    (goto-char 0)
    (when (search-forward "#+hugo_draft: t")
      (beginning-of-line)
      (kill-line)
      (kill-line))))

(defun my/denote-remove-draft-keyword-from-filename ()
  "Remove denote keyword \"draft\" from filename of current file."
  (let* ((file (buffer-file-name))
         (title (org-get-title))
         (keywords (delete "draft" (org-get-tags)))
         (identifier (denote-retrieve-filename-identifier file)))
    (denote-rename-file file title keywords "" "" identifier)))

(defun my/denote-convert-note-to-blog-post ()
  "Mark file of current `denote' buffer to be marked as a draft blog post."
  (interactive)
  (let* ((file (buffer-file-name))
         (keywords (append (org-get-tags) (quote ("draft"))))
         (title (org-get-title))
         (identifier (denote-retrieve-filename-identifier file)))
    (denote-rename-file file title keywords "" "" identifier)
    (my/move-current-buffer-file-to-subdirectory "blog/")
    (my/insert-hugo-draft-status)
    (my/insert-hugo-export-file-name)
    (save-buffer)))

(defun my/denote-publish-hugo-post ()
  "Mark file of current `denote' buffer to be published as a blog post."
  (interactive)
  (my/insert-hugo-published-date)
  (my/denote-remove-hugo-draft-status)
  (my/denote-remove-draft-tag-from-metadata)
  (my/denote-remove-draft-keyword-from-filename)
  (save-buffer))

A DWIM fullscreen function for Emacs and Sway

Mon, 06 Nov 2023 00:00:00 +0000

For several years now, I have been using the method that Pavel Korytov describes in this post to gain a consistent set of keybindings between Emacs and Sway. I have been extremely happy with the setup and I decided that if I ever move away from Sway, I will need to replicate this setup in another window manager.

I mostly work on a 14 inch laptop screen, so being able to make applications fullscreen is something I find very useful. Previously I had been using the below function for fullscreening windows in Emacs, but having seen how frictionless window management between Emacs and Sway could be, I decided to try a new approach.

(defun toggle-maximize-buffer ()
  "Toggle maximize buffer"
  (interactive)
  (if (one-window-p)
      (let ((my-saved-point (point)))
        (set-window-configuration my-saved-window-configuration)
        (goto-char my-saved-point))
    (progn
      (setq my-saved-window-configuration (current-window-configuration))
      (delete-other-windows))))

To achieve the desired results, it is first necessary to to know what window is active at any time and if it is fullscreen. I will be referring to Emacs as fullscreen if there is only one window in the current frame. To tell if Emacs meets my definition of fullscreen, we can use the built-in one-window-p function, and I have also written functions to determine if Emacs is the active window, and if Sway is in fullscreen mode.

(defconst my/sway-get-fullscreen
  "swaymsg -t get_tree | jq '.. | select(.type?) | select(.focused==true).fullscreen_mode'")

(defconst my/sway-get-active-app
  "swaymsg -t get_tree | jq '.. | select(.type?) | select(.focused==true).app_id'")

(defun my/sway-get-active-app ()
  "Return name of active window in Sway Window Manager as a string."
  (let ((app (shell-command-to-string my/sway-get-active-app)))
    (and (string-match "\"\\(.+\\)\"" app) (match-string 1 app))))

(defun my/sway-emacs-active-p ()
  "Return non-nil if Emacs is active window in Sway Window Manager."
  (equal (my/sway-get-active-app) "emacs"))

(defun my/sway-fullscreen-p ()
  "Return non-nil if current Window is fullscreen in Sway Window Manager."
  (let ((fullscreen (shell-command-to-string my/sway-get-fullscreen)))
    (eq (string-to-number fullscreen) 1)))

The Sway IPC protocol allows for commands to be run from the shell, which means that we can call them from Emacs. I am using the call-process function to toggle Sway’s fullscreen mode and I also wrote a simple function that toggles fullscreen for both Sway and Emacs at the same time as this is the desired outcome when neither are in fullscreen mode or both are in fullscreen mode.

(defun my/sway-toggle-fullscreen ()
  "Toggle fullscreen mode in Sway Window Manager."
  (call-process "swaymsg" nil nil nil "fullscreen"))

(defun my/toggle-emacs-and-sway-fullscreen ()
  "Toggles fullscreen for both Emacs and Sway window manager."
  (my/sway-toggle-fullscreen)
  (toggle-maximize-buffer))

Finally, it’s just a simple matter of putting everything together in the main function.

The logic is as follows:

If the active window does not belong to Emacs, then call Sway’s inbuilt fullscreen command.
If the active window belongs to Emacs, then do one of the following depending on combinations of Sway and Emacs being fullscreened
- If both Emacs and Sway are fullscreened or neither are fullscreened, toggle fullscreen for both.
- If Emacs is fullscreened and Sway is not, make Sway fullscreen.
- If Sway is fullscreened and Emacs is not, make Emacs fullscreen."

(defun my/toggle-fullscreen-dwim ()
  "Fullscreen function to be called from Sway Window Manger.

If the active window does not belong to Emacs, then call Sway's
inbuilt fullscreen command.

If the active window belongs to Emacs, then do one of the following
depending on combinations of Sway and Emacs being fullscreened:

If both Emacs and Sway are fullscreened or neither are fullscreened,
toggle fullscreen for both.

If Emacs is fullscreened and Sway is not, make Sway fullscreen.

If Sway is fullscreened and Emacs is not, make Emacs fullscreen."
  (let ((ea (my/sway-emacs-active-p))
        (ef (one-window-p))
        (sf (my/sway-fullscreen-p)))
    ;; emacs not active
    (cond ((not ea)
           (my/sway-toggle-fullscreen))
          ;; both fullscreen
          ((and ef sf)
           (my/toggle-emacs-and-sway-fullscreen))
          ;; emacs fullscreen, sway not fullscreen
          ((and ef (not sf))
           (my/sway-toggle-fullscreen))
          ;; sway fullscreen, emacs not fullscreen
          ((and sf (not ef))
           (toggle-maximize-buffer))
          ;; neither fullscreen
          ((and (not sf) (not ef))
           (my/toggle-emacs-and-sway-fullscreen)))))

I then made sure to bind the function in my Sway config.

bindsym $mod+f exec emacsclient -e '(my/toggle-fullscreen-dwim)'

I have been using this approach for a few days now and I am happy with how it has turned out. As much as I like doing everything in Emacs, there are definitely times where it is impractical. With this approach, I am getting consistent binding across all my applications and I no longer really need to consider what the application is. I can treat them all the same now.

Caveats

The only problem that I have had, is one that I have had ever since I started combining keybindings between Sway and Emacs. When I first turn my PC on, Emacs is not able to locate the Sway socket. In fact, I am unable to run any swaymsg command from within Emacs. I’m sure that it could be fixed, but for now I simply restart Emacs once before I start working in it.

If anyone has found ways of getting around this or has any further suggestions, I would love to hear them by email or on Mastodon.

Writing a simple CV in Org-Mode

Sun, 13 Mar 2022 00:00:00 +0000

Background

The first time I wrote a CV, it was in Microsoft word. Getting the relevant information onto the page was not particularly difficult or time consuming. The difficult part was the formatting. Going in and changing all the margins, font sizes and table properties nearly drove me insane.

A few years went by and I got sick of having to spend so long formatting after making any simple change, so I tried converting my CV to LaTeX. I had no experience of LaTex at the time, but after several hours of searching online, I had manage to recreate my old CV, and the only visible difference were the fonts.

Nowadays, whenever I’m writing documents, I’m using Org-Mode in Emacs. I don’t think that there should be any difference for my CV, and now thanks to Org-Mode’s ability to export to LaTex, there doesn’t need to be. I’m quite happy with how it turned out.

Figure 1: Screenshot of a sample CV made in Org-mode

How you can do the same

My technique makes heavy use of tables. Luckily for us, Org-Mode has excellent support for plain text tables. This was actually the main reason that I decided to make this conversion in the first place. Tables in LaTeX can be very powerful, but I find that Org-Mode’s tables can do everything I need while being much more pleasant to write and manage.

One thing worth noting is that because I wanted cells in the right hand column to be two or three rows tall, I have to add a physical line break as seen below.

#+ATTR_LATEX: :environment tabular :align {L!{\VRule}R}
   |---------------+-------------------------------------------------------|
   | 09/2021-      | *Job title, Company name*                             |
   |               | Something I did whilst working for the company        |
   |---------------+-------------------------------------------------------|
   | 10/20-08/2021 | *Another title, Another company*                      |
   |               | A description of what my role at the company entailed |
   |               | My achievements within that role                      |
   |---------------+-------------------------------------------------------|

The LaTeX

The only packages that need to be installed on top of the standard texlive-core I got from my package manager are titlesec and titling. I installed them with tllocalmgr.

I keep all of the necessary LaTeX in a seperate org file that I call as a setup file, but you could also have them in the header of your main file. Most of this was directly transferred from my old CV.

#+DATE:
#+OPTIONS: toc:nil num:nil
#+LaTeX_CLASS: article
#+LaTeX_CLASS_OPTIONS: [8pt,a4paper]

# Hide page number
#+LaTeX_HEADER: \pagenumbering{gobble}

# Setup packages to be used
#+LaTeX_HEADER: \usepackage{array, xcolor, bibentry}
#+LaTeX_HEADER: \usepackage[margin=2cm]{geometry}
#+LaTeX_HEADER: \usepackage{titlesec}
#+LaTeX_HEADER: \usepackage{titling}

# Table aesthetics
#+LaTeX_HEADER: \definecolor{lightgray}{gray}{0.8}
#+LaTeX_HEADER: \newcolumntype{L}{>{\raggedleft}p{0.14\textwidth}}
#+LaTeX_HEADER: \newcolumntype{R}{p{0.78\textwidth}}
#+LaTeX_HEADER: \newcommand\VRule{\color{lightgray}\vrule width 0.5pt}
#+LaTeX_HEADER: \renewcommand{\hline}{}

# Indentation
#+LaTeX_HEADER: \setlength{\parindent}{0pt}

# Subtitles
#+latex_header: \titleformat{\section}{\bfseries}{}{0em}{}[\titlerule]
#+LaTeX_HEADER: \titlespacing{\section}{0pt}{5pt}{5pt}

# Header
#+LaTeX_HEADER: \renewcommand{\maketitle}{\begin{center}{\LARGE\bfseries \theauthor} \vspace{5pt} \smallbreak \thetitle \end{center}}

I had to make two small additions to get my desired output. These are the two instances of \renewcommand that you can see above.

Because of how I had set up my tables, the exporter wanted to draw a horizontal line between each row. I didn’t have these in my old LaTeX document, and I found that the easiest way to solve this issue was to set \hline to do nothing.

The other change is a bit more of a hack and it involves the displaying of the header at the top of the document. I ended up putting some personal information as the title of the document, and while it is not ideal it is the simplest way of dealing with it. I probably could have done it as a subtitle, but I’m happy enough with how I’ve done it here, even if it is a hack.

# -*- eval: (org-cv-local-variables)  -*-
#+TITLE: My address --- My email address --- My phone number
#+AUTHOR: Jiewawa
#+SETUPFILE: ~/notes/setup/cv_setup.org

Finally, there are a few variables that I wanted to set when loading the file. I hadn’t installed any additional packages ontop of the default texlive-core from my package manager. Disabling the two variables below allow the document to compile without errors.

The other option is more a matter of personal preference. I normally have olivetti-mode enabled in Org-Mode buffers as I like having a narrow and central column for writing, but I decided to disable it for this current file because some of the tables exceed the text body width.

(defun org-cv-local-variables ()
  (setq-local org-latex-with-hyperref nil)
  (setq-local org-latex-default-packages-alist nil)
  (olivetti-mode -1))

Why would you want to do this?

Besides wanting to spend as much time as possible within Org-Mode, generating a CV this way has many practical uses. I feel as though I’m finally at a point where the next time I need to update my CV, I won’t need to completely change the format and can just make the necessary changes in a few minutes and get on with more important things, like configuring Emacs.

Emacs on Jiewawa's blog

Overriding keybindings with Meow

Tools for Studying Chinese with Emacs

On AI/LLMs

Paw

jieba

CC-CEDICT

pinyin-convert

Typing Chinese

zh-utils

Tone Colours

Anki

Fonts

Further reading

Trying to do the last 20%

Org-workout

Koreader-import

eww-filters

meow-paren

Chinese Helpers

Conclusion

Useful Emacs commands for reading

Removing visual fluff

Centring text

Hiding mode-line

Hiding the cursor

Navigating

Tying it all together

Another Way of integrating Mozilla Readability in Emacs EWW

Blogging with Denote and Hugo

The three stages of a blog post

Linking

Moving between the three stages

Conclusion

Update - 2026/04/03

A DWIM fullscreen function for Emacs and Sway

Caveats

Writing a simple CV in Org-Mode

Background

How you can do the same

The LaTeX

Why would you want to do this?