Migrating from Hugo to Lichen

date: 2023-01-01

I have been using the popular Hugo static site generator to publish the retroedge.tech website. I like Hugo, but it was time for a change in how my website looked and functioned. I could have used a different theme with Hugo to get the simplicity that I was going for, but I wanted a challenge.

The change was inspired by seeing the announcement of the release of the Lichen CMS, version 2.0. The author had rewritten Lichen in the Forth programming language, it had previously been PHP. I very much appreciated the clean design of the demo website.


The syntax that Lichen uses is gemtext, the format used by the Gemini Protocol. It is much simpler than Markdown, the default format that Hugo uses. That simplicity does mean that I loose some of the features that Markdown had. Right now, I am liking that. There's a "why gemtext" point on the Lichen website that I resonated with:

Constraints breed creativity

As I went about converting my Hugo website to gemtext, I found that to be true and a welcome change.

An Introduction to gemtext

Lichen CMS can be used as a Content Management System, but it can also be used as a static site generator (ssg). I am more interested in that approach, as I was already used to Hugo and am getting used to doing my writing and editing from within vim.

Writing gemtext files will also allow me to publish the same content by rsyncing the .gmi files to a Gemini server. I plan to do that.

Converting .md to .gmi

All my previous website posts were in the markdown format. I decided to use a converter program to generate gemtext .gmi files out of the files I already had.

I found a program called gemgen that was designed to do exactly that.


I decided to compile it from source. It is written in the Go programming language, so I had to manually install Go to get a version new enough to compile gemgen (the Go version in the Debian/Devuan repositories is one version too old). The instructions for doing so on the Go website were easy to follow and I had Go installed in little time. I was surprised at how large it is, though. The Go language compiler is hundreds of megabytes.

The build instructions for gemgen were also excellent and it also built a man page, too. After building gemgen from source, I ran it in the folder that I had copied all my previous markdown post files to and it nearly instantaneously converted the .md files into gemtext and outputed them to .gmi files.

I then used the Lichen ./build.sh script to transform those .gmi files to .html files. There was some leftover cruft from the Hugo metadata and not everything converted over perfectly, but gemgen is a great tool and saved me a lot of time.

I will be going over my old posts in the gemtext files and making some manual changes. I have an idea on how to handle tags, which is part of that "Contraints breed creativity" thing.


It did take me a while to figure out the look that I had envisioned. I wanted the retroedge.tech logo to be to the left of the text in a specific spot and float float there as you scrolled down. I finally found the solution by calculating its position from the center of the page.

background-image: url('./images/retroedgetech-logo.png');
background-attachment: fixed;
background-repeat: no-repeat;
background-size: 209px 209px;
background-position: calc(50% - 410px) 50px;

I also changed the accent color that came with the Lichen template CSS to the orange color from my logo.


I copied the deploy script that I had made for my Hugo website, which just uses rsync, and made a few changes:


rsync -avz --delete gemtext/*.html user@server:/var/www/html/

rsync -avz --delete gemtext/images/ user@server:/var/www/html/images/

Note: deploy script modified slightly for publication so as not to show full paths or server info.

Special pages

I made an index.gmi as my homepage and a subscribe.gmi as a way to let people know about my RSS, email newsletter and Fediverse accounts. Then I made slight modifications to the footer template to include links to them.

An About page and Tags pages are planned for the future.


There's just a great feeling that I get writing posts in vim, running the build script and then the deploy script to publish. It all feels so clean and fast.

tags: #gemini #gemtext #hugo #smolweb