Static Site Generators: A Comparison

Static Site Generators: A Comparison

Decisions, decisions...

Static site generators are becoming more and more popular, and this trend can be hugely attributed to the rise of the Jamstack architecture that enables the designation of fast, secure websites that are easy to scale. This is allowed by the pre-rendering or pre-generation core principle of Jamstack that makes it possible for markup that presents the page view to be generated at build-time as opposed to in real-time or on demand, eliminating the need for web servers to undertake this task every time a request is received. This means that the entire website front-end is prebuilt into highly optimized static pages and assets during the build process. Therefore, when a user requests a page from the website, they are able to access it quickly without requiring any call to a database. The HTML, Markdown, or whichever markup is already pre-generated, so it will just respond with the file itself.

These pre-generated files can be easily hosted in a Content Delivery Network (CDN); due to this pre-rendering process, your site can be served directly and quickly from the CDN, minimising the cost, risk and complexity of dynamic web servers. Moreover, you wouldn't need to build or manage your own back-end server- or have to run your own database, making it incredibly easy to run your site locally, automate builds, switch to a different host, etc. The absence of a database or dynamic interpreter running on your servers severely secures your website from hackers.

There are, without a doubt, many static site generators, each one with its strengths and weaknesses that would influence one's preference for one over another. This is where decision-making becomes a skill. Because decisions have consequences. You'd have to weigh your options, consider the trade-offs- at the end of the day, you'll need a framework that is right for your project. Always keep in mind that the technically best solution is not always the right solution.

The best solution is not always the right solution.

The stakes are even higher when yours is an open-source project; in this case, you'd have to consider how your decision might affect other members of your community. Factors like barrier to entry would come into play, since I reckon you would like your community members to have a pleasant experience contributing to and interacting with your project by and large.

I had to make this difficult decision just a few months ago during my mentorship program at Tremor, whereby I was undertaking a web redesign project that required identifying and implementing a framework that would unify all content forms i.e. documentation, courseware, rfcs as well as all other web content in a central place, under a single consolidated theme and design. At the moment, the content was scattered across different platforms, primarily Hugo and MkDocs. We finally settled on Docusaurus, but not without an intense deliberation. Refer to this repository for a more detailed insight into the process. It covers the criteria that were important to us and unique to our particular situation, but these vary with different projects and needs.

I will cover a few more general criteria for consideration in this article, with three underlying assumptions:

  1. That it is for an open-source project.

  2. The project focuses on documentation (you need a documentation website).

  3. Markdown is your preferred tool for data entry (markup language).

An important thing to always keep in mind, as I have learnt, is that every decision is better than no decision. You've just got to get started. You are allowed to experiment with your options, make a bad decision, reset and start over- or commit the sunk cost fallacy and throw good money after bad. Your choice.

Every decision is better than no decision.

You may also find it useful to share your decision early with your community and enjoy the benefit of early feedback. Anyways, I digress. Lets get started for real.

Criteria for Consideration

It is highly unlikely that one framework will be able to address every single criteria, or to have every nice little thing you want. Consider the most important criteria to you, keeping your users, community and overall team in mind: Good vs perfect.

  • Markdown- Provides the basic structure for the content. Promotes a lower learning curve- it is easy to understand, write, and many editors give a good preview of the content at hand.
  • Focus on Documentation.
  • Navigation- An easy-to-navigate theme/framework is great for enhanced user experience. A framework that comes with breadcrumbs would be most ideal.
  • Versioned Documentation- Able to support multiple, separate versions of your documentation.
  • Syntax Highlighting- Able to support code block and even individual line highlighting.
  • Visual Appeal- For better user experience, a beautiful theme would be best.
  • Wide community- Huge following demonstrated by number of forks and stars on GitHub, for example. Ensures the longevity of support for the framework.
  • Lower Learning Curve- To minimise barriers to entry; enable community contribute with ease.
  • Free and Open-source- Also ensures the longevity of support for the framework.
  • Search Bar- Should support search integration.
  • Dark/Light Mode Integration- Recently, Dark Mode has gained a lot of traction as many people are continually showing preference towards it. Consequently, more and more websites are implementing Dark Mode design.

Selected Frameworks for Comparison

After a lot of research, with the above considerations in mind, we settled on a few candidates to test out at Tremor before making a choice for our project:

  • Hugo
  • Docusaurus
  • MkDocs
  • VuePress
  • Gatsby
  • Sphinx
  • Zola

Let's take a look at each framework and its properties to find out if it satisfies our criteria.

I. Hugo

Hugo is a very popular open-source static site generator with a myriad of themes, suitable for building various types of websites, from documentation to landing pages, to e-commerce, etc. We tested the Ananke and Docsy themes for their visual appeal and focus on documentation respectively.

Some relevant properties of Hugo:

  • Written in Go (Golang).
  • Multiple themes for various needs.
  • Supports Markdown.
  • Suitable for documentation (Docsy theme).
  • Comes with really fast syntax highlighting from Chroma.
  • Multilingual (i18n)- Hugo supports the creation of websites with multiple languages side by side. Uses go-i18n to support string translations.
  • Blazingly fast.
  • Thriving community- 53K stars, 6K forks. Very active forum, making it easy to get help.
  • Free & open-source.

A few negative aspects:

  • Steep learning curve.
  • Doesn't have plugin support- adding highly custom functionality is not possible.
  • Enabling versioning for docs is quite difficult.

II. Docusaurus

Docusaurus is a tool that facilitates easy building, deploying, and maintaining open-source project websites. It is built with React, and has gained a lot of popularity since its release only in 2017. This popularity can be largely attributed to its endorsement by Facebook (Docusaurus has been used by a large number of the Facebook open-source projects- and by over 100 external projects.). It stood out for us at Tremor, owing to its many attractive features that were line with our project's objectives:

  • Focus on documentation- Docusaurus makes it extremely easy to maintain open-source documentation websites, owing to its efforts to "put (users') focus on writing good documentation instead of worrying about the infrastructure of a website."
  • Sensitive to open-source project needs- Docusaurus provides features that many open-source websites need e.g. blog support, search and versioning.
  • Supports Markdown.
  • Supports documentation versioning- enables you to keep documentation in sync with project releases, and support users on all versions of your project.
  • Enables syntax highlighting that is customisable- Code blocks within documentation are super-powered; by using the matching language meta string for your code blocks, you allow Docusaurus to pick up syntax highlighting automatically, powered by Prism React Renderer.
  • Visual appeal- Beautiful theme.
  • Easy navigation.
  • Blog support.
  • Supports a search integration using Algolia documentation search.
  • Free & open-source.
  • Enables translation to over 70 languages using Crowdin- Localisation comes pre-configured.
  • Comes with Light Mode/Dark Mode.
  • Plugin support.
  • Large community- 25.2K stars, 2K forks.
  • Low learning curve.

A few negative aspects (specific to our project):

  • It's built with React- hard to compile with Go (used by our host, the CNCF or Rust (used by most of our community members). This would present a bit of a learning curve.
  • Not endorsed by the CNCF- we would miss out on their support.

III. MkDocs

MkDocs is a fast and simple site generator, also geared towards building project documentation. It's written in Python, and is what we initially used at Tremor. However, it lacked some of our desired features, hence the need for the redesign and migration. Its features:

  • Supports Markdown- documentation source files are written in Markdown, and configured with a single YAML configuration file.
  • Variety of themes- MkDocs includes two built-in themes: mkdocs and readthedocs. Also available are many third party themes to choose from.
  • Low learning curve- It’s quite easy to configure and deploy.
  • Easy customisation- lets you modify your site to look however you want by customising your theme, installing plugins or even modifying Markdown's behaviour with Markdown extensions.
  • Plugin support.
  • Material for MkDocs is a beautiful theme.
  • Average community following- 12.5K stars, 1.8 forks on GitHub.
  • Free & open-source.

A few negative aspects we had encountered:

  • Documentation versioning isn't built-in- requires mkdocs versioning plugin.
  • No syntax highligting.
  • The mkdocs theme isn't very visually appealling.

IV. VuePress

VuePress is a minimalistic static site generator powered by Vue, with a default theme optimised for writing technical documentation. It was created to support the documentation needs of Vue’s own sub projects. VuePress is quite similar to Docusaurus given its heavy focus on content-centric websites and tailored documentation features out of the box, except that VuePress is powered by Vue, unlike its counterpart which is powered by React. Features:

  • Built-in Markdown extensions.
  • Documentation versioning support.
  • Syntax highlighting- in code blocks as well as line highlighting.
  • Line numbers and code snippet import- You can enable line numbers for each code block, and also import code snippets from existing files.

Input:

export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}

Output:

highlight.png

In addition to a single line, you can also specify multiple single lines, ranges, or both.

  • Vue in Markdown- you can use Vue-style interpolation in text, as well as Vue components.
  • Vue-powered custom theme system- default theme and blog theme.
  • Built-in search- you can disable the built-in search box with themeConfig.search: false, and customise how many suggestions will be shown with themeConfig.searchMaxSuggestions. Moreover, the themeConfig.algolia option allows you to use Algolia DocSearch (opens new window) to replace the simple built-in search.
  • Plugin support- Powerful Plugin API, Blog Plugin, Search Plugin, PWA Plugin, Google Analytics Plugin.
  • Multi-language support (internationalisation)- the default theme has built-in i18n support.
  • Free & open-source.
  • Relatively wide community- 19.2K stars, 4.1K forks on Github.

Negative aspects:

  • Heavily Vue-powered, which might present a barrier to entry for contributors, and not very suitable for community members who are not well versed with Vue.
  • Requires a lot of customisation.

You can the find set-up and installation instructions on this test site repository.

V. Gatsby

