Newbie is having major grief with Quick Start

support
1

I’m new to Hugo and just working through the Hugo “Quick Start” on the suggestion of an acquaintance. I’m afraid I’m having some problems though, especially with Part 8.

I’m going to mention a major issue I had before Part 8 first, just in case that is part of my current problem. In the part where I was first creating good-to-great.md, I found that the syntax of that file was quite different from the instructions. I initially typed the file just as it appeared but found it didn’t work. I had to make several changes before it would. For example, although the tutorial said to start and end with three consecutive plus signs, I had to change those to minus signs. Also, the equal signs had to be changed to colons and the three lines between the minus signs essentially had to be written on the same physical line as the minus signs. Now, maybe that is because I was using Notepad at the command prompt in my 64-bit copy of Windows 10 or maybe Hugo itself has changed its rules and the tutorial just hasn’t kept pace but it was tedious to have to figure that out. Newbies shouldn’t be forced to figure out a lot of non-obvious stuff just so they can get through the beginners tutorial! I feel very strongly about that and am very disappointed that this doesn’t seem to be the philosophy of the developers of Hugo.

Okay, that aside, I kept working my way through the tutorial and got through Part 7 okay. I even started Part 8 okay and got as far as replacing the original graphic with the hand containing the leather artifact (book??) successfully. However, when I created li.html, copied it verbatim from the tutorial, and then redisplayed the website, it still contained the first few lines of the book review although the tutorial said it shouldn’t. I kept going, on the theory that it might take care of itself in due course. I created default_foot.html, again verbatim from the tutorial, and redisplayed the page, expecting the verbiage about the Robust theme to disappear. It did not. I found and added some book cover images and they displayed okay.

Then I did something I didn’t see in the instructions but that seemed necessary: I added some more files to post/content, patterned on good-to-great.md but referring to the covers I’d added from Part 8. I created the new .md files in the same way as I had done good-to-great.md, starting with hugo new post/my-bookname1.md and then editing the file with notepad from the command line to put in the appropriate image line.

Then I did a “buildDrafts” and got this ugly mess:

C:\Hugo\Sites\bookshelf>hugo server --theme=hugo_theme_robust --buildDrafts
Started building sites …
ERROR 2017/07/22 21:08:24 unable to read frontmatter at filepos 100: EOF
ERROR 2017/07/22 21:08:24 failed to parse page metadata for “post\farmer-in-the-sky.md”: yaml: line 3: mapping values are not allowed in this context
ERROR 2017/07/22 21:08:24 failed to parse page metadata for “post\red-planet.md”: yaml: line 3: mapping values are not allowed in this context
ERROR 2017/07/22 21:08:24 unable to read frontmatter at filepos 100: EOF
ERROR 2017/07/22 21:08:24 unable to read frontmatter at filepos 96: EOF
ERROR 2017/07/22 21:08:24 unable to read frontmatter at filepos 91: EOF
Error: Error building site: Errors reading pages: Error: unable to read frontmatter at filepos 100: EOF for beyond-this-horizon.md
Error: failed to parse page metadata for “post\farmer-in-the-sky.md”: yaml: line 3: mapping values are not allowed in this context for farmer-in-the-sky.md
Error: failed to parse page metadata for “post\red-planet.md”: yaml: line 3: mapping values are not allowed in this context for red-planet.md
Error: unable to read frontmatter at filepos 100: EOF for rocket-ship-galileo.md
Error: unable to read frontmatter at filepos 96: EOF for good-to-great.md
Error: unable to read frontmatter at filepos 91: EOF for space-cadet.md

What the HECK is going on here and why am I having so much trouble with this supposedly simple beginners tutorial? How do I clean this up?

By the way, I am using Hugo v0.25.1 windows/amd64 on a Windows 10 64-bit computer.

2

Yea it’s a pretty bad quick start. I used it in my first and was not very successful. A lot of steps are missing and unexplained. Best tutorial I’ve seen is on digital ocean. Search digital ocean hugo. You’ll find it. It’s for Ubuntu but just skip the Ubuntu setup part. I’m working on a very noob friendly tutorial, but it won’t be out anytime soon. It’s not Hugo devs fault, but the quick start is bad.

3

I appreciate your suggestion to try the Digital Ocean tutorial but didn’t find it very satisfactory. It is just too Linux-oriented. Every step seems to depend extensively not just on having Linux as the operating system but also using any number of Linux commands. Now, I have some limited Linux exposure in my past but it was a while back and I don’t necessarily know enough to translate all the commands to Windows equivalents.

Is there any kind of a reference manual or YouTube video or something besides the Quick Start to get me up to speed?

Also, I should mention that I got rid of all the errors from my builds by using the editor in Eclipse - my preferred IDE - to remove all the newlines (\n) from the files. As soon as I did that, the errors went away. So it appears that newline characters are a major problem in Hugo. Personally, I find that distressing: it’s hard to edit files when you can’t even start a new line and have to make the whole file one long line! Seriously, which is easier to edit:

