Treat everything like a Page

[mattstratton]

Much of the logic/structure in this theme is heavily dependent upon data files, and a lot of inefficient queries. Modern Hugo treats every element as a Page object, which drives more of the information into the frontmatter elements instead of where we do it with a lot of looping queries based upon file locations. I suspect we could get more efficiency by pushing things down to the Page levels

Page Bundles

Here's what I wrote on this topic in 2020:

If we refactor how content is organized, we can leverage Page Bundles, which would allow us to group resources associated with an event in one place (and which gives us the ability to do some clever things with processing the files in the Hugo part itself, rather than trying to do things in build pipelines, etc). Here is a helpful post with some pros/cons to bundles vs static folder.

I wrote some code back in 2020 that implemented this, and I don't recall all the discoveries that I came up with, but I'll do some digging and update this thread with what I find.

File structure

I have made the argument before that the filesystem for a lot of this is unwieldy. Of course changes to the paths for events would need to be handled with redirects or alias so that old URLs don't break. But for example, I see something like this:

content/
└── events
    └── 2020
        └── ponyville
            ├── index.md
            ├── logo.png
            ├── speakers.md
            └── speaker-images
                └── twilight-sparkle.jpg
        └── hoofington
            ├── index.md
            └── speakers.md

So what you have there is a generated path of devopsdays.org/events/2020/ponyville which would want to make sure to have redirects created for backward-compatibility so that devopsdays.org/events/2020-ponyville still works.

The data directory has already been refactored to fit this model, so this would keep them parallel.

Alternatively, we could have city be the top level with subdirectories for the years, as mentioned in Taxonomy and layout discussion.

Migrate from data files to Page frontmatter

Again, here's words I wrote back in 2020. Similar to Bundles, i did work with this. There are some challenges with it, which I'll list some of them after this and others later.

This is a big one, and it might not work out super well. Much of what is in the data/events/YYYY-CITY.yml files could be moved to frontmatter for the Pages; the challenge I see is there is data that is used on multiple pages (although TBH there isn't that much). Data fields that are used by more than one page are:

city - this is the "friendly" name of the city. It's used in a lot of places, I think.
year and name - these are used in a lot of places, but to construct queries. They probably aren't needed anymore, and if they are needed, can be obtained via the file path.
ga_tracking_id - the Google Analytics UA ID. This is used (when set) on every page for the event.
cancel - while not really used by pages themselves, used for queries. TBH this probably is handled in frontmatter of the index.md page for the event and queries will hit that, the same way they use the dates, etc.
startdate, etc - there are multiple date fields which are used on event pages, but also in "top level" page queries (open CFP, etc). The start/end date fields could be in index.md and the cfp related ones in propose.md, etc. I think we could probably figure out how to query against that (pseudocode - "select all pages of type propose where cfp end date is greater than now", etc)

Navigation is currently handled in the data file; instead it could simply be built by iterating through the pages in the event's directory. If someone wanted a link that wasn't to a Page, we could provide docs on how to do that (you would actually create a page for it, with no content, and maybe of the type "redirect" with frontmatter of the actual URL, and it would do two things: one, if someone hit that path somehow, it would redirect there, but the menu building logic could be like "range through all the pages; if it's type 'redirect' then make a different URL, but otherwise pull the name or something to make the menu")

Sponsor stuff is currently all in the data file; this one would be trickier. I don't have any ideas for this yet.

The other data elements are all very page-specific and would be able to be moved to frontmatter.

One thing that came up with this was that our use of date/time in the data files is very lenient, which doesn't translate well to a proper date/time in Hugo frontmatter. I wrote migrator to convert the data files to page frontmatter, but what i found was that I kept having to wait for it to spin and find a file with a malformed date, etc, and error out - at which point i would go and "fix" it in the source data file and then have to run migrator again. I suppose error checking in migrator would help this. It's not a reason to not do it though.

Change Program template to use Pages

Again, words I wrote in 2020. From what I can tell from devopsdays/devopsdays-web#9839, it was actually not that bad (at least in implementation; the migrator tool never got updated to migrate programs)

I believe that the data file concept for the Program makes is a lot more unwieldy. The program could be dynamically generated based on frontmatter elements (which the current script actually creates, but we don't use), i.e., the program element pages all have a date, start, and end time, and they get collected into one place, sorted, displayed, etc. This makes it a lot easier to create some custom program elements (you just create a Page for them).

Downside of that is things that have to go on the program that you repeat a lot, but don't want to create a whole Page element just for them (like breaks).

Maybe the Program gets actually done via shortcodes in the markdown; you have a list of the things for the day, and the shortcode takes arguments to turn it into what needs to be done. So, the program.md would look like this:

{{< program_element type="talk" name="twilight-sparkle" start_time="08:00" end_time="08:30">}}
{{< program_element type="custom" name="Morning Break" start_time="08:30" end_time="09:00">}}

Upon reflection, I can't see how that actually works, because of HTML. But I'm keeping the reference so that we don't think it's a good idea in the future.

Another possibility with the "get all the program elements from frontmatter of the pages in the program directory" is that the pages could support more than one start/end time (for the custom stuff like breaks).

It's a not trivial problem, that's for sure.

A simpler mechanism might be to create a script that will generate the program for you, based upon prompts, and it outputs it as HTML to the program.md page. The good part of this idea is that it's VERY easy to customize it later by hacking the HTML (if you wanted to do fancy things/stuff not supported by the default template, like having multiple blocks of ignites, etc).

Downside is that the script has to be where we make changes if we want to improve the styling, etc, of the program.

The other thing we could do is keep all the program layout in the markdown file, and just have the generated program be a "sample" and people have to do it manually. That's not great either. I think that the happy medium is to have a templated markdown file that people can use as inspiration, but also provide a script to make one based upon prompts.

---

More info on all these topics this and things I learned from doing it can be found here - #4

[nimbinatus]

Will chew on this more, but on the bundles: This actually might be really good to make a city landing page with the idea of changing the top level taxonomy to city vs year, with each year highlighted. So each city gets a permanent spot on an easy-to-find page; no more digging to find the city you want that might not have their year up. And then someone coming to sponsor or speak can pick the city and see at a glance which year is current (or whether you had your event yet). And that would also help with (1) I want to start a DevOpsDays in my city but I can't find a past example and (2) you can put high-level details about your city there. So, for example, for Austin I might put down a bit about our demographics and that we always have our event in May.

[mattstratton]

I’d say data files is not just no longer idiomatic, it’s the wrong solution and we will continue to run into issues with future Hugo if we are too dependent on our weird implementation because there’s literally nobody else using Hugo the way we are with them (I’ve been told this by Hugo maintainers before, that we are basically abusing the feature lol)

[mattstratton]

The other thing is with properly formatted front matter and consistent files, we can revisit better automation that doesn’t require editing actual files to do these things…

[mattstratton]

Although if it’s merge down, the logo/banner works , i get it now.

Also I don’t know that bundles actually work the way.

But keep in mind data files are not part of a bundle. So any “nesting” we do is our own logic we build ourselves.

[jerdog]

Sounds like what is being driven to is a sort of Headless Bundle implementation, which uses front matter to identify if something is published and letting the content be used on other pages.

Or are you thinking of using the branch bundle and utilizing _index.md to add front matter and content to home, section, taxonomy, and term pages (accessed via .Site.GetPage?

I've seen a lot of newer themes going the _index.md route for some useful nested structure.

[jerdog]

And to the larger question around structure, I personally feel like by city and then by year is a more useful, manageable tree