docsy VS hugo-blox-builder

> cd (The root directory of the Git project. themes exists in current) > git submodule add https://github.com/google/docsy.git themes/docsy

Site URL Hugo theme introduction https://themes.gohugo.io/themes/docsy/ Sample/Demo https://example.docsy.dev/ Documentation https://www.docsy.dev/ Repository https://github.com/google/docsy

A set of Hugo documentation templates for launching open source content. Use case(s): Documentation Author: The Docsy Authors Minimum Hugo version: 0.73.0 Github stars: 1706 Last updated: 2022-05-14 License: Apache-2.0

Download Docsy Docsy demo site ​​​​Minimum Hugo version: 0.73 GitHub stars: 1.7k License: Apache-2.0

Background: I've been a technical writer for 9 years. 6 at Google, 3 as the only writer at an IoT startup.

I helped Corrily with their docs [1] in August. They were interested in readme.io. I wasn't keen on it because I had worked with Retool a few years back and had found readme.io lacking. But I was pleasantly surprised by how much readme.io has progressed since then! If you're looking for a documentation product that is very easy to update and mostly just works, then it's worth checking out.

On https://web.dev I was introduced to Eleventy. Eleventy [2] is now my go to. The documentation for Elecenty itself is very strangely organized and needs a refactor. But I have found that there is always a way to accomplish whatever I need, and usually elegantly.

Another project worth checking out is Docsy [3]. This is a Jekyll template specifically created for technical documentation.

Back at the IoT startup I had to set up the whole documentation system / tooling myself. I used Sphinx and deployed to Heroku. Haven't used Sphinx since then but I remember being satisfied with it back then.

[1] https://docs.corrily.com

[2] https://11ty.dev

[3] https://docsy.dev

I haven't used either of these, but I've heard good things about both https://github.com/google/docsy and https://thegooddocsproject.dev/. If you choose to use either of these, I'd love to hear about it. I have coworkers who contribute to both of them.

Have seen similar reports in the past about Academic, such as https://discourse.gohugo.io/t/hugo-academic-adapting-old-hero-widget-css-custom-code/31611 and the related https://github.com/wowchemy/wowchemy-hugo-themes/discussions/2213 (and this particular oddity illustrates perfectly why growing numbers of Hugo afficionados think the “themes-first” approach of Hugo documentation is flawed) — but, of course, none of that helps you now. Does your project have a public repository for viewing, since the Academic documentation is (as you say) unhelpful?

If you're building a personal website from scratch in 2021 (especially a blog), I strongly recommend Hugo over Jekyll. I had used Jekyll for a decade and very often hit random quirks that have been completely eliminated with modern Hugo. However, there's a bit of a migration process if you are moving from Jekyll to Hugo despite both being Markdown-based blogs.

If you want a more advanced framework for a personal website, I recommend Wowchemy (https://wowchemy.com/) on top of Hugo, which gives the tools needed out-of-the-box like lazy loading/SEO/object-oriented collections, albeit with a massive learning curve.