Hugo All Kinds Theme

Hugo theme for handling all kinds of pages

Proposed design

Rethink how to add project doc to Hugo. It doesn’t have to be sui generis.

Project ideas (lead) can be blog post (is Category appropriate here?)

Design details for a project can be pages under folder. Sequence by weight (autogenerate?) Date metadata not important, position in project TOC is.

Project TOC spans multiple pages. Blog post TOC doesn’t.

API doc (from godoc)

New project: _index.md content is project overview, front matter names the project.

Chrome:

Project page:

  • title – project
  • subtitle – site name
  • left nav – RSS page list, including curr page TOC at appropriate spot. (page.TableOfContents)
  • right panel – content
  • native order: configured sequence

Blog page:

  • title – site name
  • subtitle – site tag line
  • left panel – content
  • right nav – about, related,
  • native order: posted (or modified?) date

Pagination:

  • 1 . . . drill . . . <last>
  • <prev> Drill down <next>
  • Need breadcrumbs if offer drill down.

Open questions

  1. [Resolved] Page properties inheritable from section? Then project index could default project name, category. And new page might only have a few distinguishing props.

    Not in general. But section list template can refer to .Section or similar to access parameters defined exclusively in section _index.md. Page cannot override.

    Cannot, e.g define category or tags in section index, that will remain a page-specific thing.

  2. But see: $.Params – documented to look first in page FM, then in site paramaters.

  3. can use slice A B C to invoke (a partial) with a list of things, or dict K1 V1 K2 V2 ... to invoke with a property bag.

  4. Modified date provided automatically?

  5. If no Title, name from file name | title?

  6. [resolved] template folder structure follows content (e.g content/{blog, projects} ==> layout/{blog,projects}/{list,single}.html). Hugo page.Type is the best variable to distinguish templates (better than .Section or .Kind, I think?)

  7. $. refers to initial value of . when template invoked.

To document

This is the menu in the chrome above the section or site title. It highlights the section you are currently viewing.

In config.toml:

# specify name of main menu
[params]
   mainMenu = "masthead"
. . .
# (optional) configure any static (external) links via standard menu config
[[menu.masthead]]
  url = "https://a.b.c/d/e"
  name = "abc"

In the section index _index.md for each section that you want to appear in the menu:

+++
title = "The long-awaited Foo project"
linkTitle = "Foo project"    # link title used for menu entry, if defined.
menu = "main" 
+++

Do likewise for /content/posts/_index.md, if you want your blog to appear in the menu.

Mermaid support

Enable mermaid-js diagrams embedded in fenced code blocks

​```mermaid
graph
    A --> B;
    B --> C;
​```

Using a trick documented in: https://discourse.gohugo.io/t/use-mermaid-with-code-fences/17211

Note: this fix is fragile. It configured mermaid to process <div class="mermaid-language"> which is what goldmark does with unrecognized code blocks.

Blog title in blog’s _index.md not params

Since we now have multiple sections, use the section’s _index.md (or index.md) to specify the section title and subtitle, as well as other items section-wide items (menus?) that might otherwise be expected in config.toml.

Project landing page.

The site home page is a list of blog posts, rendered by a list template. This makes sense for the blog because it doesn’t have a sidebar to show a list of other posts. Likewise taxonomy and term landing pages. These are rendered by a canonical list.md which doesn’t have a side bar and does render a list of items from the current section in the body panel.

But the landing page for a project is different. It wants to show project overview in the body panel and to have a sidebar that lists other pages in a static order. Yet it must have kind == section in order for the .CurrentSection to be the project folder not its parent. We “finesse” this by:

  1. Naming the landing page _index.md, so it’s considered a section file and will be rendered by a layout/projects/list.html template.
  2. The list.html template content looks very similar to the projects/single.html template, except the page title is not rendered at the top of the content body, as it would be for a normal page. This template does have the usual sidebar and does not render a list of items from the current section.
  3. Formatting the landing page like a standard single page, except it has:
    • menu = <name of main menu> so the project link appears in the main menu
    • weight = 10 so the landing page appears first in the list of section pages
    • title and description for the project as a whole, not the page in particular
    • content below the front matter that is a full page project overview.