Questions about the quick start guide

Using Themes
2

The “maintenance mode” message was posted on 3 Jan 2024 by one of the original Ananke maintainers, both of whom have left the project. Nine months later, on 23 Sep 2024, the original maintainers announced that @davidsneighbour was taking over the project.

Whether the Ananke project lead plans to add new features is a question for him, but he has put many hours of effort into the project since taking it over. Thank you @davidsneighbour .

Regarding the quick start guide and why it shows theme addition via Git submodules, I’ve written about this before:

  1. Adding a theme as a module has two dependencies: Git and Go. While you and I may consider Go installation a trivial task, our user base has a broad range of experience and skills, and this may be an impediment[1] to trial and/or adoption.
  2. When you add a theme as a module, the components (layouts, assets, etc.) are not visible. That means that a new user has no idea how the site is rendered, which template to override, etc. To see components they must run hugo mod vendor which copies the files to the _vendor directory, find what they need to find, then remember to delete the _vendor directory so that they can update the module in the future using hugo mod get -u github.com/user/hugo-theme.

We are working on restructuring the documentation. This includes a concept page describing the three methods to add an existing theme: cloning, adding a Git submodule, or adding a Hugo module. The quick start guide will (most likely) reference these methods, but will be modified to use something like:

hugo new site my-site
cd my-site
hugo new theme my-theme
echo "theme = 'my-theme'" >> hugo.toml
hugo server

The result is a functional example that:

  1. Doesn’t require Git, Go, Dart Sass, or Node.js
  2. Is always compatible with the current version of Hugo
  3. Demonstrates a subset of current features
  4. Is easy to explore and examine

  1. Either technical or, more likely, conceptual. “I don’t know Go.” “Go’s a programming language but I’m not a programmer.” “You mean everyone on my team has to install Go?” ↩︎

5 Likes