Next: Introduction [Contents]

Jotain ¶

Jotain — a GNU Emacs 31 configuration (floor: Emacs 30.1) with a Nix build layer.

Copyright © Markus Jylhänkangas.

This manual is generated from the Markdown sources under docs/ in the Jotain source tree and the Nix module option metadata. Use C-h i d m Jotain RET to open it inside Emacs, or M-x consult-info to search across every installed manual including this one.

Table of Contents

1 Introduction
- 1.1 Why Jotain?
- 1.2 Source Code
2 Installation
- 2.1 Prerequisites
- 2.2 Building Emacs
  - 2.2.1 Build Matrix
- 2.3 Installing from a Consumer Flake
  - 2.3.1 nix-on-droid (Android)
  - 2.3.2 Overriding nixpkgs
- 2.4 Running
3 Quickstart
- 3.1 Clone the repository
- 3.2 Enter the development shell
- 3.3 Build and run Emacs with the Jotain configuration
- 3.4 Sanity-check the configuration
- 3.5 Clean build artifacts
- 3.6 Update pinned sources
4 Architecture Overview
- 4.1 File Structure
- 4.2 Layers
5 Nix Build Layer
- 5.1 Two-Layer Architecture
- 5.2 Key Build Options
- 5.3 IGC Variant
- 5.4 Git Variants
- 5.5 nix-on-droid
- 5.6 Overriding nixpkgs
6 Module Reference
- 6.1 Conventions
- 6.2 Load order
- 6.3 Core modules
- 6.4 Language modules
- 6.5 Adding a new module
7 Init File
- 7.1 Package archives
- 7.2 Load path
- 7.3 Custom file
- 7.4 Module loading
8 Early Init
- 8.1 Garbage collection
- 8.2 Bidirectional text
- 8.3 Load preference
- 8.4 package.el and use-package
  - 8.4.1 Silencing a quickstart false-positive
- 8.5 Frame chrome
- 8.6 Byte-compiler noise
- 8.7 Font caches
- 8.8 Native compilation
- 8.9 Tree-sitter grammars
- 8.10 Terminal aliases
9 Packages
- 9.1 Provenance
- 9.2 Tree-sitter grammars
- 9.3 Packages that live in Nix
- 9.4 The devenv shell
- 9.5 Adding a new package
10 Package Reference
- 10.1 Package Reference
11 Launching Emacs
- 11.1 One-shot
- 11.2 Daemon + client
- 11.3 Quick edit (-Q -nw)
- 11.4 Which one to use
12 Devenv Integration
- 12.1 Entry point: C-c v
- 12.2 Process dashboard
- 12.3 Environment loading and reload
- 12.4 Auto-activation trust (devenv allow / revoke)
- 12.5 Mode-line status
- 12.6 LSP for devenv.nix
- 12.7 MCP server for the AI stack
- 12.8 Customization
13 Notebooks
- 13.1 The loop
  - 13.1.1 The C-c b prefix
- 13.2 Sessions
- 13.3 Results
  - 13.3.1 Plots
- 13.4 Evaluation prompts and trust
- 13.5 Export
- 13.6 Tangling
- 13.7 Languages
  - 13.7.1 Python and IPython
- 13.8 Structure templates
- 13.9 What this is not
14 AI Screenshots
- 14.1 M-x jotain-screenshot
- 14.2 The emacs_screenshot MCP tool
- 14.3 Headless: just screenshot
15 Finding Information in Emacs
- 15.1 The self-documenting editor
- 15.2 1. The Help system (C-h)
- 15.3 2. The describe family
- 15.4 3. Apropos, finding what you don’t know the name of
- 15.5 4. The Info reader, structured manuals
- 15.6 5. Automatic and contextual help
- 15.7 6. Source code navigation
  - 15.7.1 find-function family
  - 15.7.2 xref (cross-reference framework)
- 15.8 7. Shortdoc, function groups by topic
- 15.9 8. Customization browser
- 15.10 9. Search-based discovery
- 15.11 10. External documentation inside Emacs
- 15.12 11. Runtime introspection
- 15.13 12. Elisp introspection functions
- 15.14 13. Accessing documentation from outside Emacs
- 15.15 14. What ships with Emacs
- 15.16 Quick reference: "How do I find out about...?"
16 Compilation Mode
- 16.1 Configuration
- 16.2 Running a compilation
- 16.3 Navigating errors
- 16.4 Editing grep results
- 16.5 How error parsing works
  - 16.5.1 Adding a custom error regexp
- 16.6 Useful variables
- 16.7 The compilation mode family
17 Keybindings
- 17.1 C-c — user namespace
- 17.2 C-x — control namespace
- 17.3 Other global bindings
- 17.4 Disabled by default
- 17.5 Mode-local overrides
- 17.6 Embark action menu
- 17.7 Window navigation
- 17.8 Why no leader-key framework?
18 Setting Variables
- 18.1 Use setopt for user options (defcustom)
- 18.2 Use setq for regular variables
- 18.3 Use setq-default for buffer-local defaults
- 18.4 Use setq-local for buffer-local values
- 18.5 Use set when the variable name is computed
- 18.6 Quick decision table
- 18.7 Sources
19 Ergonomics
- 19.1 Repeat-mode: the Emacs-native one-shot
- 19.2 Jotain-specific maps
- 19.3 Extending repeat-maps
- 19.4 Pinky-stretch escape hatches Jotain already takes
- 19.5 Beyond Emacs: the rest of Prot’s advice
- 19.6 Optional: modifier-bar-mode
- 19.7 Further reading
20 Inspiration
- 20.1 Emacs
- 20.2 Linux
- 20.3 MacOS
- 20.4 Android
- 20.5 Nix
- 20.6 Keybindings — considered and not adopted
Appendix A Module Options
- A.1 Jotain — Module Options Reference
- A.2 Home Manager Module
- A.3 System Module (NixOS / nix-darwin)
- A.4 devenv Module

Next: Introduction [Contents]