+++
date = "2017-02-19T21:09:05-06:00"
title = "good to great"
draft = true

+++

-OR-

— title: “Good To Great” date: 2017-07-22T18:48:16-04:00 draft: true image: “default.jpg”—

I think it’s very clear that the former is FAR easier to edit but it appears that Hugo forces you to write the latter.

Or is it simply that I need to use a different text editor? As far as I can tell, notepad is the only built-in editor that works from the command line in 64-bit versions of Windows. What editors do the rest of you use for your Windows 64-bit environments?

4

I understand your frustration, but something seems to be wrong with your editor. Try Sublime Text which is available for windows as well: https://www.sublimetext.com/download

Of course you don’t have to write everything on one line. That would be truly weird. You can write exactly as in your own example which is the Toml syntax by the way. There is a tutorial available on Udemy “Build Static Sites in Seconds with Hugo”. To me it looks worth the investment if you really want to learn Hugo.

I worked long time with Jekyll, know that very well and changed a few weeks ago to Hugo. Same frustration level for me. Why did I change? Speed and flexibility. Hugo is so damned fast and I can now work on sites in real time where Jekyll took minutes for the refresh only. Example: I tested my first project with appr. 20 pages and 80 posts where Jekyll needed more than 2 minutes for the build. Same site with Hugo took 700ms. And Hugo’s templating system is so powerful and flexible. But only this took me several days and tests to understand.

You’ll get a hang of it - just keep trying and read some articles. Here’s one good article from Markus Oberlehner: https://markus.oberlehner.net/blog/building-a-blog-with-the-static-website-generator-hugo/ Just search with Google and you’ll find a lot of more like that.

5

Your text editor is jacked up or is just inherently not doing a good job at editing text. Try Sublime, Atom, Notepad++, Visual Studio Code, Brackets… all great lightweight editors.

6

I’ve already got a bunch of editors on my computer and don’t particularly want to add yet another.

I reported all the errors I got during a build in the first post in this thread. As you’ll see if you look back at them, the errors mentioned “EOF” (End of File). Typically, that indicates problems with the \n and/or \r characters that Windows puts at the end of every line of code you write. I found that when I hunted for those characters (with an editor that could see them) and then removed the \n characters and saved the files, I no longer got any of those errors, confirming my theory that Hugo has a problem with those characters.

In one of my editors, removing the \n characters caused my various lines to merge into one long line. I’ve now found a different editor (also in my Eclipse IDE) that seems to remove the characters WITHOUT merging the lines, meaning the files generate cleanly AND things are still on different lines, making them easy to read and edit.

But I’m still not getting the behaviour that is implied by the tutorial. The tutorial implies that if you create additional book reviews, add an image = "mycover.jpg", and then put the jpg in the static\images folder, each book review will be selectable/readable on the main part of the screen and each will have the appropriate cover picture. I’ve done all of that but each book review uses the exact SAME picture, default.jpg. I suspect that either the syntax of the image = "mycover.jpg" line is wrong or I’ve put the pictures in the wrong place but I’m darned if I can figure out where they should go from this miserable tutorial.

Can anyone enlighten me?

7

As gaetawoo said - it’s definitely the editor.

Perhaps this helps: https://gohugo.io/troubleshooting/eof-error/

Windows uses a pair of CR and LF characters to terminate lines. OS X (i. e. Unix) uses a single LF character. Problems arise when transferring text files between different operating systems and using software that is not smart enough to detect the line break style used by a file. E.g. if you open a UNIX file in Microsoft Notepad, it will display the text as if the file contained no line breaks at all. If you open a Windows file in a UNIX editor like “joe” or “vi”, you will see a control character (the CR) at the end of each line.

You see there’s a lot going on with these damned line breaks.

8

Some editors have the option to choose what type of line endings they use in the configuration settings. Check the ones you already have installed.

9

the “mycover.jpg” needs to be a different name for each page… that might seem obvious but i’m just advising to check if that’s the case. page A can be “image-A.jpg” and page b can be “image-B.jpg”

10

I’m aware of all of that, Leo, and I can certainly change the preferences/rules that my editors are using.

What I don’t know is what expectations Hugo has for terminating lines when it’s running on Windows. Is it, in fact, expecting each logical line to end with a CR and an LF? Because I am installed on Windows 10, 64-bit, and so is Eclipse, the IDE which contains the editors I prefer to use. It would seem reasonable to expect both CR and LF at the end of each line yet I was getting errors when they were there so there is obviously something not quite right somewhere, or I would not have had those errors.

I’ll happily adjust the editor settings once someone who knows to a certainly can tell me what expectations Hugo has.

