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
andsitemap.xml
files.-
./bin
Holds the static site generator's binaries, they're used to generate the static site../bin/lmt
Small utility part oflts
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 viapp
and renders them inside theshare/l.upphtml
layout file outputing anHTML
file for each one.index.upphtml
is transformed toindex.html
,docs.upphtml
is transformed todocs.html
, etc. It also creates the mainCSS
file,s.css
fromshare/s.uppcss
and thesitemap.xml
file fromshare/sitemap.uppxml
../bin/pp
Thepp
preprocessor, it allows nestingsh
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 likehtml
,body
,head
are located here. The standard layout file found in the archive, which is also part of thebase
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 viapp
so it's scriptable viash
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'>
Download
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.8.tgz.
is the OpenBSD binary version.
Deploy to Netlify Deploy to Vercel
Sources
- mkws@4.0.8.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 POSIXsh
preprocessor - lts@0.1.2.tgz
-
File time data