Hugo vs. Docusaurus
These days, static websites are becoming more and more popular. But how to pick the right solution for your documentation team? In this blog, we will compare two popular static site generators: Hugo and Docusaurus.
What is Hugo?
Hugo is an open-source static site generator that was initially released in 2013. Since Hugo is written in Golang (Go), it quickly gained popularity among Go communities and since then became one of the most well-known documentation solutions for projects such as Kubernetes and many companies around it.
What is Docusaurus?
Created by Facebook®, Docusaurus is written in JavaScript and uses React. Docusaurus provides a basic website template that you can modify as needed if you are familiar with Javascript. The template website provides built-in APIs, Docs, Help, and Blog template pages. This website runs on Docusaurus.
Now, how to pick the right one between the two seamingly similar documentation engines? Here are a few things to consider.
Supported platforms and installation
Whether you are most comfortable with UI or command line interface (CLI), you can configure your website to run locally as quickly as in under 30 minutes. Hugo supports any OS that has a Golang compiler running on it, including macOS, Windows, Linux, and so on. With Hugo, you can use the command line or download a binary for your platform.
Docusaurus is a bit more Unix-oriented tool and if you are on a Windows machine, you need to have a Windows Subsystem for Linux environment enabled. This blog focuses on a macOS way of doing things with Hugo and Docusaurus.
Formatting syntax
Both tools support Markdown but use different Markdown parsers. If you do not really care which one to use, it should not make any difference for you when you make your choice. Hugo uses the Blackfriday markdown parser and Hugo uses Recommonmark.
If you are new to Markdown, do not hesitate to give it a try. It is lightweight and easy to start writing with. Most people find markdown easier than HTML or XML, and it is supported by all major documentation tools, as well as GitHub and Atlassian® JIRA.
Here is an example of markdown file:
Documentation
I find that the Hugo documentation is a bit more detailed than the Docusaurus documentation. Even if you do not have previous experience with static website generators, follow the docs to start quickly. The Hugo documentation provides more practical examples of how to host your website on GitLab, Netlify, GitHub, and other platforms. The Hugo docs even have a continuous integration (CI) configuration file example that you can use with little modifications. With Docusaurus, it might take some time to configure hosting and CI as no step-by-step instructions are available.
Themes
Another thing to consider is the free website themes available for both tools. This page provides numerous Hugo themes for various types of websites. Whether you are setting up a website for educational purposes or for enterprise-class documentation, you can pick and use a theme as needed. Modifying things like colors and menu item are relatively easy as well. One thing that I particularly loved in Hugo's themes is support for Font Awesome that allows you to easily insert icons in your text or user interface (UI) elements.
Docusaurus provides one built-in theme. However, if you are knowledgeable in React, it is not difficult to add changes. I was able to set up this website on Docusaurus with just basic knowledge of JavaScript.
Search
All static site generators suffer from the lack of reliable search functionality. You need to pick an open-source or a paid search engine provider. Your open-source options include back-end search engines, such as Solr, ElasticSearch, or Lunr. You can also pick a commercial solution, such as Algolia if you do not want to maintain the search platform yourself. Algolia is free for non-commercial use. Picking a search solution depends on how often you plan your documentation to be updated and how critical it is for the search results to be up-to-date at all times.
Summary
To summarize what was discussed above, let's look at the table below:
| Hugo | Docusaurus | |
|---|---|---|
| Markdown support | Blackfriday | Recommonmark |
| GitLab/GitHub hosting support | ✔ | ✔ |
| Language | GoLang | JavaScript |
| Developer-oriented | ✔ | |
| Writer-oriented | ✔ | |
| Cross-platform | ✔ | ✔ |
| Ease of customization | ✔ | |
| Search | custom | custom |