Why I don't use static website generators like Hugo

How to create a static website without Python, Ruby, Node, PHP, Hugo, Jekyll and WordPress? It is freeware mdBook

Free Download mdBook (Windows, Mac and Linux)

Make sure to put the path to the binary into your PATH environment variable

Standards for Best Static website generator

It may be the Best static website builder if it meets the following rules:

Support writing articles in markdown format and converting to static HTML
Write and save our articles on local computer instead of server
So I can save articles in Cloud software like OneDrive or Dropbox, and I never lose them, and I don't need to backup a database on the server
The Generator should only one binary file, no dependencies
So I don't need any professional skills to set up a complex environment to run it
We don't have to worry about hacking
All static, static html files and statically compiled website generator
If we don't use dynamic techniques and don't install PHP, Python or Ruby on the server, how do hackers attack static html files?
The static website builder should be in active development and we don't have to worry about it being abandoned in the near future

Why don't I use Hugo or Zola

Hugo book vs mdBook

Hugo and Zola seem to meet the Standards for Best Static website generator but I (King Eca) don't use them, why?

I don't like adding the following header to the beginning of each source file:

---
title: "I love EasiestSoft.com"
date: 2019-12-21T08:47:11+01:00
draft: true
---

The additional header make the source article dirty and ugly, I just can't accept
The first line of the article can be/is the title, why do we need to define it again in the extra header? It is a waste of time and complicates simple things
The date part is not very important in the article, we can put it on the last line of the article (This page is an example)
And the date format is too complicated, YYYY-MM-DD is enough (for me)
If you want to sort the articles on the same day by time, you can touch the file to change the time, and let the program read the last modified time of the file, which is still easier than manually modifying the time in the source file header
The last line of this article consists of two parts:
YYYY-MM-DD Author Name
A program can easily extract the date from the last line of the source file, and the source files looks very clean
The draft definition in the header is not necessary
- For most personal websites/blogs, we may not use the draft definition very often and it is not worthwhile to add it to each source file
- We can define a rule that the folder/file name that starts with some characters is draft (for example zz_)
- And we can easily exclude draft folders/files in .gitignore file or find programs (zz_* in .gitignore)
Maybe someone is not used to my solution, but I am curious how you exclude draft files/folders from a version control system like git

For most personal websites/blogs, such additional header complicates simple things, and I disagree with this design

But if you have complex needs, you might need an additional header in article head. However, I will try to avoid such need, because the simplicity of the source file is important for aesthetic humans

mdBook basic usage

$ mdbook --help
mdbook v0.3.5
Mathieu David <mathieudavid at mathieudavid.org>
Creates a book from markdown files
USAGE:
    mdbook.exe [SUBCOMMAND]
FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information
SUBCOMMANDS:
    build    Builds a book from its markdown files
    clean    Deletes a built book
    help     Prints this message or the help of the given subcommand(s)
    init     Creates the boilerplate structure and files for a new book
    serve    Serves a book at http://localhost:3000, and rebuilds it on changes
    test     Tests that a book's Rust code samples compile
    watch    Watches a book's files and rebuilds it on changes
For more information about a specific command, try `mdbook <command> --help`

Let's start building our static HTML website

mdBook is a utility to create modern online documents/books from Markdown files, we can also use it to build our static website/blog, https://easiestsoft.com is a live example website built by mdBook

You can read the mdBook online official guide first, I'm sure it will be easier than Hugo

I assume you have downloaded mdBook and read the official guide, and you can build a simple static website using mdBook

I run all the commands in this article on Windows, but most commands can be used on Linux and Mac. You can follow the article https://easiestsoft.com/win/software-to-run-linux-commands-on-windows/ to set up a smallest linux system on Windows, which will make your life easier

I assume you put your site/blog in mybook/easiestsoft.com folder

Let's initialize a new static site with the default theme

$ cd mybook/easiestsoft.com
$ mdbook init --theme

Copying the default theme to src
This could potentially overwrite files already present in that directory.

Are you sure you want to continue? (y/n) y

Do you want a .gitignore to be created? (y/n)
n
What title would you like to give the book?
EasiestSoft.com official
2019-12-21 17:14:02 [INFO] (mdbook::book::init): Creating a new book with stub content

All done, no errors...

Now let's take a look at the structure of our website:

# tree on Linux/Mac
$ tree.com //f

│   book.toml
│
├───book
└───src
    │   chapter_1.md
    │   SUMMARY.md
    │
    └───theme
        │   book.js
        │   favicon.png
        │   highlight.css
        │   highlight.js
        │   index.hbs
        │
        └───css
                chrome.css
                general.css
                print.css
                variables.css

How to Customize the theme for our static website

Read this mdBook official guide on how to customize the theme

In the previous section, we initialized a new site with the default theme. The default theme includes files:

└───theme
    │   book.js
    │   favicon.png
    │   highlight.css
    │   highlight.js
    │   index.hbs
    │
    └───css
            chrome.css
            general.css
            print.css
            variables.css

If you do not change anything in the theme folder, you can completely delete the theme directory

In this article, we delete all files but keep theme/index.hbs

One day, you want to modify another theme file, you can run the following command:

$ cd mybook/easiestsoft.com
$ mkdir tmp
$ cd tmp
$ mdbook init --theme

# Move the file that you want to modify to mybook/easiestsoft.com/theme folder, then
$ cd ..
$ rm --recursive --force tmp

The point is, do not run mdbook init --theme in the root directory of the book( mybook/easiestsoft.com in this article )

How to customize the menu title for our static website:
Open mybook/easiestsoft.com/theme/index.hbs in a text editor, find menu-title, edit the text:
```
<h1 class="menu-title">Easiest solution in the world</h1>
```

How to add links to the right of the menu title:

Open mybook/easiestsoft.com/theme/index.hbs in a text editor, find right-buttons, edit the text:

<div class="right-buttons"><a href="https://easiestsoft.com" title="EasiestSoft home">Home</a> | <a href="https://easiestsoft.com/win/a/movie-editor-for-windows.html" title="EasiestSoft Movie Editor for Windows">Video Editor</a>

How to add a footer bellow the article content:

Add footer bellow the article

Find {{{ content }}} in index.hbs, edit it as:

{{{ content }}}<hr><p align=center>©2012-2019 <a href="https://easiestsoft.com">EasiestSoft</a></p>

Configuration for static website

Static website configuration tutorial on mdBook official site

This is a sample book.toml from https://easiestsoft.com

[book]
title = "EasiestSoft Official, EasiestSoft Movie Editor and Video Converter"
author = "EasiestSoft"
language = "en"
description = "Easy Movie Editor, Video Converter, Home DVD Ripper, DVD Copier software provider"

[build]
create-missing = false
build-dir = "D:/dl/book-easiestsoft"

[output.html]
default-theme = "rust"

[output.html.fold]
enable = true

[output.html.search]
enable = false

#[output.linkcheck]
#follow-web-links = false
#warning-policy = "ignore"

The default build directory is mybook/easiestsoft.com/book, but the output html files is not very important compared to source files, so in the above book.toml, set build-dir to a temporary directory for local testing

How to generate html pages that are not listed in `SUMMARY.md`

mdBook official tutorial of SUMMARY.md

The summary file is used by mdBook to know what chapters to include, in what order they should appear, what their hierarchy is and where the source files are. Without this file, there is no book

mdBook just converts the .md files listed in SUMMARY.md, if there is no cba.md in SUMMARY.md, there is no corresponding cba.html output

For example, you want to provide a 404 not-found.html page for your site, but you don't want to explicitly add not-found.md to SUMMARY.md, how do you do?

We can add not-found.md to SUMMARY.md with special tags, and remove some tagged content from the html

EasiestSoft.com puts non-essential files in z folder, for example /z/not-found.md. Add [~-not found-~](./z/not-found.md) to SUMMARY.md, here ~- and -~ are special tags, then run the following command after building the book:

    fd -0 --extension html | xargs -0 sd '(?:<[^>]+>){2}~-[\w\s_/-]+?-~</a></li>' ''
    fd -0 --extension html | xargs -0 sd '(<title>)~-([\w\s_/-]+?)-~' '$1$2'

To understand the above commands, you can read the tutorials:

How to remove `index.html` from URL

You can run the following command after building the book to remove index.html from folder-name/index.html

fd -0 --extension html | xargs -0 sd --string-mode '"' '"'

When I visit any non-existing page of my website, the `not-found.html` page may lose its style

mdBook uses relative paths by default, not-found.html will lose it's style when a non-existing page has a different path depth than not-found.html

We can fix it by using absolute paths in not-found.html, run the following command after building the book:

sd --string-mode '../' 'https://easiestsoft.com/' z/not-found.html

How to upload static website to server

EasiestSoft.com upload recent changed source files to server and build book on server

Download mdbook on the server:

EasistSoft@server: ~$ cd ~/bin/tmp
EasistSoft@server: ~/bin/tmp$ wget https://github.com/rust-lang/mdBook/ releases/download/v0.3.5mdbook-v0.3.5-x86_64-unknown-linux-gnu.tar.gz
EasistSoft@server: ~/bin/tmp$ tar --extract --gz --file *.gz
EasistSoft@server: ~/bin/tmp$ mv mdbook ..
EasistSoft@server: ~/bin/tmp$ rm -rf *
EasistSoft@server: ~/bin/tmp$ cd ..
EasistSoft@server: ~/bin$ chmod 700 mdbook
# Add mdbook to PATH
EasistSoft@server: ~/bin$ vi ~/.profile
PATH="$HOME/bin:$PATH"
EasistSoft@server: ~/bin$ source ~/.profile

Create a bash script on Windows/Linux/Mac:

upload-easiestsoft:

#!/bin/bash

# Author: King Eca https://easiestsoft.com
# Date: 2019-12-21

fxz=src.xz
sshost=host-easiestsoft

cd ~/mybook/easiestsoft.com
rm --force $fxz
tar --create --xz --file=$fxz $(fd --changed-within 1d --exclude 'zz_*' -E '*.xz' --type file --path-separator '//')
ls -l --human-readable $fxz

sftp $sshost:/home/easiestsoft.com/mdbook <<< $"put $fxz"

ssh $sshost <<'ENDSSH'
	book=/home/easiestsoft.com/mdbook
	public=/home/easiestsoft.com/public
	out=~/out-mdbook
	fxz=src.xz

    cd $book
    tar --extract --xz --file=$fxz
    rm --force $fxz

    mdbook build --dest-dir $out
    cd $out
    fd -0 --extension html | xargs -0 sd --string-mode '"' '"'
    fd -0 --extension html | xargs -0 sd '(?:<[^>]+>){2}~-[\w\s_/-]+?-~</a></li>' ''
    fd -0 --extension html | xargs -0 sd '(<title>)~-([\w\s_/-]+?)-~' '$1$2'
    sd --string-mode '../' 'https://easiestsoft.com/' z/not-found.html

    # Suppose we don't use any puglins for mdBook
    # if we use a plugin, we should use `$out/html/*` instead of `$out/*`
    cp --recursive $out/* $public
    rm --recursive --force $out
ENDSSH

rm --force $fxz

host-easiestsoft is a ssh host, you need to set it up in file ~/.ssh/config:

Host host-easiestsoft
    HostName 98.76.54.32
    User easiestsoft
    Port 210
    IdentityFile ~/path/to/public/key
    IdentitiesOnly yes

And make sure you can ssh host-easiestsoft log in to the remote server

I created and ran this bash script on Windows and it runs on Linux and Mac without changes (except remove --path-separator on Non-Windows systems)

Please read the guide How to run Linux commands on Windows

This bash script automatically and quickly does the following:

Compress recently changed source files into src.xz
sftp upload the src.xz to the server
Extract src.xz on the server
Build book on the server
Delete unnecessary files

I put the path to upload-easiestsoft into the system PATH environment variable, and run command in VS Code or MSYS2 bash on local Windows PC:

$ upload-easiestsoft

Useful Links:

2019-12-21 King Eca

Easiest Software Official