Linode is a popular cloud infrastructure platform who run their documentation site on static site generator, Hugo. In this showcase, we’ll see how it’s put together.
There are over 14,000 pages on the Linode documentation side. Designing and developing the sidebar hierarchy to handle this amount of content is a huge undertaking, and for the most part, it works nicely. However, some of the menus can get lengthy. The one below has six levels 😱.
Linode needs a way to ensure new content is well structured and consistent with so many content types. That’s precisely what Hugo’s Archetypes do. Archetypes are a content template that has front matter and content. They’re essentially the same as a regular markdown file with a few extra features, such as the ability to have use Hugo templating in the front matter. Running
hugo new to create a new content file will use the appropriate archetype and put the content writer on an excellent path to consistency.
Linode uses five archetypes for their documentation site. Let’s take a look at default.md to see how it works:
This is a good demonstration of how powerful Archetypes are. The slug is initialized to the directory the file is in. The same goes for the title but replacing hyphens with spaces, and the date is set to now. You the full power of Hugo’s templating languages here, which gives you complete control over how new content is initialized.
The theme of this showcase is how to manage large amounts of content. Working with large quantities of content also means working with large amounts of assets.
When organizing assets on a Jekyll site, I’ll usually create a directory for assets. For small sites, all the assets live in this one directory. For larger sites, I’ll try to create subdirectories for each blog post or content page. The problem comes when content gets chopped, changed, and deleted. With this loose connection between content and assets, I often end up with many orphaned assets I’m not sure are used anywhere on the site.
Hugo has an interesting feature called Page Bundles which can make this a little less daunting. The way it works is content and assets live together like this:
If you want to add or remove content or assets, it becomes obvious where to do this and the dependencies involved.
The docs have a blog section that lists and categorizes posts from their blog. It doesn’t feel like a good spot for blog content. They already have a different blog, so why pull the content into here? While the idea is dubious, the implementation is pretty cool.
A painful way of doing this is every time a new post is published, you also publish a reference to it in the docs. Doing it this way would enviability get out of sync and be a headache to maintain. The solution Linode has come up with is to use Algolia. On this site, not only is Algolia used to power search, but it also powers the navigation and the entire Blog section. When the page loads, a query is sent to Algolia to get the number of items in each content type. The results of this query populate the navigation and the counts you see. Clicking into a blog category shows a list of posts. Again, while it looks like this content is part of the site, it’s actually an Algolia query to fetch the content. All the documentation site needs from Algolia is the title, short description, hero image, and a link to the post.
The blog can live on its own on a separate platform. When new content is added or deleted, Algolia is updated, also updating the documentation site. Super elegant.
One improvement that would be worth exploring is whether this content can be rendered in the source HTML rather than generated on page load. The initial query is about 100KB of gzipped data. On my internet connection, it’s unnoticeable, but on a slower connection, there could be a delay between page load and seeing the nav or the blog posts. Algolia also charges per 1000 searches, so they’re potentially spending a sizable amount just to render the initial state of the doc pages.
Hugo can query an external data source as part of a build. Using this feature would allow Linode to still have the power and flexibility of Algolia without having to do any queries on page load. It would also mean doing one query per build rather than once per page load. The downside of doing this is the potential for content to get stale, which can be addressed by scheduling a periodic build every hour (or whatever your tolerance is).
The Linode documentation is an excellent example of managing large amounts of content with a static site generator. Hugo is the correct choice for such a large site due to its speedy build times. Kudos to the Linode team for making their documentation site source code public so we can all learn and contribute to making it even better.
If you’re interested in using Hugo for your own documentation site, take a look at this Hugo tutorial, to get started.
29 November 2021
15 November 2021
8 November 2021