Hugo new theme should generate enough default templating to render basic content


#1

I just installed Hugo for the first time (version 0.47 via homebrew) and have been following the docs on gohugo.io to get up and running. It hasn’t been going well and I could use some help.

Just to keep everyone on the same page about how I went about getting set up and what my directory looks like, here’s some of those details.

brew install hugo
hugo new site blog
cd blog
git init

hugo new theme materialize
hugo new _index.md
hugo new posts/hello-world.md

 tree
.
├── archetypes
│   └── default.md
├── config.toml
├── content
│   ├── _index.md
│   └── posts
│       └── hello-world.md
├── data
├── i18n
│   └── en.toml
├── layouts
├── public
│   ├── categories
│   │   └── index.xml
│   ├── css
│   ├── index.xml
│   ├── js
│   ├── posts
│   │   └── index.xml
│   ├── sitemap.xml
│   └── tags
│       └── index.xml
├── resources
├── static
└── themes
    └── materialize
        ├── LICENSE
        ├── archetypes
        │   └── default.md
        ├── layouts
        │   ├── 404.html
        │   ├── _default
        │   │   ├── baseof.html
        │   │   ├── list.html
        │   │   └── single.html
        │   ├── index.html
        │   └── partials
        │       ├── footer.html
        │       ├── head.html
        │       └── header.html
        ├── static
        │   ├── css
        │   └── js
        └── theme.toml

Here’s the content of some relevant files.

config.toml

baseURL = "https://blog.erichiggins.com/"
languageCode = "en-us"
title = "My Blog"
theme = "materialize"

content/_index.md

---
title: "Homepage"
---

# My Blog

Hello world.

content/posts/hello-world.md

---
title: "Hello World"
date: 2018-08-18T10:34:02-07:00
---

# Hello World

Hello world.

Here are the issues I’ve encountered so far, in no particular order.

  • The documentation doesn’t match the application’s behavior.
  • The documentation lacks a thoughtful workflow.
  • The application lacks sane defaults.
  • I cannot get a single simple page of content to be rendered.

More detail on these…

The documentation doesn’t match the application’s behavior.

A simple example can be found simply by running the hugo command. Here’s the output I see when I run it:

$ hugo

                   | EN  
+------------------+----+
  Pages            |  4  
  Paginator pages  |  0  
  Non-page files   |  0  
  Static files     |  3  
  Processed images |  0  
  Aliases          |  0  
  Sitemaps         |  1  
  Cleaned          |  0  

Total in 24 ms

This is quite different from what the documentation tells me to expect…
Example from Quick Start

Started building sites ...
Built site for language en:
1 of 1 draft rendered
0 future content
0 expired content
1 regular pages created
8 other pages created
0 non-page files copied
1 paginator pages created
0 categories created
0 tags created
total in 18 ms

Another example is in the syntax it states for the configuration file.

  • Install and Use Themes > config file*
    Says to use theme: themename instead of theme: "themename"

The documentation lacks a thoughtful workflow.

The Quick Start guide comes pretty close, but it barely mentions the critical issue of Drafts not being rendered. It really should mention this and link to more documentation that talks about Draft status and default behavior. Instead, it just gives the reader a command and glosses over it.

The content of Basic Usage page, however, doesn’t seem to do the readers any favors. It seems to hop around from topic to topic, rather than explaining what I would expect the basic usage to be. That is to say, I would expect this page to talk about the most common daily use-case for using Hugo (creating new pages of different types, managing the content, changing or adjusting themes, keeping dependencies up to date, managing authors, etc).

Rather than that, the first section is “Test Installation”… Huh? Shouldn’t that be under the Installation section? What does this have to do with Basic Usage?

The application lacks sane defaults.

As far as I can tell, Hugo won’t work without installing a theme. I can understand the reasons why that might be from a technical perspective, but as a user, this creates a frustrating experience. It does help that the Hugo command can easily generate a new blank theme, though I have yet to see that these blank themes come with defaults that “just work”.

