Styling and third-party Javascript

Last updated:
2020-09-25 19:08

Overview

Firn is not particularly picky about how you style your site. You can setup your own styling mechanisms if you want to use a style preprocessor, or you can use plain css. The simplest method would be to write css as you normally would by placing css files in the _firn/static/css folder and then having firn move them into your _site folder when run. Styling is applied through hiccup.

Pre-configured styles

With that said, Firn does come out of the box with a stylesheet and some predefined styles. Because org-mode syntax is quite powerful and offers unique features over other markups, there are several "components" that you may want to target. For example, an org-mode headline might have a priority, or a todo keyword. These pieces of org syntax will come with a css class already assigned to them, so that users may style them to their liking.

An Example

To use an example, when Firn parses your org-content, whenever it runs into a priority assigned to a headline, it will assign two css classes:

  • .firn-headline-priority

  • .firn-headline-priority__A (Where A corresponds to a priority of [#A])

Correspondingly, the "base" css layer that ships out of the box with Firn will handle assigning a style-set that you can change to your liking. You may view the file _firn/static/css/firn_base.css to see what elements have css classes already associated with them.

How do I customize the styling of my layouts?FAQ

As with normal HTML, you'll need to add a head tag with a link that references to a css file. It might make sense for you to create a partial for defining your html head tag, allowing it to be shared across layouts:

(defn head
  []
  [:head
    [:link {:rel "stylesheet" :href "/static/css/firn_base.css"}]])

How do I add Javascript across the site?FAQ

Similarly, you can define the head function to bring in third-party Javascript dependencies. Here, for example, an instance of Firn is set up to import and use MathJax, enabling LaTeX markup for equations and in-line mathematical expressions across the site.

(defn head
  [build-url]
  [:doctype :html5]
   [:head
    [:meta {:charset "UTF-8"}]
    [:meta {:name "viewport" :content "width=device-width, initial-scale=1.0"}]
    [:script {:type "text/x-mathjax-config"}
     (str "MathJax.Hub.Config({
    tex2jax: {
      inlineMath: [ ['$','$'], ['\\\\(','\\\\)'] ],
      processEscapes: true
    }
  });")]
    [:script {:src "https://polyfill.io/v3/polyfill.min.js?features=es6"}]
    [:script {:type "text/javascript" :async "async" :src "https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"}]
    [:link {:rel "stylesheet" :href (build-url "/static/css/firn_base.css")}]])