path: root/config.org

-*- buffer-read-only: t -*-
#+title: Emacs Configuration
#+startup: overview
#+DATE: 2026-03-24T10:00:00+11:00
#+DRAFT: false
#+PROPERTY: header-args:emacs-lisp :results silent :tangle init.el

* Early startup

These settings have to exist before the first GUI frame is created, so they
tangle into =early-init.el=.

#+begin_src emacs-lisp :tangle early-init.el
  ;;; early-init.el --- generated from config.org -*- lexical-binding: t; -*-

  ;;; Commentary:

  ;; This file is generated from config.org. Do not edit it directly.

  ;;; Code:

  (dolist (parameter '((width . 140)
                       (height . 42)))
    (add-to-list 'default-frame-alist parameter)
    (add-to-list 'initial-frame-alist parameter))
#+end_src

* Bootstrapping

This is the start of the main runtime entry point, which tangles into =init.el=.

#+begin_src emacs-lisp
  ;;; init.el --- generated from config.org -*- lexical-binding: t; -*-

  ;;; Commentary:

  ;; This file is generated from config.org. Do not edit it directly.

  ;;; Code:

  (let ((minver "27.1"))
    (when (version< emacs-version minver)
      (error "Your Emacs is too old -- this config requires v%s or higher" minver)))
  (when (version< emacs-version "28.1")
    (message
     (concat
      "Your Emacs is old, and some functionality in this config will be "
      "disabled. Please upgrade if possible.")))
#+end_src

* Shared paths and system identity

These definitions set up the shared paths used by the rest of the
configuration, including the Org directory under =~/org/=.

#+begin_src emacs-lisp
  (defconst *spell-check-support-enabled* nil)
  (defconst *is-a-windows* (memq system-type '(windows-nt ms-dos cygwin)))
  (defconst *is-a-linux* (eq system-type 'gnu/linux))
  (defconst *is-a-mac* (eq system-type 'darwin))

  (provide 'init-paths)

  ;; Keep custom-set-variables out of the main config.
  (setq custom-file (expand-file-name "custom.el" user-emacs-directory))
#+end_src

* Package setup

This section bootstraps packages and defines the archives the rest of the
configuration relies on.

#+begin_src emacs-lisp
  (require 'package)

  (setq package-archives
        (append '(("melpa" . "https://melpa.org/packages/"))
                package-archives)
        package-archive-priorities '(("gnu" . 10)
                                     ("nongnu" . 8)
                                     ("melpa" . 5))
        package-install-upgrade-built-in t
        use-package-always-ensure nil)

  (package-initialize)
  (require 'use-package)
#+end_src

* Interface defaults

This section sets the visual defaults: theme, fonts, and frame behavior.

#+begin_src emacs-lisp
  (when (display-graphic-p)
    (set-frame-size (selected-frame) 140 42)
    (menu-bar-mode -1)
    (tool-bar-mode -1)
    (scroll-bar-mode -1)
    (tooltip-mode -1)
    (set-face-attribute
     'default nil
     :family "JetBrains Mono" :height 140 :weight 'medium)
    (set-face-attribute
     'fixed-pitch nil
     :family "JetBrains Mono" :weight 'medium)
    (set-face-attribute
     'fixed-pitch-serif nil
     :family "JetBrains Mono" :weight 'medium))

  (unless (display-graphic-p)
    (add-hook 'emacs-startup-hook (lambda () (menu-bar-mode -1))))

  (setq inhibit-startup-message t
        inhibit-startup-screen t
        ring-bell-function 'ignore)

  (use-package modus-themes
    :ensure nil
    :no-require t
    :config
    (load-theme 'modus-vivendi t))

  (line-number-mode 1)
  (column-number-mode 1)
  (show-paren-mode 1)

  ;; Disable all fringe indicators
  (setq-default indicate-empty-lines nil)
  (setq-default indicate-buffer-boundaries nil)
  (setq-default fringe-indicator-alist nil)

#+end_src

* Modeline

#+begin_src emacs-lisp
  (use-package time
    :ensure nil
    :config
    ;; Enable 24-hour time display without load average.
    (setq display-time-24hr-format t
          display-time-day-and-date t
          display-time-default-load-average nil)
    (display-time-mode 1))

  ;; Keep the theme's faces, but make the right edge alignment dynamic.
  (setq-default mode-line-format
                (list
                 ;; Left padding
                 "  "
                 "%e"
                 mode-line-front-space
                 mode-line-mule-info
                 mode-line-client
                 mode-line-modified
                 mode-line-remote
                 mode-line-frame-identification
                 mode-line-buffer-identification
                 "   "
                 mode-line-position
                 '(vc-mode vc-mode)
                 "  "
                 mode-line-modes
                 ;; Right-align from here
                 '(:eval (propertize
                          " "
                          'display
                          `((space :align-to
                                   (- right
                                      ,(+ 2 (string-width (format-mode-line mode-line-misc-info))))))))
                 mode-line-misc-info
                 ;; Right padding
                 "  "
                 mode-line-end-spaces))

#+end_src

* Editing defaults

This section covers global editing behavior and a few startup-time tuning
choices.

#+begin_src emacs-lisp
  (set-language-environment "UTF-8")
  (set-default-coding-systems 'utf-8)
  (prefer-coding-system 'utf-8)

  (setq auto-save-default nil
        backup-inhibited t
        echo-keystrokes 0.1
        compilation-ask-about-save nil
        mouse-wheel-scroll-amount '(1 ((shift) . 1))
        mouse-wheel-progressive-speed nil
        mouse-wheel-follow-mouse t
        scroll-step 1
        scroll-conservatively 101
        enable-recursive-minibuffers t
        gc-cons-threshold (* 128 1024 1024)
        read-process-output-max (* 4 1024 1024)
        process-adaptive-read-buffering nil)

  (fset 'yes-or-no-p 'y-or-n-p)
  (global-auto-revert-mode 1)
  (delete-selection-mode 1)

  (setq-default indent-tabs-mode nil
                fill-column 80
                tab-width 2
                indicate-empty-lines t
                sentence-end-double-space nil)

#+end_src

* Dired

On macOS, the system =ls= does not support GNU's =--dired= flag. Keeping
Dired on its built-in path avoids noisy directory listing errors when opening
folders from note helpers.

#+begin_src emacs-lisp
  (use-package dired
    :ensure nil
    :custom
    (dired-use-ls-dired nil))
#+end_src

* Minibuffer completion

This keeps completion close to standard Emacs behaviour while improving the
minibuffer prompts used throughout the notes workflow. Vertico provides the
UI, Orderless handles flexible matching, and Marginalia adds lightweight
annotations.

#+begin_src emacs-lisp
  (use-package vertico
    :ensure t
    :pin melpa
    :init
    (vertico-mode 1))

  (use-package orderless
    :ensure t
    :pin melpa
    :custom
    (completion-styles '(orderless basic))
    (completion-category-defaults nil)
    (completion-category-overrides '((file (styles basic partial-completion)))))

  (use-package marginalia
    :ensure t
    :pin melpa
    :after vertico
    :init
    (marginalia-mode 1))
#+end_src

* Notes workflow

This keeps the note-taking system deliberately small. Daily notes stay as plain
Org files in =~/org/daily/=, while longer-lived notes use Denote inside the
same root directory and rely on links for relationships.

** Org foundations

The Org setup establishes the shared directories, ensures the PARA structure is
present at startup, and provides a small helper for opening today's daily note
with the standard section layout already in place. Agenda views stay focused on
PARA notes, so project, area, and resource files can surface TODOs without
pulling in daily or archived notes. A small directory helper keeps PARA
subdirectories easy to create from the minibuffer before capturing into them.
A curated =moc.org= in the Org root acts as the startup landing page and quick
navigation surface. The config assumes that file already exists and opens it
directly during startup rather than creating it on demand.

#+begin_src emacs-lisp
  (use-package org
    :ensure nil
    :functions (denote-keywords-prompt)
    :defines (denote-directory denote-use-directory denote-use-keywords)
    :preface
    (defconst ss/org-directory (expand-file-name "~/org/")
      "Root directory for Org files.")

    (defconst ss/org-daily-directory (expand-file-name "daily/" ss/org-directory)
      "Directory for plain daily Org notes.")

    (defconst ss/org-projects-directory (expand-file-name "projects/" ss/org-directory)
      "Directory for project notes.")

    (defconst ss/org-areas-directory (expand-file-name "areas/" ss/org-directory)
      "Directory for area notes.")

    (defconst ss/org-people-directory (expand-file-name "areas/people/" ss/org-directory)
      "Directory for people notes.")

    (defconst ss/org-resources-directory (expand-file-name "resources/" ss/org-directory)
      "Directory for resource notes.")

    (defconst ss/org-archives-directory (expand-file-name "archives/" ss/org-directory)
      "Directory for archived notes.")

    (defconst ss/moc-file (expand-file-name "moc.org" ss/org-directory)
      "Central MOC note.")

    (defconst ss/org-note-directories
      (list ss/org-directory
            ss/org-daily-directory
            ss/org-projects-directory
            ss/org-areas-directory
            ss/org-people-directory
            ss/org-resources-directory
            ss/org-archives-directory)
      "Directories that make up the note-taking workflow.")

    (defconst ss/org-agenda-directories
      (list ss/org-projects-directory
            ss/org-areas-directory)
      "Directories whose Org files feed the agenda.")

    (defconst ss/org-subdirectory-roots
      `(("projects" . ,ss/org-projects-directory)
        ("areas" . ,ss/org-areas-directory)
        ("people" . ,ss/org-people-directory)
        ("resources" . ,ss/org-resources-directory))
      "Capture roots offered when creating note subdirectories.")

    (defun ss/denote-capture-in-directory (directory &optional keywords &rest prompts)
      "Start a Denote Org capture in DIRECTORY with KEYWORDS and PROMPTS.
  If PROMPTS is empty, rely on `denote-prompts'."
      (let* ((prompt-for-keywords (memq :keywords prompts))
             (denote-directory directory)
             (denote-use-directory (unless (memq :subdirectory prompts) directory))
             (denote-use-keywords
              (if prompt-for-keywords
                  (delete-dups (append keywords (denote-keywords-prompt)))
                keywords)))
        (if prompts
            (denote-org-capture-with-prompts
             (memq :title prompts)
             nil
             (memq :subdirectory prompts)
             (memq :date prompts)
             (memq :template prompts))
          (denote-org-capture))))

    (defun ss/create-note-subdirectory ()
      "Create a PARA subdirectory using minibuffer completion."
      (interactive)
      (let* ((root-name (completing-read
                         "Capture root: "
                         (mapcar #'car ss/org-subdirectory-roots)
                         nil t))
             (root (alist-get root-name ss/org-subdirectory-roots nil nil #'string=))
             (completion-extra-properties '(:category file))
             (candidates
              (sort
               (delete-dups
                (mapcar (lambda (path)
                          (directory-file-name (file-relative-name path root)))
                        (seq-filter
                         #'file-directory-p
                         (directory-files-recursively root directory-files-no-dot-files-regexp t t))))
               #'string<))
             (subdirectory (completing-read
                            (format "Subdirectory in %s: " root-name)
                            candidates
                            nil nil))
             (target (expand-file-name subdirectory root))
             (existing (file-directory-p target)))
        (make-directory target t)
        (ss/refresh-org-agenda-files)
        (message "%s note directory: %s"
                 (if existing "Using existing" "Created")
                 target)))

    (defun ss/refresh-org-agenda-files (&rest _)
      "Refresh `org-agenda-files' from the current PARA directories.
  Ignore any arguments passed by advice wrappers."
      (require 'org-agenda)
      (setq org-agenda-files
            (delete-dups
             (apply #'append
                    (mapcar (lambda (directory)
                              (if (file-directory-p directory)
                                  (directory-files-recursively directory org-agenda-file-regexp)
                                nil))
                            ss/org-agenda-directories)))))

    (defun ss/ensure-daily-note (&optional time)
      "Create the daily note for TIME when it does not exist.
  Return the path to the note."
      (let* ((date (or time (current-time)))
             (file (expand-file-name
                    (format-time-string "%Y-%m-%d.org" date)
                    ss/org-daily-directory)))
        (unless (file-exists-p file)
          (make-directory (file-name-directory file) t)
          (with-temp-file file
            (insert (format "#+title: %s\n\n* Tasks\n\n* Notes\n\n* Open Loops\n"
                            (format-time-string "%Y-%m-%d" date)))))
        file))

    (defun ss/open-todays-note ()
      "Open today's daily Org note."
      (interactive)
      (find-file (ss/ensure-daily-note)))

    (defun ss/open-moc ()
      "Open the central MOC note."
      (interactive)
      (find-file ss/moc-file))

    (defun ss/open-agenda ()
      "Refresh agenda files and invoke `org-agenda'."
      (interactive)
      (call-interactively #'org-agenda))
    :init
    (add-hook 'emacs-startup-hook (lambda () (find-file ss/moc-file)))
    :bind (("C-c a" . ss/open-agenda)
           ("C-c c" . org-capture)
           ("C-c n M" . ss/open-moc)
           ("C-c n m" . ss/create-note-subdirectory)
           ("C-c n d" . ss/open-todays-note))
    :config
    (setq org-directory ss/org-directory
          org-hide-emphasis-markers t)
    (add-hook 'org-mode-hook
              (lambda ()
                (setq-local org-hide-emphasis-markers t)
                (font-lock-flush)
                (font-lock-ensure)))
    (ss/refresh-org-agenda-files)
    (advice-add 'org-agenda :before #'ss/refresh-org-agenda-files)
    (mapc (lambda (directory)
            (make-directory directory t))
          ss/org-note-directories))
#+end_src

** Capture entry points

Daily capture goes to today's plain Org file. Tasks land under =Tasks= while
notes and meetings land under =Notes=. Denote capture uses Denote's own Org
integration so note identity, metadata, and directories stay under Denote's
control rather than custom code. The convenience templates keep the familiar
entry points, but only project capture injects a structural keyword by default.

#+begin_src emacs-lisp
  (use-package org-capture
    :ensure nil
    :after (org denote)
    :config
    (setq org-capture-templates
          `(("d" "Daily")
            ("dt" "Task" entry
             (file+headline ,#'ss/ensure-daily-note "Tasks")
             "* TODO %?")
            ("dn" "Note" entry
             (file+headline ,#'ss/ensure-daily-note "Notes")
             "* %?")
            ("dm" "Meeting" entry
             (file+headline ,#'ss/ensure-daily-note "Notes")
             "* %<%H:%M> meeting %?")
            ("n" "Denote")
            ("nn" "Generic" plain
             (file denote-last-path)
             (function
              (lambda ()
                (denote-org-capture-with-prompts :title :keywords :subdirectory)))
             :no-save t
             :immediate-finish nil
             :kill-buffer t
             :jump-to-captured t)
            ("np" "Project" plain
             (file denote-last-path)
             (function
              (lambda ()
                (ss/denote-capture-in-directory
                 ss/org-projects-directory '("project") :title :keywords :subdirectory)))
             :no-save t
             :immediate-finish nil
             :kill-buffer t
             :jump-to-captured t)
            ("na" "Area" plain
             (file denote-last-path)
             (function
              (lambda ()
                (ss/denote-capture-in-directory
                 ss/org-areas-directory nil :title :keywords :subdirectory)))
             :no-save t
             :immediate-finish nil
             :kill-buffer t
             :jump-to-captured t)
            ("nP" "Person" plain
             (file denote-last-path)
             (function
              (lambda ()
                (ss/denote-capture-in-directory
                 ss/org-people-directory nil :title :keywords :subdirectory)))
             :no-save t
             :immediate-finish nil
             :kill-buffer t
             :jump-to-captured t)
            ("nr" "Resource" plain
             (file denote-last-path)
             (function
              (lambda ()
                (ss/denote-capture-in-directory
                 ss/org-resources-directory nil :title :keywords :subdirectory)))
             :no-save t
             :immediate-finish nil
             :kill-buffer t
             :jump-to-captured t))))
#+end_src

** Denote

Denote manages the durable notes. Folder placement carries most of the
structural meaning, while Denote handles naming, metadata, linking, and
retrieval. Built-in keywords stay intentionally sparse, with =project=
retained because project note titles are often ambiguous outside their folder.

#+begin_src emacs-lisp
  (use-package denote
    :ensure t
    :after org
    :bind (("C-c n n" . denote-open-or-create)
           ("C-c n l" . denote-link))
    :config
    (setq denote-directory ss/org-directory
          denote-known-keywords '("project")
          denote-prompts '(title keywords)
          denote-org-capture-specifiers "%?")
    (denote-rename-buffer-mode 1))
#+end_src

** Automatic git commits

The notes tree can enable =git-auto-commit-mode= through a =.dir-locals.el=
at =~/org/=. The Emacs config keeps the package available and sets the
machine-specific shell command chaining based on the active shell, while the
repo-local behavior lives with the notes tree.

#+begin_src emacs-lisp
  (use-package git-auto-commit-mode
    :ensure t
    :pin melpa
    :commands (git-auto-commit-mode)
    :init
    (setq gac-shell-and
          (if (string-match-p "fish\\'" shell-file-name)
              " ; and "
            " && ")))
#+end_src

* Gptel workflow

This keeps LLM chat available as a small workflow tool inside Emacs. GitHub
Copilot authentication is handled on demand by gptel, so there is no token
plumbing in this file.

#+begin_src emacs-lisp
  (use-package gptel
    :ensure t
    :init
    (setq gptel-default-mode 'org-mode
          gptel-model 'gpt-4o
          gptel-backend (gptel-make-gh-copilot "Copilot"))
    :bind (("C-c n g" . gptel)
           ("C-c n s" . gptel-send)
           ("C-c n r" . gptel-rewrite)
           ("C-c n a" . gptel-add)))
#+end_src

* Generated file footers

The closing blocks just finish the generated startup files cleanly.

#+begin_src emacs-lisp

  (when (file-exists-p custom-file)
    (load custom-file nil 'nomessage))

  ;;; init.el ends here
#+end_src

#+begin_src emacs-lisp :tangle early-init.el

  ;;; early-init.el ends here
#+end_src