A New Website For A New Age


Hey. It's been a while.

I'm gonna be honest, my primary reason for the neglect is just laziness. I mean, I did have a pretty big stretch where I worked full time on making an engine in C++ for a game I planned to sell, so I've been doing stuff, just not here, and generally not publicly, and I plan to change that.

Or rather, I've already done so to some extent, given that you're reading this, and seeing it on the new website.

Previously, I noted with some degree of smugness that I wrote the website in raw, hand-designed HTML, so it may come as some surprise that I've opted to use Pelican, a python-based static site generator, to generate the site for me from some much-simplified markdown.

Why?

Because flexing with HTML is like posting a selfie in which you're lifing a 10 pound weight. I mean, yeah, it's a flex, but if that's what you're showing off with, you should be thinking about what kind of person you are. Also, I found that the amount of fiddling required by raw html introduced so much friction to the process that I put off updating the site effectively forever.

In an attempt to solve that, at one point I added Drupal to my site to run the blog. It did make it somewhat easier to write blog posts, but it introduced a big design disconnect between the pages for the projects and the blog, and I got enormous amounts of automated comment spam.

Let's take a moment to step back though, the site exists primarily to put the projects on, and secondarily to put the blog on. If what I'm doing as a developer isn't doing that efficiently, I'm dumb.

Having had some exposure to Drupal, I came to the conclusion that content management systems are more trouble than they're worth, especially if you're not on a team, and if code doesn't terrify you in the first place.

So, since that path to website success is out because it's on the high side of abstraction from the html, and just doing html itself is too close to the swamp that is web development, we're looking for something in between.

Enter Pelican

Pelican strikes a pretty nifty middle ground; it's clearly targetted at developers, but the number of angle brackets you'll be writing is hovering around zero, because you write most everything on the site in a simple markup language like markdown or restructured text, and Pelican takes that and generates nicely-styled html in a theme of your choice.

The Journey

Pelican is good, and I'd certainly recommend it, but I did have a bit of a journey with it...

It's Great!

The themes in pelican are made in something called Jinja, a generalized text template engine, which in this case is used to plug bits of html together. When writing the vast majority of content, you don't have to worry about that, but if you want to configure the theme of the site to change how it's skin looks, you have pretty good access to the raw html, which means we don't need to worry about that, but if you're picky, you absolutely can dip into the swamp without much friction.

There's a big number of available themes, and quite a few plugins as well.

It doesn't have very strong opinions about how you organize your content (it does have some, but they're reasonable), and there's a python config file that integrates with your theme, which helps enforce the walls between things that should be in a config, things that should be in your theme, and things that should be in the content. It's easy, especially working with the web, to get those walls in the wrong spot, and Pelican seems to do it relatively well.

Speaking of content, you really don't need to put hardly any code in your content at all. If you're using markdown, other than a handful of metadata tags (written and update time, tags, a summary) at the top, the ratio of content to markup is really good. That said, if you're used to the freedom of hand-coded html, the things you can do in markdown will feel limited, but I found that, for the most part, could compromise and still be happy with it.

The Honeymoon Ended

Pelican is nice, but there's always that point where you hit something your automagical tech can't do, or can do, just poorly. Unfortunately for pelican, that was pretty quickly; you see, Pelican calls itself a static site generator, but, at least out of the box, it's really not, it's a static blog generator. There are features in place to make non-blog pages that don't follow exactly the same theme, but I made my first non-blog article page, and realized every one of them is going to show up in the header.

K. So I fixed that, and decided I'd try some themes. I go browsing their theme repository - singular - they're all in one giant git repository, which is an epically bad idea. They are changing it, but why would you ever do that in the first place? Whatever, that's fine, but then the first theme I tried had a syntax error. The second theme looked very little like the screenshots. I did eventually find one that worked, but was a bit baffled to find that it didn't even bother to look at the social links or header info I had just fixed in my config.

