Alternatives to Hugo+Wowchemy

[rcannood]

I'm a big fan of static site generators like Jekyll, Hugo and now Quarto[^1]. I originally quite liked Hugo and Wowchemy[^2], since it offers a decent library library of building blocks which allows you to quickly build a website without a lot of effort.

Hugo+Wowchemy

However, IMO maintaining a site built using Wowchemy is difficult to maintain over time because the framework keeps changing and adding breaking changes in every release. Some of my biggest annoyances:

• First, the documentation keeps on changing. Since the documentation is not versioned and doesn't appear to be in a public repository, it's hard to find back how things are supposed to be developed for the version of Wowchemy we're using.
• Wowchemy introduces breaking changes in nearly every release and it fails to describe them properly in the release notes. The release notes aren't even in the same place. To upgrade from Wowchemy 5.2.0 to 5.7.1, for instance, I created diffs between every release of the template we originally used for the website and mimicked the changes for this repo. I also went back t
• Some of the new features (at least, I think they are new) don't seem to be working properly. At some point I tried to add a Collection block and without changing anything to the source, multiple renders of the same page would result in vastly different results.

Thus, I'd like to consider switching to something other than Hugo+Wowchemy.

Quarto

Ever since I encountered Quarto, I've been a huge fan. In essence, it's very similar to Hugo: A static site generator using markdown documents to store content. What I like about it:

• Quarto is way more suitable for writing technical documents because natively supports dynamic content with Python, R, Julia and even interactive content with Observable. This means code documentation can also be a unit test (because the website will not render if something is broken).
• I think it was mainly built because people at Posit were frustrated with certain limitations of RMarkdown, so they took a step back and designed something new.
• Since the developers already had experience with RMarkdown and pandoc, everything in quarto seems to be well thought out from the get-go.
• More active developers. Hugo seems to be maintained mainly by one person who has to make all of the decisions, while Quarto has three active developers and the Posit team behind it.
• Quarto natively supports interactive content !

One downside is that Quarto doesn't have all of the built-in blocks that Wowchemy has. However, it has quite a few already (e.g. about pages and listing pages), and the ones that do exist usually offer better customization than those in Wowchemy.

Others

Are there other alternatives that should be considered?

Demo

I pasted some of the content of our current website into a quarto web page, with pretty similar results. Since both frameworks have pretty similar functionality and notation, it was mostly a copy paste with some minor changes and fine-tuning of the stylesheet. Here are a few comparisons you could make between the two versions (both visually and based on the source code).

• Main page: Original (source), Experimental (source)
• Team: Original (source), Experimental (source)
• NeurIPS 2021 Documentation: Original (source), Experimental (source)

Maintainability

If I were the only person who knew how to build a quarto web page, the bus factor would not be that great. However, since most of quarto is just standard markdown and it only took 2-3 hours to port most of the content from openproblems.bio to openproblems-experimental.netlify.app, I'd say if I were to land under a bus somebody else would be able to pick it up quite easily. Also I've heard people at Helmholtz have also been picking up quarto recently (:eyes: @lazappi).

Summary

I'm okay working with Hugo+Wowchemy; I just notice that I spend so much time bumping into issues with Wowchemy that I know can be solved quite easily with Quarto.

[^1]: Though Quarto is actually much more than just a static site generator. [^2]: After all, my personal website was built with Wowchemy :)

[lazappi]

I haven't looked much at how the website works but here are some general thoughts.

• Similar opinion about Wowchemy, it's cool but I don't think it's reliable enough for something like this
• I think the priority is something that's easy for people to pick up and maintain. No good using a fancy framework if only a couple of people know how it works.
• We also don't want to create something completely custom
• Quarto is a great option if we need to run code during rendering. I'm not sure if this is necessary though or if we can just do plots etc. with JavaScript
• It's probably possibly to combine Hugo/Quarto with other frameworks/themes if needed (but I would stick with things that are well-maintained/commonly used)

[dburkhardt]

First, let's separate Hugo from Wowchemy. Wowchemy is templates and themes, Hugo is a static site generator.

It's not a popularity contest, but...

1. Wowchemy is popular with 7k stars on GitHub - https://github.com/wowchemy/wowchemy-hugo-themes
2. Hugo is even more popular, with 65k stars on GitHub - https://github.com/gohugoio/hugo
3. Quarto is up and coming with 1.8k starts on GitHub - https://github.com/quarto-dev/quarto-cli

Why does this matter? The more widely used a framework / theming system, the more likely someone is to know how to use it, find relevant answers on StackOverflow, have questions answered in a forum.

Upgrading versions Wowchemy used to have a script to help with version upgrades, but it looks like that's gone away. They do seem to have a "breaking changes" section to every release on their github page, and offer support for upgrading on Discord. @rcannood are those notes insufficient?

Another option

Why don't we pin wowchemy and develop additional functionality ourselves using custom templates? We don't necessarily need a whole theme, we can do just the parts we need.

[dsm-72]

Developer Manifesto

TLDR

• I don't think the thing we want to do (interactive, intuitive comparison of methods with dynamics / custom filtering) and the the tool we are using (static site generator Hugo that doesn't use components) is the correct pairing
• If I had to deploy a single MD file right now and had to choose between a metaframework (any of them Next, Nuxt, SvelteKit) or a SSG (Jekyll, Gastby, Hugo), I am using a metaframework

My 2 cents

Ultimately, my stance is as follows:

• whatever you want

Frameworks, frameworks, frameworks

In regards to frameworks, almost any time we broach this subject we look at JamStack, sorted by stars they are:

# Top 16 only
1. Next.js (Meta-framework for React with 97,399 stars)
2. Hugo (SSG with 64,086 stars)
3. Gatsby
4. Jekyll
5. Nuxt (Vue version of Next.js, 41,678 stars, and current personal fav)
6. Docusaurus
7. Hexo
8. Slate
9. GitBook
10. Astro (with 23,173 stars and up-and-comer)
11. Docsify
12. VuePress
13. MkDocs
14. UmiJS
15. Eleventy
16. SvelteKit (Meta-framework for Svelte with 11,477 stars)

Takeaway, stars are NOT the full story!

Please take a look at Frameworks by Usage and Satisfaction.

# Top 16 only
1. React (what Nextjs is built on)
2. Express
3. Next.js (1 previously)
4. jQuery
5. Vue (what Nuxtjs is built on)
6. Vite (made by the guy who built Vue and is rapidly replacing webpack everywhere)
7. Gatsby (Prev 3)
8. Nuxt.js (5 previously)
9. Angular 2+
10. 11ty
11. Svelte (what SvelteKit is built on)
12. SvelteKit (16th previously)
13. Jekyll
14. Angular 1.x
15. Hugo (Prev 2)                                  <--------------- big drop, and this is on usage and satisfaction
16. Preact

Key points?

• The "meta" of what is good and in is always changing.
• React/Nextjs is "grandfathered" in and any competing libraries that have new / better feature that Next/React might want eventually get consumed. If we care about "maintainability" as well as ensure that future developers will have familiarity from now until as long as possible, we are using Nextjs.
• Metaframeworks (nextjs, nextjs, SvelteKit, etc) produce static sites while allowing for more reusable / maintainable custom components (easier to debug and test since they are more bit-sized!)
• PURE SSGs (Hugo, Jekyll, Gatsby, etc) despite being high in stars are not what devs enjoy working with. Mostly because they are great at what they do (static MD sites) and painful at everything else. That doesn't mean they can't do it (JavaScript can do anything).
• SSGs have prebuilt themes for people who hate CSS or don't have the time for it (negated by style-component frameworks like Material Design, BootStrap, IBM's Carbon, etc)

Why care?

Mimicking PapersWithCode

If we are trying to mirror PapersWithCode maybe we might be interested in their techstack, which from StackShare states:

• Python (for Django and more seamless integration with their APIs)
• jQuery (for frontend nonsense)
• CloudFlare (for hosting)
• Bootstrap (for CSS)
• Django (for routing, deployment, user-auth etc)

Style

Fixing margins, etc? We use properly set up the theme of the CSS library we are using (bootstrap) and ideally make sure the template we are using (if we use one in the future) matches that library.

Interactivity

As we continue to try and add more nuanced features and fancier features, component-based frameworks (React, Vue, Svelte, etc) and meta frameworks (Nextjs, Nuxtjs, Sveltekit, etc) will be our friend. Yes Hugo has partials, but they are not ideal for managing state and reactivity.

response to lazzapi comments:

No good using a fancy framework if only a couple of people know how it works.

1. People know how they work. If not, there is no short of tutorials not to mention the premade free to use component ecosystem. They are called meta-frameworks because they not only handle larger problems but because the progressive state of web-dev (since their inception in 2016) has grown due to community support and adoption
2. Fancy ≠ bad. Fancy means all the hard stuff is taken care for you and you don't have to worry about it. For example USER-AUTH Hugo? Not supported. Nextjs, Nuxtjs, Sveltekit, Django, all built in.

I think the priority is something that's easy for people to pick up and maintain.

1. Yes that is why we should be using a component based framework with TypeScript. Components are smaller, more portable, and easier to maintain / test.
2. See previous comment on components and tutorials.

It's probably possibly to combine Hugo/Quarto with other frameworks/themes if needed (but I would stick with things that are well-maintained/commonly used)

1. With all things JS related, technically yes (and if no, just wait a year or two). Just depends on how bad you want it.

[dsm-72]

Also I also recreated the website 8-months ago in Nuxtjs with Vuetify

Screenshot free text conjunctive-normal-form supporting, timsortable datatable

Screenshot Highlightable, scrollable TOC:

[scottgigante-immunai]

I'm not going to argue the merits here because I mostly don't have a stake, but one important point in response to @dburkhardt's suggestion, which was also my first suggestion:

Why don't we pin wowchemy and develop additional functionality ourselves using custom templates?

The answer is docs. As far as I can tell there is no easy way to access old wowchemy docs. See https://github.com/wowchemy/wowchemy-hugo-themes/issues/2907

[LuckyMD]

Similar to @scottgigante-immunai, I also don't have a stake in this, and I just want it to work. It does occur to me that wowchemy has started several independent conversations now, and it might not make sense to hold on to something that everyone who is further developing the website at the moment doesn't like. As for what to switch to... I am more likely to be able to pick up quarto if it's RMarkdown-based... but I understand @dsm-72's arguments as well. If we are considering moving to hire a web developer in future, i imagine quarto may not be the most likely basis for that, but react or newer javascript-based tools.

[dburkhardt]

So I'm not saying we shouldn't consider moving to a different framework in the future. I just want to make sure if we switch, we make a single decision that we know will be long term maintainable and stick with it.

@dsm-72 brings up some good points about popularity != satisfaction. I didn't realize those kinds of metrics exist, and frankly I'm not surprised people don't love hugo, even though they use it. Thank you for bringing it up 🙂

I'd like to understand more about how metaframeworks could help us. My understanding is those sorts of tools are designed for web-apps, where users interact with a system to perform functions that alter the underlying state of the app. E.g. a user signs in, adds a picture, and that picture is now visible on the app to other users.

We don't have that though, we have an underlying database that we want to provide interactive visualizations for. This seems like a static site to me, no? How will a metaframework like Next.js help us? Can you provide specific examples?

[dsm-72]

Re: metaframewroks They are extra functionality for the corresponding underlying framework (e.g. React / Svelte). That includes static site generation and will compile and bundle components into the static site. Sort of an have your cake and eat it too.

Yes they can assist with that kind of state (e.g. user-auth), but we have state in our application. Specifically, raw vs scaled on our data tables, the table sort order, plots that may be based off of selected algorithms / methods, etc. We are not just displaying data. We are display data and then letting the user interacted with how it is displayed.

Writing a more usable DataTable component would be an example where we might very much prefer React/Vue/Svelte or their meta frameworks Nextjs/Nuxtjs/SvelteKit.

As for user login / user auth, we may want to one day let users submit via the frontend

[dburkhardt]

I had a bunch more questions, but rather than bother you @dsm-72 , I just asked ChatGPT. Can you confirm if this is correct?

Q: How do web metaframeworks like next.js work?

A: Next.js is a framework for building server-side rendered (SSR) React applications. It works by using Node.js to render your React components on the server, then sends the HTML to the client. This allows for improved performance, SEO optimization, and faster initial load times. Next.js also includes features like automatic code splitting, optimized asset loading, and API routes for serverless functions.

Q: What's the difference between Next.js and react?

A: React is a JavaScript library for building user interfaces, while Next.js is a framework built on top of React that provides specific tools and optimizations for building web applications.

React provides a basic set of tools for building UI components, but doesn't provide many of the additional features needed to build a full-fledged web application, such as routing, server-side rendering, and code splitting.

Next.js fills these gaps and provides a more comprehensive set of tools to build modern web applications. It provides server-side rendering out-of-the-box, automatic code splitting, optimized asset loading, and many other performance-enhancing features.

In short, React is a building block for UI development, while Next.js provides a complete framework for building web applications.

Q: What are the advantages and disadvantages of using a framework like Next.js compared to static site generator like Hugo? When might you want to use one versus the other?

A: Advantages of using Next.js:

1. Server-side rendering: Next.js provides server-side rendering out-of-the-box, which can improve the performance and load time of your site.
2. Dynamic content: Next.js is well-suited for sites with dynamic content, since it can fetch and render data on the server before sending it to the client.
3. API routes: Next.js provides built-in support for API routes, which makes it easier to build and deploy serverless functions.
4. Full-fledged framework: Next.js provides a complete framework for building web applications, including routing, code splitting, and asset optimization.

Disadvantages of using Next.js:

1. Complexity: Next.js can be more complex to set up and use than a static site generator like Hugo.
2. Resource requirements: Next.js requires a Node.js server to run, which can be more resource-intensive than a static site.
3. Steep learning curve: Next.js has a steeper learning curve than a static site generator like Hugo, which can make it more difficult for beginners to get started.

Advantages of using Hugo:

1. Simplicity: Hugo is a simple, straightforward static site generator that's easy to set up and use.
2. Performance: Hugo generates a static site that can be served directly from a CDN, which can lead to improved performance and lower costs.
3. Low resource requirements: Hugo doesn't require a server to run, so it can be more cost-effective and scalable than a framework like Next.js.

Disadvantages of using Hugo:

1. Limited functionality: Hugo is limited to generating static sites, so it's not well-suited for sites with dynamic content.
2. No server-side rendering: Hugo doesn't provide server-side rendering, which can limit its performance and SEO optimization.

You might want to use Next.js over Hugo if you're building a complex web application with dynamic content and need server-side rendering, or if you're using serverless functions and need built-in support for API routes.

You might want to use Hugo over Next.js if you're building a simple, static site and want a straightforward and easy-to-use solution, or if you want to minimize costs and resource requirements.

[dsm-72]

What’s missing is that metaframeworks can compile to static sites so that advantage of Hugo, simple serving, served directly, disappears

[dburkhardt]

Either way, Netlify supports Next.js out of the box, and we have a free OSS account, so I'm not so concerned with deployment.

[rcannood]

Welp. I apologise for having brought up this topic again.

I think we should still be a little pragmatic here. Ideally, I wouldn't change anything to the website (don't fix what ain't broken). However, I've been bumping into issues with Wowchemy a little too frequently.

The reason why I brought up Quarto is because I found porting content from Hugo to Quarto is actually quite easy and Quarto offers so much more functionality out of the box without having to install a theme with custom shortcodes on top.

In deciding which framework we might want to switch to, we should consider not only the technical pros and cons of that framework, but also what is the effort involved in recreating our current website.

I really want to avoid having to spend 6 months rewriting it from scratch in a totally different framework. Our previous experiments with Nuxtjs and Vuetify demonstrated that this can be non trivial.

It's interesting bringing ChatGPT into this discussion to help navigate the issue, though each of us can get the answer we want by typing the right questions into the prompt :stuck_out_tongue: . I tried my best to explain our current situation to ChatGPT:

Q: The website for OpenProblems is currently written with Hugo and Wowchemy, but we've been having some issues regarding maintainability thanks to Wowchemy frequently introducing breaking changes at every release. We're considering simply sticking with Wowchemy, using plain Hugo, switching to a framework like Next.js or Nuxtjs, or porting our content to Quarto. Can you explain the pros and cons of each of these approaches?

Sure, here's a brief rundown of the pros and cons of each approach:

Sticking with Wowchemy

Pros:

• The website is already built with Wowchemy and Hugo, so there will be no need to learn a new framework or port content to a different platform.

Cons:

• Wowchemy has a history of introducing breaking changes with each release, which can make maintaining the website difficult.

Plain Hugo

Pros:

• Hugo is a well-documented, widely-used static site generator that is known for its simplicity and speed.
• There are many resources available online to help with development and maintenance.

Cons:

• You may miss some of the features that Wowchemy provides, such as page builder, shortcodes, and other customizations.
• You'll have to invest time into building custom solutions or finding plugins that provide the functionality you need.

Next.js or Nuxt.js

Pros:

