Ronaldo GliganHome

Ronaldo's Emacs literate configuration

Table of Contents

  • 1. Personal
  • 2. Packages
  • 3. Emacs window
  • 4. Mac OS
  • 5. Packages for languages
  • 6. Languages
  • 7. Org mode
  • 8. Nicities

    • This is my vanilla Emacs literate configuration file. You can skim through the table of contents to find snippets that could suit you.

    This is my config file, and I do as I please with it — anything is subject to change without further notice. You are free to take the parts you may want and adapt them however you please. Also, there is no need to cite me if you copy anything below.

    This text assumes that you are using a Fedora distribution with perhaps some tools installed. When problems or requirements arise, be smart and search efficiently to solve your problems if your setup isn't like mine.

    You can have a raw version of my configuration files here (init.el) and here (early-init.el). Important: before using these files, if you're using an Emacs version < 29, please install use-package, otherwise they won't work (install with M-x install-package RET use-package RET).

    Finally, if you have questions or suggestions, please contact me through email.

    gligan-emacs.png

    Figure 1: This is a screenshot of my Emacs, and the open buffer is the configuration I present to you below. Metamorphosis.

    These are the custom key bindings I have for my set-up. Notice I tend to prefix them by M-g.

    Key binding Function Defined
    M-g t Toggle between themes gligan/dark-theme and gligan/light-theme here
    M-g e Open a terminal emulator. Order: vterm, eshell, term here
    M-g d Input the current date here
    M-g j j Insert a new journal entry here
    M-g j s Search through my journal entries here
    M-g o Open buffer, recent file, bookmark, … here
    M-g s Search for a string in open buffers here

    Things I like about my Emacs

    0.1. GC trick

    This trick is pretty old. With the aim of optimising startup time, I increased the garbage collection threshold to 32 megabytes (Emacs' default is ~8 megs). I arrived at this number by trial and error – finding the sweet spot is just a matter of trying a number, increasing or decreasing it and seeing what works, repeating this process a few times and you get your number (this is basically Newton's method). 

    (setq gc-cons-threshold (* 32 1024 1024)
      gc-cons-percentage 0.6)

    You should find the number to put in gc-cons-threshold through the method described above by yourself. I haven't touched gc-cons-percentage, but you could; it could give you better start-up times.

    Having an astronimically large gc-cons-threshold wouldn't be of any help. Worse, it would probably slow down Emacs as garbage collection would take longer. Be advised!

    1. Personal

    1.1. Name and email

    On your Emacs installation, use your name and your email. 

    (setq user-full-name "Ronaldo Gligan"
      user-mail-address "[email protected]")

    1.2. Elisp interactive functions

    1.2.1. Insert today's date

    I find that I often need to write today's date, and although I prefer the European date format (DD-MM-YYYY), the YYYY-MM-DD ISO 8601 format is much more convenient because it sorts itself and is easier to manipulate. (Please don't ever mention to me the sick MM-DD-YYYY format, why?) 

    (defun gligan/today ()
  "Insert today's date as YYYY-MM-DD"
  (interactive) 
  (insert (format-time-string "%Y-%m-%d")))

(global-set-key (kbd "M-g d") 'gligan/today)

    1.2.2. Open a terminal emulator 

    (defun gligan/open-terminal-emulator ()
  "Tries to open the first one available: vterm, eshell, term"
  (interactive)
  (if (package-installed-p 'vterm)
      (vterm)
    (if (package-installed-p ' eshell)
        (eshell)
      (term))))

(global-set-key (kbd "M-g e") 'gligan/open-terminal-emulator)

    2. Packages

    For managing installed packages, auto-download and configure them I make use of use-package. For Emacs < 29, use-package has to be installed separately as it does not come by default. 

    (require 'package)

    Emacs comes with GNU ELPA by default: a curated package repository containing, well, not many packages. What I'm doing below is pretty standard: I'm adding the larger MELPA repository so that I can install more packages I might want or need. Just be aware of what you're installing and you should be fine. 

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

    Do not forget to initialise: 

    (package-initialize)

    3. Emacs window

    3.1. Early

    Emacs has the ability to run Elisp code before the Emacs window –or TUI– is initialised. Not all code can run this way, however. This portion of code should be placed in ~/.emacs.d/early-init.el in most cases. 

    ;; Title
(setq frame-title-format "%b - Emacs")

;; Minimal window without buttons or scrollbars
(menu-bar-mode -1)
(tool-bar-mode -1)
(scroll-bar-mode -1)

;; Maximised at start up
;; (add-hook 'window-setup-hook 'toggle-frame-maximized t)
;; Fullscreen at start up
;; (add-hook 'window-setup-hook 'toggle-frame-fullscreen t)

;; No window decorations -- good for tiling window managers or minimal
;; configs
;; (add-to-list 'default-frame-alist '(undecorated . t))

    Running code early can reduce the startup time of Emacs. For example, in the snippet above, we're disabling the menu, tool and scrollbar modes before they're even loaded. I'm pretty sure this won't affect our init times negatively.

    3.2. Main window properties

    Like many pop songs, here's my verse for this section:

    • I want a semi-transparent window to see my beautiful backgrounds
    • I want tabs as spaces, as 2 spaces
    • I want the cursor to be a little bar, not a block
    • I want automatic saving of files and backup files just in case.
    • I want a message telling me how long Emacs took to load
    • I don't want line numbers
    • I don't want startup or scratch buffer messages

    This code basically does the all of the above: 

    ;; Window transparency
(set-frame-parameter (selected-frame) 'alpha-background 95)

;; Use two spaces
(setq-default tab-width 2)
(setq-default indent-tabs-mode nil)
(delete-selection-mode 1)

;; Use a small bar as a cursor
(setq-default cursor-type 'bar)

;; I don't like line numbers
(setq display-line-numbers-type nil)

;; No welcome message; no scratch buffer message
(setq inhibit-startup-message t)
(setq initial-scratch-message nil)

;; Auto-save & back up files
(setq auto-save-default t
      make-backup-files t)

(setq backup-directory-alist '(("." . "~/.emacs.d/backup")))

(defun display-startup-echo-area-message ()
  (message "%s with %d collections"
       (format "%.2f seconds"
               (float-time
                (time-subtract after-init-time before-init-time)))
       gcs-done))

    3.3. Fonts

    There are as many programming fonts as there are minutes in a day, really. This is a nice site for choosing one. I use Iosevka Comfy, a modified version of Iosevka by Protesilaos Stavrou, which I really like.

    The following variables define the fonts I use through all of this configuration. 

    (setq gligan/fixed-pitch-font "Iosevka Comfy Motion"
      gligan/mixed-pitch-font "Iosevka Comfy Motion Duo"
      gligan/default-font-size 130)

    I don't want Emacs panicking if the fonts I'm setting are not available. For that reason, I define gligan/set-font-when-available as a sort of middleman. 

    (defun gligan/set-font-when-available (face font height)
  (if (member font (font-family-list))
      (set-face-attribute face nil
                          :family font
                          :height height)
    (message (concat font " not available"))))

(gligan/set-font-when-available 'default
                                gligan/fixed-pitch-font
                                gligan/default-font-size)
(gligan/set-font-when-available 'fixed-pitch
                                gligan/fixed-pitch-font
                                gligan/default-font-size)
(gligan/set-font-when-available 'variable-pitch
                                gligan/mixed-pitch-font
                                gligan/default-font-size)

    3.3.1. Font set-up for Org-mode

    I want titles in Org-mode to be bigger than their surrounding paragraph text. Through the gligan/org-mode-font-setup function I make that possible. 

    (defun gligan/org-mode-font-setup ()
  ;; These numbers below define the proportions of the org mode
  ;; headers in contrast to the paragraph text.
  (dolist (face '((org-document-title . 1.8)
                  (org-level-1        . 1.3)
                  (org-level-2        . 1.2)
                  (org-level-3        . 1.1)))
    (set-face-attribute (car face) nil
                        :font gligan/mixed-pitch-font
                        :weight 'regular
                        :height (cdr face))))

    Note that here I set up this function as a Org-mode hook.

    3.4. Themes

    First, if I have a theme installed, I'll treat it as safe; I'm willing to risk my files! Nah, that's just a joke. In practice, most themes are respectable in the sense that people, perhaphs you too, can look at their source, so there is a public judgement in between – this is, in fact, one of the blessings of libre software. 

    ;; Declare all themes as safe. That way, Emacs won't ask the user if
;; it's okay to load a theme
(setq custom-safe-themes t)

    My main Emacs theme is Monokate; a port that I made of the homonymous theme from Sublime Text. Monokate is a dark, Monokai-like theme that presents just the right amount of contrast; it is neither too mushy nor eye-straining white text on a black background – it is what I desired for my Emacs, so I ported it.

    The same sort of features Monokate has I desire for a white theme for when I'm outside or sun rays hit my monitor. For that reason I've developed a white theme of my own: Ellas. Ellas is a warm theme inspired by a less-than-one-week trip I've made to Athens and Santorini. It is nice to look at, but that is my opinion. See my Emacs themes page for screenshots and download instructions.

    Other honourable mentions for themes are the ef-themes collection by Protesilaos Stavrou, an Emacs personality, especially the greenish ef-cyprus theme and perhaps the collection of themes from Doom Emacs.

    I've put all the rest of the code in this section into my early-init file and it works.

    Everything nowadays has theme toggling; why shouldn't Emacs too? These two variables designate my dark and light theme inside all of this configuration. 

    (setq gligan/dark-theme  'monokate)
(setq gligan/light-theme 'ellas)

    Here I have defined the gligan/toggle-theme function, that I can run with M-g t or with M-x gligan/toggle-theme RET. 

    (defun gligan/toggle-theme ()
  "Switch between Gligan's dark and light themes"
  (interactive)
  (disable-theme gligan/current-theme)
  (setq next-theme (if (equal gligan/current-theme gligan/light-theme)
                       gligan/dark-theme
                     gligan/light-theme))
  (setq gligan/current-theme next-theme)
  (load-theme next-theme t))

(global-set-key (kbd "M-g t") 'gligan/toggle-theme)

    I'm not doing anything fancy: I have two variables that dictate when the light theme should be and if the time when Emacs was open lies between those two hours, then the light theme is set. 

    ;; We start with the dark theme
(setq gligan/current-theme gligan/dark-theme)

;; Between these two hours, when opening Emacs, the light theme should be the default
(defvar gligan/light-theme-hour-start 8)
(defvar gligan/light-theme-hour-end  20) 

;; Switch to light theme if we're between the bounds defined above
(let ((hour (string-to-number (substring (current-time-string) 11 13))))  
  (if (and
       (<= gligan/light-theme-hour-start hour)
       (>  gligan/light-theme-hour-end   hour))
    (gligan/toggle-theme)
    (load-theme gligan/current-theme t)))

    4. Mac OS

    (when (eq system-type 'darwin)
  (setq mac-option-key-is-meta  nil
        mac-command-key-is-meta t
        mac-command-modifier    'meta
        mac-option-modifier     'super))

    5. Packages for languages

    5.1. LSP server (eglot)

    Eglot is a minimalistic LSP client for Emacs. For Emacs >= 29, it comes installed by default. The main alternative to Eglot is lsp-mode, which is more complete: it has more features and more customisations, but it is slower and it does not come with Emacs. 

    (use-package eglot
  :ensure t ; Older versions of Emacs do not have Eglot installed by default
  :hook ((c-mode                        ; Alphabetically ordered
          haskell-mode
          nim-mode
          python-mode
          rust-mode
          tuareg-mode
          zig-mode)
         . eglot-ensure)
  :custom
  (eglot-autoshutdown t))

    Here is a list of all the servers that Eglot can communicate to. On Fedora I had to install the following:

    • LSP features on C are achieved with clangd. 

      (sudo) dnf install clang-tools-extra
    • Haskell has haskell-language-server, that can be installed with ghcup.
    • Nim's LSP server does not work for me.

    • Python has many LSP servers, I use pylsp. 

      pip install python-lsp-server
    • Rust has rust-analyzer.

    • OCaml needs ocaml-lsp-server and optionally ocamlformat. 

      opam install ocaml-lsp-server ocamlformat
    • I can't build Zig's LSP server because it needs a custom version of the compile.

    5.2. Completion (corfu)

    (use-package corfu
  :ensure t
  :custom
  (corfu-cycle t)
  ;; (corfu-auto t)
  :init
  (global-corfu-mode))

    (use-package cape
  :ensure t
  :bind (("C-c p p" . completion-at-point) ;; capf
         ("C-c p t" . complete-tag)        ;; etags
         ("C-c p d" . cape-dabbrev)        ;; or dabbrev-completion
         ("C-c p h" . cape-history)
         ("C-c p f" . cape-file)
         ("C-c p k" . cape-keyword)
         ("C-c p s" . cape-elisp-symbol)
         ("C-c p e" . cape-elisp-block)
         ("C-c p a" . cape-abbrev)
         ("C-c p l" . cape-line)
         ("C-c p w" . cape-dict)
         ("C-c p :" . cape-emoji)
         ("C-c p \\" . cape-tex)
         ("C-c p _" . cape-tex)
         ("C-c p ^" . cape-tex)
         ("C-c p &" . cape-sgml)
         ("C-c p r" . cape-rfc1345))
  :init
  (add-to-list 'completion-at-point-functions #'cape-dabbrev)
  (add-to-list 'completion-at-point-functions #'cape-file)
  (add-to-list 'completion-at-point-functions #'cape-elisp-block)
  ;;(add-to-list 'completion-at-point-functions #'cape-history)
  (add-to-list 'completion-at-point-functions #'cape-keyword)
  ;;(add-to-list 'completion-at-point-functions #'cape-tex)
  ;;(add-to-list 'completion-at-point-functions #'cape-sgml)
  ;;(add-to-list 'completion-at-point-functions #'cape-rfc1345)
  ;;(add-to-list 'completion-at-point-functions #'cape-abbrev)
  ;;(add-to-list 'completion-at-point-functions #'cape-dict)
  ;;(add-to-list 'completion-at-point-functions #'cape-elisp-symbol)
  ;;(add-to-list 'completion-at-point-functions #'cape-line)
  )

    (use-package dabbrev
  :ensure t
  ;; Swap M-/ and C-M-/
  :bind (("M-/" . dabbrev-completion)
         ("C-M-/" . dabbrev-expand)))

    6. Languages

    6.1. C

    (use-package irony-eldoc
  :ensure t
  :defer t)

    6.2. Haskell

    (use-package haskell-mode
  :ensure t
  :defer t
  :config)

    6.3. OCaml

    (use-package tuareg
  :ensure t
  :defer t)

(use-package dune
  :ensure t
  :defer t)

(use-package merlin
  :ensure t
  :defer t
  :config
  (add-hook 'tuareg-mode-hook #'merlin-mode)
  (setq merlin-error-after-save nil))

(use-package merlin-eldoc
  :ensure t
  :defer t
  :hook (tuareg . merlin-eldoc-setup))

(use-package utop
  :ensure t
  :defer t
  :config
  (add-hook 'tuareg-mode-hook #'utop-minor-mode))

    6.4. Zig

    (use-package zig-mode
  :ensure t
  :defer t)

    6.5. Nim

    (use-package nim-mode
  :ensure t
  :defer t)

    7. Org mode 

    (use-package org
  :hook ((org-mode   . gligan/org-mode-font-setup)
         (after-save . org-babel-tangle)) ; Auto tangle on save
  :config
  (setq org-directory "~/org/")

  (setq org-hide-emphasis-markers t)
  (setq org-startup-folded 'fold)
  (setq org-startup-indented t)

  (setq org-preview-latex-default-process 'dvipng))

    7.1. org-journal

    org-journal is a nice way to have a journal. I have set up two keybindings; one for creating a new journal entry and another for searching for substrings in my journals.

    One of the nice things about it, compared to other apps like Notion, Apple Notes, Google Keep or most other note/journal apps, is that my entries are kept on my machine and they're plain text; nothing proprietary. I can export them to other formats if I need to and I can easily read them as plain text if I don't have Emacs. It is also very nicely implemented in Emacs. 

    (use-package org-journal
  :ensure t
  :bind (("M-g j j" . 'org-journal-new-entry)
         ("M-g j s" . 'org-journal-search-forever))
  :config
  (setq journal-dir "~/org/journal/")
  (setq org-journal-date-format "%A, %d %B %Y") ; e.g. "Friday, 8 March 2024"
  (add-hook 'org-agenda-finalize-hook #'org-modern-agenda))

    7.2. Skeletons for org-mode

    A skeleton is a template for documents. For my blog, I wrote a very simple skeleton called org-header-skeleton. Each skeleton can be invoked by its name from the M-x menu, or it can even be bound to a keybinding when in org-mode. It is up to you. 

    (define-skeleton org-header-skeleton
  "Header for my org files, mainly for blog posts"
  nil
  "#+title: " (skeleton-read "Document title: ") "\n"
  "#+author: " user-full-name "\n"
  ;; "#+EMAIL: " user-mail-address "\n"
  "#+date: " (format-time-string "%Y-%m-%d") "\n"
  "#+setupfile: blog.config")

    Note that skeletons are not restricted to Org mode. For example, org-header-skeleton could be used in c-mode, for example, even though it makes no sense. This means that skeletons are mode independent.

    7.3. Org modern (org-modern)

    The org-modern package gives Org documents a really nice look: it replaces the header asterisks with nice Unicode characters, blocks get a UI rather than a textual look, et cet. You should have a look at the org-modern repository. 

    (use-package org-modern
  :ensure t
  :defer t
  :hook (org-mode . org-modern-mode))

    7.4. Zen mode (olivetti)

    (use-package olivetti
  :ensure t
  :defer t
  :hook (org-mode . olivetti-mode))

    7.5. Proportional fonts (mixed-pitch)

    (use-package mixed-pitch
  :ensure t
  :hook (text-mode . mixed-pitch-mode))

    7.6. Exporting

    7.6.1. to LaTeX

    1. Syntax highlighting with minted

      Minted is a LaTeX package that adds syntax highlighting to code blocks. 

      (setq org-latex-src-block-backend 'minted
      org-latex-packages-alist '(("" "minted"))
      org-latex-pdf-process
      '("pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"
        "pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"))

    8. Nicities

    The following sections configure packages that, whilst not necessary, make the Emacs experience much better.

    8.1. Save the session

    When using consult (see here), there is no need to restore the session, as I can search the recently opened files and bookmarks. It also doubles the startup time of Emacs. 

    ;; (desktop-save-mode 1)

    8.2. Auto close and colorise parentheses, brackets, et cet. (electric-pair-mode)

    Having auto-closing parentheses and coloured pairs of them is a must for some. I have put this section under "Nicities" because I can program without it, although the experience is not pleasant.

    As far as I know, electric-pair-mode comes with Emacs. What is does is it autocompletes parentheses: you insert ( and it adds ) so that (| ===> (|), where the bar is the cursor. It does the same with other pairs of characters like brackets or quotes. 

    (electric-pair-mode 1)

    Some languages, especially Lisps, make a heavy use of parentheses to denote scope, and so it can be hard to keep track of parenthesis mismatch. With colours, you don't have to count them, just see the rainbow pattern. 

    (use-package rainbow-delimiters
  :ensure t
  :defer t
  :hook (prog-mode . rainbow-delimiters-mode))

    8.3. Ligatures

    With the font I'm using, not all but most of the ligatures below work. As far as I know, all Iosevka and Cascadia Code ligatures are included in this list. 

    (use-package ligature
  :ensure t
  :config
  (ligature-set-ligatures
   'prog-mode
   '("!!" "!!." "!=" "!==" "#!" "##" "###" "####" "#(" "#:" "#=" "#?" "#[" "#_" "#_(" "#{" "$>" "%%" "&&" "(*" "*)" "**" "***" "*/" "*>" "++" "+++" "+:" "+>" "--" "---" "--->" "-->" "-:" "-<" "-<<" "->" "->>" "-|" "-~" ".-" ".." "..." "..<" ".=" ".?" "/*" "//" "///" "/=" "/==" "/>" ":+" ":-" "://" "::" ":::" "::=" ":<" ":=" ":>" ";;" "<!--" "<!---" "<$" "<$>" "<*" "<******>" "<*>" "<+" "<+>" "<-" "<--" "<---" "<---->" "<--->" "<-->" "<-<" "<->" "</" "</>" "<:" "<<" "<<-" "<<<" "<<=" "<=" "<=<" "<==" "<===" "<====>" "<===>" "<==>" "<=>" "<>" "<|" "<|>" "<||" "<|||" "<~" "<~>" "<~~" "=!=" "=/=" "=:" "=:=" "=<<" "==" "===" "===>" "==>" "=>" "=>>" ">-" ">->" ">:" ">=" ">=>" ">>" ">>-" ">>=" ">>>" "?." "?:" "?=" "??" "[|" "\\\\" "]#" "^=" "__" "_|_" "www" "{|" "|-" "|=" "|>" "|]" "||" "||=" "||>" "|||>" "|}" "~-" "~=" "~>" "~@" "~~" "~~>"))
  (global-ligature-mode t))

    8.4. TODO, NOTE, FIXME, BUG, … (hl-todo)

    (use-package hl-todo
  :ensure t
  :config
  (global-hl-todo-mode 1))

    8.5. Better M-x completion (vertico)

    (use-package vertico
  :ensure t
  :config
  (setq vertico-cycle t)
  (vertico-mode))

(use-package savehist
  :ensure t
  :config
  (savehist-mode))

(use-package orderless
  :ensure t
  :config
  (setq completion-styles '(orderless basic)
        completion-category-defaults nil
        completion-category-overrides '((file (styles partial-completion)))))

(use-package marginalia
  :ensure t
  :config
  (marginalia-mode))

    8.6. Search everything (consult)

    Preview files, and search open buffers, recently opened files, bookmarks, … all in one place 

    (use-package consult
  :ensure t
  :bind (("M-g o" . 'consult-buffer)
         ("M-g s" . 'consult-line-multi))
  :config
  (recentf-mode))

    8.7. Icons with dired integration (nerd-icons)

    (use-package nerd-icons
  :ensure t)

(use-package nerd-icons-dired
  :ensure t
  :hook (dired-mode . nerd-icons-dired-mode))

    8.8. Custom modeline (doom-modeline)

    The default mode line is not bad; it does the job of showing the status of the buffer. If you want something more, doom-modeline might be good. It is more full-featured than simple-modeline (link), which is more minimalistic and is what I was using before. 

    (use-package doom-modeline
  :ensure t
  :hook (after-init . doom-modeline-mode)
  :config
  (setq doom-modeline-bar-width 0)
  (column-number-mode 1))

    Another interesting alternative is mini-echo-mode (link), which collapses the modeline and minibuffer into a single line.

    8.9. Show possible key bindings (which-key)

    which-key implements a menu that appears after a certain amount of time when sa half-pressed keybinding is entered, showing all the possible routes or functions you can perform from there. 

    (use-package which-key
  :ensure t
  :config
  (which-key-mode))

    8.10. Show what you're typing (keycast)

    If for some reason I need to show the keys I'm typing I use keycast. I don't find it necesary, though, and so I don't enfore its installation. Also, for ease of use, I bind a key binding to it. Remember that all my custom key bindings are listed at the top of this page if you're reading this text in a website.

    The keycast package has multiple ways of showing the keys that you should see here. I find the mode line version helpful and not intrusive.

    Also, note that my themes takes into account keycast-mode-line-mode so that it looks well integrated into the mode line. 

    (use-package keycast
  :unless (member 'simple-modeline package-activated-list)
  :bind ("M-g k" . 'keycast-mode-line-mode))

    8.11. TODO Fold code (yafolding)

    (use-package yafolding
  :ensure t
  :hook (prog-mode . yafolding-mode))

    8.12. TODO Snippets (yasnippet)

    (use-package yasnippet
  :config
  (setq yas-snippet-dirs '("~/.emacs.d/snippets/"))
  (yas-global-mode))

(use-package warnings
  :config
  (add-to-list 'warning-suppress-types '(yasnippet backquote-change)))