Fedback as a first time user converting from jekyll

dev
1

Well, I´m a developer and used a lot of projects in my life. I´ve never really written anything like this:

Switching over from Jekyll should have been easy, but it turned into a bit of a nightmare.

Starting off seemed to work all right, choosing a theme and getting it installed didn´t work due to some use of deprecated syntax in the theme but was ok to fix, then took some time to figure out on how to make the right content show on the Homepage. It seems to be quite biased towards blogs.

The first bigger roadblock was deploying it, choosing Github pages with Actions - those failed to build due to the Theme being a subproject and the modifications won´t be able to be pushed. Which kinda makes sense, but I don´t know how non-technical users are ever gonna figure stuff like that out… I ended up just copying the theme files / removing git (a fork would be the other route, but got stuck somehow, too)

The second road block was new pages didn´t show up. Probably a issue with the theme, but replacing the theme with a new example theme didn´t help either for some reason. Mysterious.

What helped was creating a new site (which I ended up doing a bunch). It worked there. Copying things over. Adding the theme back. Suddenly the theme is broken. Did a diff and can´t figure out why. Maybe some caching the dev server does? Installed the standard version of the theme from the orignal git. Still broken.

I seems there is some level of stuff going on that´s not reflected in the files. Maybe some page build caching somewhere? Doing a new site seems to resolve one issue, creating another issue seemingly randomly. I´m kinda frustrated at this point.

On further investigation, It seems the theme CSS is rendered out to /public, but the dev server is serving a different CSS? Very strange. A bunch of things that should just work are a bit of a nightmare. How am I debugging a whole thing, I mean adding a template to a static site generator shouldn’t be rocket science…

On a separate note: Mixing yaml and toml is kinda confusing. Some come with the project, some with the theme, some with examples when looking for answers to fix things (total mix out there).

Summary/Suggestions:

  • Themes install as own git modules by default are good in theory, bad in practise: Good to update if unchanged, bad setup to store modifications.
  • A working, built-in default theme would be great:
    – For Testing when things don´t work as expected
    – For a quick start without dealing with themes (they often seem not to work / have deprecated things in them as things have changed in the meantime)
  • Allowing yaml and toml: Great in theory, bad in practice. Seemingly creates more issues than it´s worth.

A Theme install command would also help:

  • A theme Installer that sets up a Theme in a way that of the box is setup to handle changes to the Theme. A subproject of a public theme repository isn´t great. Forcing you to fork it or just copying the plain files might be better.
  • That theme installer should ideally keep the theme consistent with the yaml/toml choice of the project
  • Also, it maybe should check for deprecated functions and remedy them or notify that the theme is out of date

Thanks :slight_smile:

2

PS: The broken CSS seemed some caching issue when changing themes. Not sure if it was on the dev server side or the browser side…

3

What else I´ve learned:

  1. Choosing a theme is tricky, the one I chose had a lot of basic stuff missing.
  2. Changing themes does not only require a restart of the dev server, deleting /public also seems to be needed.

And the main issue: Adding a index.md to your /content breaks everything basically for some reason. No warning.

4

Proposition: Continue to use Jekyll.

5

Sorry to hear of all your issues.

It seems most, but not all, stems from the themes you tested. Picking a theme is indeed difficult. With Hugo themes gets a lot of freedom, including plenty of opportunities to make less optimal choices.

  • Use toml, yaml or json? Hugo allows you to pick/mix them as you like.
  • Build themes with a baseof and blocks or manually construct each template?
  • Hardcode things or make them configurable?
  • Have each post be a file or a directory, your pick.
  • etc.

I build every site on top of my own base theme. I have taken a lot of inspiration from other themes but I need a stable base to build on.

For customers I lock their site on a specific base theme version and a Hugo version. That way their site will continue to work for years without issues. If/when I do new work on the site I update the versions.

Installing themes

The quickstart guide and many themes show how to install themes as git submodules. A far better option is to install themes as go modules but then you must have go installed and it is a bit more complex. Should the quickstart be quick or optimal?

Themes not updated will commonly break since Hugo is being actively developed. You can still use them with older Hugo version. Being a single binary makes it easy to handle different Hugo versions.

Editing themes

Editing third party themes is discourages. It will make updating the theme a lot harder. Better to override/extend the theme by placing files in the root layout directory. See Template lookup order | Hugo.

The go templating language is not my favorit. I would prefer to work with e.g. Jinja from the Python world. But having the speed of go and the fact that Hugo is a single binary are huge advantages for me.

GitHub pages

GitHub actions can handle git submodules without issue. The action on Host on GitHub Pages works well. (Go modules is still preferred.)

1 Like
6

It needs to be named _index.md.

To understand why, read Page bundles | Hugo to learn the difference between page and leaf bundles.

1 Like
7

This command will create a minimum working theme.

2 Likes
8

Thanks for responding :).

I´m certain there are good reasons behind all the design decisions, what I wanted to express is that some of those are counter-intuitive to first time users and it would be greatly appreciated if there would be some help/warnings about them. And by warning, I don´t mean in the docs, as those often only can be found if you know what you are looking for and few people read all docs before starting.

The following dev Server warnings might be helpful for example:

  • Warning that a top level (/content) index.md might be a mistake (I guess in rare cases it´s intentional)
    – For example: Warning: You are using a index.md on /content. This will cause it to be the only file considered in the directory. Did you mean to name it ‘_index.md’?
  • If a theme seems to be out of date (when use of deprecated things that throw a warning anyway)
    – For example: Warning: The theme you are using seems to be outdated. Consider using another theme or work with the author to update it or fork it and update it on you own.
  • If there is a mix between toml and yaml (there is a conversion function anyway) - If it even mattes: I was never sure if mixing both potentially caused issues or not
    – For example: Warning: Your project uses both yaml and toml. This will cause issues (or not???). You can use hugo convert to convert to one format.

The themes thing is more difficult:

My path to it was clearly sub-optimal, choosing a theme based on the design and then figuring out it was using outdated, trying to fix it and in the process altering it.

I image that would happen to a lot of first time users though, kinda like playing russian roulette ;). Not ideal for the experience of first time users.

Ideally the project itself helps and guides the users to avoid that mistakes. How to implement that is difficult though. Suggestions:

  • A built-in base theme. Basically, disabling the theme line in the config reverts back to the base theme. Here is why: On the index.md issue I had a hard time figuring out if it was theme-related or not. Having one that is built-in and basically guaranteed to work would put that at rest. I was using the “hugo new theme” to create a test theme, but then still wasn´t sure/confident if wasn´t possibly theme-related.

A better guide on installing themes or even a installer for it
For example (from the quickstart):

git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

to

hugo add theme ananke (or https://github.com/theNewDynamic/gohugo-theme-ananke.git to keep it open)

that then presents choices:

  • Install as submodule (best to only be changed by the New Dynamic · GitHub)
  • Install as (…)
  • You may also fork the theme and install it from there

Sorry for the long text, I hope you consider the feeback helpful :slight_smile:

9

Not a bad idea I think. Add an issue suggesting this new feature.

[quote=“tom3000, post:8, topic:52146”]
– For example: Warning: The theme you are using seems to be outdated. [/quote]

Hugo already has a system for depreciation warnings and errors.

There is no problem for Hugo to mix them.