diff -urP mkws/4.0.14/mkws/README mkws/4.0.15/mkws/README
--- mkws/4.0.14/mkws/README Tue Sep 14 22:00:12 2021
+++ mkws/4.0.15/mkws/README Tue Oct 5 23:08:56 2021
@@ -4,9 +4,9 @@
## Requirements
-We provide binaries for [Linux](https://mkws.sh/mkws@4.0.14.tgz),
-[macOS](https://mkws.sh/mkws-darwin@4.0.14.tgz),
-or [OpenBSD](mkws-openbsd@4.0.14.tgz). It can also run on
+We provide binaries for [Linux](https://mkws.sh/mkws@4.0.15.tgz),
+[macOS](https://mkws.sh/mkws-darwin@4.0.15.tgz),
+or [OpenBSD](mkws-openbsd@4.0.15.tgz). It can also run on
[Windows](https://www.microsoft.com/windows) via the
[Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10)
for other UNIX like operating systems, you
@@ -15,14 +15,14 @@
## Install `mkws`
On a Linux machine, just download the archive from
-[https://mkws.sh/mkws@4.0.14.tgz](https://mkws.sh/mkws@4.0.14.tgz) or in
+[https://mkws.sh/mkws@4.0.15.tgz](https://mkws.sh/mkws@4.0.15.tgz) or in
the terminal, assuming `curl` is installed, type:
- curl -so - https://mkws.sh/mkws@4.0.14.tgz | tar -xzvf -
+ curl -so - https://mkws.sh/mkws@4.0.15.tgz | tar -xzvf -
On macOS, the command would be:
- curl -so - https://mkws.sh/mkws-darwin@4.0.14.tgz | tar -xzvf -
+ curl -so - https://mkws.sh/mkws-darwin@4.0.15.tgz | tar -xzvf -
## Generate the Static Site
@@ -173,6 +173,187 @@
<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](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](https://mkws.sh/https/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](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](https://en.wikipedia.org/wiki/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](https://eradman.com/entrproject/), get
+[live.js](https://livejs.com/), 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](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`](https://github.com/Gottox/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](https://github.com/commonmark/cmark),
+[lowdown](https://github.com/kristapsdz/lowdown)
+[Orc](https://github.com/Orc/discount).
+
+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:
@@ -253,8 +434,8 @@
* `./share/man`
`man` pages
- * `./share/s.upcss`
+ * `./share/s.uppcss`
`CSS` template. It's also processed via
[`pp`](https://mkws.sh/pp.html) so it's scriptable via `sh` code.
* `./share/sitemap.uppxml`
- `sitemap.xml` template.
+`sitemap.xml` template.