Whisper Engine - The Emacs-powered Static Site Generator

Whisper Engine: Minimalist, Emacs-powered static site generator. No JS. No telemetry. No noise.

One-way signal for those who require simplicity.

From simple org files to static sites. In one Emacs window.

Features

• Minimalist: No JS, no telemetry, no noise
• Pure Emacs Lisp
• Paginated index pages
• RSS feed generation
• Automatic article sorting by date
• Teaser + thumbnail support
• Category-based navigation:
  • Dedicated category pages for each category
  • Global categories.html index page
• Removes the orphaned HTML files
• SHA256-based incremental builds for speed and integrity
• Incremental build M-x ds/generate-site
• Full rebuild: C-u M-x ds/generate-site

Requirements

• Emacs 28.1 or newer
• Org Mode 9.5 or newer
• libxml

Configuration & customization

The whisper-engine.el file is self-contained. The top of the file contains a couple of configuration variables.

You can configure them in-place.

The ds/cache-file variable is a full-path to the cache file for incremental site building. SHA256 is used to spot file changes.

(defvar ds/cache-file "/path/to/whisper-cache.el"
  "Path to the Whisper Engine cache file storing file hashes and HTML paths.")

The ds/public-article-dir variable is a full-path to a directory. This is the target for the generated HTML and the static pages, images. This directory is presented by the web server.

(defvar ds/public-article-dir "/path/to/public-html-dir"
  "Public directory where the HTML files will be generated.")

The ds/org-article-dir variable is a full-path to a directory. This is the Whisper Engine input as Org Mode article files. They have special keywords and properties.

(defvar ds/org-article-dir "/path/to/private-org-file-dir"
  "The org file dir. Article sources are here.")

The ds/index-title configures the title of the index pages.

(defvar ds/index-title "Ghost Operator Whispers"
  "Title of the index page.")

The ds/posts-per-page configures how many articles are shown on the index page.

(defvar ds/posts-per-page 6
  "This option sets how many articles are presented on the index page.")

The ds/site-url configures the URL of the generated site.

(defvar ds/site-url "https://site-url.tld"
  "The URL of the site.")

You can customize the footer, the navigation bar and the base html template with the following variables:

• ds/html-nav
• ds/html-footer
• ds/base-html-template

At line 485 the protected files and directories can be configured for site rebuild:

(protected '("static" "CNAME")))

Org File Metadata

The Whisper Engine is powered by Emacs Org Mode.

Org files are the engine of the tool in the ds/org-article-dir directory.

The following keywords configure the exported articles:

#+TITLE: Article Title
#+DATE: <2025-05-23 Fri>
#+CATEGORY: Article category
#+TAGS: #WhisperEngine #Emacs #OrgMode #StaticSiteGenerator #DeadSwitch 
#+IMAGE: /path/to/img.jpg
#+TEASER: Article teaser
#+READY_FOR_DEPLOY: nil

Only the #+READY_FOR_DEPLOY: t articles are exported to HTML and used on the site.

The #+DATE: <2025-05-23 Fri> keyword affects the order of the articles on the index page. Newer articles are on the top.

The #+IMAGE: keyword configures a thumbnail of the article on the index page.

Quick Start

1. Clone the repository:

   git clone https://github.com/deadswitch404/whisper-engine.git
   cd whisper-engine
       

2. Open whisper-engine.el in Emacs and configure:
   • ds/org-article-dir
   • ds/public-article-dir
   • ds/site-url
3. Load the file in Emacs:

   (load-file "/path/to/whisper-engine.el")
   (ds/generate-site)
       

4. Serve the ds/public-article-dir directory via your web server.
5. Browse /index.html for the main feed and /categories.html for category navigation.
6. (Optional) Custom CSS can go to the /static directory.

Demo

The site https://silentarchitect.org is generated by Whisper Engine.

License

MIT License

[ Fear the Silence. Fear the Switch. ]