Clarifying Params and Themes for new users

[seffw]

This looks like such a good system. But it seems it's aimed at a select few who are lucky enough to know what the documentation means.

For example, there is a mention of .Params.categories. But no way to know how to use it. The only use of it in the themes is within the post itself. And how is this different to Taxonomies? (but this is an example only. Every part of Hugo's docs is like this).

Each theme appears to be a whole site. For example, simple-a. I have tmy Hugo site folders, and the same folders exist also within the theme. So it's not a theme. It's a complete site. But a site that also looks in my folders. Do you see how confusing this is? Theme separation is a must unless we want to go backwards.

So I have an idea.

Is there a very typical website plus blog example, with theme intergrated? This project needs a tutorial to re-make such a site, and explain the concepts (with examples!) along the way.

I would happily contribute to this tutorial (once I'd figured it out from the example). If it stays as-is, this project will be great for some and a waste of time for others (and that is a sure way to see an open-source project not get the usage it deserves).

[natefinch]

I'm sorry the docs aren't helpful for you, but I understand it can be overwhelming.

For a very typical sure, try my blog, npf.io - it's just a blog with a few standalone pages. The first few posts talk about how I set it up and there are links to the github repos where you can see the exact code.

Hopefully that'll help. We are trying to work on the docs to make them more clear and to have a more basic example site to make it easier to get up to speed. On Sep 13, 2014 2:58 PM, "simplyeffectiveweb" notifications@github.com wrote:

This looks like such a good system. But it seems it's aimed at a select few who are lucky enough to know what the documentation means.

For example, there is a mention of .Params.categories. But no way to know how to use it. The only use of it in the themes is within the post itself. And how is this different to Taxonomies?

I've been around and around, and the more I try the mor confusing it gets.

And then there's the themes. But each theme appears to be a whole site. Tryign to use simple-a, I have my site folers, and the same folders within the theme. So it's not a theme. It's a site. But a site that also looks in my folders. Do you see how confusing this is?

So I have an idea.

Is there a very typical website plus blog example, with theme intergrated? This project needs a tutorial to re-make such a site, and explain the concepts (with examples!) along the way.

I would happily contribute to this tutorial (once I'd figured it out from the example). If it stays as-is, this project will be great for some and a waste of time for others (and that is a sure way to see an open-source project not get the usage it deserves).

— Reply to this email directly or view it on GitHub https://github.com/spf13/hugo/issues/507.

[seffw]

Wow, what a quick response. I meant to suggest I'd help, but I got carried away.

I'm in two minds how to proceed. The two options are 1) continue with Hugo but get involved (I couldn't use it and watch it continue as it is with this awful approach to documentation) or 2) move on.

It's not my first open-source project. I saw how close Drupal got to being obliterated by Joomla due to similar things I see here. Drupal became much more newbie friendly just in time.

What is going to put tons of people off, and what Wordpress does so well, is the appearence (or lack of) simplicity. Tags, categories, params, taxonomy, template variables. It makes Drupal seem simple, and it makes Jekyll seem incrdibly straight-forward.

Yet, I really get the impression Hugo is excellent, once the developer's logic is understood.

I'll take a look at your blog, thanks..

If I try to continue with Hugo, I'll think how I can contribute to the docs. A separate start to end tutorial seems the best way.

And themes......... they need to be separated as a theme only layer. This is a must nowadays.

EDIT: removed unhelpful harseness, and the bit about themes

[natefinch]

Try going through the quick start and let us know where the problems lie. I do think there needs to be a more gentle introduction. Keep in mind that this project is still pre 1.0, so it's still in the works. We'd absolutely love any help you'd be willing to give.

One problem is that the docs don't hide any of the complexity until after you get the basic concepts, so it seems like a lot, but you don't need to know most of it until you want to make your site more complex.

Also take a look at my other Hugo site http://npf.io/tod/ If anything, it's even more simple than my blog. Just some content and a theme.

There's a lot to do to clean up some rough edges with Hugo, but I think it's going to be big. On Sep 13, 2014 3:15 PM, "simplyeffectiveweb" notifications@github.com wrote:

Wow, what a quick response. I meant to suggest I'd help, but I got carried away.

I'm in two minds how to proceed. The two options are 1) continue with Hugo but get involved (I couldn't use it and watch it continue as it is with this awful approach to documentation) or 2) move on.

It's not my first open-source project. I saw how close Drupal got to being obliterated by Joomla due to similar things I see here. Drupal became much more newbie friendly just in time.

What is going to put tons of people off, and what Wordpress does so well, is the appearence (or lack of) simplicity. Tags, categories, params, taxonomy, template variables. It makes Drupal seem simple, and it makes Jekyll seem incrdibly straight-forward.

Yet, I really get the impression Hugo is excellent, once the developer's logic is understood.

I'll take a look at your blog, thanks..

If I try to continue with Hugo, I'll think of how I can contribute to the docs (personally I;d scrap them and start again, they add more confusion than help). A separate start to end tutorial seems the best way.

— Reply to this email directly or view it on GitHub https://github.com/spf13/hugo/issues/507#issuecomment-55503749.

[natefinch]

Oh yeah, the code for the tod site is at github.com/natefinch/tod

[seffw]

I thought the gentleness of the Quick Start was fine. But I wasnt looking for a gentle start. The site I wanted to create was in my head. Not such a simple one.

But the issue with the docs is not just about the docs. Yes, they need real-world examples / use-cases / context (at least one of those). The bigger issue is the logic in Hugo for some things.

1) The initial issue with the docs is description out of context. Back to my example of .Params.categories. The only way to try to use it is trial and error. The doc has no use case or example.

2) Hugo needs to be much clearer with the different forms of taxonomy / metadata. There seems to be a lot of crossover (this is how it appears anyway). Tags and catgories have logic. But what then is taxonomy? Surely it is categories. And template variables are like tags? I would put a lot of money (if I had it) on Hugo not being big unless this is changed. This is not just a docs issue.

3) Themes. In Hugo, theme are not themes. Templates are themes. Themes are site samples with different layouts (my Hugo structure has identical folders in my site and my chosen theme. This is not logical. The theme should be the layout, not something that includes the layout).

The real shame here is the first imprssion of Hugo is wow! But then it becomes a muddle.

[seffw]

Hey, by the way, my frustration is not with you or the developer. Apologies it comes across like that. My frustration is with seeing such potential not be useable (by many). Really appreciate that you are given this your time.

[natefinch]

I think a lot of it is docs because there are done obvious misunderstandings. Categories and tags are examples of taxonomies. They are just some default ones that come used by some themes.

Definitely the docs could be better about use cases, and I think that would help a lot.

Themes include default templates so that you can get up and running without writing your own templates. You may override any of those templates by making them in your site under layouts. Templates are the code that transform a piece of content or a list of pages into a webpage. Themes need to specify several of these to make a usable website.

The idea of themes is that you can just write your own content, and never need to touch a template, and still have a usable site. That's the theory, anyway. On Sep 13, 2014 3:45 PM, "simplyeffectiveweb" notifications@github.com wrote:

I thought the gentleness of the Quick Start was fine. But I wasnt looking for a gentle start. The site I wanted to create was in my head. Not such a simple one.

But the issue with the docs is not just about the docs. Yes, they need real-world examples / use-cases / context (at least one of those). The bigger issue is the logic in Hugo for some things.

1) The initial issue with the docs is description out of context. Back to my example of .Params.categories. The only way to try to use it is trial and error. The doc has no use case or example.

2) Hugo needs to be much clearer with the different forms of taxonomy / metadata. There seems to be a lot of crossover (this is how it appears anyway). Tags and catgories have logic. But what then is taxonomy? Surely it is categories. And template variables are like tags? I would put a lot of money (if I had it) on Hugo not being big unless this is changed. This is not just a docs issue.

