oscarbenedito.com - Source code for my personal website. git clone https://git.oscarbenedito.com/oscarbenedito.com

About | Log | Files | Refs | Submodules | License | Contribute

2020-09-27-switching-to-own-ssg.html (10255B) - raw

---

 <!-- title: Switching to my own static site generator -->
 <!-- slug: switching-to-own-ssg -->
 <!-- categories: FOSS, Personal domain, Projects -->
 <!-- date: 2020-09-27T16:27:00Z -->
 
 <p>
   Since the start of this website (its first anniversary was a couple of weeks ago!) until recently,
   I have been using the static site generator <a href="https://gohugo.io">Hugo</a>. Static site
   generators are very useful when building relatively complex static websites, and Hugo has served
   me well. I have also used <a href="https://www.getlektor.com">Lektor</a> and <a
   href="https://jekyllrb.com">Jekyll</a> before for other projects, but for a site with a blog, I
   like Hugo the most. However, with time, some issues have arisen with Hugo, and I finally decided
   to change my site's generator.</p>
 <!-- /p -->
 
 <h2>Issues with Hugo</h2>
 
 <p>
   If you build your website with a static site generator, it will probably be the most critical
   dependency of your site. Of course, it's a dependency I'm fine with as it makes things much easier
   (dealing with Markdown content, categories, web feeds...), but if something goes wrong, the site
   won't render as you want. Hugo in particular is a very big project and I don't feel like jumping
   into the source code every time I have an issue with the program (especially since I've never used
   Go, and I don't want to spend hours for minor annoyances). Although Hugo works wonderfully, I have
   encountered moments where it has acted unpredictably, and documentation doesn't help most of the
   time.</p>
 <!-- /p -->
 
 <p>
   On top of that, although it works perfectly well (and it is one of the most popular SSGs), it is
   on a beta stage and the developers have made backward-incompatible changes without warning in the
   past. The change I have in mind was clearly stated on the release page, but I normally let my
   package manager handle the updates, and I want my computer to keep working correctly (or throw big
   red warnings all over the place). In this case, HTML inside Markdown files stopped rendering, and
   I only found out coincidentally a couple of weeks later as the web feed was not valid anymore.
   From that moment on, I started checking the release notes for every update (which are frequent,
   about once a week), but it was an annoying routine.</p>
 <!-- /p -->
 
 <p>
   I understand that the program is in beta and it was on me to check for breaking changes, but to be
   fair, Hugo is marketed as a fully functional program (as if it wasn't on a beta stage) on the
   official website. Considering my last issue, this was concerning and ended up creating uncertainty
   on the stability of Hugo and the transparency of the developers, so I decided to change my site
   generator.</p>
 <!-- /p -->
 
 <h2>Taking the leap</h2>
 
 <p>
   I wanted to move to something lightweight that could still be useful in a few years' time, ideally
   a program that was easy to understand and maintain. The problem was that I had some very specific
   needs that small programs didn't fulfill, leaving only big programs as an option (which I didn't
   want to use). I thought of the possibility of creating my own site generator, but it looked like a
   large task I didn't want to spend my time on. Hugo was working fine, and although I kept looking
   up other SSGs when I discovered them, I stopped actively looking for alternatives or thinking
   about designing my own.</p>
 <!-- /p -->
 
 <p>
   Until the night of the 5th of September, when I came across <a
   href="https://github.com/sunainapai/makesite">makesite.py</a>. This project was just perfect, and
   I couldn't resist. Let me show you an extract of the README:</p>
 <!-- /p -->
 
 <blockquote>
   <p>Have you used a popular static site generator like Jekyll to generate your blog?</p>
 </blockquote>
 
 <p>Yes...</p>
 
 <blockquote>
   <p>
     I have too. It is simple and great. But then did you yearn to use something even simpler to
     generate your blog? Do you like Python? Perhaps the thought of writing your own static site
     generator crossed your mind but you thought it would be too much work?</p>
   <!-- /p -->
 </blockquote>
 
 <p>Yes, yes, and definitely yes!</p>
 
 <blockquote>
   <p>If you answered "yes" to these questions, then this project is for you.</p>
 </blockquote>
 
 <p>
   Nice! That night I read the README and the source code (which is shorter than the README). The
   program is very simple and a lot of the basic functionality I needed out of a static site
   generator was already there. On top of that, it didn't use any non-standard Python library except
   for the Markdown parser. I really liked the project and I thought it could be the foundation of my
   personal static site generator.</p>
 <!-- /p -->
 
 <p>
   It was. The next morning, I started coding to make it usable for my website. I had to implement
   many new features, but with Python it was <a href="https://xkcd.com/353/">easy and fun</a>. After
   two days of working on it, I finally released my site using a personal fork of makesite.py,
   <a href="https://git.oscarbenedito.com/oscarbenedito.com/file/gensite.py.html">gensite.py</a>!</p>
 <!-- /p -->
 
 <h2>The new benefits</h2>
 
 <p>
   So, why change the SSG if Hugo was working fine? As I said, I've had my issues with Hugo, and I
   don't want to be forced to leave my static site generator if more arise in the future. I don't
   know if I'll be able to switch SSGs when (and if) the time comes, and now I have the time and
   motivation needed to do it, so I decided to take the chance while it was there. On top of that,
   <em>gensite.py</em> is not only my "way out of Hugo", it is a program that has many features that
   could have made me do the change without having any troubles with the last SSG.</p>
 <!-- /p -->
 
 <p>
   First of all, the program is very small, it's only about 270 lines of code and it's written in
   Python. That makes it very easy for me to read and understand the whole program very quickly, even
   if I have completely forgotten everything about it. Obviously, this doesn't count the lines of
   code of the libraries it depends on, but those are all standard libraries and the functions are
   easy to understand, except for the Markdown parser, but if that ever gives me any trouble I can
   change it without much effort.</p>
 <!-- /p -->
 
 <p>
   Since <em>gensite.py</em> is made exclusively for my website, it is more closely tied to the rest
   of my site. For example, it doesn't have a complex template engine, instead, templates only
   process the following two snippets:</p>
 <!-- /p -->
 
 <ul>
   <li><code>{{ var }}</code>: substitutes the string for the value of variable <code>var</code>.</li>
   <li>
     <code>{{ _if var }}text{{ _fi }}</code>: will render the text <code>text</code> if variable
     <code>var</code> is defined. You can't have an <code>_if</code> inside another.</li>
   <!-- /li -->
 </ul>
 
 <p>
   If I need anything more complex, I will use Python to create the text and pass it as a variable
   when rendering the template. I prefer this approach as it is a lot nicer to implement those
   features in Python than it is with a template engine. For some pages—for example, the
   archive—Python does some more heavy lifting and creates part of the HTML. This can sound weird in
   comparison with other static site generators, where HTML is only dealt with in the template files,
   but it makes things simpler, and I no longer need hacky templates to create certain outputs.</p>
 <!-- /p -->
 
 <p>
   Moreover, I like the file structure a lot better (I designed it!), and if I ever want to change
   it, it shouldn't take long to do so. Similarly, any other design options are exactly as I want
   them to be, since it is me who decided them. In case it is not clear: everything works exactly as
   I want it to!</p>
 <!-- /p -->
 
 <p>
   Finally, it's a project that doesn't move too fast. One of the problems with websites is that
   links are easily broken: entities change their backend, run out of money, mess up an update, etc.
   and let their links break. Right now, I am pretty dedicated to my website, and if my SSG broke
   something on my website, I would spend the time to fix it, but I can't ensure I'll do the same in
   two or five years (and I don't want to break any links, even on the long term, but that's a post
   for another day). Unless something happens with Python, <em>gensite.py</em> will work and so will
   the generation of my website. There won't be any updates that break some random page or that
   change a certain behaviour<sup id="fnref1"><a href="#fn1">1</a></sup>. I hope <em>gensite.py</em>
   can stand the test of time, but we'll see...</p>
 <!-- /p -->
 
 <h2>Final comments</h2>
 
 <p>
   Forking <em>makesite.py</em> and setting up everything I needed for my website was very fun, but
   it is surely a process that not everyone will enjoy. I have lately been leaning towards software
   that is a simple as possible, software that is easy to understand and change if needed. It takes
   time to set up, but once it's working, you can forget about it (and if you need to make changes,
   they are quickly implemented) and you will have software that works exactly as you want it to. I
   am very meticulous about this website and try to have good control over everything that happens
   during the website's generation, and I couldn't be happier with <em>gensite.py</em>.</p>
 <!-- /p -->
 
 <p>
   On another note, I don't want to end this post without saying that Hugo has been a great static
   site generator, and I'd recommend it to anyone who wants to have a blog on a static website. In a
   new update with breaking changes, they did throw errors if the old feature was used, so maybe my
   experience wouldn't happen again. Just remember, it's still in beta.</p>
 <!-- /p -->
 
 <!-- footnotes -->
 <hr />
 
 <ol>
   <li id="fn1">
     Also, whenever I make changes to <em>gensite.py</em>, I can run <code>diff -r</code> to check
     for differences for the outputs before and after the update. With Hugo, many files changed
     without explanation (although it was mostly style choices, it made it hard to see the real
     changes in content between updates). <a href="#fnref1" title="Jump back to footnote 1 in the
     text">&#8617;</a></li>
   <!-- /li -->
 </ol>