Hello! I wanted to tell you all about an open source project I’m working on that I’m pretty excited about. It’s called Tract and it’s a Hugo theme for large documentation projects. I aim to release version 0.1.0 by the end of 2019. In the meantime, check out the current home page or a sample docs page.

Or check out this screenshot of a docs page:

Or this screenshot of the landing page:

Anyone who knows me well (in the tech industry at least) knows that I’m a major Hugo bigot. It’s not the easiest tool to love—it has quite the learning curve and some of its core concepts, like sections, feel pretty clunky even to me—but it’s unbelievably fast and extremely flexible. It’s big and bad enough to handle the Kubernetes documentation (which I work on) with aplomb and features like Hugo Pipes are simply a delight.

I’ve been working with Hugo a ton the past two years and wanted to crystallize my hard-won knowledge into something that can benefit others.

Project status and goals

Tract is currently in a pre-alpha state (issues very welcome!). I’m still hammering out the basic aesthetic and making low-level design and organizational choices. But my goal is to make Tract an industry standard. Here are some of my guiding aims:

• Sane defaults, deep customizability — Documentation projects using Tract will be gorgeous to look at, even with zero customization. Some of my current design inspirations include the docs for Algolia, Google Cloud Platform, Stripe, and various Hashicorp tools. I want you to have something nearly as beautiful (for free!) in minutes. But I also want to enable you to customize just about everything, not just the color scheme and fonts. You should be able to select one of several styles for the sidebar navigation, the header nav, the page-specific table of contents, the footer, and so on.
• Built-in search — I do really like tools like Algolia, and I’d like to enable people to use it with Tract, but I also want to provide an out-of-the-box search capability that doesn’t require a third-party platform. This is something I built for the docs for the Jaeger distributed tracing platform by having Hugo generate a big JSON object for all of the docs. This isn’t a super scalable option but works great for smaller projects.
• Versioning — Most large docs projects have a concept of versioning, with a version selector widget. This is usually a pretty painful thing to have to build yourself (I’ve done it many times) and I don’t want anyone to have to do this themselves. This will be a few months out (and non mandatory) but is very much on the roadmap.
• Internationalization — Hugo has fantastic built-in i18n primitives. Tract will eventually have a built-in language selector and first-class support for as many translations as you have the resources to provide.
• Dark mode — This is a longer-term goal, but I love how the Docker docs have a dark/light mode selector. So extremely slick. This is hard to get right because you basically have to structure your entire Sass/CSS stack to accommodate it, but might as well reach for the stars here, no?
• Taxonomies — Hugo has a great taxonomies feature that is under-utilized in other docs themes. I want to make extensive use of tags, categories, etc. for use in large projects with hundreds or even thousands of pages.
• Fun goodies — The possibilities are endless. Project timelines, fancy release notes, diagram tool integration, copy/pastable code snippets. Anything that you’ve seen and loved in other docs is a candidate for consideration.

Why not {insert other theme}?

There are many Hugo themes for documentation out there, but I find them all extremely lackluster. You can see a listing of documentation themes on the Hugo site. They feel like afterthoughts and weekend projects to me. Even the venerable Google’s contribution to the space, Docsy, feels disjoint and wayward. Some of the other themes are just plain ugly to me.

What can I say, I just know that I can do better 🤷🏼‍♂️

The “stack”

I’m using a web design “stack” that I’ve grown quite accustomed to over the last year or so:

• Bulma — My love affair with Bulma began back when I put together the docs for Apache BookKeeper and has grown since. I even created a “dashboard” extension a while back that’s seen some usage in random projects (I also learned a ton about Flexbox building that extension). I like Bulma for two main reasons:
  • It has a “batteries included” approach that provides a total CSS solution. I rarely need to build my own components and I can always opt out of components I don’t use.
  • I find the aesthetic much more to my liking than Bootstrap, Foundation, and others. Many of these are fine and can be customized to provide a sleek, contemporary look and feel, but Bulma gives me the kind of aesthetic I want by default.
• jQuery — I know it’s not cool anymore but I don’t need React.js or Vue or anything crazy like that. Just about everything in Tract is accomplished with plain old HTML and CSS, and jQuery is plenty powerful for the bits that go beyond that.
• Hugo — Already covered above 😀
• Anchor.js — Provides nice clickable/linkable anchors for Markdown content
• Tocbot — Hugo does have built-in support for tables of content but I don’t love it. It only generates a big blob of HTML, which can be styled sort of to my liking, but Tocbot provides the kind of fine-grained configurability that’s important for such a crucial UX feature.
• Popper.js — I love really nice tooltips and Popper has always been my go-to solution. Nothing has come along to dethrone it.

Contributing

Even though Tract is in a pre-alpha state (but almost there!) I’d love to get feedback and feature requests. Feel free to tweet at me or open an issue.

No pull requests just yet, please, but that will change soon 😎