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.
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.
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.
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.
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.
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.
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.
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.
Reference API documentation site built with Gatsby. The theme is based on Slate and Stripes API docs.
Reference for the Pet Store API
Reference for the Pet Store API
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.
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.
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.
In this article, I explain how to align image center in your Docusaurus site.
In this article, I explain how to change image size in your Docusaurus site.
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
In this article, I explain how to add versioning to your docs generated with Docusaurus or MkDocs Material.
I’ve decided to give Publii a second chance after several years when I first tried to create my blog.
The search field in your Docusaurus site doesn’t come out-of-the-box. If you want to add the full-text search to your Docusaurus site and deploy the site to GitHub Pages, follow the instructions.
Add a chatbot to search in your Docusaurus site docs. This is another way to search your site contents by asking the chatbot and getting the links to the docs articles.
Sometimes you need to wrap the lines of code in the code blocks or snippets that you add in Markdown. If the line of code is too long, you need to scroll horizontally to get to the end of the line. If there are many lines of code in your code block, you need to scroll down first, scroll to the end of the line, and then scroll up to see the long line of code. Follow these instructions to add the word wrapping in the code blocks.