The Weary Travelers

A blog for computer scientists

Date: 2023-07-02
Author: Suhail
Suhail.png

Static site generators

Static site generators are useful, however, they’re not all created the same.1In addition to their implementation language, a major difference is the input format that is supported. This is a pity, because it means the choice of using one vs another can have consequences that only become apparent after the fact. How much Go do you need to know to extend syntax highlighting for a static site generator written in Go? Which one should you prefer if your intent is personal blogging vs building websites for clients? By the end of this post you should be able to answer some of these questions.

What are static site generators

From Wikipedia:

Static site generators (SSGs) are engines that use text input files (such as Markdown, reStructuredText, and AsciiDoc) to generate static web pages.[​ 1​] Static sites generated by static site generators do not require a backend after site generation …

Not needing a backend2And, thus, not needing to manage state server-side., makes them attractive for the usecases where they are suited (serving static content). Wikipedia, itself, is an excellent example of a statically generated website.

Some notable static site generators

Jekyll3Extensibility, both for general markup and specifically for syntax highlighting, requires Ruby knowledge.

Hugo8Extensibility for input formats requires Go knowledge; extensibility for syntax highlighting requires Python knowledge.

Gatsby10 Extensibility, both for general markup (in Markdown) and specifically for syntax highlighting is via remark plugins and requires JavaScript/TypeScript knowledge.

Gatsby is a static site generator built on top of Node.js using React.

Next.js10 Extensibility, both for general markup (in Markdown) and specifically for syntax highlighting is via remark plugins and requires JavaScript/TypeScript knowledge.

Netx.js is more than just a static site generator - it a web development framework for React-based web applications, but also includes static website generation.

Sphinx12 Extensibility, both for general markup and specifically for syntax highlighting requires (only) Python knowledge.

Sphinx is a documentation generator written in Python that primarily uses reStructuredText as the input format.

Conclusion

When building websites for others, the selection of available themes as well as the ability to migrate content from other platforms is perhaps most important. Hugo and Jekyll are perhaps best suited when it’s unlikely that the website may have some dynamic content.

When it is important to have the option to convert the static website into a dynamic one,14Possibly at a later point. generators based on React such as Gatsby and Next.js might be well-suited.

Sphinx is perhaps best-suited for technical documentation and technical blogs. What it lacks in available themes, it makes up for in ease of extensibility.12 Extensibility, both for general markup and specifically for syntax highlighting requires (only) Python knowledge.

Comments

Comments can be left on twitter, mastodon, as well as below, so have at it.

To view the Giscus comment thread, enable Giscus and GitHub’s JavaScript or navigate to the specific discussion on Github.

Footnotes:

1

In addition to their implementation language, a major difference is the input format that is supported.

2

And, thus, not needing to manage state server-side.

3

Extensibility, both for general markup and specifically for syntax highlighting, requires Ruby knowledge.

4

And use that to generate html snippets that can be embedded in webpages.

5

E.g., AsciiDoc, Slim etc.

6

A CSS theme inspired by Edward Tufte’s books and handouts which, among other things, supports notes in the right margin.

7

From Wordpress, Blogger, Medium etc.

8

Extensibility for input formats requires Go knowledge; extensibility for syntax highlighting requires Python knowledge.

9

Supports a large number of languages and can be extended by writing a custom Pygments lexer.

10

Extensibility, both for general markup (in Markdown) and specifically for syntax highlighting is via remark plugins and requires JavaScript/TypeScript knowledge.

11

However, the markdown converter it relies on is no longer maintained.

12

Extensibility, both for general markup and specifically for syntax highlighting requires (only) Python knowledge.

13

reStructuredText can be extended via custom text roles.

14

Possibly at a later point.