Static Site Generator for Emacs Lisp programmers

Have you ever wanted to write a blog:

  • contained in a unique org file,

  • rendered with only one Emacs command,

  • that can be modified by writing Emacs Lisp code (and CSS too),

  • with "html templates" that are plain Emacs Lisp data,

  • with no config file,

  • and no dependencies on external static site generators?

If so, you might be interested in one.el a simple Static Site Generator for Emacs Lisp programmers and org-mode users.

To get started right away check Install one.el and Getting started pages.

You can find the code here: https://github.com/tonyaldon/one.el.

Athough one.el uses org-mode not all the org elements are useful to build technical blog sites (see Why one.el?). So only a few org elements have an transcoder function implemented in one-ox, the org backend used by one.el to build the default website (see one-default render function). Please check Org elements not supported before relying on one.el.

In one.el, the following org document defines a website with 3 pages that we build by calling one-build command while we are visiting it: 

* My website
:PROPERTIES:
:ONE: one-default-home
:CUSTOM_ID: /
:END:

Welcome to my website!

* Blog post 1
:PROPERTIES:
:ONE: one-default
:CUSTOM_ID: /blog/page-1/
:END:

My first blog post!

* Blog post 2
:PROPERTIES:
:ONE: one-default
:CUSTOM_ID: /blog/page-2/
:END:

My second blog post!

Note that if we want to use the default css style sheet we can add it by calling one-default-add-css-file before building the website.

The path / in the first CUSTOM_ID org property tells one.el that the page "My website" is the home page. That page is rendered using one-default-home render function, value of ONE org property of the same headline.

The path /blog/page-1/ in the second CUSTOM_ID org property tells one.el that we want to render "Blog post 1" page in such a way that when we serve our website locally at http://localhost:3000 for instance, that page is served at http://localhost:3000/blog/page-1/. How that page is rendered is determined by the value of ONE org property of the same headline which is one-default, a render function.

The same goes for the last page "Blog post 2".

As you might have noticed, a one.el website is an org file where the pages are the headlines of level 1 with the org properties ONE and CUSTOM_ID set. Nothing more!

ONE is the only org property added by one.el. Its value, an Emacs Lisp function which returns an HTML string, for a given page determines how one.el renders that page.

Paths of pages are set using CUSTOM_ID org property.

With that said, if you want to try it you can check Install one.el and Getting started pages.

Why one.el?

I wrote one.el because I didn't find an existing static site generator with the following requirements:

  • I'm not looking for a solution for every type of websites, only for technical blog sites which are basically chunks of code surrounded by text,

  • I want something simple that I understand and that I can modify only by writting some Emacs Lisp,

  • I want websites to be written to a single org file,

  • I want something with no dependencies other than emacs packages that are not bridges to feed other static site frameworks,

  • I want something with no configuration options, if you want to modify something you write Emacs Lisp code and

  • Finally, I want an Emacs solution for an Emacs user.

Following those requirements led me to one.el, an opiniated static site generator for Emacs Lisp programmers and Org mode users that works well if you want to build websites like

all built with one.el.

RANDOMNEXT