How to add a structured documentation page within my website?


I started using Hugo recently to build my website for my music application. I reused the Navigator theme and was able to tweak it like I wanted thanks to the docs -and a lot of trial and errors…

Now I’d like to add a page for the documentation/help within this site (ie with same header/footer). The main part of this help page should be very classic: on the left a fixed hierarchized list which show help topics, and we display the selected help content on the right part.

The help topics list and the help contents would be automatically built from .md files found in a content subdirectory.

What would be the simplest way to achieve this ?

Using the “Theme Components” approach, I tried injecting parts of the Hugo techdoc in the Navigator theme, but I was not able to make it work correctly.

Any help welcome…

I would start with different sections, the help-section use a different partial for navigation on he left site.

You can hold the names identical, one with help-prefix.

You can use a map to assign the pages (see dict, scratch etc…)

Hope this gives you some ideas to go on.

Thank you but I did not really understand your recommendations : why using different sections ? I checked the dict function but I also don’t understand why I need it…

I made a few tests and I think I’ll do like this :

1/ Create a content/doc section directory

It will contain .md files for each help page. I will use a file naming convention, so that the alphabetical order can be used as the display order in the side menu. I’ll add a frontmatter variable “help_heading=true/false” so that .md’s title rendering in the side menu can be differentiated (I want to keep simple so there will be only 2 hierarchical levels).

2/ Create layouts/doc directory

Override single.html and list.html so that they both just display .Title and .Content.

Override baseof.html to enclose the {{ define main }} with the HTML code for the side menu and the content part. Side menu will not depend on the current page, it will be filled by listing the .Title of all .md files found in the “doc” content directory, sorted by filename, and with special rendering if the help_heading param is true. Content part will just be {{ .Content }}

Does this look right ? I’ll try this tonight…

Looks right :wink:

my mistake
if you will do different docs and helps -> go different sections
But your help is under /doc - this is fine