3) Themes. In Hugo, theme are not themes. Templates are themes. Themes are site samples with different layouts (my Hugo structure has identical folders in my site and my chosen theme. This is not logical. The theme should be the layout, not something that includes the layout).

The real shame here is the first imprssion of Hugo is wow! But then it becomes a muddle.

— Reply to this email directly or view it on GitHub https://github.com/spf13/hugo/issues/507#issuecomment-55504659.

[seffw]

Categories and tags are *examples of taxonomies. They are just some default ones that come used by some themes.*

That makes much more sense. Thanks for that. And a great line to add to the docs.

Re. themes, I have to say I find that logic difficult to grasp. To me, what that is, is a complete site, with the part Hugo is not calling theme is just the textual content created by the user.

What I see as a new user is a duplicate (almost) of the structure of my site and the structure of the theme. I would find that very hard to work with.

I've been experimenting, The only logical way I can go fowards is to take my chosen theme (simple-a) and combine it with the Hugo created site, and remove the Themes folder. This makes a far more logical site in my opinion, and one that I could see docs and a tutorial being built from.

[natefinch]

You definitely can just use the theme as the basis of your site and not have a theme folder.

The idea is that the theme gives you a default that you can then selectively override in your actual site, then can easily switch out the theme to make site look completely different but with same content. On Sep 13, 2014 4:44 PM, "simplyeffectiveweb" notifications@github.com wrote:

Categories and tags are *examples of taxonomies. They are just some default ones that come used by some themes.*

That makes more sense.

Re. themes, I have to say I find that logic difficult to grasp. To me, what that is, is a complete site, with the part Hugo is not calling theme is just the textual content created by the user.

What I see as a new user is a duplicate (almost) of the structure of my site and the structure of the theme. I would find that very hard to work with.

I've ben experimenting, The only logical way I can go fowards is to take my chosen theme (simple-a) and combine it with the Hugo created site, and remove the Themes folder. This makes a far mor logical site, and one that docs and a tutorial could be built from.

— Reply to this email directly or view it on GitHub https://github.com/spf13/hugo/issues/507#issuecomment-55506148.

[seffw]

You definitely can just use the theme as the basis of your site and not have a theme folder.

Yes, but that to me is an issue. It should not be the case if what we want is a theme in the sense of what most users will expect (based on the usual definition).

This complication / confusion is clearly highlighted on this page http://hugo.spf13.com/overview/source-directory/ where even the example organisation structure is mixing layouts and theme. The html files in Layouts would be specific layout, yet the theme is shown as 'hyde' (so what is the theme doing?). There is no separation here. The theme in this case is just acting as the default layout.

Perhaps this seems just to be perspective. So if this is the way it works, what would be more logical is not to have duplicated the folders. Again, referring to the above link, if we could look a few levels deeper into 'hyde' we'd find the folders we already have, duplicated (except for content).

The more I look at this, the more I believe the issue is the structure and logic of the system as much as the docs. Perhaps it's just me though. But it's the first time (really the first) where I've spent hours with a new website system and got nowhere near what I wanted to do, and still without understanding the logic behind it.

Therefore I won't take up more of your time. I hope you're right that it'll be big. Potential looks big. I just don't think I can be along for the ride. And thanks again.

[seffw]

To finish on a more helpful note, here is a visual of what worries me with the approach to structure and themes.

Here is the current approach:

archetypes content indexes layouts public static themes ----- [themname] ---------- archetypes ---------- indexes ---------- layouts ---------- static

Really, this is a site within a site. There is no theme layer, only that the site within contains more layout. One thing the CMS journey taught us is that theme separation makes for happier developers. As it is, the simiplicity of changing themes feels a bit gimicy, due to this non-separation, because this simplicity ends once you realise you end up with two sites to work with rathr than one.

