Skip to content

README.org

Latest commit

 

History

History
171 lines (120 loc) · 5.79 KB

README.org

File metadata and controls

171 lines (120 loc) · 5.79 KB

gimel

Static site generator in Clojure, with some potential to become a CMS. It will also collect metadata from those files and store them in a sqlite database.

Description

gimel, like most staic website generators, is an “opinionated” implementation. It fits a particular workflow. It originally watched a directory for file changes and then convert any changed files into html for a static site. I tried maintaining my websites in markdown, but becamw eutterly dissatisfied, as I had been maintaing my websites as org-mode projects. Org-mode publish became slow as the site grew, and I needed something faster. Dissatisfied with the the current state of org-mode parsers in any language, except elisp, I opted for a different path forward. So I created an Emacs package that minimally convert org-mode files into html snippets. gimel.el will properly convert links, add id’s to section headers. It can be run in batch mode, but batch mode is almost as slow as org-publish. So individual files can be exported on save. File-level properties for org-mode files are saved as metadata and stored in the sqlite database.

Quickstart

Get from zero to a publishing site in five minutes.

Gimel has two moving parts: the gimel server, a Clojure application that renders your site, and gimel.el, an Emacs package that converts your org-mode files and triggers a render on every save.

Prerequisites

  • Emacs 25.1 or later with Projectile 2.7.0 or later
  • Java 11 or later
  • Leiningen

Step 1 — Clone the repository

git clone https://github.com/timotheosh/gimel.git
cd gimel

Step 2 — Install gimel.el

Choose whichever method matches your Emacs setup.

Doom Emacs — add to ~/.doom.d/packages.el, then run doom sync:

(package! gimel
  :recipe (:host github :repo "timotheosh/gimel"
           :files ("resources/emacs/gimel.el")))

straight.el:

(straight-use-package
 '(gimel :host github :repo "timotheosh/gimel"
         :files ("resources/emacs/gimel.el")))

Manual — add to your init file:

(add-to-list 'load-path "~/path/to/gimel/resources/emacs")
(require 'gimel)

Also add the after-save hook so publishing happens automatically:

(add-hook 'after-save-hook #'gimel-run-on-save)

Step 3 — Create your project

mkdir -p my-site/{org,html,public}
cd my-site

Step 4 — Configure the gimel server

Create ~/.config/gimel/my-site.toml (or place gimel.toml in your project root):

[server]
port           = 8080
web-url        = "https://example.com"
webroot        = "/path/to/my-site/public"
org-source     = "/path/to/my-site/org"
snippet-output = "/path/to/my-site/html"
template       = "resources/templates/html5-page-layout"
footer         = "My Site © 2026"

[database]
dbname = "my-site.db"

Step 5 — Configure gimel.el

Create .dir-locals.el in your project root:

((nil . ((gimel-config-file  . "/home/you/.config/gimel/my-site.toml")
         (gimel-auto-publish . t))))

gimel.el reads the TOML file automatically when you open a file in the project. The port and directory paths are set from the config — you don’t need to duplicate them here.

Step 6 — Start the gimel server

From the gimel repository root:

lein run -- -c /home/you/.config/gimel/my-site.toml

Step 7 — Write your first page

Create my-site/org/index.org:

#+TITLE: My First Page
#+AUTHOR: Your Name

* Hello, Gimel

This is my first page.

\*\* A Section

Some content here.

Open the file in Emacs. When you save it, gimel.el will:

  1. Convert the org file to an HTML snippet in html/
  2. Ping the gimel server via GET /api/export
  3. The server renders the full site into public/

You should see gimel site exported in the minibuffer. Your rendered page is now in public/index.html.

What’s next?

  • Add a navbar by creating org/navbar.org — gimel.el will post-process its links to absolute paths automatically
  • Customise the template — see the Template System section of the full guide
  • Trigger a full rebuild with M-x gimel-batch-process-org-files after making changes that affect all pages

For complete reference documentation see guide.org.

Future

At some point, I may use the data generated in the database as a means for generating menus and “related links” section for the sites.

License

MIT License

Copyright © 2019-2026 Tim Hawes

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.