Org Website Backend

• Org Website Backend
  • Introduction
  • What this backend does
  • Why Dart?
  • Why SCSS?
  • How to run this project
  • Running in development mode
  • How can I use this in my org files?

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 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 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:

  cd /path/to/your/org/website
  ln -s /path/to/your/owb/directory/*

Here is what I add at the top of my org files in order to get it working:

  #+HTML_HEAD_EXTRA: <link rel="stylesheet" href="/style/style.css"/>
  #+HTML_HEAD_EXTRA: <script defer src="/dart/main.dart.js"></script>

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:

  pub global activate webdev
  webdev build -r

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 can add to your environment the variable RELEASE with the value debug. Running the backend locally, you would start it like so:

  RELEASE=debug ./start.sh

Running it with Docker, you would use the following command:

  docker run \
    -p 8080:8080 \
    -v ./web:/app/web \
    -e RELEASE=debug \
    --restart always \
    --detach \
    --name owb \
    owb:1.0

And with docker-compose, you would add the following line to your owb service:

  environment:
    - RELEASE=debug

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:

  #+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>

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:

  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;
  }

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