Bear in mind, I'm not entirely clear what 'indexes' should contain in terms of data vs layout. It seems to be a mix as it is. So that might need to be adjusted in the following examples.

Here is alternative approach #1, with a focus on theme / layout separation:

content indexes public themes ----- [themname] ---------- archetypes ---------- layouts ---------- static

Alternatively, #2 is taking the approach Drupal and some other CMS systems use:

content layouts ----- theme ---------- [themname] --------------- archetypes --------------- indexes ---------- all --------------- archetypes --------------- indexes ----- static public

Or an alternative to this, #3, if the 'layout' folder is needed within the theme:

content style ----- theme ---------- [themname] --------------- archetypes --------------- indexes --------------- layouts ---------- all --------------- archetypes --------------- indexes --------------- layouts ----- static public

My examples above, I think, show a better way to separate theme. This mix of layout, theme and indexes, all of which affect data and layout may not go down well with developers like me with a CMS background (which I think will be quite a lot).

One other major recommendation I have for Hugo (which I think currently will put off many style and protocol-obsessed coders, of which I am probably one) is changing the .html file extension for files that contain Go. I guess the obvious solution is .go.html. The reason is that, in some cases a site before static generation will still contain pure html files. Mixing those two seems an unnecessary confusion.

---

Finally, there is taxonomy. The confusion in the docs and example sites / themes about this will I think turn many away. In fact, when starting the server you are given a list (globally) of how many categories. But '.Params.categories' is an empty variable except within posts (this is where i go to).

So, although the need for getting a static blog made today means not using Hugo (sometimes open-source site generators can bite you by simply working against you), I do see a light at the end of the tunnel here. So if there is a site using most of the features shown in the docs (especially tags used in posts, categories used outside of posts, other taxonomy used, along with regular pages plus blog posts), once I get time again I would like to try to understand it and then create a tutorial for re-creating it.

[natefinch]

So, the directory layouts you suggested seem no better and in some ways worse than what we have now.

Honestly, #1 doesn't make any sense. You don't have layouts in the base site, so you don't have the same default & override behavior where the theme has a default that your specific site can override.

2 & #3 aren't terrible, but archetypes is default metadata, so probably

should go under layout. Also, I don't like treating the layout for your specific site as if it's just another theme. It's not, it overrides the theme. That's why it deserves to be at a higher level in the directory structure.

Also, indexes is not a thing... that's what taxonomies used to be called, but I don't think it was put in its own folder.

I could almost sort of see something like this:

content style ----- themes ---------- [theme_name] --------------- archetypes --------------- layouts --------------- static ----- archetypes ----- layouts ----- static public

(basically put everything that isn't content in its own subdirectory)

But it makes it more difficult to get to your layouts and such. This doesn't really gain you much except requiring another directory change when you want to edit your layouts etc.

I think your point about the layouts being .html when they're not really .html is valid. It would be easier to tell what's a template and what's not if they ended in .tmpl or something. As you said, .go.html might be the best solution, that way html highlighting/autocomplete still works in your editor of choice (I assume that's why it was html in the first place).

Certainly the docs can be improved, and taxonomies are a little tricky to wrap your head around. I almost wonder if the name itself is a problem... if we just called it like "customizable tags" it might be more obvious... since most everyone is familiar with how tags work, and taxonomies are just tags you can call by different names to separate them out into their own buckets. Hell, maybe buckets would be a good name :)

On Sun, Sep 14, 2014 at 4:41 AM, simplyeffectiveweb < notifications@github.com> wrote:

To finish on a more helpful note, here is a visual of what worries me with the approach to structure and themes.

Here is the current approach:

archetypes content indexes layouts public static themes ----- [themname] ---------- archetypes ---------- indexes ---------- layouts ---------- static

Really, this is a site within a site. There is no theme layer, only that the site within contains more layout. One thing the CMS journey taught us is that theme separation makes for happier developers. As it is, the simiplicity of changing themes feels a bit gimicy, due to this non-separation, because this simplicity ends once you realise you end up with two sites to work with rathr than one.