Additionally, it appears that the i18n/ directory is missing by default, which causes Hugo to throw the following warnings.

WARN 2018/08/18 11:16:18 No translation bundle found for default language "en"
WARN 2018/08/18 11:16:18 Translation func for language en not found, use default.
WARN 2018/08/18 11:16:18 i18n not initialized, check that you have language file (in i18n) that matches the site language or the default language.

This seems like an easy thing for the developers to fix so that the end user doesn’t have to start their experience by immediately debugging the application.

I cannot get a single simple page of content to be rendered.

So, I’ve followed the instructions, created my content, and want to see it. I can’t. I’ve tried the following commands, but still only see blank pages.

hugo server
hugo server -D
hugo -v server -D
hugo
hugo -v
hugo -vD

No matter what I do, all I see on http://localhost:1313 is a blank page with the content <pre></pre>. Further, my pages aren’t rendered to the public/ directory. Here’s what I see in there instead.

$ tree public/
public/
├── categories
│   └── index.xml
├── css
├── index.xml
├── js
├── posts
│   └── index.xml
├── sitemap.xml
└── tags
    └── index.xml

5 directories, 5 files

Suffice it to say that this has been a very frustrating experience for me. I started the day wanting to get my blog site and first post live, but instead I’m stuck trying to debug a tool that doesn’t appear to do the one thing it was designed for. I’d really love some help here and maybe someone to share their thoughts on why I should continue to choose Hugo instead of moving on to another tool.

Edit: In trying to create this Topic and linking to the documentation pages on which I have seen issues, I was greeted with a warning that reads “Sorry, new users can only put 2 links in a post.”.
You’re killing me, Smalls.


#2

The Quick Start Guide uses the Ananke Theme and it was written with that in mind.

Hugo themes do things in different ways so what is written in the Quick Start Guide may not apply to the Materialize theme.

It would help if you posted the link to your repository, so that we can see what’s going on.

The links limit is enforced by the Forum software automatically, because we get a lot of spam here.


#3

Thanks for the quick reply.

The Materialize theme doesn’t exist anywhere outside of my local directory. As you can see, I just generated it myself and edited no files in it thinking it would just work.

I can’t link you to my repo since it’s only local at the moment. I noted all files I edited and how, but beyond that, everything is as Hugo generates it.


#4

You bring up a solid point on the --buildDrafts flag. Even after a year of Hugo this has still bitten me and I remembered being confused as a beginner even moreso as this.

There are things which may be done to ease this burden and it’s typically an overlooked design detail in themes:

  1. If the index page lists posts it can check for zero pages and message the user no currently published content exists.
  2. Streamlined installation. Many (may, most) themes ask users to copy config and every manual step is a chance to introduce an error. For beginners this can considerably steepen the learning curve. Config is code and should be treated as such IMO.

#5

Ok. Can you please tell me what is the content of the file under /themes/materialize/layouts/_default/list.html ?

If it is a blank file then you need to write those templates.

The Docs state that when using the command hugo new theme:

New theme is a skeleton

It would be easier for you to clone an existing Hugo theme like Ananke or use any other theme from https://themes.gohugo.io


#6

Yep, it’s a blank file. Would you mind linking me to the docs where this is talked about in more detail so I have a better understanding of what to put in here?

This goes to my point about Hugo not having sane defaults. It would go a long way for a newly created theme to work out of the box. That is to say, it doesn’t need to have any specific HTML markup, but should have the output variables in the correct files so that folks can change them as needed, rather than starting with troubleshooting. Stating that a “new theme is a skeleton” does not also explain to the reader that their pages won’t render unless they make changes.

I understand the point you’re trying to make, but that isn’t where I want to start. I don’t want to create any git submodules that I have to struggle to remove later. I don’t want to start with a theme that is nothing like I want, or struggle with a theme that hasn’t been maintained and may not work with the version of Hugo I have installed. What I prefer is to start with the most basic HTML and be able to define my own “theme” from a working starting point. Like Hugo itself, I prefer to have no dependencies.

