bUwUma - Build System for Websites

Build Websites using Make

bUwUma is a build system that uses GNU make and a preprocessor to build static, multilingual websites.

bUwUma includes the following features:

• Embed markdown files in your HTML
• Variables
• Conditional control structures (if, else)
• SASS support
• Generation of a XML sitemap
• Generation if all required favicons from a single file
• Generation of thumbnails for videos, audio files and pdfs
• Generation of web-optimized versions of images
• Generation of a (side-)navigation menu from HTML headings and custom links
• Simple creation of a website in multiple languages

Approach

bUwUma aims to allow the creation of a classic website (html+css+javascript) following the DRY and KISS principles. That means: Reduce repetitions and keep it simple, in order to make the project more maintainable.

The approach to building a website using bUwUma is similar to building a C-project: You have a source and a build directory. The source (code), which are all the html, css, javascript files as well as all the resources like images and fonts, live in the source directory. make then... makes the website and places it in the build directory. You can then deploy the website by copying the build directory onto your webserver.

Build process

During the build process, the following happens:

• HTML files are processed by the preprocessor. It will substitute all variables and include additional files into the document (for example a head, footer or text written in markdown). Additionally, a navigation menu can be generated in included in the file. The resulting HTML document will be placed into the build directory.
• A sitemap in the XML format is created in the build directory. It will contain all files in which the preprocessor found a sitemap include command.
• SASS files are compiled by sass compiler and the resulting CSS files are placed into the build directory.
• Favicons are generated from a single image. This includes the favicon.ico, as well as favicon.png, apple-touch-icon.png, android-chrome.png and mstile.png variants an appropriate sizes.
• Thumbnails are generated for the desired files in the desired format and placed in the build directory.
• Web-optimized versions are generated for the desired images in the desired format and placed in the build directory.
• All other source files (css, javascript, resources like fonts and images) are copied into the build directory.

Undesired features can be disabled in the Makefile.

Getting Started

To build a website using bUwUma, you will only have to install the dependencies, edit a few well documented variables in the Makefile and learn a handful of preprocessor commands. The commands should be pretty intuitive to use.

bUwUma is made primarily for Unix, but it only requires a suitable command line environment. That makes it also usable in Windows Subsystem for Linux or in directly Windows, if the required dependencies are installed.

Dependencies

• GNU Make: [MacOS - Windows - should be already installed on Linux]
• Posix-like Shell: z.B. bash oder zsh [already installed on Linux and MacOS]
• Python >=3.10
• Optional:
  • dart-sass: for compiling sass
  • imagemagick: for thumbnail and favicon generation
  • poppler: for generating thumbnails for pdfs
  • ffmpeg: for generating thumbnails from audio files [MacOS - Windows - auf fast allen Linux-Distros bereits installiert]

Installation

bUwUma is available on github and on my gitea. You can install it with git:

git clone https://github.com/MatthiasQuintern/bUwUma

Alternatively, you can just download the Makefile and html_preprocessor.py from the links above.

Configuration

1. Modify the paths in the Makefile. Each variable should be documented well enough in the file
2. Run make print check if the output matches your expectations
3. Run make and watch the magic happen!

nginx

The repo contains a nginx.conf, which can be used to locally test the webpage with nginx. You can run make start or make stop to start/stop the server. You might need to change the root directory in nginx.conf.

The HTML preprocessor

The html preprocessor allows you to use variables, conditional control structures and commands like include, similar to the C preprocessor.

All available commands are documented in the readme of the GitHub repo.

Here is a short summary of the most important things to know:

• Commands are in HTML comment tags to not confuse the syntax highlighting
• A comment may only contain a single command. In multi-line comments, each line may only contain a single command.
• Variables can be used anywhere using

The most important commands are:

• include: Include the content of another file at this position (markdown will be converted to html)
• set: Set the value of a variable

The include functionality allows you to, for example, use a single html <head> for all your files. If you then want to use a custom title for every html file, you can set a variable in each file and use this variable in the <title> tag in the <head>.

The Makefile

The Makefile uses just a few variables to generate the whole website. It runs the preprocessor on all html files and copies all the other files. Because of the way make works, when a single file is modified, only that file and the ones that depend on it are rebuilt, making the process fast and efficient.

To configure the Makefile to your project, you will only have to customize the names of your source, resource and out directories at the top of the file.

Building a website in multiple languages

If you want your website to support multiple languages, you could translate all the files and save them in another directory. This may be quickly done once; However changing something in both languages later on, like the layout, stylesheet or images, will become tedious. The bUwUma gives you two better possibilities:

1. Write a template html and two or more files containing the actual text (which can also be written in markdown!) and include them in the template html using the lang variable in the include path
2. Write a html for both languages and one which contains the parts which both have in common (for example a series of images), then include the common one in the others

Of course, you could also mix both solutions.

---

License