maisiliym / firn

Org Mode Static Site Generator

Firn

A Static Site Generator for Org Mode

   

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. Further, live reload changes will not be triggered when you change .org files in nested directories beyond the top directory of firn. For the most part, dunnwurryaboutit.

Footnotes

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

[fn:1]

<My footnote>

Not like this:

[fn:1] <My Footnote>