This document describes a step-by-step process to generate a static site with Firn. The author assumes the reader has a working familiarity with the command-line.

Head to GitHub to get the latest release of Firn. Currently, Firn is supported on Mac and Linux. After downloading the release, unzip it and move it to usr/local/bin if you prefer to be able to run the binary from anywhere on your system.

mv ~/Downloads/firn /usr/local/bin

If you are on Linux, you may need to run chmod +x firn to make Firn executable on your system.

This document assumes that you are working with a totally new directory with no org-files yet created. The below code sample will create a folder in your root directory, as well as a index.org file with some text redirected into it.

mkdir -p ~/firn-test-site # create a test directory at root
cd ~/firn-test-site       # navigate into the new directory
touch index.org           # create a sample org file

# redirect some sample org-mode content into the new file.
echo "#+TITLE: My Index Page \n* Test heading" >> index.org

Great! Let's see if it builds.

firn new          # creates a _firn directory in ~/firn-test-site
firn build        # transform org files to html files
ls -l _firn/_site # take a look at resulting built files:

# your terminal should look something like this:
# -rw-r--r--  1   staff  266 22 Jun 18:23 feed.xml
# -rw-r--r--  1   staff  343 22 Jun 18:23 index.html
# drwxr-xr-x  3   staff   96 22 Jun 18:23 static

If you open the compiled index.html file, you should see the sample "Test heading" on the page.

You've got yourself a plain, simple HTML page, with very little functionality. Behind the scenes, however, a few things happened.

When calling the firn new command, a series of folders and files are created:

# the `tree` command, run in the firn-test-site dir shows the following:

.
├── _firn
│   ├── _site
│   │   ├── feed.xml
│   │   ├── index.html
│   │   └── static
│   │       └── css
│   │           └── main.css
│   ├── config.edn
│   ├── layouts
│   │   └── default.clj
│   ├── partials
│   │   └── head.clj
│   ├── pages
│   │   └── tags.clj
│   └── static
│       └── css
│           └── main.css
└── index.org

These files are the defaults that come out of the box with Firn. They provide you with the tools to write a bit of CSS, code the layout of your files, and configure the build process and features Firn offers.

Running firn build every time you make a change is a bit cumbersome. This is where the development server comes in. In your terminal run the following command:

firn serve

Your site is now being served on port 4000 - head to http://localhost:4000 to take a look.

Try adding another heading to the index.org file - it will re-compile and display in the browser on refresh. You will also notice that page looks different. The output of a Firn site (the _site folder) is intended to be hosted on a server or CDN. So, running firn build will simply output the files as they are expected to be hosted on a server - this means that your styles and inter-linking between files will not work. Using the development server will solve this, and be used frequently for this purpose.

For Firn to be able to "pick-up" and transform org-mode files into html, a file will need to have something that is often known as "front-matter" in a static-site-generator. In org-mode, in-buffer-settings are used to create "front-matter." All files must have at least a #+TITLE: keyword, but should also have a FIRN_LAYOUT: keywords as well. The keywords are documented in the reference section.

Firn is capable of picking and choosing what parts of an org-file you want to render (display as HTML). Let's explore that now. In your editor, create an org mode file with several headings, and content under each heading. Following, open the file _firn/layouts/default.clj. It will look something like this:

(defn default
  [{:keys [render partials]}]
  (let [{:keys [head]} partials
        default-styles {:style "max-width: 700px; padding: 32px; margin: 0 auto"}]
    (head
     [:body default-styles
      [:main
       [:article
        [:div (render :file)] ;; < this line is important
        ]]])))

The above is Clojure code, which is the language that was used to build Firn. This code uses Hiccup to render HTML. Look to the (render ...) function. Right now, it's indicating that the default layout for an org-mode file should render the file in it's entirety.

Change that line to the following:

(render "{My New Heading}")

Where you will replace {My New Heading} with the specific headline you have created. On saving changes, the server will reload the layout and only render the specified heading and it's contents.

Read more about the render function and layouts in the layout document.

When generating a new site, Firn will create a config.edn file in the _firn directory. This file covers several different aspects of customization for the building of your site. Making changes to this file will largely affect the build output of Firn, as well as rendering behaviour across all files.

Consider an intial config.edn file:

{:dir-data         "data"   ; org-attachments/files to get copied into _site.
 :enable-rss?      true     ; If true, creates a feed.xml in _site.
 :firn-properties? false    ; global: whether to render properties under all headings
 :firn-toc         nil      ; global: settings for any rendered table of contents
 :ignored-dirs     ["priv"] ; Directories to ignore org files in.
 :site-desc        ""       ; Used for RSS.
 :site-title       ""       ; Used for RSS.
 :site-url         ""}

Most of the keys and their values are self explanatory, but let's discuss an example none-the-less. Perhaps a user already has an existing folder of org-files, and these files often link to images in a directory named "attach". Rather than have to rename "attach" to "data" and painfully rename several file links in org-files, a user can change the dir-data key to point to the folder that already exists.

The available configuration keys are commented within the file itself, and are more heavily documented in the configuration documentation. Beyond the above example, the functionality of this file is out of scope for the getting started guide.

The above example largely describes how to use "attachments" (ie, a folder with images etc). Set the name of your folder where images/files are linked to, and it will copy the contents over.

Attachments must be linked with a "file" type link. Attachment links are not currently supported.

NOTE: Currently, Firn copies the entirety of this folder into your build output. This means that if you have attachments which are private or simply unlinked to from org-files, they will be included in your build output.

1. Download the latest release (only Mac and Linux currently supported)

2. Move the Firn binary into your path: mv ~/Downloads/firn /usr/local/bin

3. Navigate to your directory of org files

4. Run firn new

5. Run firn serve

6. Run firn build when ready to put your site online!