Bear in mind, I'm not entirely clear what 'indexes' should contain in terms of data vs layout. It seems to be a mix as it is. So that might need to be adjusted in the following examples.

Here is alternative approach #1 https://github.com/spf13/hugo/pull/1, with a focus on theme / layout separation:

content indexes public themes ----- [themname] ---------- archetypes ---------- layouts ---------- static

Alternatively, #2 https://github.com/spf13/hugo/pull/2 is taking the approach Drupal and some other CMS systems use:

content layouts ----- theme ---------- [themname] --------------- archetypes --------------- indexes ---------- all --------------- archetypes --------------- indexes ----- static public

Or an alternative to this, #3 https://github.com/spf13/hugo/pull/3, if the 'layout' folder is needed within the theme:

content style ----- theme ---------- [themname] --------------- archetypes --------------- indexes --------------- layouts ---------- all --------------- archetypes --------------- indexes --------------- layouts ----- static public

My examples above, I think, show a better way to separate theme. This mix of layout, theme and indexes, all of which affect data and layout may not go down well with developers like me with a CMS background (which I think will be quite a lot).

One other major recommendation I have for Hugo (which I think currently will put off many style and protocol-obsessed coders, of which I am probably one) is changing the .html file extension for files that contain Go. I guess the obvious solution is .go.html. The reason is that, in some cases a site before static generation will still contain pure html files.

Mixing those two seems an unnecessary confusion.

Finally, there is taxonomy. The confusion in the docs and example sites / themes about this will I think turn many away. Especially the fact that when starting the server you are given a list of globally how many categories, yet '.Params.categories' is an empty variable except within posts (this is where i go to).

So, although the need for getting a static blog made today means not using Hugo (sometimes open-source site generators can bite you by simply working against you), I do see a light at the end of the tunnel here. So if there is a site using most of the features shown in the docs (especially tags used in posts, categories used outside of posts, other taxonomy used, along with regular pages plus blog posts), once I get time again I would like to try to understand it and then create a tutorial for re-creating it.

— Reply to this email directly or view it on GitHub https://github.com/spf13/hugo/issues/507#issuecomment-55519445.

[seffw]

First off, I appreciate the structurss I'm suggesting may be lacking due to my limited knowledge of Hugo. So please take them as nothing more than representations (the indexes folder was in the site created by Hugo, or in the theme I don't remember which).

1 I believe is similar to how Jekyll does it (if not Jekyll it was one of the node.js generators I tested).

Reviewing what I wrote, #2 seems the most logical. What I don't get is the repetition of folders.

So, in my opinion:

content style ----- themes ---------- [theme_name] --------------- archetypes --------------- layouts --------------- static ----- archetypes ----- layouts ----- static public

would be confusing due to the repetition. I have never seen a system (static site generator or CMS) repeat folders in it's base form (as your example and how Hugo with a Theme is).

Things that I think I see differently:

• the concept of overiding Themes. To me it should be the other way round
• I see no reason why a deeper folder cannot be an override for a higher level one (if that makes sense)
• If it is part of the Theme, then it shouldn't be overridden (in my opinion). Themes should do the overriding (if anything at all)
• multiple duplicate folders for overrides does not make sense to me. In that case, really what you want is a different / modified theme, or a subtheme (but they can be a mess).

What also seems to be confusing is the collation of data and layout with Templates. The question that needs to b clarified is, are they part of Theme or not? At the moment they seem to be both (data collators but also block layouts).

I would say they should not be a part ot the theme, unless a theme overides them due to specific styling needs. This would then put the theme as the override.

So if it is not Theme but can be overriden by the Theme, or alternativly if it is said to be a part of the Theme, then this goes some way to determining structure.

I do realise that my limited Hugo knwlegde may mean I am missing some details. But overall, not have repeated folders is a must, with the exception of where it only has the purpose of overriding.

