#+html:

Firn

A Static Site Generator for Org Mode

• 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.

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 [[https://github.com/PoiScript/orgize][Orgize.]]
• Collects all file links and logbooks across all files.
• Passes files through a template system with Hiccup, and renders to HTML.

• Quickstart

1. Download the [[https://github.com/theiceshelf/firn/releases][latest release]] (only Mac and Linux currently supported), or use the below code snippet to install: #+BEGIN_SRC sh 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 ~//install-firn

   #+END_SRC
2. Navigate to your directory of org files
3. Run =firn new=
4. Run =firn serve=
5. Run =firn build= when ready to put your site online!

• Usage

The Firn documentation is available [[https://firn.theiceshelf.com/][here]] and is mirrored and built from the [[file:docs/index.org][docs/]] folder in this repo.

#+BEGIN_SRC sh 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. #+END_SRC

** Docker

Firn can also be used in Docker.

#+begin_src docker run
-it
--rm
-p 4000:4000
-v "$PWD":"$PWD"
--workdir "$PWD"
theiceshelf/firn
--help #+end_src

• Development ** Prerequisites:

• Download [[https://www.graalvm.org/downloads/][GraalVM]] and set =GRAALVM_HOME=.
• Use =gu= to install the =native-image= executable.
• Install [[https://github.com/technomancy/leiningen][lein]]
• Install [[https://doc.rust-lang.org/cargo/getting-started/installation.html][cargo]] (we use 1.41.1)

** Building

This creates a single binary called =firn=.

#+BEGIN_SRC sh git clone [email protected]:theiceshelf/firn.git && cd firn

compile Rust, Clojure and the GraalVM Native Image.

bin/compile #+END_SRC

*** Container image

Firn can be built as a container image, using #+begin_src sh docker build -t theiceshelf/firn . #+end_src

** Developing

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.

*** Clojure setup / Emacs use.

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 use cider-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 enter DEV > 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 the util.clj namespace; largely, the functions that have issues with reflection.

*** Rust Parser

• 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's

• Thank you to [[https://github.com/borkdude][@borkdude]] for building some awesome libraries ([[https://github.com/borkdude/sci][sci]] is used in firn to evaluate layouts) and for answering questions about compiling with GraalVM /and/ for figuring out how to compile [[https://github.com/borkdude/clojure-rust-graalvm][rust and clojure together]].
• PoiScript's org-mode [[https://github.com/PoiScript/orgize][parser]].
• [[https://andybrewer.github.io/mvp/][mvp.css]] for base layer styles.