Orgify

A simple static site generator that understands org.

Orgify is a simple static site generator for exporting org files.

Under the hood Orgify works similarly to `org-publish', the publishing framework that ships with Emacs. It uses the same ox-html backend and re-uses many of ox's export settings. The main difference is the addition of an HTML templating language that gives you more control over your org files and keywords during the final export.

Installation

Emacs 29

With Emacs 29 you can install packages directly from git repositories: 

(use-package orgify
  :vc (:fetcher sourcehut :repo mgmarlow/orgify))

Earlier Emacs versions

Clone Orgify to your local machine and add it to your load path: 

git clone https://git.sr.ht/~mgmarlow/orgify /path/to/orgify

(add-to-list 'load-path "/path/to/orgify")
(require 'orgify)

Using Orgify

There are two main ways to use Orgify:

  1. Use the `orgify-build-project' interactive command.
  2. Use a build script with `orgify-build'.

The `orgify-build-project' command works great for existing projects managed by project.el. It offers no configuration and assumes the default Orgify folder structure.

Using a build script is ideal for publishing via CI or if building org files in directories other than the project root.

Orgify as an interactive command

When `orgify-build-project' is called, it searches for *.org files from your project root (via `project-root'). When these files are converted to HTML their file names and directories are preserved. You must be visiting a buffer located in that project when invoking `orgify-build-project', otherwise Orgify won't know how to locate your project root.

The exception is the special public/ folder, which contains static assets for your site. These files are copied into the output directory as-is.

For example, this folder structure: 

my-project-root/
  posts/
    2023-07-01-my-first-post.org
    2023-07-02-my-second-post.org
  public/
    404.html
    favicon.io
  index.org

Outputs: 

my-project-root/
  output/
    posts/
      2023-07-01-my-first-post.html
      2023-07-02-my-second-post.html
    404.html
    favicon.io
    index.html

See Emacs Projects for more details.

Orgify as a build script

Create a new build script, build.el, to publish your files. Note that Orgify must be installed as a package or available on your `load-path' before you can require it. 

(add-to-list 'load-path "/path/to/orgify")
(require 'orgify)
(orgify-build
 :base-dir "."
 :out-dir "output/"
 :static-dir "public/")

Execute the script with emacs --script: 

emacs --script build.el

Configuration options

`orgify-build' accepts the following keyword arguments:

  • :base-dir: Directory where Orgify searches for .org files. Defaults to current directory ("*").
  • :out-dir: Build destination for the final HTML site. Defaults to "output/".
  • :static-dir: Static files that are copied into the output folder as-is. Defaults to "public/".

Templates

Orgify supports a handlebars-like templating language, allowing you to pass keywords from your org-mode files into your HTML templates.

Use the layout keyword in your org file to specify a local template in your project.

For example, this org file: 

#+title: My first post
#+layout: my_layout.html

* Hello world!

That's pointing to this template: 

<!-- my_layout.html -->
<html lang="en">
  <head>
    <title>{{ title }}</title>
  </head>
  <body>
    <main>{{ content }}</main>
  </body>
</html>

Renders this as final output 

<html lang="en">
  <head>
    <title>My first post</title>
  </head>
  <body>
    <main><h2>Hello world!</h2></main>
  </body>
</html>

Protected keywords

Orgify has a few protected keywords:

  • content: The HTML output of your org file.
  • layout: Path to the HTML template that lays out the current org file. Defaults to Orgify's Simple.css template.
  • options: The same as org's Export Settings.

All other user-defined keywords are fair game.

Sites using Orgify

Kudos/prior art