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.