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.

$ cd ~/Website/src

$ make

Making directory ../www/de/

Making directory ../www/en/

Building html de/kontakt.html at ../www/de/kontakt.html

Building html in lang de: common/index.html at ../www/de/index.html

Building html in lang en: common/index.html at ../www/en/index.html

Making directory ../www/style/

Building: style/style.css at ../www/style/style.css

$ ls ../www

de en style

$ ls ../www/de

index.html kontakt.html

$ make clean

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:

< s p a n c l a s s = " u n a c c e n t e d " > [M a c O S] (h t t p s : / / f o r m u l a e . b r e w . s h / f o r m u l a / m a k e) - [W i n d o w s] (h t t p s : / / c o m m u n i t y . c h o c o l a t e y . o r g / p a c k a g e s / m a k e) - s h o u l d b e a l r e a d y i n s t a l l e d o n L i n u x] - * * P o s i x - l i k e S h e l l * * : z . B . b a s h o d e r z s h \[< s p a n c l a s s = " u n a c c e n t e d " > a l r e a d y i n s t a l l e d o n L i n u x a n d M a c O S < / s p a n >] - * * P y t h o n > = 3.10 * * - O p t i o n a l : - [* * d a r t - s a s s * *] (h t t p s : / / s a s s - l a n g . c o m / d a r t - s a s s /) : f o r c o m p i l i n g s a s s - [* * i m a g e m a g i c k * *] (h t t p s : / / i m a g e m a g i c k . o r g / s c r i p t / d o w n l o a d . p h p) : f o r t h u m b n a i l a n d f a v i c o n g e n e r a t i o n - [* * p o p p l e r * *] (h t t p s : / / p d f 2 i m a g e . r e a d t h e d o c s . i o / e n / l a t e s t / i n s t a l l a t i o n . h t m l) : f o r g e n e r a t i n g t h u m b n a i l s f o r p d f s - * * f f m p e g * * : f o r g e n e r a t i n g t h u m b n a i l s f r o m a u d i o f i l e s < s p a n c l a s s = " u n a c c e n t e d " > \[[M a c O S] (h t t p s : / / f o r m u l a e . b r e w . s h / f o r m u l a / f f m p e g) - [W i n d o w s] (h t t p s : / / c o m m u n i t y . c h o c o l a t e y . o r g / p a c k a g e s / f f m p e g) - a u f f a s t a l l e n L i n u x - D i s t r o s b e r e i t s i n s t a l l i e r t] < / s p a n > # # # I n s t a l l a t i o n C o D e R e P l A c E m E n T D j b Y J I l g R m p d v O H D a H i s a v a i l a b l e o n [g i t h u b] (h t t p s : / / g i t h u b . c o m / M a t t h i a s Q u i n t e r n / b U w U m a) a n d o n m y [g i t e a] (h t t p s : / / g i t . q u i n t e r n . x y z / M a t t h i a s Q u i n t e r n / b U w U m a) . Y o u c a n i n s t a l l i t w i t h g i t : < c o d e c l a s s = " t e r m i n a l - s p a n " > g i t c l o n e h t t p s : / / g i t h u b . c o m / M a t t h i a s Q u i n t e r n / b U w U m a < / c o d e > A l t e r n a t i v e l y, y o u c a n j u s t d o w n l o a d t h e C o D e R e P l A c E m E n T R a N q J c k z d O Y v x f F c D q a n d C o D e R e P l A c E m E n T y X a l H p A g U E g h k O L C l Z f r o m t h e l i n k s a b o v e . # # # C o n f i g u r a t i o n 1 . M o d i f y t h e p a t h s i n t h e C o D e R e P l A c E m E n T w W e K G u d C Q B W y k a H Y n Y . E a c h v a r i a b l e s h o u l d b e d o c u m e n t e d w e l l e n o u g h i n t h e f i l e 2 . R u n C o D e R e P l A c E m E n T M l Y Z z g z T u G j I h Y c x f D c h e c k i f t h e o u t p u t m a t c h e s y o u r e x p e c t a t i o n s 3 . R u n C o D e R e P l A c E m E n T l i q o X U x h U u r X o L D O h Z a n d w a t c h t h e m a g i c h a p p e n! # # # n g i n x T h e r e p o c o n t a i n s a C o D e R e P l A c E m E n T N y W H v k G H C G i N y o R c B p, w h i c h c a n b e u s e d t o l o c a l l y t e s t t h e w e b p a g e w i t h n g i n x . Y o u c a n r u n C o D e R e P l A c E m E n T O o c l s b D S O o E D r z S o H C o r C o D e R e P l A c E m E n T w L C z X c r m A n s q X R N d h f t o s t a r t / s t o p t h e s e r v e r . Y o u m i g h t n e e d t o c h a n g e t h e C o D e R e P l A c E m E n T H q a r W f j l V c y r r h P N Z Z d i r e c t o r y i n C o D e R e P l A c E m E n T D e s a Y H j z a J i X i E z S E H . # # # # T h e H T M L p r e p r o c e s s o r T h e h t m l * p r e p r o c e s s o r * a l l o w s y o u t o u s e v a r i a b l e s, c o n d i t i o n a l c o n t r o l s t r u c t u r e s a n d c o m m a n d s l i k e C o D e R e P l A c E m E n T Q l o o A W c o O z x j W R O d X y, s i m i l a r t o t h e * C * p r e p r o c e s s o r . A l l a v a i l a b l e c o m m a n d s a r e d o c u m e n t e d i n t h e [r e a d m e o f t h e G i t H u b r e p o] (h t t p s : / / g i t h u b . c o m / M a t t h i a s Q u i n t e r n / b u w u m a) . H e r e i s a s h o r t s u m m a r y o f t h e m o s t i m p o r t a n t t h i n g s t o k n o w : - C o m m a n d s a r e i n H T M L c o m m e n t t a g s t o n o t c o n f u s e t h e s y n t a x h i g h l i g h t i n g - A c o m m e n t m a y o n l y c o n t a i n a s i n g l e c o m m a n d . I n m u l t i - l i n e c o m m e n t s, e a c h l i n e m a y o n l y c o n t a i n a s i n g l e c o m m a n d . - V a r i a b l e s c a n b e u s e d a n y w h e r e u s i n g C o D e R e P l A c E m E n T S P R K m j d t Y S S y d r L R A d T h e m o s t i m p o r t a n t c o m m a n d s a r e : - C o D e R e P l A c E m E n T B l C t H d u m U J y C W g l w D L : I n c l u d e t h e c o n t e n t o f a n o t h e r f i l e a t t h i s p o s i t i o n (m a r k d o w n w i l l b e c o n v e r t e d t o h t m l) - C o D e R e P l A c E m E n T e r P h u h G N x w t p i X v C j L : S e t t h e v a l u e o f a v a r i a b l e T h e C o D e R e P l A c E m E n T N a c U q Z p D W J D D f b G X W v f u n c t i o n a l i t y a l l o w s y o u t o, f o r e x a m p l e, u s e a s i n g l e h t m l C o D e R e P l A c E m E n T X z T O E V A v Z f Z k t f X s i N f o r a l l y o u r f i l e s . I f y o u t h e n w a n t t o u s e a c u s t o m t i t l e f o r e v e r y h t m l f i l e, y o u c a n s e t a v a r i a b l e i n e a c h f i l e a n d u s e t h i s v a r i a b l e i n t h e C o D e R e P l A c E m E n T L r Z l u a x v s M g T n A h P t H t a g i n t h e C o D e R e P l A c E m E n T A U E m x a m V q f b u j y H s Y z . # # # T h e M a k e f i l e T h e C o D e R e P l A c E m E n T s O N F Z n J D X C e n K e d B p o u s e s j u s t a f e w v a r i a b l e s t o g e n e r a t e t h e w h o l e w e b s i t e . I t r u n s t h e * p r e p r o c e s s o r * o n a l l h t m l f i l e s a n d c o p i e s a l l t h e o t h e r f i l e s . B e c a u s e o f t h e w a y C o D e R e P l A c E m E n T W b x J R k w C S r V Z t A C o q z w o r k s, w h e n a s i n g l e f i l e i s m o d i f i e d, o n l y t h a t f i l e a n d t h e o n e s t h a t d e p e n d o n i t a r e r e b u i l t, m a k i n g t h e p r o c e s s f a s t a n d e f f i c i e n t . T o c o n f i g u r e t h e C o D e R e P l A c E m E n T U c u A M E u A u t M a Y d D O X w t o y o u r p r o j e c t, y o u w i l l o n l y h a v e t o c u s t o m i z e t h e n a m e s o f y o u r * s o u r c e *, * r e s o u r c e * a n d * o u t * d i r e c t o r i e s a t t h e t o p o f t h e f i l e . <! - - # s i d e n a v n a m e M u l t i l i n g u a l w e b s i t e - - > < h 4 i d = " m u l t i l a n g " > B u i l d i n g a w e b s i t e i n m u l t i p l e l a n g u a g e s < / h 4 > I f y o u w a n t y o u r w e b s i t e t o s u p p o r t m u l t i p l e l a n g u a g e s, y o u c o u l d t r a n s l a t e a l l t h e f i l e s a n d s a v e t h e m i n a n o t h e r d i r e c t o r y . T h i s m a y b e q u i c k l y d o n e o n c e; H o w e v e r c h a n g i n g s o m e t h i n g i n b o t h l a n g u a g e s l a t e r o n, l i k e t h e l a y o u t, s t y l e s h e e t o r i m a g e s, w i l l b e c o m e t e d i o u s . T h e C o D e R e P l A c E m E n T C v X O z j Q w t v x Z w Y j l I Z g i v e s y o u t w o b e t t e r p o s s i b i l i t i e s : 1 . W r i t e a * t e m p l a t e * h t m l a n d t w o o r m o r e f i l e s c o n t a i n i n g t h e a c t u a l t e x t (w h i c h c a n a l s o b e w r i t t e n i n * m a r k d o w n *!) a n d C o D e R e P l A c E m E n T N a Y s F z x Y l M U f C i q P k j t h e m i n t h e t e m p l a t e h t m l u s i n g t h e C o D e R e P l A c E m E n T O g Z E r Q W Z B W O P k Y H N S A v a r i a b l e i n t h e i n c l u d e p a t h 2 . W r i t e a h t m l f o r b o t h l a n g u a g e s a n d o n e w h i c h c o n t a i n s t h e p a r t s w h i c h b o t h h a v e i n c o m m o n (f o r e x a m p l e a s e r i e s o f i m a g e s), t h e n C o D e R e P l A c E m E n T f b R b v i p e r F w e g L y s s v t h e c o m m o n o n e i n t h e o t h e r s O f c o u r s e, y o u c o u l d a l s o m i x b o t h s o l u t i o n s . R E P L H A S H D O L L A R (l i c e n s e_{g} p l_{e} n)