The test-level-minimum-for-content-and-titles branch will alway have the above level of minimalism. The master branch and future branches may add more than that (which may be appropriate depending on what it is for which you are trying to create a test case).
The purpose of the repo is not for CI or automated testing, but to have a set of minimal layouts for creating minimum reproducible test cases for reporting bugs to the Hugo developers.
I have a specific possible bug that I need to add a little more layout to test, and am planning on adding branches that properly support taxonomies and other features defined in hugoBasicExample site.
It uses modern Hugo and so far has only been tested against 0.81.0.
This has already proved more useful than expected as the minimal layout above and adding pagination works, which wasn’t the case with the more complicated layout to which I was adding pagination. So this has proven to me that the issue is why the more complicated theme and not a bug. Saving bep time is probably a good thing. (it’s also why I didn’t @ mention him in this comment).
@davidsneighbour : I appreciate the thoughts! I’m glad there is at least some interest in this.
I’m planning on adding taxonomies as a ‘level-2’ version of the theme (as many themes / sites are built without taxonomies, so for an absolute minimum test case they’re not needed, but there are cases where they are needed to trigger the behaviour one is testing for, so is still a useful minimum complete test case)
I like the hello world short code and will definitely add it
I’m not quite clear on what you mean by ‘a custom layout’. Do you mean just a ‘random (i.e. different from the default in some arbitrary way)’ layout that is accessed via layout: custom in order to be able have test cases involving the use of a custom layout? If so, that does seem a useful level-2 test.
On the problem of needing different test cases and therefore different ‘minimal’ themes:
How to make the test cases available
I initially was thinking of just using one repository and using branches
I think this gets ugly from deployment standpoint
OTOH having a separate repository per theme ends up with a great many independent repositories
Despite that, since some of the test cases I am thinking of will use Hugo modules, one really needs the separate repos
In addition separate repositories vs. separate branches doesn’t add to the problem that this isn’t as DRY as I would like (if modules were a required part of Hugo, this would be less of an issue IMO, but they are optional), and does help with the cases where Hugo modules are used, as Hugo/Go modules seem to require separate repos.
Where Hugo modules are in play, this is easier as the differences can largely be managed by having a common base and ‘composing’ a test theme with different modules (I hope).
I don’t want to add a lot of logic to the theme to do the ‘pick a test case’ thing, because in my view that is no longer a minimal reproducible test case situation, and is in fact adding a whole layer of complexity that then could cause issues.
Maybe I’m worrying too much; how many ‘minimal’ test cases can there be?
I am German and we coined the term “eierlegende Wollmilchsau” (egg laying wool-milk-pig), which basically means “one thing for everything”. So the level-2 way is not something I would go. It sounds like you would have to update all level-2 branches if you update something in your main theme. I would have solved that more or less by something like a “weird” taxonomy (for instance movie) that can be added to a sample repo by adding two lines of config. If those two lines ([taxonomies] and movie = "movies") are not added then the layouts just are there and are ignored. If I need to display a bug within the taxonomy system I would add those lines to my config, add movie: blafasel to my frontmatter in a post and we go from there. Your README.md would add a section that says something along the lines of “if you want to present a taxonomy issue add this to your config and that to your frontmatter”.
I would be ok and understand the level-2 concept, but if your project wants to make it easier for people that are not programmers you might want to go this way instead of introducing a branching system - I am afraid, not many are “versatile in Git”.
About the custom layout: yes, a quite common way to display things is a custom layout that is referenced via layout. One of the most common support requests for Hugo is some form of “layout priority issue” where layouts override each other depending on where Hugo is creating (sections, custom layouts, default layouts, etc.) - so a “default” custom layout would be nice. It would be enough to just have it say something like "custom: " before the title so it shows up on compilation. It might even make sense to have at least one sample-section (posts?) to have all three use cases available. Again - this should be something that might be configurable by using a certain term for the section name, so that a pretty simple content sample won’t “trigger” a section template.
I don’t want to add a lot of logic to the theme to do the ‘pick a test case’ thing,
But isn’t the “level-2” concept exactly that? I think it might be easier to make certain special cases configurable. It of course depends who your target-users are. In my mind it’s always “for the dummies” because “we geeks” know what we do and won’t need that.
Last note: please run hugo mod init danielfdickinson/hugoMinimalTestTheme (or something comparable) and add go.mod to your repo. That will instantly transform your project into a Hugo module and makes it much easier to be added to a repo. Sub-modules are nice, but they should be a thing of the past, hehe.
Heh! I’m more used to the ‘Unix philosophy’ (a tool should do one thing well, and one combine tools when one wants to do more complex things), although I’ve tended to find, as usual, the truth is somewhere in the middle.
I think this is a valid point, and the taxonomies case is one where there doesn’t seem to be a need to keep it entirely separate, since it only comes into play under the conditions you mentioned.
Come to think if it, I think using custom layouts to do things like adding pagination tests is a better way than branches as well. I also think I will add the go.mod (via hugo mod init) as well, as I realized that I don’t have to use module ‘stuff’ (like mounts) within the theme for the theme to be used as a module itself.
I was thinking separate repos or branches, but that’s a maintainability problem, and there is also, in retrospect, the problem of communication which repo or branch to use. If there is one repo with a README on how to configure the tests cases that makes a lot more sense than having multiple repos/branches. It’s easier for users to find and therefore use, which is ultimately the goal.
I still see a enough cases where they are being used (or even required), so I was hesitant to modularize, but I belatedly realized that being a module isn’t the same as using modules in the theme.
Not only that but by being a module, one can include instructions on how to include a module that adds tests cases (should any come up) that aren’t easily turned on and off via simple configuration.
So once again thank you for helping me think about this.
@zwbetz I love the debug table! I’ll have to think about how to add it to fit my goals, but it’s awesome (and enough leg work that I would likely not have added it on my own). I definitely want it to be available to users of the new minimal test theme that I’m working on.
I also like how you’ve done a really minimal theme, although not in the type of ‘layouts’ layout that a site is likely to have.
I’ve decided that I’m going to eliminate this branch now that I’ve implemented @davidsneighbour’s suggestion of using custom layouts to turn features on and off.
I assume you mean links to terms and taxonomies? The current behaviour is already to render the terms (not sure which template it uses by default) and the taxonomies using the _default/list.html. If one enters /tags in the URL of the test site, one will see the list of tags, and from there one can get a list of pages for a given tag.
I hope you’ll agree the repo is much more useful now, while still keeping the goal of being designed for the creation of minimum reproducible test cases.
So, the theme is, IMO, ready for others to take a look! I’ve added the debug table as suggested by @zwbetz and incorporated @davidsneighbour’s ideas/requests. I hope this proves useful to others.
Now back to the theme that got me thinking I needed this to do debugging…
I’d love to hear some feedback and/or hear about the results of applying this to various sites, remembering that this isn’t a be-all and end-all theme, but intended to allow creating test cases for debugging issues. In that respect it’s not as minimal as I’d prefer, but I did branch at an earlier minimal version, but I discovered there is a lot that can’t be tested if one is too minimal.
As with A Hugo 'debug table' module, I have archived the old repositories for this, and created new ones, that get the original purpose, “This theme is not intended to be used as a normal theme. It is intended as a framework for creating minimal reproducible test cases.”
I’ve decluttered the repo and removed all styling from the theme repo (although I do continue to use the debug tables styling because it makes the tables nicer to work with, but that is configurable via a site param).
I hope you find this undoing of the mess I made of things (which was exacerbated by trying to do my own git hosting; the repos are back on GitHub and will stay there) helpful and worth the time and effort.
Indeed you are correct. I appreciate the offer of a PR, however it reminded me there was at least one other fix to make in the READMEs and website docs as well, so I’ve done that and more (pushing shortly), with much thanks.
(it’s also why I didn’t @ mention him in this comment).
for helping me think about this.