Skip to content

Instantly share code, notes, and snippets.

@warpfork

warpfork/static_site_roundup_2021.md

Last active November 27, 2021 08:45
Show Gist options
  • Save warpfork/79edc135e049f1c43142a7e14c8beb31 to your computer and use it in GitHub Desktop.
Save warpfork/79edc135e049f1c43142a7e14c8beb31 to your computer and use it in GitHub Desktop.
Download ZIP
Static Site Generator Roundup 2021
Raw
static_site_roundup_2021.md

Static Site Generator Roundup 2021

Criteria & Considerations

  • does it consume markdown?
  • is it fast?
    • (a "hello world" site should take milliseconds or less to build. Definitely not full seconds; certainly not multiple full seconds.)
  • is it reasonably shipped?
    • (defined as: can I download a binary and run the thing? litmus test: if I have to learn about the tool's language's build system, it's not reasonably shipped.)
  • can I have the content at the root of my github repo (so github's linking and the site linking aligns)?
    • (for some reason many tools in recent crops insist you have a "./content" dir, instead of putting themselves in a ".tool" dir, and this is unfortunate.)
  • does it compose sanely?
    • is the index page magical in any way?
    • how many files to I have to edit to create a new page?
      • (do I have to create a template for each new page? new directories? new top level directories? etc)
    • does it have "shortcode" features (or other simple composition)? (is it different than templating?)
    • if it has themes: is the override structure comprehensible and look like functions, or is it magical and "good luck"?
    • litmus test: how hard is it to build breadcrumbs based on simply the directory structure?
    • litmus test: how hard is it to build a site TOC (and customize it)?
      • how hard is it to build more than one TOC for separate subsections of the site?
        • could I render two distinct TOCs covering different subsets of the site... as sibling elements in one page?
        • (all of this should be trivial if there's a functional composition model, and will be impossible if there's a magic central feature trying to do these things.)
  • does it automatically generate in-page anchor links to headings?
  • if it has a syntax highlighting feature for code blocks... can it be configured without rebuilding the whole tool?
  • does it have a css preprocessor built in? (either less or sass)
  • is the output sane?
    • does the result still render in case of noscript?
    • does the output have the order of magnitude right size output, or is it full of crazy cruft?
    • is there anything behaviorally weird about it? (open ended question; it's amazing how special some tools can get.)

contenders

11ty

... is going to the top of the list, because I've started using it, and it works really well.

(following notes are rough and should be revisited; I was too satisified to actually finish a robust comparison.)

  • content:
    • collections were introduced before pagination.
      • THANK YOU. LORD.
    • collections appear to be completely nonmagical. you just define your own tags at will.
      • there's a builtin "all" collection. that's totally sane.
      • there's nothing magical about the word "blog".
      • there's no weird different thing for the root dir vs the first depth dirs vs subsequent depth dirs.
    • you can easily override any output path logic by using "permalink" properties.
      • these can also include templated content, including referring to other variables you set in the front matter, and so both very direct and very powerful.
      • a more general feature that applies here: you can configure front matter in layouts and templates, too -- which means: you can make a permalink pattern there, and fill in some values per file, and it all just works.
    • it does recursion sanely. (!!!)
      • check out the docs on the "Data Cascade"
      • and then even more specifically, the subpage about "directory data files".
      • it's exactly what you'd want and expect.
      • okay, there's one weird-ish exception: any data files in the root directory have to go in "_data".
        • I kind of wish they would've just made this symmetrically applicable to subdirs too?
          • e.g. "zas" got this right.
        • but, okay. It's... there's a decent excuse for this, at least. And it's not like the feature is missing, it's just mildly weird in one case. Fine. I can live with this.
        • the norm is "foobar/subdir/subdir.json" -- note the redundancy. I wish this had just been "foobar/subdir/.11tydata.json". sigh. Oh well. Minor.
    • I was confirmedly able to build both breadcrumb path links and a rich site ToC nav with minimal and reasonable effort.
  • heading links: missing by default :(
    • I was able to patch them in without too much madness. I think there was a plugin.
  • speed: less than a second for the empty site. this is acceptable.
  • output size: super trim. no bullshit. excellent.

General feel is that you can compose things here. Wherever I found something I wanted wasn't happening out-of-the-box, there was usually a plugin for it, and adding it and customizing it was easy. (I like this a lot better than starting with the kitchen sink and trying (often unsuccessfully) to trim things down, which is how a lot of these other things have gone.)

hugo

  • consumes markdown: yes
  • is fast: yes
  • is shipped: yes
  • can have content at root: not entirely clear. Maybe contentDir can be configured to . but I bet it'll barf somehow. Test results welcome.
  • composes sanely: heavens no.
    • you have to make a theme to get anything to render.
    • the index page of the overall site is very magical.
    • there's this melange of stuff going on about templates for singles vs lists and it's really confusing to get started with.
    • top-level content directories cause magical behavior. it's something about page kinds (? or something), and it's overridable, but it's friction by default and it's very weird, IMO.
    • the override structure in themes is extremely magical and "good luck". individual themes invent their own keywords for overrideable parts and it's all glued together with strings.
    • there's some wacky "category" pages and other stuff that you get opted into by default, and if you don't notice this, and try to write a custom theme that does only what you want, there's... probably going to be huge chunks of your site that you didn't even know existed, and they will probably render wrong.
    • litmus test: breadcrumbs: lol. it's possible but it involved trying a dozen random wrong things from stack overflow before hitting one that appears to work.
    • litmus test: two distinct TOCs: lol. maybe it's possible, but most things i've seen try to implement them using a single centralized registry thing in the site config? which is a really weird place for it, and indeed, definitely does not compose functionally.
  • in-page anchors: mostly, yes.
    • in some versions, it's been insane (it added long hash mangles). in recent versions, it seems mostly sane.
  • syntax highlighting: mostly, yes. I think configuring it would require forking it and patching the library it uses for highlighters (chroma) and then making a custom build of the whole tool, though.
  • css preprocessor: yes, the heavy builds have them baked in.
  • sane output: largely, yes.
    • things using golang templates tend to have a wild west of whitespace, but this isn't generally an issue for any practical purpose.

Summary: you can live here, but it's fairly maddening.

vuepress

  • consumes markdown: yes
  • is fast: no :( A nearly-empty site with one "hello" page takes between 4 and 6 seconds to build on my beefy desktop. That's ridiculous. I can load most AAA video game titles released this year faster than this.
  • is shipped: no :( Extremely no. You have to deal with npm, write build script json files for npm, experience npm resolving versions of things... it's very whee.
  • can have content at root: not entirely clear, and trending towards "no".
    • I might've found some ways to hack it with symlinks, but it certainly can't be done with configuration. (There isn't any configuration, as far as I can see.)
    • There's a bonus little intrigue that even if you could put most of the content at the root, you then couldn't make the README.md for github and the root page of the site be different, because VuePress consumes files called readme and makes them the index when generating the html. Woopsie.
  • composes sanely: fairly, relatively, I think. I have a better impression than of Hugo, let's put it that way.
    • the index page isn't magical -- as it should be.
    • new top level directories aren't magical either. As it should be.
  • in-page anchors: yes.
  • syntax highlighting: yep. Adding new languages is also possible: it requires writing javascript, but it's possible to do without "recompiling the tool". (In as much as anything is -- remember, you need to wrangle npm to use this tool at all.)
  • sane output: oof. no :( it works, but I'm not able to bring myself to call it sane.
    • the output is present roughly twice.
      • It's present once in plain HTML (as it should be), so it does render reasonably when noscript is in effect.
      • It's present again in javascript objects (?!), of which VuePress generates many dozens of files (??!), and these are used when noscript isn't present.
      • This is especially bizarre because an outcome of this is: you can manipulate the HTML files in ways that are perfectly reasonable and result in "correct" site rendering when noscript is in effect, but will make the JS content panic (?????) and fail to render content.
      • There are plugins to remove these javascript outputs again, but they're undermaintained (???) and it's quite weird to have to add more code to remove this feature (especially considering I'm willing to bet this enormous js emission contributes significantly to the overall painfully large build time).

Summary: you can live here, but only if you don't mind incredible slowness, incredible output bloat, and experiencing an entire javascript development toolchain up close and personal.

(Side note: this author actually really likes Vue -- as a dynamic content system, it's great: very incrementalist to adopt, very productionized (trivial to start using with a single file, no npm universe on your head). It's a shame that VuePress seems to be the very opposite of those things. It's like VuePress is more of a demo of "hey look what you can do with Vue!" than a real thing taking itself seriously as a product; and it's definitely not built by people with the same ethos as Vue.)

zola

  • consumes markdown: yes
  • is fast: yes
  • is shipped: yes
    • although I have to admit I'm hitting rather more crashes than I'd want to have to expect. (Things like: empty yaml front matter: crash. Uuf. Something about build works, but serve mode crashes. Uuf uuf.)
  • can have content at root: not entirely clear, and trending towards "no".
  • composes sanely: no :(
    • by example:
      • I create an content/_index.md file. Does it render? No.
      • The home page actually comes from templates/index.html.
      • I create content/page.md. This would need another different template.
      • I create content/deeper/_index.md. This appear to need... ANOTHER different template?
    • this is basically all the same stuff as Hugo.
      • I don't know what to call it other than "the Hugo braindamage". I cannot imagine someone inventing this system from first principles unless they're copying Hugo. It's altogether too odd.
    • there's also some utter crazypants about filenames being checked for RFC3339 dates, and then (waving hands) different things happen.
    • I think I'm liking the templating system a bit more than Hugo's. The examples I'm seeing for breadcrumbs and TOC generation looks... reasonable.
    • Has the "you need a theme, we won't do anything useful by default" braindamage.
      • Admittedly, it's slightly better than hugo, in that it will warn you about this. But I still don't understand why some of these tools intentionally thumb their nose at you instead of shipping the dang content. I want to know if your markdown processor literally so much as works correctly before I start chasing themes, aite??
      • Arguably only a "getting started" problem.
    • Has the pagination braindamage: as in, you literally cannot use the starter themes without configuring pagination.
      • Possibly only a problem of the starter theme I tried rather than the system as a whole, but it was still not a pleasant or impressive experience if you know pagination is something you will explicitly not be needing or wanting for the content arrangement you intend to build.
    • I did try to see if I could attain "content at root" by aggressive application of symlinks.
      • Nope.
  • in-page anchors: yes.
    • These are actually unusually nice. There's an extension to the markdown syntax for headers which lets you customize them explicitly.
  • syntax highlighting: yep. And it's really easy to add new ones: it uses the sublime text highlighter config system, which is just plain files, no recompilation required.
  • sane output: yep.
  • additional rough edges:
    • (as of v0.13 / 2021Feb) the serve mode panics when a markdown file has a frontmatter indicator but no actual yaml body. uufdah.

Summary: this is pretty good. Probably better than Hugo, on grounds of customizable syntax highlighters, if that's a key feature for you.

But it's got the exact same "I need HOW many files of templates to get started?" madness and a lot of the other same hangups as Hugo, so... I'm gonna keep looking for alternatives, personally. And there's a serious threat that I'd still just go with Hugo over Zola because the distinctions are just... so small.

The pagination thing made me tap out on my full attempt to run with Zola. I'm not sure what it will take to make me give it another try.

cobalt

  • consumes markdown: yes
  • is fast: yes
  • is shipped: yes
  • can have content at root: yes. (oh my god. finally, someone does this.)
    • it's trivial, you just put an index.md in the root of your repo and exactly what you expect to happen happens.
  • composes sanely: yes.
    • it's just directories.
    • the directories and filenames in the output match the directories and filenames in the input.
      • it's insane that I have to say this, but, if you look at the competitors, this is actually saying something.
    • do things render if there's no template/layout for them: yes.
      • again, somewhat bizarre I have to say this, but here we are. it's the only tool in the comparison list with this trait so far.
      • not prettily, of course, but some content appears, so at least you know you fucked up on connecting the layout rather than on understanding the actual URL structure.
    • bit of a downer: you have to repeat the layout: default.liquid snippet in the frontmatter of every page, apparently.
      • most competitor systems have a directory-based hinting in addition to this, and I have to admit that does help.
      • TODO: resesarch if this can be done with pages.default.* in the config. I bet it can.
    • the templating system, "liquid", appears to be the same as Zola, and seems roughly sane at first glance.
      • offhand observation, I also have to say I get really good error messages from this system (stark contrast to most of the go templating errors).
    • okay, it does have a bit of magic for a "posts/" directory, and that appears to be non-composable.
      • see https://cobalt-org.github.io/docs/posts/ for details.
      • i'm mostly not mad about this. it's stuff you'd want for a blog, and I don't see wanting to use it more than once in the same site.
      • would be happier if it was available "as a function call" or as some kind of trait you can annotate to more than one directory, but, whatever.
    • ... okay, I don't know how to list a directory with the variables available to this template system.
      • the magic for "posts" is getting worse. you can loop over {% for post in collections.posts.pages %} but I can't see any alternative to that for other collections.
      • this might be gg-no-re territory.
    • there's no option for making a directory for every output page.
      • this is common in many tools nowadays, because it lets you dodge ugly file extensions.
      • nothing stopping you from doing it yourself with ton of directories and index.md files, of course.
  • in-page anchors: nope.
  • syntax highlighting: yep. And it's really easy to add new ones: it uses the sublime text highlighter config system, which is just plain files, no recompilation required.
  • sane output: yep.
  • aside: "cobalt" is a sufficiently common word that searching the internet for docs for this thing is painful.

Summary: heck, this is really close. Most of the complaints I have are solvable with "give more info to the template evaluator" or other similarly minor (rather than architectural) work. Jury's out on if I could actually live here today, though.

verless

https://github.com/verless/verless

Review todo.

Nuxtjs

https://nuxtjs.org/

Review todo.

Note: this appears to bill itself as an application framework, which may be significantly more power and complexity than is desired for a static site generator tool

Zas

https://github.com/imdario/zas

Review todo.

One thing very notable about this is that it's very natural in its approach to recursion. Adding a .zas directory anywhere in the content tree applies traits to the directories below. Very straightforward.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment