Static Site Generators

Find out how to use various SSGs.

This section is about setting up various static site generators.

In these tutorials I will share my experience in setting up SSG such as Jekyll, Hugo, etc.


Jekyll

When I first started exploring the CI/CD and the SSGs, the first generator that I learned was Jekyll. I used Getting started with the Documentation Theme for Jekyll by Tom Johnson, the famous guru of technical writing known by his I’d Rather Be Writing blog. So without too many words, let’s start building our first documentation portal using Tom’s Jekyll theme. I will try to explain even the evident things.

Jekyll API site

At some point, you start looking for a way to generate a site hosting the API documentation. Yes, all those API endpoints, calls, requests, and parameters illustrated by the code blocks. Tom Johnson, in his Documenting APIs guide for technical writers shows the Aviator theme for Jekyll as an example of the API documentation site. Let’s publish this site using the instructions below.

Create online CV with Jekyll

One of my first Jekyll sites was my resume available online. While many HRs and recruiters still prefer the classic PDF, I decided to give the online thing a try. After all, it’s so easy just to send the link to your CV. In this article, I will show you how to create your online CV using Jekyll as a static site generator and Vercel for deploying and hosting your site.

How to install Hugo on Windows

Hugo was my second static site generator after Jekyll. Now it’s my favorite SSG. It has many nice features but its strongest advantage is the build time—the fastest among all other SSGs. In this article I will show you how to install Hugo on your Windows computer.

Hugo API site

I’ve created about 10 different Hugo sites. So far it’s my favorite static site generator. The build speed is less than a minute for every site that I’ve deployed. However, the setup process for Hugo sites isn’t very clear for me. I wish I had clear instructions on how to add a theme and publish it online. Lots of Hugo themes are available at JAMstack Themes.

The docs-as-code approach for creating documentation using the Docusaurus static site generator

In this article, I will talk about the docs-as-code approach to creating documentation as a static site using Docusaurus, a static site generator. In addition to general information about the modern approach to creating documentation, I offer step-by-step instructions on how to create a site with documentation without knowledge of the programming language, as well as publish this site on the Internet.

How to remove Hugo from Windows

Sometimes you need to delete or uninstall Hugo that you’ve installed on Windows. I failed to find the instructions on the internet. Here’s the way to remove Hugo from your computer.

Gatsby API site

Reference API documentation site built with Gatsby. The theme is based on Slate and Stripes API docs.

Pet Store Swagger API

Reference for the Pet Store API

Pet Store Redoc API

Reference for the Pet Store API

Deploy Docusaurus site to GitLab Pages

In this article, I explain how to publish a Docusaurus site to GitLab Pages using a CI configuration file. This is an alternative way to deploy the Docusaurus site on your company GitLab or your private GitLab account.

AsciiDoc and Antora: Cyrillic bold characters

In this article, I explain how to bold characters or words in AsciiDoc and Antora. Even though official documentation provides an easy way to bold text with single asterisks, this doesn’t work for the Ukrainian or any other Cyrillic charaters.

Image zoom in Docusaurus site

In this article, I explain how to add the image zoom in your Docusaurus site. When you click any image, it should expand to its full size. This feature works the same as all images in Medium articles.

Image align center in Docusaurus

In this article, I explain how to align image center in your Docusaurus site.

Image size in Docusaurus

In this article, I explain how to change image size in your Docusaurus site.

Tools for your docs: Docusaurus and MkDocs Material

In this article, I explain what tool you can select for your documentation. Specifically, I discuss the two tools that I recommend for technical writers: Docusaurus and MkDocs Material

Docs versioning: Docusaurus and MkDocs

In this article, I explain how to add versioning to your docs generated with Docusaurus or MkDocs Material.

Use Publii CMS for a blog

I’ve decided to give Publii a second chance after several years when I first tried to create my blog.


Last modified March 9, 2023: first commit (98b8333)