mkws plus blog

it's mkws, plus a blog

mkws plus blog is a minimal (but highly extensible) terminal-based static site generator that turns unprocessed text files into HTML for a website. For more information on how mkws works, check the docs. mkws is developed by Adrian Emil Grigore.

mkws plus blog only changes the shell script, mkws. It adds an auto-populating blog page and a basic RSS feed. Because it's designed for my personal use, the workflow is (currently) slightly quirky. Please read this fully before using it. If you want to see a website that uses mkws plus blog, please visit Rust Red River.

Prerequisites

• A shell processor. I have only tested this on a UNIX system (Linux) but see no reason it would break on BSD or even MacOS. Windows users may see their mileage vary, but if you can run sh or similar then this should work.

That's it. I would also recommend a good markdown setup to make blogging even easier but that is not required.

Setup

1. Download the repo as a zip and extracts its contents to a folder.
2. You can now run bin/mkws example_website_name to make a basic website.

Using mkws plus blog

To make a new page on your website, make a .upphtml file in the root directory of your website (where your top level index.upphtml lives). If you want to make a new blog post, make a .upphtml file in the blog subdirectory. mkws will render these files within a template defined by share/l.upphtml. If you want to add elements to all of your pages (like nav and footers) then edit the share/l.upphtml file.

Do not make a .upphtml file for your blog index. The blog index is autogenerated from preamble.txt, which is where you should make any edits specific to the blog index. preamble.txt will have all of your blog posts automatically appended below. mkws plus blog does not currently allow you to add a "postamble" i.e. any non-template html content below the blog index, but this may change in future releases.

To make the html files for your actual site, run the command bin/mkws <your domain name here>. This will run the mkws shell script and process your .upphtml files. Your full static site will be found in the output subdirectory.

To style your site, you can edit/replace share/s.uppcss. mkws will write the whole contents of share/s.uppcss to a <style> tag within each page of your site.

Blogging Workflow

mkws plus blog expects three things of your blog posts out of the box.

1. The <h1> tag contains your blog post name.
2. The <h1> tag contains your blog post publication date separated from your blog post name by a | character and a space either side (this is for the RSS feed).
3. The <h2> tag contains your blog post short description.

Blog posts are made in the blog directory. Each post is an upphtml file in line with how mkws normally works. I recommend tagging your posts with the datestamp as the first part of the filename in YYYYMMDD format, which will make your feed chronological.

mkws plus blog will generate your blog post links from your blog post filenames. It is highly recommended each blog post has a unique name that does not contain sensitive information.

mkws plus blog is set up to copy everything you have in the assets folder to the output folder in a separate assets folder. This provides an easy place to store images, videos, and other files you may want to embed into your pages from across the site. Here is an example usage of the assets folder.

<img src="/assets/image.jpg" alt="an image I keep in my assets folder">

Customising

Like mkws, plus blog is fully scriptable. Edit the mwks file to change the behaviour of the programme. Good places to start may include

• Changing the separator for the date and blog post title
• Changing the name of your blog to something like "posts"
• Doing something different with the assets folder

Maximising .upphtml files

You can do some pretty cool things with .upphtml files. With a terminal-based markdown parser like cmark, you could write

#!
	cmark file.md
#!

This will take the output from cmark file.md, which is typically html text, and dump it straight into the html file when it's processed. You can run any command that you would use in the terminal in a .upphtml file to generate text.

robots.txt

mkws plus blog comes with a blank robots.txt file. It will copy this into the output folder. If you want to avoid crawlers, populate this file (and hope that the crawlers respect it).

If you want to avoid many of the AI/LLM crawlers that are operating today, this repo can help you.

Contribute

The mkws developer likes to see websites built with mkws. You can find my contact details on Rust Red River, and send me your blogs.