Thanks again for your help, I really do appreciate it. Hopefully I can get things working from this point.


#7

I did. It’s the page about the command hugo new theme

You will need to read the entire Documentation to write your own theme.

Hugo does not ship with a default theme.

There are some bare bones themes in the Themes site. Have a look at these themes. You can always switch theme later.


#8

What I needed to add to the layouts/index.html and layouts/_defaults/list.html files in order to get content to render was the following:

{{ define "main" }}
  {{ .Content }}
{{ end }}

This was not included on the documentation page you linked to, but I was able to just figure it out from looking at an existing theme on GitHub.

I’m not asking for Hugo to ship with a default theme.
What I’m suggesting is that when a user runs hugo new theme ..., those lines should be included so that content is rendered by default.


#9

@erichiggins

  1. The docs are far from perfect, but they’re still pretty extensive. With your verbose approach to this forum, it would seem you’re a good fit for submitting a PR to the docs now that you’ve identified some of the areas you’ve found confusing.
  2. I don’t know how you’d just have a theme work out of the box, since content comes first with Hugo, and the theme should follow.
  3. A new theme comes with some scaffolding for the undeniable facets of a website. The reason that the define block you mentioned isn’t automatically added is because main is not a Hugo keyword. You can title the block whatever makes sense to you as a developer, and that’s critical since Hugo is appealing to an international audience and has really robust internationalization features. Search for the words defaul or block and you’ll find the documentation you’re looking for.
  4. You seem to conflate the lack of sane defaults (what about content sections as site sections, default RSS templates, well maintained out of the box templates, etc?), a matter of programming with documentation, which is intended to inform users of said programming. Which is your issue? Both?

In short, I’m having trouble understanding your thread in a way that allows the Hugo community to productively provide You any form of support.


#10

Hey @rdwatters , thanks for the reply. I’ll do my best to answer each point/question you brought up.

I’d be happy to file PRs for some issues that I found after I get through my own workload. That said, if the release cycle for Hugo is pretty frequent and new syntax is being introduced, you may need to invest time in version-specific documentation. I’m not sure that’s something I can add in a PR.

Two things about this.

  1. If content comes first with Hugo, then should a Theme even be required to use Hugo? Why does the Quick Start documentation have you install a Theme before creating content? That might not be what you meant literally, but I want to point out the discrepancy.
  2. I feel like I’ve tried to raise the same point several times in this thread that a newly-generated theme should display content, but the responses I’ve gotten keep telling me that there is no default theme. We’re not talking about the same thing.

While it may be true that main is not a Hugo keyword, but I’m not sure why that matters. When the hugo new theme command is run, it adds the following line to layouts/_default/baseof.html.

{{- block "main" . }}{{- end }}

So, why couldn’t the other generated files reference that so that they render content by default?
I understand that these can be renamed. That’s fine, but I don’t think that matters.

I get the point you’re trying to make. There are a lot of use-cases for Hugo and not everyone may agree on what defaults may constitute as being “sane.” I get that.
I’m not suggesting that you have to cover all use-cases, or that all different types of content sections need to be rendered by default. What I would prefer to see, which I think other generation tools do well, is when the Huge app is used to generate files (or themes), that they be filled out with documented boilerplate code that will, at minimum, render the most basic form of content (which I guess would be blog posts, or whatever is generated under content/ by the hugo new command.

To put it another way, my personal belief is that Hugo commands which generate files or file structures should, by default, include enough boilerplate code to 1) render some content and 2) offer some basic documentation or instruction. Perhaps this is a discussion that belongs in a GitHub issue rather than the support channel.

Well, I think that this thread has helped me to identify and resolve a few core issues that I was struggling with, so progress has been made. My intention was to raise a variety of issues that I encountered, not all of them blocking, in hopes that the would reach the right folks for either discussion or resolution.


#11

