Firn Setup (with Emacs)

Last updated:
2020-08-27 15:57

The following are optional notes and suggestions on how to best setup Emacs and your folder of org-files with a few best practices for a Firn site.

Folder Structure

Firn was originally intended to build sites from a flat wiki structure, although this is not mandatory. Firn works well with Org-Roam, which is also not required, but useful. You can have nested folders, which will translate into nested url paths.

An example directory:

❯ tree -L 2
.
├── _firn
│   ├── _site
│   ├── bin
│   ├── layouts
│   ├── partials
│   └── static
├── attach
│   ├── _20200328_190456_an_attachment.jpg
│   └── test-img.png
├── file1.org        # => site.com/file1.html
├── file2.org        # => site.com/file2.html
└── foo
    └── level-2.org  # => site.com/foo/file1.html

Links

Linking between files

All links should be relative.

In your wiki directory, add a .dir-locals.el file with these contents to make sure org links are relative (or just change it in your config.el if you don't mind having this setting apply across all org files.):

((org-mode
  (org-link-file-path-type . relative)))

Attachments

When it comes to attachments:

  • It's recommended to put all images/attachments in a single folder (your :dir-data)

  • You can configure which directory this is via the :dir-data key in your config.

Miscellaneous

How to auto timestamp DATE_UPDATED on every file

  • Ensure that you have a #+DATE_UPDATED keyword in your org-files:

#+TITLE: Firn
#+DATE_CREATED: <2020-03-01 09:53>
#+DATE_UPDATED: <2020-03-22 13:24>
  • In your wiki directory, add a .dir-locals file with these contents

((org-mode
  (time-stamp-pattern . "8/DATE_UPDATED:[ 	]+\\\\?[\"<]+%:y-%02m-%02d %02H:%02M\\\\?[\">]")
  ))
  • Somewhere in your config, add a hook to run emacs' time-stamp function on save:

(add-hook 'write-file-hooks 'time-stamp) ; update timestamp, if it exists, when saving

Ignoring certain files or directories

Setting the keyword #+FIRN_PRIVATE: true in an org-mode file will cause the file not to be rendered. Similarly, you can set an entire directory to be ignored in your config.edn