understanding types, layout and menus in Hugo

[epogrebnyak]

Our situatoin: we started working with project structure based on https://github.com/h-enk/doks/tree/master/content and soon realised if we are not putting new markdown files in docs folder we get wrong and distorted layout.

So our questions were:

• what controls indiviual page layout
• how menus are built
• how do we make different left-side menu for different types

Our understanding so far:

Types:

• Hugo assigns type to a document based on content/<type1>/something.md folder structure
• there is no predefined list of document types, Hugo will create list of document types based on what it sees in content folder
• archetypes do not control whet types are availaable, they are helper templates
• is there is layout/<type1> folder, Hugo will use the layout fromt that folder to render something.md
• otherwise Hugo falls back to layout/_default - we have not changed it, so it may be responsible for rotten layout

Menus:

• menus seem like building a tree for Site.Menus - is it correct that menu.toml and front matter are used to create some structure for Site.Menus, but the point when menus it actually affect layout is when Site.Menus in layout and partials?

• I was surprised by behavior when some menu was not listed in menu.toml, but if it appeared in front matter - we still had it in rendered page, so it took time to adjust menu.toml is not the only place that controls menu-building.

• in Doks theme there are four types of menus: main, docs, footer, social. I wonder where this is defined? I assume main, docs, footer, social become effectful when used in layouts? there is not other mechanism

• is this true in menus.toml we can have [[xyz]] and then this xyz becomes Site.Menus.xyz, and when it is used in some layout (or partial), this starts to affect the rendering result

• is defining a new menu in front matter equally valid as defining it in menus.toml?

• what does this structure mean in front ? menu is front mater tag, then docs is what - Site.Menus.docs variable? where does extras have to be defined? menus.toml? what is extras called? I think the meaning is subsection in docs, but maybe there is nothter term.

menu:
  docs:
    parent: 'extras'
    weight: 20

[epogrebnyak]

@necelentano - the above summarises my findings about Hugo menus, please add if you have some quastion related to how hugo works with menus, types and layouts - you can write in Russian and I can translate.

Hope to get @webuimaker to answer and comment in this thread.

[webuimaker]

Menus:

• menus seem like building a tree for Site.Menus - is it correct that menu.toml and front matter are used to create some structure for Site.Menus, but the point when menus it actually affect layout is when Site.Menus in layout and partials?

[yes ots using .toml to render menu and also used front matter like docs left side menu ]

• I was surprised by behavior when some menu was not listed in menu.toml, but if it appeared in front matter - we still had it in rendered page, so it took time to adjust menu.toml is not the only place that controls menu-building.

[yes, hugo have option to render menu as per the frontmatter under content like docs - > left sidebar menu]

• in Doks theme there are four types of menus: main, docs, footer, social. I wonder where this is defined? I assume main, docs, footer, social become effectful when used in layouts? there is not other mechanism

[its also define under config-> menu.toml]

• is this true in menus.toml we can have [[xyz]] and then this xyz becomes Site.Menus.xyz, and when it is used in some layout (or partial), this starts to affect the rendering result

[yes]

• is defining a new menu in front matter equally valid as defining it in menus.toml?

[yes likr [[]socail]]

• what does this structure mean in front ? menu is front mater tag, then docs is what - Site.Menus.docs variable? where does extras have to be defined? menus.toml? what is extras called? I think the meaning is subsection in docs, but maybe there is nothter term.

[it's used for render page menu and as per this extras is the parent ]

menu:
  docs:
    parent: 'extras'
    weight: 20

[epogrebnyak]

I think the key to understanding left menus in this partial:

https://github.com/necelentano/finec-mgimo-v2/blob/df9a97040ea5f3efc632ab81d58f83f39a3b2e36/layouts/partials/sidebar/docs-menu.html#L1-L13

My takeaways:

• docs name defined in menu.toml and affects .Site.Menus.docs variable
• name doks embedded in assets/scss a lot, so the name is not really replacable
• the partial above is responsible for laying out the left sidebar in html

Not clear to me:

• is ther is a section s like tutorials of probuct as seen in other examples, what do they do to make a different left section