Gatsby is a dynamic site generator that provides development teams an open-source front-end framework for creating dynamic, optimized websites and a cloud platform. for delivering them on a blazing fast edge network. It's a React-based framework that enables building of fast, secure, performant, scalable and accessible websites of different kinds (from marketing sites, to eCommerce stores, to documentation), which are then hosted on [Gatsby Cloud (gatsbyjs.com/products/cloud).

  • Supports versioned documentation.
  • Supports syntax highlighting.
  • Rich ecosystem of plugins, themes and starters- "Go from idea to production in less time with starters, themes, and over 2500 plugins that can help connect nearly any CMS, eCommerce platform, analytics tool, or other web service and get your website up and running in just minutes."
  • Blog support- you can leverage themes and starters to build blogs in your site, for example the Gatsby Blog Starter.
  • Free & open-source.
  • Can unify multiple content forms and data from different sources while maintaining consistency- Gatsby has an innovative data layer built on GraphQL that allows developers to easily combine data from different sources and render them alongside each other. You can add content to your site, from a Shopify store, a WordPress blog, and some JSON from a payment processor all in a consistent manner.
  • Unparalleled speed and responsiveness- combines static-site generation and intelligent page rendering to selectively preload only the content that matters - give you a blazing fast website that feels incredibly smooth.
  • Docz theme for building documentation is beautiful and easily configurable and customisable, and fully plugable.
  • Huge community- 50.9K stars, 9.8 forks.
  • Screenshots enabled in documentation.

Some observed negative aspects:

  • High learning curve- Gatsby is packed with a myriad of features, capabilities and plugins, which, naturally, comes at a cost of a higher learning curve. It also leverages GraphQL (not necessarily, though), which may present a barrier to entry for contributors not versed with the tool.
  • Not focused on documentation- suitable for building different types of dynamic wesites, from e-commerce to marketing, to documentation sites).

VI. Sphinx

Sphinx is a powerful Python documentation generator with excellent facilities for the documentation of software projects in a range of languages. It has many great features for writing technical documentation. Sphinx was originally created for the Python documentation. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, Docutils. Relevant features to highlight:

  • Supports Markdown- you can use reStructuredText (default markup format) or Markdown to write documentation.
  • Syntax highlighted code samples- automatic highlighting using the Pygments highlighter.
  • Supports versioned documentation- holzhaus.github.io/sphinx-multiversion/mast...
  • A vibrant ecosystem of first and third-party extensions.
  • Hierarchical structure- easy definition of a document tree, with automatic links to siblings, parents and children (enables the activation of breadcrumbs).
  • Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information.
  • Focus on documentation- Sphinx focuses on documentation, in particular handwritten documentation However, Sphinx can also be used to generate blogs, homepages and even books. Much of Sphinx’s power comes from the richness of its default plain-text markup format, reStructuredText, along with its significant extensibility capabilities.
  • Search bar.
  • Blog support.
  • Free & open-source- in fact, there are dozens of extensions contributed by users, most of them installable from PyPI.
  • Multiple themes- some of which are beautiful e.g. the Read the Docs, Material and PDJ themes.

A number of negative aspects that stood out:

  • Steep learning curve- using reStructuredText, which is not as simple as Markdown to master, as its default markup language would present a barrier to entry for contributors of an open-source project such as Tremor.
  • Default theme design is not very visually appealling.
  • Not very popular: quite a small community- 4K stars, 1.5K forks on GitHub.

VII. Zola

Zola is a static site generator (SSG), similar to Hugo. It is written in Rust, and its content written in CommonMark, a strongly defined, highly compatible specification of Markdown.

  • Written in Rust- this presented a huge advantage for Tremor which is also written in Rust; support from the Tremor team and community would be easy- low barrier to entry.
  • No dependencies- Zola comes as a single executable with Sass compilation, syntax highlighting, table of contents and many other features that traditionally require setting up a dev environment or adding some JavaScript libraries to your site.
  • Augmented Markdown- Zola comes with shortcodes and internal links to make it easier to write your content.
  • Comes with breadcrumbs- enables easy navigation.
  • Syntax highlighted code samples.
  • Blog support.
  • Search bar.
  • Ease of use (lower learning curve)- From the CLI to the template engine, everything is designed to be intuitive.
  • Flexible- Zola gets out of your way so you can focus on your content, be it a blog, a knowledge base, a landing page or a combination of them.
  • Variety of themes- enable building blogs, landing pages, documentation sites, etc.

Negative aspects:

  • Very small community following- 7.2K stars, 530 forks on GitHub- support for it in the long run is not guaranteed; smaller forums.
  • The default design isn't particularly visually appealing, although there are beautiful themes to choose from.

Final Tally

CriteriaHugoDocusaurusMkDocsVuePressGatsbySphinxZola
Markdown111111/21
Syntax Highlighting1101111
Versioning0101110
Focus on Documentation1/2111011
Breadcrumbs0000001
Visual Appeal111/2111/21/2
Dark/Light Mode0100000
Search Bar1111111
Wide Community111/21/2100
Free & Open-source1111111
Low Learning Curve0100001
TOTAL6.51057.5767.5

The defence rests.

Verdict

After carefully analysing the frameworks considered, weighing their pros and cons with respect to your project's objectives, you will hopefully have a clear winner. Ours was Docusaurus. What is yours?

Reference links: