Books - multi-page subsections

[dnym]

So I've been meaning to update my personal website and decided on Hugo with this lovely theme Hinode, in large part because of the docs section. I don't plan on writing documentation as such, but I do want a section where I can post longer multi-part texts, such as tutorials; I'll call these entries/subsections "books". In case it would help anyone else looking for something similar I thought I'd describe how I did it. In the end I did not go the docs route.

The demo site is here, with code here. (The books' dummy content is ChatGPT generated.)

First, books is just added to the config as another entry in sections under params.home.

The content itself I ordered as a books list page e.g. example.com/en/books/; below that are book pages describing each book, e.g. example.com/en/books/my-book/. For my examples I created parts and chapters, although parts are chapter aliases; e.g. example.com/en/books/my-book/part-1/chapter-1/. Only the actual chapter pages are single pages, while the book info pages are list pages (linking all chapters in the current book). The home page and the books list page should only link to book info pages, not chapters, so I put nested = false in params.sections.books in the config.

Even though I don't use the docs-specific functionality I wanted to get the sidebar menu to work. I put content in files in the data folder, but I could only get it to work if I collected all books in one file, but then every book would list each chapter of every other book. I created files like data/books/my-book.en.yaml, but that's read into the wrong format for the "menu interpreter". I edited the layouts/partials/utilities/GetMenu.html file from mod-utils to check whether the first menu read fails because it's a map[string]interface {}, if so try using a custom per-content-page field sidebarFilename with or without language code (e.g. en) to get the menu contents.

I wanted tags to work for book info pages, so I also had to edit layouts/tags/list.html to iterate not just over normal pages {{ range .Pages }}, but all pages: {{ $tag := lower $page.Title }}{{ $allPages := where .Site.Pages "Params.tags" "intersect" (slice $tag) }}{{ range $allPages }}.

Finally, looking at the fiction books dummy content I realized that using page description as lead paragraph isn't quite the right thing to do. I wanted the chapter listings to show short synopses so I used the description field for that, and a synopsis is a weird way to open a chapter. There should probably be a difference between a page description and its lead paragraph for non-fiction content as well, where a description should be a concise... well, description, e.g. "In this article we compare and contrast foo and bar, and examine alternatives such as baz." A lead paragraph may be more conversational, like "Have you ever wondered why people like foos and bars? Today we'll take a look at these fan favourites, and even explore some lesser known alternatives. Let's dive right in!"

So I added an optional lead field to the content pages, and changed layouts/_default/single/header.html to use .Params.lead instead of .Description, and inserted a line in layouts/_default/list/body.html to use it on book info pages.

And that's pretty much it, although I had to do some more things to get the demo site to work.

[markdumay]

Thanks for sharing @dnym! Great example of how you adapted the theme to your needs.