Docsy Theme to-do

Converting the blog and projects site to Docsy Hugo theme.

Docsy theme seems to have most of the bells and whistles I was looking for in my own All Kinds Theme. It has blog but also room for project-oriented sections (which in the authors' minds, are for documentation, not design.) It is also modular and extensible, so I believe I can add the features it doesn't provide.

Another advantage of Docsy is that it is aware of colloquial Hugo, and encourages the author to leverage Hugo in the "right" way. I was unaware of colloquial Hugo, so first, I have to undo some tangents I went off on.


Front matter "image" vs "images"

"images" (array) is supposed to name all the resources in the page bundle (mostly for the convenience of SEO?). I was using "image" as the name of the post cover image, and simple markdown for other images.

Docsy makes this easier: I can use a file naming convention: the cover image shall be called featured-background in the page bundle, and does not need to be named in FM at all. This image will automatically be resized appropriately. Typora won't show it unless I reference it explicitly, but at least I can use WYSIWYG for the other images. The alternative is to use two screen editing, keeping one screen open on a hugo-server-generated preview, then I can use all the fancy shortcodes on all the images.

Blog categories

Again, less front matter. I can put posts in categories by creating sections (subdirectories with and putting the posts (or page bundles) there. I don't do this much.


Docsy provides distinct templates for blog/ and projects/ sections and already provides section index in left nav and page TOC in right.

All changes to the theme shall be done by override files in the blog, not in the theme. Docsy assures me the search order is blog first, and that would be great if true. Will create a resync issue when I pick up changes to the theme, though.

To-dos, all templates:

  1. Remove 'edit this page' links in right nav
  2. List templates show page summary, not description

To-do, blog template(s)

  1. consider removing right nav. Don't need page TOC on a blog post.
  2. shoehorn tags or tags cloud somewhere. Consider whether reverse chrono of blog posts is correct thing for left nav.
  3. Title shows post tags and categories?
  4. List template in content shows list of posts and summaries not descriptions. Don't show left nav, it's redundant??

Todo, project templates

  1. list page doesn't show list of pages, just content in leave left nav as is.
  2. Convenient way to show pages in a good order. hugo uses .Params.weight for this, but that's awkward to manage.

To-do, home page

  1. Should show list of blog posts

Changes made

All changes made as local project overrides of theme files of the same name. Thank you, Hugo or Docsy for making this possible! In the future, I will have to reconcile updates in theme files back into the project overrides, but that's OK.

  1. Override SSCS variables -- none, actually, so far.

  2. Remove 'edit this page' and 'submit issue for this page' from right nav.

    Did it by unconfiguring github path in config.toml, not deleting the <div>. Rest of the theme gets out of kilter.

  3. Move 'print entire section' link to footer.