Docs: setup/build instructions; notes on server.

README.org

@@ -1,11 +1,11 @@
 #+BEGIN_QUOTE
-Static site generator using org-mode.
+Static site generator for org-mode.
+Status: ⚠️ Alpha.
 #+END_QUOTE
 
-* What's this?
+* Overview
 
-Firn generates a website from org-mode files. Firn's original intention was
-to support the building of a flat file wiki, but it can also handle nested content.
+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) we can make this data available when org-content is parsed into a data structure (read more [[file:docs/org-tree.org][here]]).
 
 Currently, running the =firn= binary on a directory of org files performs the following:
 
@@ -14,20 +14,42 @@ Currently, running the =firn= binary on a directory of org files performs the fo
 - Collects all file links and logbooks across all files.
 - Passes files through a template system with Hiccup, and renders to HTML.
 
-* TODO Usage
-* TODO Assumptions / Limitations
+* Usage
 
-- the content _directory name_ (ex: "my_wiki") should not exist anywhere else in
-  the path to a file in the wiki. (TODO: this might not be a problem anymore.)
-  - for example, this is bad: =/development/my_wiki/some_more_dirs/my_wiki/file_1.org=
-  - Unlikely that user's will have this, but it's currently a limitation nonetheless.
-- Org mode links should be set to relative. You can probably do this with
-  dir-locals and setting [[https://emacs.stackexchange.com/questions/32601/how-can-i-get-with-org-store-link-relative-path-instead-of-absolute][org-link-file-path-type]] to =relative=. Read [[file:docs/setup.org][setup]] for
-  more details.
+*Note!*
+
+Firn is currently being developed; many things are subject to change, or may be simply broken. Currently, only binaries for MacOs  are being successfully compiled.
+
+** Building a static site
+*** With Binary
+
+1. Download the Firn Binary. (Currently there are no releases, but you can always navigate to a successful [[https://github.com/theiceshelf/firn/actions/runs/100693222][CI build]] and grab one.)
+2. Move the binary in your path.
+3. Navigate to the directory of your org-mode files.
+4. Run =firn new=. This will create a =_firn= directory.
+5. Run =firn build=, still in the directory of your org-mode files.
+6. Navigate to =_firn/_site= to see your built site.
+
+*** With the Repo
+
+You also clone this repo and start a repl and run the build commands from the codebase yourself, take a look at =build.clj= for a starting point.
+
+** Development server
+It's possible to run a server that will live-reload your files a you make changes to templates and partials. Navigate to your directory of files and run =firn serve=
+
+** Configuration and Recommendations
+
+- When you run =firn new= you create a folder with a =config.edn= file that allows
+  you to customize some elements of how Firn runs. The possible customization
+  options are currently limited and are described in the file.
+- In order for files to link to each other, org-mode links should be set to
+  *relative*. You can probably do this with dir-locals and setting
+  [[https://emacs.stackexchange.com/questions/32601/how-can-i-get-with-org-store-link-relative-path-instead-of-absolute][org-link-file-path-type]] to =relative=. Read [[file:docs/setup.org][setup]] for more details.
+- Firn was built to be used alongside the suggested structure of [[https://github.com/org-roam/org-roam][Org Roam]]
 
 * Developing
 
-Prerequisites:
+** Prerequisites:
 
 - Download [[https://www.graalvm.org/downloads/][GraalVM]] and set =GRAALVM_HOME=.
 -  Use =gu= to install the =native-image= executable.
@@ -45,9 +67,11 @@ cd firn
 bin/script/compile
 #+END_SRC
 
-** Developing [50%]
-- set  an environment variable in your shell / emacs (m-x setenv) : =DEV=TRUE=
-*** TODO Document setting up the repl / compiling test org files.
+** Developing
+- From the directory you run your repl, set an environment variable of: =DEV=TRUE=
+- If you use Emacs, you can set the environment variable to =M-x setenv=
+- There is a directory for testing Firn on a set of dummy org files, located at =clojure/test/firn/demo_org=
+- You can run test / build commands inside the =core-test= namespace.
 * Thank-you's
 
 - Thank you to [[https://github.com/borkdude][@borkdude]] for building some awesome libraries ([[https://github.com/borkdude/sci][sci]] is used in

clojure/resources/firn/_firn_starter/config.edn

@@ -1,2 +1,2 @@
-{:dir-data   "data"    ; org attachments/files to get copied into _site.
+{:dir-data   "data"      ; org attachments/files to get copied into _site.
  :ignored-dirs ["priv"]} ; Directories to ignore org files in.

clojure/src/firn/org.clj

@@ -73,4 +73,4 @@
     (try
       (.getTime (.parse sdf pod->str))
       (catch Exception e
-        (u/print-err! :error  (str "\nFailed to parse the logbook for :" "<<" name ">>" "\nThe logbook may be incorrectly formatted.\nError value:" e))))))
+        (u/print-err! :error  (str "Failed to parse the logbook for file:" "<<" name ">>" "\nThe logbook may be incorrectly formatted.\nError value:" e))))))

docs/index.org

@@ -1,12 +1,12 @@
 #+TITLE: INDEX
 #+DATE_CREATED: <2020-03-24 Tue>
-#+DATE_UPDATED: <2020-03-28 13:12>
+#+DATE_UPDATED: <2020-05-10 13:55>
 #+FILE_UNDER: docs
 #+FIRN_LAYOUT: docs
 
 
  This is the index file of documentation for Firn, a static-site-generator for org-mode.
 
 [[file:layout.org][Layout]] - Regarding the layout and formatting of org-mode files, when converted to html.
-[[file:org-tree.org][Org-tree]] - What an org mode file looks like when parsed -> converted to edn.
+[[file:org-tree.org][Org-tree]] - What an org mode file looks like when parsed and converted to edn.
 [[file:setup.org][Setup]] - Setting up emacs / wiki dir, etc.

docs/setup.org

@@ -1,17 +1,18 @@
-#+TITLE: Editor Setup
+#+TITLE: Firn Setup
 #+DATE_CREATED: <2020-03-27 Fri>
-#+DATE_UPDATED: <2020-03-28 22:05>
+#+DATE_UPDATED: <2020-05-10 15:01>
 #+FILE_UNDER: docs
 #+FIRN_LAYOUT: docs
 
-The following are notes on how to best setup your editor and folder for a Firn site.
+The following are notes on how to best setup your editor and folder for a Firn
+site.
 
 * Folder Structure.
 
-Aim to have a flat wiki. This works well with [[https://github.com/jethrokuan/org-roam][Org-Roam]], which I use in this
-setup currently. Not required, but useful.
-
-You can have nested folders, which /will/ translate into nested url paths.
+Firn was originally intended to build sites from a flat wiki structure but this
+is not mandatory. This works well with [[https://github.com/jethrokuan/org-roam][Org-Roam]], which I use in this setup
+currently. Not required, but useful. You can have nested folders, which /will/
+translate into nested url paths.
 
 An example directory:
 
@@ -34,13 +35,13 @@ An example directory:
 
 #+END_SRC
 * Links
-
 ** Linking between files
 
 All links should be relative.
 
-In your wiki directory, add a =.dir-locals= file with these contents to make
-sure org links are 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.):
 
 #+BEGIN_SRC elisp
 ((org-mode
@@ -51,12 +52,10 @@ sure org links are relative:
 
 When it comes to attachments:
 
-- It's recommended to put all images/attachments in a single folder  (your =:dir-data=)
-- =File:= links (to images, etc) are the best way to go for now.
-  - pro: you can view images inline in graphical versions of emacs.
-- Org-attach can work, but isn't officially supported. If you do use it:
-  - You'll want to use [[https://github.com/abo-abo/org-download][org-download]], =attachment:= links don't work currently.
-  - be aware that inline image viewing might not work.
+- 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.
 
 * Other Things
 ** How To get auto timestamp on =DATE_UPDATED= on every file in emacs.
@@ -82,3 +81,8 @@ When it comes to attachments:
 #+BEGIN_SRC elisp
 (add-hook 'write-file-hooks 'time-stamp) ; update timestamp, if it exists, when saving
 #+END_SRC
+** 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=