Picking a static site generator
There are so many static site generators (SSG) out there - 347 according to JamStack. The amount to choose from is overwhelming, and when the last thing you remember is Wordpress.
When I was looking for a SSG an internal documentation site I tried many of the ones out there. I did have some criteria:
- It needed to be usable to non-tech users
- No command line tools
- Publishing needs to be automated
- Be usable for documentation
- Historical tracking
However, though I was looking for a documentation framework, I wasn't looking for an API oriented one. This was more along the lines of an online handbook or procedure guide.
Though this may seem like a paid article, I can assure you I am not paid to write these things. I have paid for a full version of Retype, but thats because it fits my solution perfectly
Old system
Before I wanted to deep dive into finding something that would work across from multiple users, and have a near-to-none learning curve I was using Microsoft Word.
I created my own custom style, made it essentially align with HTML (h1
through to h6
, code blocks, quote blocks, etc).
What ended up happening was the document became so cumbersome to navigate, use, and at the end open. Before I pulled the plug on it, it was sitting at 226 pages, over 400 images, 17 chapters, and one large headache.
Once the document did load though, and new documentation had been inserted, the hardest part of the entire process was compiling to PDF, and being under the 30MB email limit.
I was converting, compressing, splitting, recompressing, combining - all to limbo under some email attachment threshold.
It ended up making me really slack on the updates because I would queue them to only deal with the process once.
Migrating from DocX
You'd think the migration was inevitable at this point, but it actually started as a look into adding .docx
files into git. I had document tracking, but I also wanted revisions like git provides.
Though there are a few tutorials out there, it is honestly not worth it. Forcing a file into a tracking system it is not designed for was the first mistake.
However, after discovering the large amount of SSG options, porting from document to markdown was fairly simple. There are some online services out there which will do it automatically, but I did it manually since I could comb through it all and edit.
One cool thing I found though was if you change your .docx
extension to .zip
and unarchive it, you will find all your media under uncompressedFile/word/media/
. This meant I could easily move them over to use in markdown without having to re-capture everything.
Shortlist
Publii
I started out with Publii
because it has an interface and an installable app. It meant that the learning for others would be the easiest, and more intuitive.
Building it to the custom design started to get convoluted though. I felt at a certain point, outside of using the templates, you may as well use Hugo or other leaf templating systems.
Publii
is great if you want an off-the-shelf solution, but it didn't pass the criteria option 4. It is good for blogging, but I couldn't get it working great for documentation.
But then it got to pushing in a corporate environment. Running non-authorised applications on work machines, as well as sitting behind a proxy - to put it simply - was a pain. Onwards..
Docsify.js
I really like docsify.js
because it is the smallest learning curve.
This framework was a no-compile solution. All I had to teach was how to write in markdown. Once we got over that hurdle, publishing documentation was ver simple and quick.
Docsify was actually very simple and integral I ended up writing three plugins:
The best part was once a user pushed the markdown, everything compiled user-side. No need to build, run an action, or update auxiliary files.
We used Docsify for about a couple of years, but found a few short comings:
- Heading anchors would shift after images loaded
- Some pages wouldn't load - hash routing would timeout
- Javascript would sometimes report console errors
- Deep customisation limits
After searching I tried a couple of other generators - Publish and Retype.
Publish
At this point I was deep into learning Swift, and thought centralising all the development and languages into one would make it more streamlined.
I was already building this site with Publish, and loved the customisation. But I quickly realised that it would be a large step backwards in the criteria.
Retype
Enter Retype app.
After trying to build many components for Docsify and forcing a framework to be what we needed it to be, Retype has it all.
Built in is everything a normal SSG has, but then it has an extensive component library.
What I love about Retype is the full customisation that is built in, hidden pages, slugs, and a built in Github action for publishing.
It seemed that Retype is the combination between Docsify simplicity, and Publish customisation. Also being in active development and using Github discussions was an added bonus.
Some negatives to the framework though:
- Limit of 100 pages on free tier
- Limit of 1000 pages on paid tier
- Unable to host completely offline
Conclusion
It's been a long journey searching for the perfect static site generator for documentation. I've gone all-in on Retype, and even use it for some smaller sites. But I still use Docsify when I want full customisation, and simple updates without needing to rebuild or remember all the command line tools.