@erichiggins Just wanted to say that I agree with the issues/complaints you raised and ran into most of them recently when testing out Hugo as well. Not having the “main” section included was extremely annoying and I still don’t know why there isn’t a super-basic theme that the docs reference (or build) to demonstrate what seems like it would be common functionality in Hugo.

It’s great that Hugo is “generic”, but that doesn’t mean there can’t be some simple up-to-date examples of a few common use cases provided to avoid people getting frustrated. A very common use case is a Blog, so just having a super simple theme that lists links to the posts and which then show the posts content would go a long way.

I’d love to ditch Hexo and the 10,000+ files it requires to generate our fairly simple website, so hopefully some of these issues can be addressed.


#12

You’re confusing content and form. Themes (presentation layer) are informed by content, not the other way around.

“Content first” is not my idea. It’s been around since well before the dawn of the Internet.


#13

I’m not, but perhaps I need to be more explicit. I get the feeling that the point I’m making is somehow being completely lost.

“a newly-generated theme should display content”

In this statement, I am not saying that the theme should contain content. I’m saying that the theme files should contain just enough boilerplate code so that the content in content/ can be rendered and output will be produced.

The current behavior of Hugo is to generate theme files (under themes/) which are empty. Empty theme files in Hugo don’t generate any output when rendering. This hides content from rendering until you explicitly define it. This is not made clear in the introductory documentation and is not a sane default.


#14

I totally agree that Hugo is difficult to get started and has a very steep learning curve. One only has to search the forum for terms like “newbie” “confused” “issues” or other terms a person would use to describe their problems getting started to find out where improvement could be made in the documentation or the product its self. It would be great if an expert on Hugo could sit down with a computer literate individual who has no experience with Hugo and observe them attempting to get a Hugo site up and running in 15 minutes following the documentation. Thank you for writing this detailed post outlining your frustrations. It is apparent from your post that you have more than basic technical knowledge and that is telling.


#15

I’m in full agreement new theme should output enough boilerplate to get started creating a theme. But themes aren’t required to use block templating so I guess I’m surprised to hear that’s output at all in a baseof template.

Speaking of base templates, I didn’t see any mention of Ace templates (how baseof got it’s name). So that’s worth pointing out as I can see why the tool wouldn’t want to lead the design implementation by providing too much boilerplate. That said seeing at least something from the tutorial should happen in 5 minutes not 10 or 15. Without that magic moment a lot of traction is sunk.

One other thing worth pointing out is the entry point to building with Hugo usually starts with the theme and not the content. Perhaps things are backwards here a bit, and the getting started doc should provide different learning paths for individuals with different goals.


#16

