Docs

`mkws`

A small, no bloat, minimalist static site generator using sh as a templating language.

Requirements

We provide statically compiled binaries for Linux or OpenBSD. It can also run on Windows via the Windows Subsystem for Linux for other UNIX like operating systems, you can build from sources.

Install `mkws`

On a Linux machine, just download the archive from https://mkws.sh/mkws@4.0.8.tgz or in the terminal, assuming wget is installed, type:

wget -O - https://mkws.sh/mkws@4.0.8.tgz | tar -xzvf -

File Hierarchy

Inside the downloaded archive you will find the following file structure:

.
|-- bin
|   |-- lmt
|   |-- mkws
|   `-- pp
`-- share
    |-- l.upphtml
    |-- man
    |   `-- man1
    |       |-- lmt.1
    |       |-- mkws.1
    |       `-- pp.1
    |-- s.uppcss
    `-- sitemap.uppxml

. The root directory, it holds the template files and other generated files, including *.html, *.css, *.js and sitemap.xml files.
- ./bin Holds the static site generator's binaries, they're used to generate the static site.
  - ./bin/lmt Small utility part of lts for printing a file's last modification time used to generate timestamps.
  - ./bin/mkws The main script, the actual static site generator, when called from the command line via ./bin/mkws <url>, it scans the . root directory for *.upptml files, mkws's template files, preprocesses them via pp and renders them inside the share/l.upphtml layout file outputing an HTML file for each one. index.upphtml is transformed to index.html, docs.upphtml is transformed to docs.html, etc. It also creates the main CSS file, s.css from share/s.uppcss and the sitemap.xml file from share/sitemap.uppxml.
  - ./bin/pp The pp preprocessor, it allows nesting sh code in any text file. It it used by the main ./bin/mkws script to preprocess any .upp* file.
- ./share Holds any files that are shared between different components of the static site generator.
  - ./share/l.upphtml The main layout file, it holds the common parts of your website. Elements like html, body, head are located here. The standard layout file found in the archive, which is also part of the base theme is:
```
 <!doctype html>
 <html lang=${LANG%%_*}>
 
 <head>
 
 <title>My website</title>
 
 <meta charset=${LANG##*.}>
 <meta name=viewport content='width=device-width'>
 
 <link rel=icon href=favicon.ico type=image/x-icon>
 <link rel=stylesheet
 href=s.css?$(lmt -f '%Y-%m-%dT%H:%M:%SZ' s.css | cut -d' ' -f1)>
 
 </head>
 
 <body>
 
 #!
 pp "$1"
 #!
 
 </body>
 
 </html>
```
- ./share/man man pages
- ./share/s.upcss CSS template. It's also processed via pp so it's scriptable via sh code.
- ./share/sitemap.uppxml sitemap.xml template.

Generate the Static Site

Rename the directory you unarchived earlier to your site's name:

mv ws.sh example.com && cd example.com

Create your first template named index.upphtml, this is required by mkws:

cat <<EOF > index.upphtml
<p>
#!
echo hello, world
#!
</p>
EOF

Run mkws:

./bin/mkws https://example.com

You just generated your first static site with mkws. You will now have an index.html file in your . root directory containing the following code:

<!doctype html>
<html lang=en>

<head>

<title>My website</title>

<meta charset=UTF-8>
<meta name=viewport content='width=device-width'>

<link rel=icon href=favicon.ico type=image/x-icon>
<link rel=stylesheet
href=s.css?2020-12-12T18:42:29Z>

</head>

<body>

<p>
hello, world
</p>

</body>

</html>

To create new pages, just add new *.upphtml files in the . root directory, mkws automatically scans for them. You can create an aboutus.upphtml or a contact.upphtml file for example to generate an aboutus.html or a contact.html page.

For further customizations you can always modify your ./bin/mkws or ./share/l.upphtml files, in fact, it's recommended.

Templates

mkws uses *.upphtml files as templates which are processed via pp, a preprocessor that allows embedding sh code in files of any type by nesting it inside the #!\n token, where \n is a new line.

As an example, for the following code:

<ul>
#!
i=1
while test $i -le 10
do
if test $((i % 2)) -eq 0
then
#!
	<li class=even>$i</li>
#!
else
#!
	<li class=odd>$i</li>
#!
fi
i=$((i + 1))
done
#!
</ul>

pp outputs:

<ul>
        <li class=odd>1</li>
        <li class=even>2</li>
        <li class=odd>3</li>
        <li class=even>4</li>
        <li class=odd>5</li>
        <li class=even>6</li>
        <li class=odd>7</li>
        <li class=even>8</li>
        <li class=odd>9</li>
        <li class=even>10</li>
</ul>

This means you can script your templates in any way you prefer using preferably, standard UNIX tools for portability reasons.

Note

Because pp uses sh internally, double quotes (") must be escaped in templates, so to get an actual double quote (") you have to write \".

This isn't a problem for HTML because quoting attribute values is optional and double quotes and single quotes are interchangeable. We recommend not quoting attribute values and using single quotes (') in special cases.

So instead of:

<!doctype html>
<html lang="en">

<head>

<title>My website</title>

<meta charset="UTF-8">
<meta name="viewport" content="width=device-width">

you would write:

<!doctype html>
<html lang=en>

<head>

<title>My website</title>

<meta charset=UTF-8>
<meta name=viewport content='width=device-width'>

Recommended Books

Download

mkws@4.0.9.tgz

The package contains a Linux amd64 pp statically compiled binary, the mkws sh script, the base theme and lmt from lts. mkws-openbsd@4.0.9.tgz. is the OpenBSD binary version.

Deploy to Netlify Deploy to Vercel

Sources

mkws@4.0.9.tgz: The main mkws sh script
base@3.0.1.tgz: Base files for a theme, you can use it to make your own theme
pp@1.0.9.tgz: pp, the POSIX sh preprocessor
lts@0.1.2.tgz: File time data