umi

umi is a very basic static site generator. It's not perfect, but it does a decent enough job that I haven't abandoned it yet.

umi makes use of HTML files and HTML templates to create sites. These HTML templates are currently a bit limited (there is no conditional syntax or text-replacement), but there are plans to expand on them a little.

To run umi, you only need a Python installation. Preferrably Python 3, however, there is still support for Python 2 (until April 2027).

Download & Install

I'd recommend cloning the entire umi git repository as this includes the documentation. However, there are alternative ways.

git

Either install git and run git clone https://codeberg.org/supercell/umi, or directly download the git repository and extract the archive (.zip, .tar.gz).

These "installation" steps only apply for POSIX systems, including OS X. Find a directory in your PATH that you have permission to write and execute from, and then create a symbolic link.

# find a directory you can write/execute to/from.
printf "%s\n" "$PATH"
# if you can't find a directory, try this:
mkdir $HOME/.local && mkdir $HOME/.local/bin
printf "export PATH="$PATH:$HOME/.local/bin\n" >> $HOME/.profile

# I'll use the directory we created above as an example, just replace
# the path with your own one.
chmod u+x ~/path/to/umi-directory/umi.py
ln -s ~/path/to/umi-directory/umi.py ~/.local/bin/umi

At some point I may make a script to automate this part, but if you have any issues feel free to ask me for help.

Directly Downloading umi.py

If you don't want the documentation/example site, then you can just download the umi.py file itself, then follow the steps above for finding a directory you can write to and execute from.

History

umi was originally created to just be a simple static site generator that didn't use any third-party libraries or programs. So far, this has held true! It has changed a little since the beginning, and there is still a lot to tidy up and smooth out, but I'm hoping that the code is somewhat easier to modify due to a self-imposed restriction of only one file for umi.

One of the main purposes of being a "simple static site generator" was that people could edit the file to fit their needs with little hassle. Something that is straight forward in how it works so it can be fully read and understood in a short amount of time (of course, this can vary between people and their experience, but hopefully you get the idea).

In February 2024, umi was improved to only re-write the files that have been updated since last run. This reduces the time required to build sites, for example, this site takes less than 60ms to build when content has changed. It's not perfect yet, since it doesn't register template updates, but that is planned.

Future

There are still a few things missing from umi before I'd call it complete (for my needs). Thankfully, this hasn't changed too much since the beginning so the only blocker on implementing them has been myself. The following sections will talk about what I'd like to change or implement. There is no particular order.

Making use of HTML attributes when using templates: The attributes would act like variables, which the template could use somewhere, and the page that includes the template supplies the name="value".
Code Readability: The never ending goal. As stated in the History section, umi is designed to be simple to hack on. So improvements to comments, variable naming, and a general cleanup.
Rebuild files if template updated: While umi will only rebuild files in your "content" directory if they've been updated since last build, it doesn't rebuild files if the templates they use have been modified.
Neocities Intergration: While this is a very personal need, it would be very helpful to be able to upload files via the CLI. Just need to implement the above "Rebuild if template updated", then work can begin on this.

Last updated: 2024-03-18