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 >
configfile*
Says to usetheme: themenameinstead oftheme: "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.
. 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.