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 project
   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.

   While I tried  to run this inside  a Docker environment serving  the Dart and
   CSS files on a  HTTP port to which I tried to redirect  requests, I found the
   easiest way was  to actually compile everything into a ~build~ directory and
   to simlink its content to the root directory of your org website like so:
   #+BEGIN_SRC sh
     cd /path/to/your/org/website
     ln -s /path/to/your/owb/directory/build/*
   #+END_SRC

   Here is what I add at the top of my org files in order to get it working:
   #+BEGIN_SRC org
     ,#+HTML_HEAD_EXTRA: <link rel="stylesheet" href="/style/style.css"/>
     ,#+HTML_HEAD_EXTRA: <script defer src="/dart/main.dart.js"></script>
   #+END_SRC
   In this order, it will make your website display stuff a bit faster.

   To compile the project, you will need to install Dart on your machine as well
   as a SCSS  compiler. While the latter is  up to you, make sur  the result CSS
   files are  in the same directory  as their original SCSS  counterpart. As for
   the Dart part of  the project, you can run the following  to create a release
   build of the project:
   #+BEGIN_SRC sh
     pub global activate webdev
     webdev build -r
   #+END_SRC

   If ~pub~ is  not found as an executable, make  sure ~$HOME/.pub-cache/bin~ is
   in your ~$PATH~. Same goes for ~webdev~ even after you install it.

** 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.