Skip to content

theiceshelf/firn

master
Switch branches/tags
Code

Firn

A Static Site Generator for Org Mode

GitHub release (latest by date including pre-releases)  Discord 

What’s Firn?

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, etc) 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 the lovely Orgize.
  • Collects all file links, tags and logbooks across all files.
  • Passes files through a template system called Tera, and renders to HTML.

How do I use it?

  • Download the latest binary from the Github Releases page.
  • Add the binary to your path, or use the -d flag to pass a directory to Firn
# navigate to a directory that has some org-files in it, then
# scaffold out a site:
firn new

# go explore what was generated:
ls -la _firn

# start a server and go looking for your files:
# if you have an org file called 'foo.org' it will become 'foo.html' etc.
firn serve

# ready to build the output?
firn build

Read the full usage documentation here.

Development & Contributing

  • Rust version 1.58.0
  • see Makefile commands.
  • You’ll need a folder of Org files to test on.

A small roadmap can be found here.

Limitations

Development Server

The development server is quite naive. There is no caching or diffing in the replacement of changed assets in the /static or /data folder.

Footnotes

Due to how the parser parses footnotes, they must look like so:

[fn:1]

<My footnote>

Not like this:

[fn:1] <My Footnote>