nord-for-org/README.org

#+title: Org Website Backend
#+author: Lucien Cartier-Tilet
#+STARTUP: content

* Org Website Backend
** Introduction
   Org Website  Backend, or  OWB, is  a backend I  created for  my org-generated
   static websites. It was originally developed  as a backend for my linguistics
   website [[https://langue.phundrak.com][langue.phundrak.com]], but  eventually I began using its  Dart and Scss
   source  code with  other generated  websites and  pages of  mine, such  as my
   configuration website hosted on [[https://phundrak.com/config][phundrak.com/config]]. I now want to just have
   it stand on its own, while my org-generated websites stay Dart and Scss code
   free.

** What this backend does
   This has one goal: provide my  org-generated websites a beautiful and unified
   interface. This is achieved by reorganizing  the HTML generated by Emacs when
   publishing my org files, and by  reading dynamically the website’s sitemap in
   order to generate some user menus so  they can navigate freely on the website
   without the need to go back to the main page.

   Visually, it also provides the user three themes:
   - a light theme, enabled by default
   - a dark theme, easier on the eyes
   - a black theme, easier on smartphones’ battery if they have an AMOLED screen
   The  user’s preferences  are kept  on their  browser’s local  storage, so  no
   cookies are used.

** Why Dart?
   Dart  is  a programming  language  developed  by  Google,  which aims  to  be
   compilable as  native code  or as  Javascript code.  In this  case, I  use it
   compiled as Javascript. Why not Javascript  then? I personally find Dart much
   easier to work  with, and to be  a way saner language than  Javascript is. It
   also  ensures  type-safety  and  —to  some  extent—  some  compile-time  code
   verification.  The   dart  compiler   also  performs  some   optimization  at
   compile-time, which is really benificial.

** Why SCSS?
   SCSS is a superset of CSS which aims at simplifying CSS users’ life, and it’s
   really good at its  job. I especially enjoy being able  to nest blocks within
   one another, there’s no more need  to rewrite endlessly some lines that could
   simply be generated by  SCSS. Why SCSS and not SASS? The  answer is simple: I
   have a buggy SASS installation, but SCSS works fine. Yep, simple as that.

   Another thing is that  I use the Ruby implementation of  SASS. The reason for
   that is also simple:  it is the only one that provides  a ~--watch~ option so
   it automatically recompiles SCSS code to CSS when the SCSS code is changed.

** How to run this backend
   This backend delivers only two main files:
   - =/dart/main.dart.js= The main  dart file compiled to  Javascript (you don’t
     need to worry about the others),
   - =/style/style.css= The main style file compiled to CSS.
   This is everything you need for beautiful org-generated websites.

*** Running locally
    You could install Dart on your machine, as well as the Ruby implementation
    of SASS with its dependencies. Then, all you have to do is run ~start.sh~,
    and you’re good to go! Content will be delivered on the 8080 port. If you
    wish to deliver content to another port, you can edit this file.

*** Docker
    A Dockerfile is also provided so you can run this server inside a Docker
    container, and thus you can avoid the hassle of installing Dart and Ruby
    Sass. In order to run OWB, you can run the following:
    #+BEGIN_SRC sh
      $ docker build . --tag owb:1.0
      $ docker run \
        -p 8080:8080 \
        -e RELEASE="release" \
        --restart always \
        --detach \
        --name owb \
        owb:1.0
    #+END_SRC

    If you wish  to run this in  development mode, you could attach  a volume so
    the  Dart  and  SCSS  code  are  linked  between  your  container  and  your
    filesystem. This will also make ~webserver~ run in development mode; expect
    shorter Dart compilation time, but slower Dart code execution.
    #+BEGIN_SRC sh
      $ docker run \
        -p 8080:8080 \
        -v ./web:/app/web \
        -e RELEASE="debug" \
        --restart always \
        --detach \
        --name owb \
        owb:1.0
    #+END_SRC

*** Docker-compose
    This repository also provides a ~docker-compose.yml~ file for easier Docker
    usage with ~docker-compose~. If you wish to run your backend in
    release-mode, simply run the following:
    #+BEGIN_SRC sh
      docker-compose up --detach
    #+END_SRC

    If, as above, you wish to enter development mode, you could modify the
 ~docker-compose.yml~ file like so:
    #+BEGIN_SRC yaml
      version: '3'

      services:
        web:
          build: .
          environment:
            - RELEASE="debug"
          ports:
            - 8080:8080
          restart: always
          volumes:
            - ./web/:/app/web/
    #+END_SRC

** How can I use this in my org files?
   Let’s say you serve your files on org.example.com, add the following lines to
   the top of your org file:
   #+BEGIN_SRC org
     ,#+HTML_HEAD_EXTRA: <link rel="stylesheet" href="https://org.example.com/style/style.css"/>
     ,#+HTML_HEAD_EXTRA: <script defer src="https://org.example.com/dart/main.dart.js"></script>
     ,#+HTML_HEAD_EXTRA: <script src="https://kit.fontawesome.com/yourtokenhere.js" crossorigin="anonymous"></script>
   #+END_SRC

   You will need to obtain a  (free) license on Fontawesome to use fontawesome’s
   icons. Then, once you  have this license, use your token  provided by them to
   edit the third header above.

   Another option is to redirect any request of your website directed to ~/dart~
   or ~/style~  to your running  instance with the  help of your  reverse proxy,
   such as Nginx. You could have for example the following lines:
   #+BEGIN_SRC nginx
     location /dart {
         root http://localhost:8080/dart;
     }

     location /style {
         root http://localhost:8080/style;
     }
   #+END_SRC

   Of course, be careful  to write the same port in the rules  above as the port
   your backend is serving on.