• Next.js and Nuxt.js are popular frameworks for building dynamic, fast web applications.
• They offer a lot of out-of-the-box functionality and can help with SEO optimization.
• Server-side rendering for improved performance.

Cons:

• The website would need to be completely re-written, as these frameworks use different technologies and architecture.
• The learning curve for these frameworks may be steep, especially if the development team is not already familiar with them.
• Potential performance issues if not properly optimized.

Porting content to Quarto

Pros:

• Quarto is a modern static site generator that is designed for ease of use and customization.
• Built specifically for writing and publishing books and technical documents.
• It provides a lot of the same functionality as Wowchemy, but with more stability and fewer breaking changes.

Cons:

• Quarto is a relatively new and less widely-used platform, so there may be fewer resources available for development and maintenance.
• The website would need to be ported to Quarto, which could take some time and effort.
• Smaller community compared to more established tools like Hugo or React.

In conclusion, the best option will depend on the specific needs and constraints of your project. Consider factors such as the size and complexity of your project, the desired level of customization, and the available resources for development and maintenance.

[LuckyMD]

I have never been in a discussion thread with so much ChatGPT... I imagine this will not be the last time ChatGPT is used to formulate clear arguments though... welcome to the future 😅 .

That being said... to put numbers to this... how much time would it take to regenerate the site and move to either Quarto @rcannood or a React metaframework @dsm-72 ?

[dsm-72]

I don’t have a horse in this. I brought up frameworks only for a more filled out discussion. Quarto is fine. I already know nuxt so making that site took what felt like a day. (I don’t actually remember but it wasn’t long since all the components already exist).

ultimately, I feel like this goes in circles because we are all a bit imprecise and are focusing more on how than what.

Eg Daniel made a good point asking about what “state” or website has.

So what is it we want? Interactive, filterable, searchable results with corresponding visualizations.

Why is this currently a pain point? We are using the data tables library which doesn’t have all the features we wants, clashes css wise with our template and makes mapping results to visualizations hard (due to Hugo not supporting state)

what can create the solution we want with minimal overhead? Quarto sounds like a compromise in the right direction.

To Robrechts point, before making any changes we should actually define far more clearly the exact end goal, so we can pick the right tool for the job.

“interactive visualizations “ is too vague.

If there is a chart on top of a table and sorting / filtering the table causes the chart to change, that is state and it will be easier to produce and maintain with something other than Hugo.

[scottgigante-immunai]

interactive visualizations

Here's an example of the static form of the visualization we might want: https://deploy-preview-90--openproblems-sca.netlify.app/benchmarks/batch_integration_embed/

Ideally we can sort and filter such a visualization.

[rcannood]

how much time would it take to regenerate the site and move to either Quarto @rcannood or a React metaframework @dsm-72 ?

• About: Copy paste. 5 minutes
• Benchmarks - I already spent a lot of time creating an updated task view for the Hugo website, but it already uses Quarto to render a qmd to a md that Hugo can interpret. So at this stage, 5 minutes.
• Competition pages and documentation - About 4 hours. The NeurIPS documentation pages contains a lot of Wowchemy blocks which turns this into a time drain.
• Bibliography: 5-15 minutes
• Team: Quarto doesn't have a pre-built block for rendering teams the same way Wowchemy does, but in a way it's just a listing with a custom template and some css. 20-30 minutes
• Top menu bar: It's not particularly complicated, so 10-20 minutes
• CSS Theme in general: Depends on how hard you want one to look like the other. Quarto already comes with a few simple themes out of the box, so choosing the one that resembles the current theme the most and customizing it a little bit probably takes 20-60 minutes

In total I'd guess it'd take about 6 hours to port openproblems.bio into Quarto for somebody who knows both Hugo+Wowchemy and Quarto well already, plus maybe some extra time for discovering and fixing minor bugs afterwards.

[dburkhardt]

Hi all, I just talked with Robrecht. For our 2022-23 objectives, we would like to plan for a website redesign. This may involve hiring a specialized web developer. We'll punt a question about Nuxt/Next.JS etc to then.

For now, we have a grant from CZI that includes deliverables on updating the website, and Robrecht is convinced he'll move faster if we use Quarto. He's going to port the website to Quarto in a new branch, and after we review, we'll deploy the website from that branch. This isn't necessarily a permanent change, but we think it will enable us to meet our aims for H1 of 2023.

Any objections?

[LuckyMD]

Sounds great!

[rcannood]

Solved in #137