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
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, 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 viapp
so it's scriptable viash
code. -
./share/sitemap.uppxml
sitemap.xml
template.
-
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.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 POSIXsh
preprocessor - lts@0.1.4.tgz
-
File time data