A Static Site Generator for Org Mode
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.
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.
- Download the latest release (only Mac and Linux currently supported), or use the below code snippet to install:
curl -s https://raw.githubusercontent.com/theiceshelf/firn/master/install -o install-firn chmod +x install-firn && ./install-firn # you may need to run the install script with sudo and/or run it with the absolute PWD path: # sudo ~/<path-to-script>/install-firn
- Navigate to your directory of org files
- Run
firn new
- Run
firn serve
- Run
firn build
when ready to put your site online!
The Firn documentation is available here and is mirrored and built from the docs/ folder in this repo.
Firn - A static-site generator for org-mode.
Usage: firn [options] action
Options:
-p, --port PORT 4000 Port number
-h, --help
-v, --version
-r, --repl
-d, --dir PATH /Users/tees/Projects/firn/firn Absolute path of directory to build/serve
Actions:
build Build a static site in a directory with org files.
new Scaffold files and folders needed to start a new site.
serve Runs a development server for processed org files.
Firn can also be used in Docker.
docker run \ -it \ --rm \ -p 4000:4000 \ -v "$PWD":"$PWD" \ --workdir "$PWD" \ theiceshelf/firn \ --help
- Download GraalVM and set
GRAALVM_HOME
. - Use
gu
to install thenative-image
executable. - Install lein
- Install cargo (we use 1.41.1)
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/compile
Firn can be built as a container image, using
docker build -t theiceshelf/firn .
Firn is a Clojure code base that reaches out to a library compiled with Rust. You won’t necessarily need to compile any rust code as the rust artifacts have been vendored into the clojure/resources folders.
This is my personal workflow for developing, it may or may not be useful.
- I open
core.clj
and boot up a Cider REPL in Emacs. - I eval the CLI functions (new, serve, build) in
core.clj
under the(comment ..)
block at the end of the file. - When building a feature, I write the code, evaluate it, and then eval the CLI
commands again in
core.clj
. I usecider-eval-region
to both stop mount (if the server is running) and to re-run the CLI command. - I usually run the tests on the docs folder that is bundled in the repo:
(mount/stop) (-main "serve" "-d" "<path_to_repo>/firn/docs")
- In emacs, I use
m-x setenv
and at the prompt enterDEV
>TRUE
- this prevents CLI exit codes from ending the REPL process.
- Note: some of the functions from the
me.raynes.fs
namespace have been duplicated in theutil.clj
namespace; largely, the functions that have issues with reflection.
- In development, we have a binary version of the Rust parser functionality that the Clojure code shells out to.
- 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 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.
- mvp.css for base layer styles.