Document your work with Hugo


#1

My first Hugo website was fairly complex. It is our corporate website. My second website, an online Magazine (shameless plug: https://www.thefreebundle.com) is at least 50% less complex.

The complexity has nothing to do with Hugo, but in how I was used on doing things with other CMS and server-side coding against doing them with Hugo.

To keep it short, the main issue for me was working my head around making my own templates, templates I can use through the website in the form of shortcodes and partials.

My Corporate site is not your regular Hugo site. Hugo has been designed to do blogging, mostly. All right, argue me that point, but that’s what it felt the first time I played around with it.

Now, my Corporate site has nothing to do with a blog, though it has a blog.

I successfully managed to mix shortcodes with partials to create an awesome super website that it’s really easy to use and update–but not as easy as the online magazine I created months later.

So what to do?

Well, the best I did (in my sheer ignorance, I can’t code, forgive me) was to create a documentation for the corporate site.

And what best tool than ANOTHER Hugo Site!

Every time I finished a feature, I created a new post in my corporate setup!

Guidelines and styles where created, besides technical notations on how to create, modify and update each part of the website.

I recently revisited the corporate site and all I’m doing is updating the CSS code. The Hugo installation, even when it’s been updated to the latest version, works flawlessly.

So, with that in mind, here are my recommendations:

Hugo for Documentation

Nothing faster than firing up a Hugo folder in VisualCode and adding a new entry.

My weapon of choice: the Cupper Documentation Tool theme.

https://thepaciellogroup.github.io/cupper/

Simply download, unzip (or better yet, fork) and that’s it. Another Hugo theme, with the wonderful characteristic, that it actually helps you documenting your project.

  • Built with Hugo, so easy to structure content and fast to compile it
  • Available to read offline, as a Progressive Web App
  • Include encapsulated live demos, inline with your markdown, using Shadow DOM
  • Quickly include WCAG and Inclusive Design Principles references
  • A responsive, screen reader and keyboard accessible static site as output
  • Automated Github Pages deployment
  • Includes a single-page printable version suitable for PDF conversion

This thing was specifically designed to work as a documentation tool. It has everything you need to document your project.

This is how it looks.

And this is the Dark Theme (switches back and forth with a click, no complex theming)

As the writing of this post (Jan 2019), nothing beats this theme for documentation. MediaWiki you say? Okay, let’s see…

Hugo vs MediaWiki

As someone who is already using a MediaWiki to document another project, I can honestly say documenting ANY software development with Hugo, even websites, its a must.

My MediaWiki servers as a sort of Library/Archive for several projects. It has its advantages for sure, but its greatly surpassed by Hugo.

  • In MediaWiki exporting/importing pages its a mess. You have to go through either a database exporting/importing process, or you have to relay on the .xml exporting feature (which usually turns into errors). Images are the biggest problem: MediaWiki has a very messy folder structure for images. You can literally end up with hundreds of folders with names as ridiculous as /a_S/ so you will never know where the image is and you’ll end up downloading it from the wiki page itself.

  • Hugo does this simple: export/import? Copy and paste your .md pages to another Hugo installation, though there is no real need for that since you can move around the public folder as you please. Images are exactly where you left them. No databases, obviously!

  • In MediaWiki if I want to have a special section on the page I have to add a “template” with wiki markup, which you have to learn and document separately if you want to keep things together and in relative order. Even with templates, there are limits to what one can do.

  • In Hugo I simply create a shortcode and that’s my special section on the page. There are no limits to what one can do with shortcodes, really. I’ve done enough to asseverate that.

  • In MediaWiki, if you update the core app, you risk losing everything. E-V-E-R-Y-T-H-I-N-G, so you better backup (did I mentioned backing up was a mess? Read the first point on exporting/importing pages)

  • In Hugo I simply update the Hugo Binary and call it a day. No database to risk. Takes literally 2 seconds.

  • MediaWiki has inner links for creating relations between pages through wiki markup.

  • Hugo has shortcodes, which themes such as Cupper use to create inner links, exactly like MediaWiki does.

Conclusion

In short, there’s no reason for me to keep using MediaWiki other than a very cool thing I did with it where I can read a QR Code on one of my physical archives with my cellphone and the MediaWiki searches the page on the fly on the computer, bringing it up in front of me, gangsta style.

I’ve been using Hugo for documenting my corporate site and I’ll be moving all my other projects to Hugo, plus, starting a small blog with it for my fiction writing.

Can’t say how happy I am. My tip? Use Hugo for documenting your projects if they are fairly complex: it will make you SMILE!


#2

Great share - tnx!


#3

@Javier_Cabrera I had no idea the The Paciello Group was still making tools. I’ve used their 508/accessibility tools back in the day but never checked their site again. Thanks for sharing this. I’m a fan of simple black-n-white designs so this is giving me some ideas.


#4

I liked this project so much, I made it into a hugo theme


#5

amazing man, good work! I’m picking up with Hugo fairly quick, soon I will be able to do what you just did here for the community!