Turns out the theme (the templates, to be specific, but those come with the theme) controls alot of what is and isn't actually relevant in the config, and there's (close to) zero standardization. Honestly, there's a case to be made that this is fine; it lets you make pelican into something that isn't just a blog generator, assuming you learn the system, but that has consequences: You can't drag and drop themes. You swap it out, and then you have to figure it out in order to configure it - because there's very few themes that have any documentation of any kind.

While these things honestly aren't too bad, I have to imagine basically everyone will encounter most of this, unless you're happy with the default theme, and the default structure of your site. In my experience, it's not whether you will encounter something your tech can't do in a way you'd want, it's when, but that time for Pelican was about an hour, which is awfully quick.

Oh, that's what it's doing

I realized they actually did well with it when I was fighting against the plugin to make the photo gallery mechanism work. You can see it in action on the pages for the projects that have screenshots, and if I ever make a blog post that needs a photo gallery. The plugin, which I realize now is actually quite good, actually does very little for you on the surface. This was a bit strange, when what you're expecting is a drop in photo gallery, but I persevered regardless, and went ahead and modified my theme to include some of the code they present as an example. Their examples were quite useful, but it was essentially requiring me to understand the engine that made my site run, and while I didn't enjoy that, as a developer, that requirement is pretty common. Learning many libraries, tools and technologies in programming often requires reading the minds of the developers. Once you're in that mode, and you have to solve the problem of making Pelican work along with the developers, you have to realize what it's actually trying to do. It isn't trying to make "Wordpress but you can tweak it at the html level", it's really trying to be a somewhat specialized, but still relatively general code generator.

As a side note, that common requirement that developers who have standards essentially reverse engineer all the tools they use may be a sign that our profession is in it's infancy, but that's a discussion for another time.

Once you realize what it's really doing, it's really kindof dumb to start complaining that your plugins and theme requires too much manual intervention. Pelican isn't a glorified lego solution, in which you snap bits of website together, it's a tool to make your life easier as a developer. If you work with it, you will still need to get your hands dirty a bit, but it does accomplish the goal of being a website generation tool pretty effectively. You might have to learn jinja and change some stuff in your theme yourself, but if you're being a developer, and not a lego builder, it does plenty of work for you.

It's good

Like I said at the beginning, Pelican is good when framed the right way. I'd definitely recommend it if that section above doesn't scare you off. It keeps a nice division between the content and the delivery mechanism, makes both pieces pretty easy to work on separately, and it does what it's supposed to do pretty well. There's critiques I've made, but honestly they did well with it.

I'll be using pelican for the forseeable future.

The Future!

You'll notice, just by scrolling around on this blog post, that there's no comments. That's partially a consequence of Pelican spitting out static html, but there is a Disqus plugin which will put javascript-based commenting functionality on the website. The fact that it's not on here was conscious. First of all, I hear Disqus isn't super friendly, but I'm unconvinced comments are a good idea to include anyway.

Back in Web 2.0 days, at the dawn of social media, comments were on everything: blogs, photo gallerys (anyone remember flikr?), videos, etc. Anyone can comment anything! democratization of the internet!

And then we all realized that anyone could just comment anything. You ever been to the youtube comment section these days?

Now, I know most people that will even find my site (let alone actually read it) because if their willingness to venture outside of facebook, will tend to output comments of a higher quality than those you see on the average youtube video, but in all the time I've had the option of having comments, all I've ever gotten is confirmation that a friend read the article (once), and spam. Mostly spam.

So comments are gone. If you want to talk about the article, do feel free to reach out to me on social media - the links are up in the header for a reason.

I have more ideas for blog posts I'd like to make, and already have some in the pipes, and since the site's now even easier to work on as a whole, I'm expecting more content out of this blog.

And, since I've been through the journey to learn Pelican's innards, I'm reasonably excited to make a theme of my own. If you remember the old look of the site as it was before the age of Pelican, this one is positively boring by comparison. It does look like it wasn't designed by a 14 year old, which is a plus, but if I make a new theme, it'll very likely be more visually interesting. I may have to work on not making it look stupid as a consequence, but that's a project for the future.