So two alternatives based on your suggestion, would be:

#4 (Templates as part of the site, not Theme, but potentially overridden by Theme):

(templates = what I was originally calling indexes, what Hugo docs call Templates)

content templates style ----- [theme_name]
---------- archetypes ---------- layouts ---------- static ----- custom (layout overrides) public

#5 (Templates as part Theme):

content style ----- [theme_name]
---------- archetypes ---------- layouts ---------- templates ---------- static ----- custom (theme layout overrides) public

[spf13]

I appreciate your feedback. Feedback is the back on which true progress is made. I believe Hugo isn't perfect yet. It's early in the project and we're constantly learning from the different ways people are using Hugo.

Allow me to respond to some of your statements.

I have never seen a system (static site generator or CMS) repeat folders in it's base form (as your example and how Hugo with a Theme is).

That means we've either done something really right or really wrong ;). I'll explain lower why we did this.

Things that I think I see differently:

the concept of overiding Themes. To me it should be the other way round

If it is part of the Theme, then it shouldn't be overridden (in my opinion). Themes should do the overriding (if anything at all) multiple duplicate folders for overrides does not make sense to me. In that case, really what you want is a different / modified theme, or a subtheme (but they can be a mess).

I have a pretty strong opinion on this. I've used a lot of CMS systems. Drupal 4 - 8, Wordpress, Jekyll, Django and a bunch more. A universal problem I've encountered is that whenever you choose a theme it's very very hard to customize it. A lot of wordpress themes build in special admin screens just for their themes to customize it, but these only work with predefined customizations and are done at great cost to the theme author. Typically people just make modifications directly to the theme and consequently make updating the theme to later versions a very painful process.

With Hugo I sought to make it very easy to customize a part of a theme without breaking any upstream capabilities. I wanted to do so in the simplest way possible. The idea to let users extend themes by supplementing their own files seemed like a great way to do it. No additional work is required by the theme author. No heavy lifting is done by the user. This completely avoids the need to do anything like child themes which are always overly complicated in my experience.

I think it's a valid point that keeping the site specific style information in the root may not have been ideal, but it does serve a purpose. It keeps the site specific information all together. Additionally all of the directories are 100% user definable. If you don't like them in the top level then put them wherever you want. It's a single line change to the config file.

I see no reason why a deeper folder cannot be an override for a higher level one (if that makes sense)

I think this is a valid point. In fact within the themes that's exactly how they are designed. When a more precise template is present it will be used instead of the default one. So I agree this is how it should be within a theme / layout and also how we currently do it.

By grouping themes together in a single subdirectory it makes it very easy to have the themes directory be it's own git repo or subrepo. In practice this works very well. I store the site in it's own repo and then the themes I use the global theme repo. I can independently update this as needed without disturbing the site.

What also seems to be confusing is the collation of data and layout with Templates. The question that needs to b clarified is, are they part of Theme or not? At the moment they seem to be both (data collators but also block layouts). I would say they should not be a part ot the theme, unless a theme overides them due to specific styling needs. This would then put the theme as the override.

I don't follow this at all. I think you mean correlation?. Themes don't contain any data. By definition themes/templates do need to be aware of the data passed into them. There is a very strong correlation between a template and data out of necessity.

In Hugo and virtually any other site generator, users define their own metadata. Hugo makes it especially easy to do this compared to other solutions like Wordpress & Drupal.

Because in Hugo each post can define the fields of data important to that post and a template must reference them specificly, Hugo developed archetypes as a bridge between the two. An archetype is a representative of a type used as a model to create new content. It specifies the fields that the template will use. Because it's a relationship between a template and the content it can accompany the theme where the template resides.

A huge amount of experience and a good amount of thought has gone into each of these decisions. I think that as you take the time to use the software you will come to understand why these and many decisions like them were made.

[github-actions[bot]]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.