Build a fast and secure website in 10 minutes
TL;DR
Static site generators are perfect for building fast and secure websites. The Jamstack community keeps track of, and lists all the static site generators across GitHub and also advocates for the modern architecture of building websites.
Intro
Whether you are a developer or a technical writer who wants to write and publish documentation, you most likely want to automate most of your work and not build a documentation website from scratch. For folks like you, we will present modern solutions for building websites… and not only for documentation purposes.
Static vs Dynamic
We can broadly divide the websites into static and dynamic. Dynamic websites are powered by content management systems (CMS) such as WordPress, Drupal, and Joomla where content is managed and stored in a database. When you request to access a URL or click on a “next” button on a website, the page, you’re directed to, is being built on the fly through PHP or another server-side scripting. The CMS then fetches content from the database, merges it with the template, and outputs rendered HTML files to your browser. It’s called server-side processing.
Static websites strip away the process of assembling the website on the server, the pages are pre-built for the server which means hosting formatted HTML pages on the server. So, when you access a URL, you instantaneously access an HTML file without any dynamic changes based on your profile (unless done with client-side JS).
What do static site generators (SSGs) bring to the table
A static site generator is a tool that uses a markup language and a set of templates to generate a static website.
Since SSGs generate HTML files and you only request an HTML file from the server, static websites are secure and fast in comparison to dynamic websites. There is no database, no server-side processing, and no CMS extensions and plugins with vulnerabilities to exploit. Changing the website from one platform to another also becomes easy with static websites — again, there is no database that has to be migrated and folks responsible for migration can attest that many database fields from one CMS don’t map (cleanly) to other databases. The site reliability also improves thanks to the removal of a database — “Error establishing a database connection” no longer is an issue and traffic surges to the database can’t cripple the system since guess what… There is no database.
You can also customize SSGs through JS/CSS/HTML and write content in Markdown or reStructuredText. Thanks to that content format, it is convenient to store it in a version control system such as GIT, treat content as code, and publish a website from your GIT repository. Inside the content, you can use templating and scripting languages e.g. Liquid, insert variables, snippets of HTML code, conditional statements, and a lot more. You can also affect how the website is generated in built through the supported programming language.
Static site generators (STGs)
There are 333 STGs according to the Jamstack community. Jamstack is also an architecture for building modern websites that puts security, scalability, performance, portability, and developer experience in the spotlight. One of the ways this architecture distinguishes itself is by removing the need of generating a page per user’s request on the server.
What is more, themes for the static site generators are plug-and-play, which means you need to download a collection of HTML/CSS/JS and add it as a variable in the configuration file for the STG. Or, you can always create your own theme if you want to fully own the look and feel of your website. One of the drawbacks of custom theming is the lack of interoperability i.e. if you start working with another platform you might need to change Jinja templating to Liquid templating and so on depending on what STG you use.
In this blog post, we will only briefly cover a couple of the most popular static site generators such as:
- Jekyll
- Hugo
- Sphinx
- Docusaurus
Jekyll
Jekyll takes Markdown as input files and transforms them into HTML output. Jekyll was developed by the co-founder of GitHub and is a Ruby-based static site generator.
I used Jekyll in my very first project as a technical writer alongside software developers. We had a repository set up for continuous integration (CI) and publishing on GitHub Pages which allowed us for automated continuous delivery. Whenever we introduced changes to the existing content or wrote a new blog post, all we had to do is push our local changes to the main branch of our Jekyll repository.
One of Jekyll’s drawbacks is slow to build times compared to its main rival — Hugo. For small projects, it doesn’t matter much but if you have thousands of pages to render, the difference is extremely noticeable (minutes as opposed to seconds kind of difference). After a few years after my leaving, I revisited my old project and discovered that my fellow friends switched from Jekyll to Hugo. In my personal opinion, it is a very good move since Hugo is on the rise and means more support and features along the way.
Theme gallery for Jekyll —click here
Some websites that were built with Jekyll:
- https://github.com/mendix/docs
- https://rubyonrails.org/
- https://www.sketch.com/
- https://devices.netflix.com/en/
- https://mobilefirstplatform.ibmcloud.com/
- https://docs.mendix.com/
- more
Hugo
Hugo is another static site generator that natively supports Markdown as the content format to generate HTML output from. This STG is based on the Go language developed by Google.
Many Google projects use Hugo and a Hugo theme (Docsy theme) by Googlers e.g. Kubernetes, Kubeflow, and gRPC. Due to this fact, Hugo can benefit from the support of Google.
Theme gallery for Hugo — click here
- https://getbootstrap.com/
- https://docs.digitalocean.com/
- https://docs.bitnami.com/
- https://www.section.io/
- https://godottutorials.com/
- https://www.smashingmagazine.com/
- more
Sphinx
Sphinx is a static site generator that natively supports reStructuredText as the text files format for the HTML files generation. Sphinx is based on Python and developed by the Python community to create the documentation for the Python programming language.
What differentiates Sphinx from Jekyll and Hugo is the fact that Sphinx was designed for documentation purposes from the ground up as opposed to Jekyll and Hugo which are more general purpose-driven.
Out of all static site generators, Sphinx is my go-to tool for building documentation websites. The main reason is probably that I’m most used to Sphinx and the platform offers many documentation-specific features e.g. cross-references, advanced search, and linking.
What is also important is the use of reStructuredText. It is semantically richer and more extensible than Markdown (which is an awesome thing for documentation purposes). However, reStructuredText is not as well known as Markdown among software developers and convincing developers to contribute in .rst (reStructuredText) instead of .md may be challenging.
Theme gallery for Sphinx— click here
- https://projectacrn.github.io/latest/index.html
- https://www.writethedocs.org/
- https://pandas.pydata.org/
- https://www.nltk.org/
- https://matplotlib.org/
- https://scikit-learn.org/stable/
- https://book.cakephp.org/4/en/index.html
- more
Docusaurus
Docusaurus is a static site generator that natively supports Markdown as input files and outputs HTML files. Docusaurus is another STG with React framework. This STG is general purpose and also opinionated toward the documentation use-case. Out of the box, you get support for the Algolia search, versioning, multi-language option, and even dark mode.
Docusaurus is great if you work with (or are) front-end developer(s) who use React for the development. You can build a very beautiful and feature-rich documentation website or a general-purpose website.
Theme gallery for Docusaurus — click here
Conclusion
You have many options to build general-purpose and documentation websites and as always a matter of choosing the right tooling boils down to a specific use case. However, the Jamstack architecture is gaining traction, and more and more proponents for the modern ways of websites.