So @erichiggins. I agree with you that “Basic Usage” can probably be removed (or at least changed to a better title of “Site Serve and Build” in addition to other structural improvements in the docs.

It also seems like you want a guide rather than just reference documentation (see this issue). If so, I agree that the docs could use a lot more examples (e.g. simple vs advanced use cases for templating functions) and a more stepwise approach to the docs (e.g. order in global nav should reflect a logical order for new Hugo users trying to learn [e.g. why is “Custom Output Formats” before “Base Templates”?]).

I have different thoughts about the Quick Start, which is that it’s for that initial impact (this works well in its current state) and is designed to be quick and not go into details. Also, check out this cool CLI utility that I think is often overlooked.

It is in Installation…and multiple other places. It’s like when a grandparent calls you about a television and the first question you ask is “is it plugged in and turned on?”

As mentioned before, it has plenty of sane defaults while still avoiding being too prescriptive. The idea of template lookup order is built entirely around the idea of sane defaults, no?

It’s a warning, not an error. I’d assume the majority of Hugo sites don’t use i18n, so it makes sense to keep it a warning. You don’t need to debug it.

Typing “server” into site search took me here immediately. Are you getting different search results?


YOUR ACTUAL QUESTION

I’ve updated the title of this post and changed it to Feature, but please let me know if I’m missing something. I have no interest in putting words in your mouth. Promise :smile:

You’re now saying this is what you want out of this thread, right?

That’s a lot shorter than your original post :wink:. Moving forward, you’ll have better luck in the forum if you focus on a single question or issue per thread. Also, try to share source whenever possible.

Basically, this is what’s currently created with hugo new theme <my-new-theme>:

├── themes
│   └── my-new-theme
│       ├── LICENSE
│       ├── archetypes
│       │   └── default.md
│       ├── layouts
│       │   ├── 404.html
│       │   ├── _default
│       │   │   ├── baseof.html
│       │   │   ├── list.html
│       │   │   └── single.html
│       │   ├── index.html
│       │   └── partials
│       │       ├── footer.html
│       │       ├── head.html
│       │       └── header.html
│       ├── static
│       │   ├── css
│       │   └── js
│       └── theme.toml

You want the above scaffolding to stay exactly the same, except you want the themes/my-new-theme/layouts/index.html and themes/my-new-theme/layouts/_default/list.html to go from blank to the following?

<!--themes/my-new-theme/layouts/index.html-->
<!--themes/my-new-theme/layouts/_default/list.html-->
{{ define "main" }}
{{ . Content }}
{{ end }} 

A few things to note:

  1. list.html is a list page, so they don’t need to contain .Content. Do you have a suggestion for something with range instead? (This could be a good idea.)
  2. themes/my-new-theme/layouts/_default/baseof.html points to use of -, partial block, etc as reference points, which should help you find out where to look inside the documentation.
  3. Rendering .Content from content/_index.md by default doesn’t seem to me like a particularly huge win. The idea is that you’re going to have to learn how to use Hugo templating, including the base templates, in order to build your theme regardless…

#17

Thanks @rdwatters, I look forward to seeing the improved documentation. Both reference docs and guides can be useful, but what is more useful is when they contain plentiful cross-linking between one another.

I never said it was an error and I did accurately refer to them as warnings. Perhaps they don’t need to be debugged, but since I was already having issues w/ rendering, warning messages can seem like signal. For my case, they were misleading noise.

I get the sense from your comment that my reason for sharing that list of commands has been taken out of context.

Seems unnecessary, but whatever you want to do.

When an application doesn’t work as expected for a new user and the documentation doesn’t help them, that doesn’t mean there is only one problem. As others have chimed in here, the Hugo docs need help.
I’ll also point out that I did actually get an answer to my issue pretty quickly, so I’m not convinced my verbosity was problematic.

Yes. I’m glad we’re finally on the same page.

Chalk that up to my being new to Hugo. I’m sure you and your team can come up with more useful boilerplate.

Ok. I guess I’d prefer there to be more comments in the file to explain to the developer what things do, what to expect, or give some insight into how to proceed? When you’re starting off with a new framework (Hugo) and language (Go templates), you’re never really sure what you should/shouldn’t change.

Not sure if you’re making a general argument or specifically for the content/_index.md path. Regardless, it’s easier to learn how to build a theme if you have a functional starting point.


#18

I’m just trying to figure out what you want so that I can provide some help :smile: When I said “This could be a good idea,” I meant it. Honestly. I think the idea of including comments inside the templates could help provide some context.

That’s unrelated. There will always be multiple problems. That’s why there is a forum. My recommendation stands w/r/t best practice for posts, though. Again, just trying to figure out the single biggest problem you’re having or that you want to address so that I can provide.

Did the reference to the list.html templates help? If you can point me to source, I’m happy to help however I can with your project. Just LMK :smile:

P.S. If you need me to change the title of the post back, I’m happy to do so. Hopefully it works since you mentioned above that we agree your request is for new theme to generate enough default templating to render basic content…


#19

@erichiggins @rdwatters I just found this thread after using "hugo new theme " and wondering why I couldn’t see any of the initial content I had created. It would be useful if newly generated themes did produce some output… even if that output was just a message to say “New themes don’t make any assumptions and don’t provide default templates - use the the theme documentation now to build your theme out.”

I think a message or a minimum default template structure would be useful - I was trying to debug my install until I decided to google the missing output problem.