Juanse Marquez

JustOneScript - SSG

I've been working on a static site generator named JustOneScript-SSG, primarily focused on publishing blogs and other types of content-centric, regularly published sites.

Uso

We just write our post in a .md file, run python justonescript.py build and the site appears in the output directory. Nothing more (and nothing less) than that.

Why?

This idea came from the multiple adaptations I've been doing to my customized version of bashblog. Bashblog is a bash script that generates a static website from files written in markdown. It's just great, but I found some limitations regarding some aspects I wanted to implement, so I've been adding messy patches to bashblog, for many years.

The main features I needed to add were:

• Defining publication date. Bashblog takes as publication date the moment the file was last modified. That is not flexible enough for my need, sometimes I write stuff I want to publish in the future.
• Avoiding regenerating files that haven't changed. Why reprocessing what will yield the same output?
• I wanted to simplify detection of title and tags, having the flexibility of changing it later.
• Including a brief excerpt to be shown on the index page, and to be able of deciding if I wanted the exerpt repeated in the article.
• I also wanted to simplify the task of setting a cover image for the post, and an easy way of giving atribution to the image authors.
• Organizing all the post's metadata in the beggining, in a frontmatter, instead of parsing the whole text to find it.
• Making it configurable via a .config.py file, just defining Python variables.
• And I wanted all of the above without installing a framework, or pulling in a long list of dependencies. It generates a simple website, but it's simple on the author's computer as well.

Advantages

Contrasted to other SSG, I find some important advantages:

• No environment dependencies, nothing depends on a Node update or a plugin. It's just a script that depends only on standard and widespread Python packages.
• Generated HTML has no abstraction layers; if something fails, there is an only place to check.
• Up and running in milliseconds.
• Completely customizable. Each author can modify it without learning the internal convention of another project.
• The site is not attached to a platform or framework, we'll always have our markdown posts in a directory, that can be easily migrated to any other platform.
• Safe. Very safe. As any other SSG, the generated result is just a bunch of html and css files, and some javascript functions. No intrusions, since there is nothing to be intruded.
• Efficient. As a static site, there is no backend and no database. Uses very low CPU, and low bandwidth.
• The resulting site is compatible with free hosting platforms, like GitHub pages, for instance.

Disadvantages

Obviously, it has its disadvantages; depending on your particular use case:

• Managing javascript, css, etc. is 100% flexible, but that means that, if you prefer not using the default setup, you must manage it by yourself.
• No responsive image support: the generated site renders OK in mobile phones, tablets or computers, but the same image set is displayed in each version. Maybe not the best option if your site is heavily dependent on pictures. However, it works well for a text-centered website, that includes pictures as a secondary resource. (This is one of the features I'd like to implement asap).
• Not multilanguage: obviously, you can write in any language. But if you want your site to have, for example, an English version and a Spanish version, it's not a good option. Nikola, for instance, is very useful if this is your case.
• No "watch + hot reload" mode. That is, you cannot see a final version preview as your write. You have to save your .md file, build the site and see how it went. Obviously, you can build as many time as you need, and it's just a fraction of a second. But it's not automatic.
• There is no theme or template environment. You can do whatever you want regarding the visual aspect, but, if you are not using the default option, you have to generate CSS by yourself.

Intended Users

Using this script demands a base of technical knowledge. None of it is a secret and anyone can learn about it:

• Writing Markdown (you can teach yourself in half an hour).
• Using git (not mandatory, but useful).
• Being at least comfortable with a basic use of command line.
• Handling the deploying to a web server, SSG is agnostic about where you publish your site.

Tags: articulos, english, cultura-libre, tools, programacion, python

Compartir / Share