165 lines
6.5 KiB
Org Mode
165 lines
6.5 KiB
Org Mode
#+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
|
||
# Release mode
|
||
RELEASE="release" ./start.sh
|
||
|
||
# Debug mode
|
||
./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 \
|
||
-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 \
|
||
--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.
|