Hugo VS MkDocs

This post is a summary of my recent decision to go back to Hugo after using Zola. I also report on how LLM assistants with Web access can aid in such decisions, not as an authority but as a research assistant.

Hugo is a fast and flexible static site generator built in Go, known for its speed and large theme ecosystem. It supports markdown, taxonomies, multilingual content, and powerful templating with minimal dependencies. Hugo is highly performant and well-suited for building large-scale documentation sites. It’s ideal for teams seeking speed and customization with minimal runtime requirements.

Try Hugo[1]. In depends on a template you choose alone whether Hugo will generate a landing page, a website, a blog, etc.

[1] https://gohugo.io

The content of the guide lives in a single Markdown file, content/_index.md. The website is built using Hugo.

Every PKMS/BASB needs a search functionality. Ever since I've created brainfck to host my own collection of thoughts/ideas/resources (aka Zettelkasten) I wanted to be able to actually search within my collection of org-roam based notes. Meanwhile for all my sites I own (this blog, my CV/portfolio, brainfck and defersec) I use hugo. All of them didn't have proper search capabilities. That's why I was looking for a proper way to include search functionalities without any major effort.

A fast and flexible static site generator built with love by bep, spf13, and friends in Go.

This project demonstrates how to deploy a static website using Hugo and Pulumi on AWS S3. Hugo is a fast static site generator, and Pulumi is an infrastructure-as-code tool that allows you to define cloud resources using TypeScript. The site is deployed to an S3 bucket configured as a static website, with public access enabled for viewing.

It was long my desire to write a blog with stuff that interests me. Lately i was studying Golang and i came across Hugo which is a really nice and fast site generation utility. This was a great opportunity to start my own blog by using Hugo and Github Pages in order to host it. Why?

HUGO is a popular and open-source static site generator framework that makes it easy to organize your files and assets where you can also leverage a taxonomy system, multilingual support, fast assets pipeline, and more. HUGO is used by millions of developers and by websites such as Bootstrap, Litecoin, Smashing Magazine, and even Flowbite.

The documentation is built with MkDocs and hosted on GitHub Pages. You can browse the complete documentation at carpet.jerolba.com.

MkDocs

MkDocs is a static site generator designed specifically for project documentation and written in Python. It’s easy to set up, uses markdown for content, and features a number of themes, including the popular Material for MkDocs. MkDocs integrates well with Python-based workflows and CI/CD tools. It’s a great choice for Python developers and teams looking for simplicity and readability.

Because of my frustrations, I've released two example GitHub repositories for two popular static site generators: MkDocs and Sphinx. The goal with these repositories is to be focussed on a minimal project using the static site generator, that builds into a Read The Docs theme compatible website, and provide supporting tooling regarding formatting of the underlying formatting language. It also provides the tooling needed to deploy to GitHub Pages both from the command line and via GitHub Actions (both are powered by the ghp-import project).

The documentation of the CLI is provided via a GitHub page as part of the repository. We are using MkDocs to generate the content, but I think most of the tools in that area are well integrated with GitHub and GitHub Actions.

The original mkdocs uses a Python package for its installer, so you can just pip install mkdocs, mkdocs new ., and then mkdocs build to convert markdown files into HTML.

If you don't like to run javascript outside of a browser, MkDocs is a great Python-based alternative: https://www.mkdocs.org/

I like Markdown because it's simple and doesn't give me that many headaches.

You know what I don't like? HTML, for user submitted content in particular. The mess I've seen, after someone opted for using HTML for messages in a system, because that's what JS based editors were available for at the time. Endless need to work against XSS, with more and more incremental updates needed to the sanitization logic, some of which broke the presentation of the data in the DB.

Never again. Markdown, BBCode, anything but that.

As for docs? Currently just some Markdown, because that's what GitHub, GitLab, Gitea and others all know how to render.

Maybe something like https://www.mkdocs.org/ for the more standalone use cases.

Developing the documentation website using an open-source static site generator like Sphinx or MkDocs to build the files locally through the command line, rather than using a commercial program.