Comment by klodolph | Hacker News Reader

Comment by klodolph | Hacker News Reader

"Boring" is nice although my experience with Hugo is that it takes a nontrivial amount of effort to get it working in the first place, such that I couldn't use it for putting project documentation on github.io and definitely wouldn't call it "boring" in the sense used in the article. It is definitely a more complex scheme even if that complexity is front-loaded and you get to keep everything boring on the server and the client (with the exception of MathJax, for good reasons). (Aside: consider Katex!)

With Hugo, I ended up fighting with themes that wouldn't render correctly, and all the mess that is shortcodes. Shortcodes are nice in theory, but there should be a larger set of "standard" shortcodes that are expected to work across most themes (some nice subset of what Bootstrap gives you) and instead of custom syntax, it seems like you should be able to use standard HTML with custom tags.

Anyway... my experience with Hugo made me feel that I would even have an easier time wrangling a Wordpress installation. It's equally possible to archive a Wordpress site by taking a snapshot of the HTML, and I've done it, it's just that the "boring" web (as the author puts it) moves the failure points to your personal computer, rather than the server you run your site on.

Hugo/Jekyll were thoroughly overkill for my little blog, so I went looking at the absolute simplest static site generators I could find (with a minor preference for something written in rust). I landed on Zola, and hand-coded myself a set of templates. It has been working out pretty well.

Hugo is just one of an incredibly large number of options to help you generate your static website.

This list should have something for everyone: https://jamstack.org/generators/

There are so many options because creating a simple site generator is actually almost trivial, given there are great markdown-to-html converters, code highlighting libraries etc. that do the hard work for you already.

My own websites are all written in markdown using a little Go framework I wrote myself. Extremely simple, does exactly what I need, has none of the Hugo complexity (Hugo started simple as well but kind of added too many features over time). Highly recommend doing this for anyone who enjoy programming and writing their own tools.

https://getpublii.com is a great free, open-source option for less-technical users who want to generate a static blog that can be deployed to any web host (or Cloudflare Pages, Github Pages, Netlify, AWS, etc)

Jekyll. That's the boring static site generator.

I might give Jekyll another shot, then.

I’m a big Jekyll fan too.

If that’s not to your liking I guess you could try pandoc and make.

I’m also a fan of vimwiki, but I guess you have to like vim for that.

Do it! I'm also currently migrating my old Wordpress blog to markdown in Jekyll using a minimalist theme [1]. I'm liking it so far.

[1] https://github.com/riggraz/no-style-please

I scripted up a dumb little Python+Jinja transformer with a dumb yaml file for vars. Its like 50 lines of code. Ifs really boring. I also use a little pandoc in my build script

I have to admit that I found Hugo easier to work with from scratch. I am not used to working with Ruby, so I found setting up Jekyll to be quite an adventure... (now, truth be told, using GitHub to build my pages is definitely easier than having to use my own server with Hugo, but the _initial_ configuration of Jekyll appeared to be more complex for me)

What's the boring-est way to run Jekyll locally? My main problem with Jekyll is that it required installing (and keeping up to date, I assume) a Ruby environment.

You could leave that to Github Pages, if you have basic requirements. (no extra plugins)

That’s worth mentioning, but I was looking to run the static site generator locally because the workflow of committing to Git, waiting for a build, etc. is too slow for iterating (and also difficult to debug when stuff inevitably doesn’t work as expected).

Yes, please use https://katex.org instead of MathJax.

KaTeX does not support LaTeX commands like \label, \eqref, \notag, etc. As long as one does not need them, KaTeX is good. But if one needs them, MathJax becomes necessary.

I often do need these commands, especially while writing proofs, solutions, or long mathematical posts. See https://susam.net/blog/integrating-factor.html for an example. These commands make it convenient to refer to previous results using equation labels and numbers in long articles.

One can work around the missing support for these commands in KaTeX by writing their own HTML to simulate the same functionality but it is nice to have MathJax do this for us automatically.

