I thought I would break the silence on this Hugo powered blog with a post about another SSG Static Site Generator . Docsify is a SSG that is truly a different kind of animal. To illustrate the difference, let me start by mapping my current workflow to make a post using Hugo as my SSG.
- Make sure I have the latest version of Hugo on my local machine. Admittedly, because it is written in Golang and comes as a single binary this is pretty easy. On my Debian workstations, I download the released deb package and install using the simple command replacing the deb package name with the latest released version of Hugo.
sudo apt install ./hugo_0.82.0_Linux-64bit.deb
- On Fedora, I have installed a COPR repo that has the latest version of Hugo, so every time there is an update, I pull down the latest Hugo version.
At this stage if you don’t already have a Hugo site, you will need to use the Hugo tools to create the skeleton of directories and files that you need to begin authoring your site. You will also need to install a Hugo theme that will create the look of your site. Once you have installed your theme into the proper directory and edited your config.toml file you can begin creating posts and content for your site.
Since discoverfoss.com has step 2 done, I can jump into creating content. For me this begins with the creation of a Markdown file in the posts directory.
After the post is ready to be posted on the blog, the fun begins with Hugo. I run a
bashscript that does the following steps:
hugoto create the static html pages in a separate
git add .in that repository
git commit -m "Blog Updated on $(date)"
git pushwhich pushes the newly created static HTML pages up to the repo on github.com that hosts the site through Github Pages.
All of the steps of 4 take mere seconds. First, because Hugo is fast when it builds a static site, and second, because I have my SSH keys saved in Github enabling me to
git push using SSH which saves me the step of having to enter my password.
In general, SSG’s typically follow above workflow where you use a local install of the SSG to create the static site from your Markdown documents, and then you will SFTP, Rsync, or git push your static files to your web server or hosting provider. There appear to be hosted solutions or continuous integration pipelines that will remove the need for a local install of the SSG, but I haven’t looked into those options for discoverfoss.com at this time.
Docsify is a different animal in the SSG world. You can install a local CLI (command line interface) version of Docsify on Linux, but I have not seen the need to do so. You may want to consider that if you want to see a local instance of Docsify on your workstation where you are authoring the Markdown documents for Docsify. Additionally, Docsify shows you how you can with just a few lines of Python spin up a web server to see your local content in a browser. Since Python is usually installed in the major distributions, I feel this is an easier solution than setting up a local CLI of Docsify with all of its dependencies.
Docsify caught my attention months ago, when I looked into options for creation webpages of documentation for a FOSS project that is near and dear to my heart. At first, I considered just using Hugo and one of its templates which are geared towards documentation projects. Hugo would be an excellent solution, but since Docsify focuses on displaying project documentation, and is designed to work well with Github Pages I felt Docsify was a better solution.
Yet, what pushed me into trying Docsify was my desire to have a personal, searchable, organized, wiki written in Markdown or ASCIIDOC files. Although, I enjoy writing my FOSS adventures in this blog, there are notes and documentation that I use everyday that I don’t need in a blog post. As an example, while I continue to learn vim I have a notes file that has keyboard shortcuts that I have not committed to memory, but still find useful a few times a week. I also like to lay out the steps that I performed to get something installed and working in the homelab. Sometimes those turn into tutorials for this blog, but other times there are steps that I’m copying down from a variety of sources for my unique setup which would be of little value for the wider FOSS community. I have used a variety of tools for this in the past. When I lived in Windows and used more proprietary software, I used Evernote until their “free” option became too limited, then I switched to Onenote. In Linux, I have used something as simple as a directory filled with text files that was synced with Syncthing between all my machines to a more robust tool like Zim . Docsify let me check the following boxes which caused it to win in the contest of what will serve as my personal wiki.
- I can do all of my documentation in Markdown. Since I’m already writing in Markdown for this blog, and using Markdown to the creation of printable PDF’s, adding another use for my Markdown skills was a plus.
- It is easy to add search to Docsify.
- It is easy to add a dark theme to Docsify.
- It is easy to have a full featured sidebar.
- The active community have coded amazing plugins for Docsify that you can use too.
- I believe Docsify would be a great solution for a FOSS project that hosts its files on Github because of the excellent support Docsify has for Github Pages. This opens Docsify up for future uses as I contribute to other FOSS projects.
Now, what makes Docsify a different animal? Docsify is an SSG, but it skips the build step of most SSG’s. Instead of reading in the Markdown files and converting a series of HTML files from those, Docsify converts the Markdown files on the fly. Docsify is up and running by creating a single
Just one look at the Jamstack list that I referenced above proves that there are plenty of possible solutions in this world of SSG’s. For me, Hugo and Docsify, have become personal favorites. What SSG do you use and love? How do you use SSG’s in your homelab to serve up information that you want access to?