Have you been toying with the idea of using a fancy Static Site Generator such as Gatsby, Hugo or Docusaurus to get your documentation up and running on the web?
Read on if your answer to the above question is a ‘yes’. These SSGs are specific tools designed to help you with hosting your documentation online in a static fashion.
What exactly is the meaning of the term ‘static’? To answer this question, let us go back in the early days of the web(1990s). The first ever websites that were designed and hosted on the web had text and information presented to the users in a read-only manner, which meant little to no interactivity. You consumed what you read. Those websites were known as ‘static websites’ and the web in those days was called ‘static web’ or ‘read-only-web’.
Fast forward to 2023, we are living in a ‘dynamic’ ever changing world around us and this is because we are constantly interacting with a dynamic web where we design, create and consume our own content. Websites such as Facebook, Twitter, ChatGPT, E-commerce, online banking websites etc. are all dynamic in nature because they give you a personalized experience depending on your needs. These sites are constantly running code and querying databases behind the scenes to serve you in the best possible way.
Static sites are much simpler to create and maintain, and are also faster to load. Our focus in this article will be on Static Site Generators since our need is to simplify documentation.
Before we look at a variety of SSGs that are available and which one you should choose, let us first understand the criteria for choosing a good SSG.
Criteria for choosing your SSG:
- Simple and easy to set up: You certainly would want something that is simpler for you to set up in comparison to a tool that takes ages for you to configure.
- Build Time: Build time refers to the amount of time it takes for an SSG to process and compile your source files into a static site. Since SSGs are supposed to make your work easier and faster, you must consider this criteria before you make a choice.
- Learning curve for the beginners: You certainly do not want your team members to feel overwhelmed with the complexity of an SSG, especially if they are new to Technical writing. Choose an SSG which offers a good trade-off between time/effort and productivity.
- Coding Knowledge: Also, one major factor to consider would be whether or not your chosen SSG expects your team members to be coding superheroes or not.
- Flexibility in Templating Languages: A good SSG must be flexible enough to process data from a variety of sources such as HTML, Markdown, JSON etc. and shouldn’t confine you to using a fixed set of pre-defined templates.
- Search Engine Optimization: A good SSG must work towards increasing your site’s visibility and ranking so that it attracts more traffic.
- Free and Open Source: In your decision making process, you may also want to consider if the SSG is free and open-source.
- Support for Docs-as-code workflow: Your SSG must work towards getting the same respect for your documentation as is given to the software code. Hence, it must provide features such as versioning, automatic updates to your documentation, search functionality etc.
- Third Party Integrations: Not all SSGs have integrations with third party tools such as analytics, ability to create forms, allowing comments, integration with social media platforms etc. It’s worth evaluating whether your SSG can connect these dots for you or not.
- Versioning: To manage your product releases better, your SSG must provide you with version control features so that you can stay on top of all updates without getting lost in the process.
- Search feature in Documentation: Some SSGs come equipped with a Search feature which allows your clients/users to look for specific information within your documentation.
Digging Deeper into our Top Three Static Site Generators
Let us now take a deep dive into our top three static site generators.
Gatsby
Hugo
Hugo: Second in our list is Hugo which is also a very popular static site generator and we will see why. First and foremost, Hugo is extremely easy to configure and use. Once you get it up and running, you will be amazed to see how fast it will build your site. The build time is under 1 millisecond per page. Hugo doesn’t assume that your documentation team would be familiar with programming and so to use Hugo, your team doesn’t need to possess any coding skills.
As regards the flexibility of templating languages, Hugo is somewhat flexible because it allows you to use Markdown for your source files. It also has some very easy to Go templates but if a comparison were to be done between Hugo and Gatsby, the latter would win in this criteria. Hugo too, just like Gatsby, was designed keeping SEO in mind and so, Hugo is very Search engine friendly because it has support built in for formats like TOML, YAMN and JSON metadata formats. Hugo is open source and free of cost. Yes, you read it right. Hugo is open source which means it is very flexible if you would like to customize it to your needs.
Hugo supports Docs-as-code workflow which means it is very modern and promotes the best technical writing practices. Coming to the other criterion in the list, you can easily put a tick mark against third party integrations because Hugo can be integrated with third party apps like Google Analytics, allows users to add comments on your content and much more. Last but not least, Hugo comes equipped with minutes to read and wordcount etc. frontend features which makes your website very user friendly.
Docusaurus
Docusaurus: Last but not least, let us look at Docusaurus. The name itself is quite interesting! Docusaurus too is amongst our top three static site generators because of what it does to assist technical writers. Docusaurus is flexible in terms of templating languages. It supports the markdown format and mdx. Docusaurus is similar to Gatsby because just like the latter, the former is based on React and so, you can use hundreds and thousands of React libraries to customize your website the way you want to.
As you would have already guessed, Docusaurus is free and open source and it also has support built in for the docs-as-code workflow. As far as versioning is concerned, Docusaurus handles versioning in a very smart way. It uses Git as the versioning system and integrates with GitHub. You can be assured that your docs are going to be in perfect sync with the code. To make your website user friendly, Docusaurus helps you utilize the power of Algolia, which is a powerful search engine. Your users can type in their search query and Algolia will come up with the most relevant documents matching the search query. With Docusaurus, you can also include a personal touch by localizing the content as per the target audience. It uses Git as well as specialized translation managers such as Crowdin.
To conclude, Static Site Generators are like your go-to-buddies when it comes to technical writing. They save your time, make your work easier and help you to be more productive.
So, which one should you choose?
There is no perfect answer to that question because your choice will depend on a number of factors. For example, if your team is comprised of Javascript engineers, then you should go for Gatsby or Docusaurus since these two are React based. On the other hand, if you are looking for faster build time, you should choose Hugo since it is blazing fast and gets your site up and running within a few seconds.