Looks great, hadn't heard of KaTeX before.

Basic question: does it share any code in common with MathJax? If not, why not just run MathJax once server-side rather than on the client? Does MathJax have browser-specific accommodations, or does it not map to HTML at all, or is it something else?

Both MathJax and KaTeX let you run once server-side, if that's your fancy.

They map to a combination of HTML and MathML, with a bunch of CSS rules.

KaTeX's JavaScript code is a mere 68 KB when gzipped. IMO, that's worth it, so I don't have to fuss about with Node.js as much when generating the site.

Looks awesome, definitely giving it a try. Thanks!

I like Hugo and made my personal website with it because: 1. It's supported on most free hosting like netlify.app (I use fleek.co for ipfs support) 2. It allows me to do anything I can do without it in a very similar way just with added templating, handling navigation, etc 3. I didn't know or care to look for comparable alternatives when I started using it and know I'm too invested in after making my own theme and converting all my wordpress to markdown with the added Hugo cherries on top

Yeah for a one-person personal site Hugo seems like overkill.

For a site that is just a collection of static pages, I think it's just as easy to write directly in HTML. HTML is no more difficult than learning some other markup language, especially if you have an editor that helps you.

Hugo and others help with things like autogeneratings tags and sidebars, that sort of thing.

It may be overkill at first, but run a site for long enough, and the static generator starts to make a lot of sense.

I originally had static HTML, but that was well over 10 years ago at this point. Soon you want to wrap your pages with a template to get rid of boilerplate and keep your site consistent. Then you want auto-generated indexes, and maybe you want to check for broken links, add width/height to <img> tags, etc.

My personal website has hundreds of pages on it, not counting the auto-generated index pages. Automation is a necessity at this point. It is still written in HTML... I never adopted anything like Markdown, and I've abandoned any use of custom syntax like Hugo's or various templating systems, at least, outside the static site generator code itself.

The problem with straight HTML, as opposed to one of the markdown-to-HTML pipelines, is that if you want to change something, it's really difficult (bordering on impossible, depending on how consistent you've been).

I migrated my blog a year and change back from Blogger to self hosted Jekyll (a rather consistent theme on this post...), and having the content, the "scaffolding" (HTML templates and such), and the render pipeline being separate means that it's trivial to change things if I want to.

As a recent example, I realized a few months back that my blog didn't render at all with Javascript disabled. That's not OK to me (it was a quirk of how the template I bought did a "gradual fade in" once the content was loaded - looks good, requires JS, I do not care about that sort of thing). To eliminate JS requirements, I had to eliminate that fade, and I had to change image embedding for a lot of things such that it didn't use lazy load - there was some JS based lazy load that meant post thumbnails and such didn't load. All I had to do was change the templates, re-render, and re-upload the site (I rsync stuff up). That would be harder to change in HTML.

The same goes for images and such. I end up with several versions of each image used - if your browser supports picture sets, it will "pick the best" based on what the browser thinks is reasonable, in terms of size and formats. I currently render to a few different resolutions of jpg (or png) and webp from the original source images. If I want to change that, add a new resolution, or add a new format, I just update a config file, re-render, and I'm done. That sort of thing helps with keeping the site "modern," if you care about it.

For an absolutely basic "few pages" site, sure, you can do HTML. But for anything with regularly updated content (I have ~260 blog posts and nearly 6000 images), it's well worth having some helpers to separate content from layout/formatting/features/etc. Despite that, it's still very much a personal only site, I'm the only author, it (now) renders without JS, sets no cookies, etc.

FWIW you can use any SGML processor to separate-out boilerplate from content files using entities (text macros), and more advanced forms of HTML templating. Makes sense since HTML itself, originally conceived as an SGML vocabulary, lacks these authoring features since present in the larger SGML context/toolchain. You can also typecheck your documents and even format markdown into HTML using SGML's SHORTREF feature; checkout [1].

[1]: http://sgmjs.net (my site)

Reply on news.ycombinator.com