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. Next, you will need to install ~webdev~ and
    install the Dart dependencies:
    #+BEGIN_SRC sh
      $ pub global activate webdev
      $ pub get
    #+END_SRC

    By the way, you  have to ensure your Dart cache’s bins  are in your ~$PATH~.
    They are generally installed in your ~$HOME/.pub-cache/bin~ directory.

    Then, you  have to 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.
    #+BEGIN_SRC sh
      ./start.sh
    #+END_SRC

*** 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 first build the Docker image:
    #+BEGIN_SRC sh
      docker build . --tag owb:1.0
    #+END_SRC

    And then you can run it:
    #+BEGIN_SRC sh
      docker run \
        -p 8080:8080 \
        -v ./web:/app/web \
        --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

** Running in development mode
   # To  run  this backend  in  development  mode, you  will  have  to remove  the
   # ~--release~ option  from the ~webdev~ command in  the ~start.sh~  file. This
   # will allow webdev  to compile Dart files  faster, but at the  price of slower
   # compiled Javascript  files. If you use  Docker, don’t forget to  rebuild your
   # image.
   To run this backend in development mode,  you can add to your environment the
   variable ~RELEASE~ with  the value ~debug~. Running the  backend locally, you
   would start it like so:
   #+BEGIN_SRC sh
     RELEASE=debug ./start.sh
   #+END_SRC

   Running it with Docker, you would use the following command:
    #+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

    And with docker-compose, you would add the following line to your ~owb~
    service:
    #+BEGIN_SRC yaml
      environment:
        - RELEASE=debug
    #+END_SRC

    Any other value  to this environment variable will make  your backend run in
    release mode (actually, it will only make ~webdev~ run in release mode).

** 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 {
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header Host $host;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_pass http://localhost:8080/dart;
     }
     location /style {
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header Host $host;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_pass http://localhost:8080/style;
     }
     location /packages {
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header Host $host;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_pass http://localhost:8080/packages;
     }
   #+END_SRC

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