11

I had already made sure that each book review had a distinctly different JPEG and I coded the appropriate name in each book review.

Again, I think either the syntax of the image = "mycover.jpg" line is wrong or the tutorial is giving me the wrong place to put those JPEGs.

12

the old quick start is now gone from the site. there is a new quick start. I would nuke the site you already have, and start fresh. there is simply not enough information to troubleshoot it, especially when there is an editor issue in the mix and the site isn’t up on github for people to inspect it. The old quick start wasn’t a great guide. There are better out there but none that are made for noobs (which I hope to fix in the future) but currently it take a bit of sleuthing to figure out anything past the super basic. as I said, the digital ocean hugo tutorial is also pretty good, though made for ubuntu. the ubuntu specific stuff though will not hinder the building of the site or pages though.

13

Note: new quick start:

2 Likes
14

The new Quick Start seems like the first few steps of the old one. You learn far less about what you can potentially do. It’s probably going to be less frustrating for beginners but people will know almost nothing when they’re finished with it.

I think the REAL lesson here is that Hugo isn’t quite ready for prime time. There just hasn’t been sufficient time to get the various tutorials, manuals, and whatever else is envisioned into good shape yet. And that’s perfectly fine and natural for a new project.

It may be amazing in the new future but right now it’s simply not mature enough to be useful to me. I’ll just build my site the old-fashioned way with HTML and CSS. I’ve never found that approach terribly hard. I just had someone recommend Hugo to me as a brilliant new way to build websites but I think he oversold it a bit. Maybe in six months or a year, Hugo will be everything it promises to be. If so, that’s great and I wish you the best of luck. I may be back then. But for now, I’ve got sites to build and Hugo is NOT going to be satisfactory for my needs at the present time.

Again, good luck to you all and I do appreciate how people tried to help on the forum.

15

A quick start is what is says: A quick start.

And while you may have some valid concerns, I think a more precise statement would be: Hugo is (currently) not for everyone. There will probably come point and click CMSes that will help people not familiar with the command line, but Hugo is more than ready for prime time in the sense that many create fully featured sites with it.

16

I am well-aware of how to use a command-line: I go back to a time BEFORE command lines. I wrote my first code in high school. That was in 1972. I first learned DOS back in 1988.

A quick start is only a useful quick start if it works when you follow the instructions. The one that was just replaced did not meet that standard. Nor was anyone able to point me to a manual that could answer my questions. Nor was anyone able to tell me why I still wasn’t seeing the correct picture with each of my fake book reviews. All those put together made it abundantly clear that Hugo is not going to meet my needs at this moment. I think I was pretty clear that it might very well be satisfactory for me in the not-too-distant future and that I hoped it would. I did NOT deny that it might be useful to some people right now.

Again, good luck to you all and to Hugo. I may check you out again somewhere down the road.

1 Like
17

Although this no longer applies to the current Quick Start, I believe what you are talking about is the difference between TOML and YAML front matter, which you can find out more about here: Front matter | Hugo

You can tell Hugo your preferred front matter (i.e., metadata) format using the metadataFormat directive in your configuration: Configure Hugo | Hugo

But you bring up a good point that we should add a note about this directive in the front matter page.

This would be the documentation, but I’m open to suggestions on how to make it better and easier for new users. Perhaps we’ve erroneously taken shortcuts under the assumption that our users have a working familiarity with the static site generator landscape (e.g., markdown with embedded metadata).

I’m only shooting from the hip, but my hope is that an understanding of Hugo’s directory/project structure will help in this regard. Images are housed in Hugo’s static folder, which is copied over as-is when the site is built:

While you clarified that you were talking about Hugo not meeting your needs, I can see how this comment might be interpreted as a sweeping indictment of the project—a project that is working quite well for a very large number of users and sites.

Perhaps you can tell us a bit more about your needs and then the community can better support your efforts? Hosted source is a convenient way for others to dive and provide better support while you’re getting up and running.

I appreciate your feedback, but I’m looking for something more substantive to work with. We will continue to improve the Quick Start and the documentation as a whole :smile:

1 Like
18

If Hugo wouldn’t be ready or mature Smashing Magazine wouldn’t have chosen it recently as their primary build tool. I’m just about to finish a complex site with a lot of loops and conditionals. Works great and I must say that Hugo is very logical in it’s process. I simply couldn’t do that site without a static site generator.

So for all the other newbies: Rhino is definitely wrong in his opinion about Hugo. Read the many positive posts about Hugo and don’t let yourself be pushed in the wrong corner.

It’s a pitty, Rhino that you couldn’t make it. I hope you change your mind about Hugo. If you need more information don’t hesitate to ask.

1 Like
19

–
Rhino

20

That’s awesome! I can see how newcomers can find this useful. Thanks @bep for a quick refresh of the quickstart :slight_smile: