Docs

`mkws`

A simple static site generator using sh as a templating language.

Requirements

We provide binaries for Linux and 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.16.tgz or in the terminal, assuming curl is installed, type:

curl -so - https://mkws.sh/mkws@4.0.16.tgz | tar -xzvf -

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, initial-scale=1'>

<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, initial-scale=1">

you would write:

<!doctype html>
<html lang=en>

<head>

<title>My website</title>

<meta charset=UTF-8>
<meta name=viewport content='width=device-width, initial-scale=1'>

How to customize `mkws`

Customization is done by editing the template (*.upp*) files in your mkws project, the ones you create yourself in the . directory, the themes files in ./share, ./share/l.upphtml, ./share/s.uppcss and ./share/sitemap.uppxml, and the main generating script in ./bin/mkws. You can also install additional utilities in the ./bin directory to enable new functionality.

Below are a few solutions to common problems.

How to output in a separate directory

A common practice static site generators use is to output the generated files in a separate directory, like out or public. mkws is designed to output its files in the current directory, along with the sources, it does hoewever have an option to specify to source path. So to output in a different directory than the sources one, you could do in your . directory:

mkdir htdocs
cd htdocs
../bin/mkws https://example.com ../

However, we do recommend distributing the .upp* files so other can people can read and learn from your code, like https://mkws.sh does at the bottom of the page.

How to preview your website

Some static site generators usually come bundled with an HTTP server, so you can run something like:

ssg -p 8080

and preview your site. mkws doesn't include a server by default, you can use any server you prefer, however we do provide the sources to a small server in Go: https.go. To install, in your web site's directory, do:

curl -so https.go https://mkws.sh/https/https.go
go build -o bin/https https.go
./bin/https

Open http://127.0.0.1:9000 in your browser to preview your website.

The server runs on port 9000 by default and uses the current directory as its root directory. It outputs a log to stdout in Common Log Format.

How to live reload

A nice feature when developing a web site, is to have the static site generator run whenever a source files has changed and reload the current page in the browser.

Assuming you installed our web server following the previous instructions, the recommended way to do this with mkws is to either install or compile entr, get live.js, in your web site's directory, do:

curl -so l.js https://livejs.com/live.js

Edit share/l.upphtml by adding:

#!
if test "$DEV" -eq 1
then
#!
<script src=/l.js></script>
#!
fi
#!

above the closing </body> tag.

Also:

cat <<EOF > bin/d
	#!/bin/sh -e

	export DEV=${DEV:-1}

	./bin/https &

	(
	echo ./bin/mkws
	find . -type f -name '*.upp*'
	) | entr sh -c 'bin/mkws https://example.com'
EOF
chmod +x bin/d

Run the development script:

./bin/d

And open http://127.0.0.1:9000 in your browser.

How to add a navigation menu

In order to add a navigation menu to your website, all you have to do is edit the ./share/l.upphtml file and add your navigation code there. Open up ./share/l.upphtml in your favorite text editor and add the following lines right below the body tag:

    <header>
        <nav>
                <ul>
                        <li><a href=/>Home</a></li>
                        <li><a href=docs.html>Docs</a></li>
                        <li><a href=src.html>Sources</a></li>
                </ul>
        </nav>
    </header>

Edit to match your website.

Then, regenerate your site using the mkws command:

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

How to add custom titles (or `meta` tags) for each page

As you can see, using ./share/l.upphtml to generate all our pages, means we have only one title tag for each page, hence all of our generated pages will have the same title. If we would prefer specific titles for each page, we would have to edit ./share/l.upphtml like in the following example:

<head>
#!
case "$1" in
./index.upphtml)
#!
<title>My Website</title>
<meta name=description content='Latest news about my website'>
#!
;;
./docs.upphtml)
#!
<title>Documentation</title>
<meta name=description content='Documentation for my website'>
#!
;;
./src.upphtml)
#!
<title>Sources</title>
<meta name=description content='Sources for my website'>
#!
;;
esac
#!
</head>

Edit to match your website.

Then, regenerate your site using the mkws command:

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

How to render `Markdown`

Rendering Markdown is not at hard at all. Our favorite CLI tool for rendering Markdown is smu. You'll have to download it and install it on your system either via source or your operating systems's package manager. In order to use it, just add:

#!
	smu <file>
#!

to any of your *.upphtml files or create a new *.upphtml files containing just the above code. Other Markdown renderders include cmark, lowdown Orc.

Future versions of mkws may allow rendering Markdown directly from source, without creating an extra *.upphtml file.

File Hierarchy

A typical mkws project has 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, initial-scale=1'>
 
 <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.uppcss CSS template. It's also processed via pp so it's scriptable via sh code.
- ./share/sitemap.uppxml sitemap.xml template.

Download

mkws@4.0.16.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.16.tgz is the OpenBSD binary version.

Sources

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