Emacs Docs

Appearance

Elpa Latest or Release Package Installation (Emacs Package Manager) ​

Once you have Emacs set up at your site, you may install GNU Hyperbole using the Emacs Package Manager. If you are not familiar with it, see Packages in the GNU Emacs Manual. Releases are done with care and occur once in awhile. In between, there is are regression-tested latest distributions packaged from the in-development code branch; these may be many months and features ahead of the release branch.

Therefore, consider using the Elpa Latest package; it pulls from the latest Hyperbole development branch tip and uses the builtin Emacs package manager. Since Hyperbole is a mature package, this is fine to use and update on a day-to-day basis. But new features are tested on this branch and once in awhile it may break for a short time before a fix is pushed.

With this branch you’ll be able to submit bug reports and feature requests but will not be able to submit pull requests for changes to the developers; use the Git Latest Package, described in the next section, instead for that.

If you have Hyperbole installed and simply want to upgrade it, invoke the Emacs Package Manager with {M-x list-packages RET}, then use the {U} key followed by the {x} key to upgrade all out-of-date packages, Hyperbole among them. Then skip the text below and move on to the next section, see Invocation.

Otherwise, to download and install the Hyperbole package, you should add the following Lisp to your Emacs initialization file, as described below. It installs the Elpa Latest package; there is one commented line in the configuration that you can switch out to pull from the older Elpa production release package. (For further details, see The Emacs Initialization File in the GNU Emacs Manual).

emacs-lisp
;;; hy-package.el --- Hyperbole package.el installation and configuration instructions  -*- lexical-binding: t; -*-
;;
;; Author:       Bob Weiner
;;
;; Orig-Date:    15-Jul-26 at 12:28:58
;; Last-Mod:     25-Jul-26 at 22:25:11 by Mats Lidell
;;
;; SPDX-License-Identifier: GPL-3.0-or-later
;;
;; Copyright (C) 2026  Free Software Foundation, Inc.
;; See the "../HY-COPY" file for license information.
;;
;; This file is part of GNU Hyperbole.

;;; ************************************************************************
;;; Requirements
;;; ************************************************************************

(require 'package)

;;; ************************************************************************
;;; Section 1: package.el setup
;;; ************************************************************************

;;; ========================================================================
;;; NOTE: This section is only if you have not yet setup the package.el
;;;       package manager.  If you have, ignore this and skip to "#Section 2"
;;;       for the Hyperbole `use-package' recipe.
;;; ========================================================================

;; Step 1: Add the function definition below near the top of your
;; "~/.emacs" or "~/.emacs.d/early-init.el" file.

;; Step 2: Add a call to the function below its definition:
;;         (setup-package)

(defun setup-package ()
  (require 'package)
  (setq package-enable-at-startup nil) ;; Prevent double loading of libraries
  (add-to-list 'package-archives
	       ;; Leave only one of the following two lines uncommented
	       '("elpa-devel" . "https://elpa.gnu.org/devel/"))
	       ;; '("elpa" . "https://elpa.gnu.org/packages/"))
  (unless (and (boundp 'package--initialized) package--initialized)
    (package-initialize))
  ;; To ensure you have the latest index of packages, you'll have to
  ;; uncomment the next line.  It is commented because retrieving the
  ;; list is slow.
  ;; (package-refresh-contents)
  )

;;; ************************************************************************
;;; Section 2: package.el Hyperbole installation and configuration
;;; ************************************************************************

;; Step 1: Add the following expression to your "~/.emacs" or
;; "~/.emacs.d/init.el" file.

(use-package hyperbole

  ;; ensure Hyperbole is installed
  :ensure t

  ;; Initialize the global HyWiki minor mode to one of these values:
  ;;   :all   - highlights and makes HyWikiWord links active in
  ;;            all text and programming buffer comments
  ;;   :pages - highlights and makes HyWikiWord links active in
  ;;            only within HyWiki page buffers
  ;;   nil    - leaves HyWiki mode disabled.
  :config
  (progn
    ;; Older Hyperbole releases do not have HyWiki
    (when (fboundp 'hywiki-mode)
      (hywiki-mode :all))

    ;; Initialize the global Hyperbole minor mode to one of these values:
    ;;   1 - enabled on startup so the Action and Assist Smart Keys are active
    ;;   0 - off until you toggle it on
    ;; If you left hywiki-mode enabled above, that enables hyperbole-mode too.
    (unless (and (fboundp 'hywiki-mode) hywiki-mode)
      (hyperbole-mode 1)))

  :bind
  (("M-RET" . hkey-either)
   ;; Uncomment the next binding if you want to emulate Hyperbole mouse drag
   ;; events from your keyboard.
   ;; See "https://www.gnu.org/s/hyperbole/man/hyperbole.html#Keyboard-Drags".
   ;; ("M-o"   . hkey-operate)
   )

  ;; Customize how Hyperbole and Org mode share the M-RET key:
  ;;   t        - With hyperbole-mode enabled, Hyperbole controls the key
  ;;   'buttons - With hyperbole-mode enabled, Hyperbole controls the key
  ;;              only when on a button or link; otherwise, Org controls it
  ;;   nil      - In Org mode, Org controls the key
  :custom
  (hsys-org-enable-smart-keys t)
  )

;;; End

Now save the file and restart Emacs. Hyperbole will then be downloaded and compiled for use with your version of Emacs; give it a minute or two.