/firn

Org Mode Static Site Generator

Primary LanguageClojureEclipse Public License 1.0EPL-1.0

Static site generator for org-mode. Status: ⚠️ Alpha.

Overview

Firn generates a static site from org-mode files. It is a bit different from other static site generators, in that it intends to be a drop in solution for creating sites from already existing folders of org-files. Further, because org-mode has great capacity for collecting and displaying different kinds of data (links, logbooks, drawers, task keywords, tags) we can make this data available when org-content is parsed into a data structure (read more here).

Currently, running the firn binary on a directory of org files performs the following:

  • Reads all .org files in the directory recursively.
  • Parses org-files into data structures with Orgize.
  • Collects all file links and logbooks across all files.
  • Passes files through a template system with Hiccup, and renders to HTML.

Usage

Note!

Firn is currently being developed; many things are subject to change, or may be simply broken. Currently, only binaries for MacOS and Linux are being successfully compiled.

Building a static site

With Binary

  1. Download the Firn Binary.
  2. Move the binary into your path (you may need to run chmod + x firn to make it executable).
  3. Navigate to the directory of your org-mode files.
  4. Run firn new. This will create a _firn directory.
  5. Run firn build, still in the directory of your org-mode files.
  6. Navigate to _firn/_site to see your built site.

With the Repo

You also clone this repo and start a repl and run the build commands from the codebase yourself, take a look at build.clj or server.clj for a starting point.

Development server

It’s possible to run a server that will live-reload your files a you make changes to templates and partials. Navigate to your directory of files and run firn serve.

Configuration and Recommendations

  • When you run firn new you create a folder with a config.edn file that allows you to customize some elements of how Firn runs. The possible customization options are currently limited and are described in the config.edn file
  • In order for files to link to each other, org-mode links should be set to relative. You can probably do this with dir-locals and setting org-link-file-path-type to relative. Read setup for more details
  • Firn was built to be used alongside the suggested structure of Org Roam

Developing

Prerequisites:

  • Download GraalVM and set GRAALVM_HOME.
  • Use gu to install the native-image executable.
  • Install lein
  • Install cargo (we use 1.41.1)

Building

This creates a single binary called firn.

git clone git@github.com:theiceshelf/firn.git cd firn
# compile Rust, Clojure and the GraalVM Native Image.
bin/script/compile

Developing

  • From the directory you run your repl, set an environment variable of: DEV=TRUE
  • If you use Emacs, you can set the environment variable to M-x setenv
  • There is a directory for testing Firn on a set of dummy org files, located at clojure/test/firn/demo_org
  • You can run test / build commands inside the core-test namespace.
  • to package up a new version of the rust binary for development (a binary we can shell out to) run the script bin/build-dev-parser

Thank-you’s

  • Thank you to @borkdude for building some awesome libraries (sci is used in firn to evaluate layouts) and for answering questions about compiling with GraalVM and for figuring out how to compile rust and clojure together.
  • PoiScript’s org-mode parser.