Clarifying Params and Themes for new users #507
Comments
|
I'm sorry the docs aren't helpful for you, but I understand it can be For a very typical sure, try my blog, npf.io - it's just a blog with a few Hopefully that'll help. We are trying to work on the docs to make them
|
|
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 |
|
Try going through the quick start and let us know where the problems lie. One problem is that the docs don't hide any of the complexity until after Also take a look at my other Hugo site http://npf.io/tod/ If anything, There's a lot to do to clean up some rough edges with Hugo, but I think
|
|
Oh yeah, the code for the tod site is at github.com/natefinch/tod |
|
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.
The real shame here is the first imprssion of Hugo is wow! But then it becomes a muddle. |
|
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. |
|
I think a lot of it is docs because there are done obvious Definitely the docs could be better about use cases, and I think that would Themes include default templates so that you can get up and running without The idea of themes is that you can just write your own content, and never
|
|
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. |
|
You definitely can just use the theme as the basis of your site and not The idea is that the theme gives you a default that you can then
|
|
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. |
|
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 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 Alternatively, #2 is taking the approach Drupal and some other CMS systems use: content Or an alternative to this, #3, if the 'layout' folder is needed within the theme: content 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. |
|
So, the directory layouts you suggested seem no better and in some ways Honestly, #1 doesn't make any sense. You don't have layouts in the base #2 & #3 aren't terrible, but archetypes is default metadata, so probably Also, indexes is not a thing... that's what taxonomies used to be called, I could almost sort of see something like this: content (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 I think your point about the layouts being .html when they're not really Certainly the docs can be improved, and taxonomies are a little tricky to On Sun, Sep 14, 2014 at 4:41 AM, simplyeffectiveweb <
|
|
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 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:
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 #5 (Templates as part Theme): content |
|
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.
That means we've either done something really right or really wrong ;). I'll explain lower why we did this.
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 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.
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. |
seffw
changed the title
|
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. |
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).
The text was updated successfully, but these errors were encountered: