April 7, 2017

endless static site fights

After a bit of messing around, completely nuking the old site (GH pages Jekyll setup), putting up silly 10mb ascii art index.html files and writing raytracers...

I admitted to myself using ruby on windows flat out stinks. Like many other open source, *nix rooted things, and I know it's not the project's fault. I have a few linux machines but my desktop is still my primary means of typing loudly while filling out markdown files pretending to program.

I switched to using pelican to generate the site myself and commit and it works great. All I need installed on windows is python and can install the rest with pip, no fuss whatsoever, including pygments.

I always thought static site generators tend to kill themselves on feature rot and losing focus, and I can't help but think others agree after seeing sites dedicated to tracking the various static site gen tools that are constantly cropping up. Take a look at staticgen for example!

However, I'm all in on pelican now. I don't care about having lots of themes to pick from, etc it works great locally and the mechanics are simple to follow and debug.

At work, I've been trying to generate a simple docs site alongside development of a greenfield project, I initially picked hugo because the project is using golang as well, and that works OK enough. I have hit huge friction trying to coerce the few documentation-style themes that aren't awful into what we want though. I will likely be giving sphinx and mkdocs a try.

It's a bummer because all I really just need a list of REST endpoints with input, output, like

PUT /foo/bar ... json body

.. expected response

One benefit of using python based generators is sitting down and creating a partial/template/wahtever they rename it in their version of the same tool, it can be more easily reused. For example Jinja2 is used across many of them so if I made a nice REST endpoint doc fragment, I could try a few different generators.

nonsense site static jekyll pelican

Previous post
Rooting steamlink pt1 This is a first in a multi-part series on digging into the steam link software and hardware. I'm hesitant to call it 'reverse engineering' because
Next post
Cross platform gradle npm builds This is a quick and dirty one, mostly so I dont forget to write down something painful I had to do recently. If you use node npm in a gradle build