OrgFolio | Turn your scattered interests into cultivated obsessions

OrgFolio is, at heart, just an Emacs lisp build script and file structure for doing the above. It takes your linked .org files and exports them to a separate HTML directory as a complete website.

It’s basically a static site generator for Emacs, but you don’t need to install or configure anything. You don’t need to do anything, just write!

(Except, you will need the simple-httpd package, if you want to serve your site on local http server, which I recommend.)

It’s also hosted on GitHub, here: OrgFolio GitHub.

I have been experimenting with using Org Mode as a static site generator for a few years, and it has some downsides. (Note: it’s possible there are solutions for all of these downsides I have simply overlooked. If so, by all means, leave a comment and share your experiences.)

First, the ox-publish manifest configuration is long and complicated, and I didn’t want to have to rewrite all of that for each notebook, website, or project. In my implementation, the build.el script uses the directory name as a variable, so no additional configuration is necessary from project to project, directory to directory.

Second, once you have your publishing list configured, it can be difficult to keep your /org and /html directories in sync. Org Mode has a built-in solution for this: ox-publish uses a timestamp cache controlled by org-publish-use-timestamps-flag. When enabled (it’s on by default), the org-publish-needed-p function checks each file’s modification time against the last export and skips anything that hasn’t changed. This can speed up the build process, but I’ve often had trouble with it and opted to simply delete the HTML contents and start fresh.

Also, it has no way of cleaning up orphaned files. Let’s say you delete or rename an .org file, the corresponding .html file will sit in the build directory, basically outdated and no longer being used but still there.

I’ve solved that problem here by wiping/deleting the html directory contents on each build via the build.el script. Though, this can increase your build time if you have a large amount of .org files. That’s why I’d recommend keeping separate notebooks organized by topic.

I would recommend first writing notes by hand using something like the Cornell method, then transcribing notes into Org Mode. (But that’s up to you.)

Then, you can build those org notes into a simple wiki style website using OrgFolio. No fuss, no complicated ox-publish configuration.

The core of this setup is the file structure. You have an /org directory for storing your Org Mode files and a /static directory for holding your optional CSS stylesheet, images, and any other static document formats you might require. Then the build.el script drives Emacs in batch mode, so you can run it right from your command line.

emacs --batch --load build.el

That single command runs four steps in sequence:

Cleaning

wipes the output folder so you always get a fresh build.

Exporting

converts every .org file to HTML5 via ox-publish with sensible defaults (table of contents, no section numbers), all of which can be rewritten as needed.

Copying static items

copies any CSS, JavaScript, images, and fonts from /static into the output directory.

Service

spins up a local HTTP server via simple-httpd at localhost:8080 for preview and reading pleasure.

Alternatively, you can load the build file and run it from withing Emacs. Your choice!

You can get everything by cloning the repo from GitHub, but for your reference and perusal, this is the basic directory structure for OrgFolio:

project/
├── build.el       ← the build script
├── org/           ← your .org source files go here
└── static/        ← CSS, JS, images, fonts

The script will build the /html directory on demand when you run it.

You will need:

• Emacs (any reasonably current version)
• simple-httpd package: M-x package-install RET simple-httpd