HUGO

AsciiDoc -- Hugo Server Shouldn't Break on WARNINGs, only ERRORs

Following on from my previous post on the trials and tribulations of converting a Hugo site from markdown to asciidoc, I’ve now run into a seemingly unsurmountable new problem.

Having succesffully converted all pages to asciidoc; now, whenever I build the site, Hugo spits out an unending screed of section title out of sequence errors:

<snip>

ERROR 2020/03/30 11:23:02 2013-03-15-ios-prototyping-prerequisites.adoc: asciidoctor: WARNING: <stdin>: line 52: section title out of sequence: expected level 1, got level 3
ERROR 2020/03/30 11:23:02 2013-03-15-ios-prototyping-prerequisites.adoc: asciidoctor: WARNING: <stdin>: line 77: section title out of sequence: expected level 1, got level 3
ERROR 2020/03/30 11:23:03 2015-02-27-samsung-android-memory-error.adoc: asciidoctor: WARNING: <stdin>: line 48: section title out of sequence: expected level 1, got level 2
ERROR 2020/03/30 11:23:06 2012-05-12-getting-stuff-into-and-out-of-your-ios-devices.adoc: asciidoctor: WARNING: <stdin>: line 7: section title out of sequence: expected level 1, got level 3
ERROR 2020/03/30 11:23:06 2012-05-12-getting-stuff-into-and-out-of-your-ios-devices.adoc: asciidoctor: WARNING: <stdin>: line 17: section title out of sequence: expected level 1, got level 3
ERROR 2020/03/30 11:23:06 2012-05-12-getting-stuff-into-and-out-of-your-ios-devices.adoc: asciidoctor: WARNING: <stdin>: line 27: section title out of sequence: expected level 1, got level 3
ERROR 2020/03/30 11:23:06 2012-05-12-getting-stuff-into-and-out-of-your-ios-devices.adoc: asciidoctor: WARNING: <stdin>: line 35: section title out of sequence: expected level 1, got level 3

<snip>

I’m not 100% certain, but I suspect that this may be caused by the asciidoc parser getting confused by = signs in the TOML frontmatter of the pages. AsciiDoctor can be quite pernickerty about this kind of thing and does tend to output a lot of warnings, if given half the chance.

Anyway, whatever the reason is, the problem is that Hugo reports these WARNINGs from Asciidoc as ERRORs and then bails out without building the site:

Error: Error building site: logged XXX error(s)

However, in the meantime, the asciidoc parser has actually processed all the content files successfully, since there were only non-critical warnings generated. I can see the pages created in my public folder and, looking at the source code, they seem perfectly fine.

So, either:

  • Hugo needs to distinguish between a WARNING coming back from the asciidoc parser and an ERROR and not to abandon site building on WARNINGs only

or [this may already exist, I can’t find any likely-sounding option though]

  • We need a way to run hugo server in a ‘standalone’ manner. That way I could at least test the site in a two-stage way by frst running hugo server and then [for example] hugo server --standalone to test the generated site, which does exist even though Hugo thinks it failed to build.

Obviously the second option wouldn’t be ideal. But it would at least do for now, until a proper fix was implemented.

Anyone got any other suggestions?

EDIT:

Actually, another option might be to convert my frontmatter from TOML to one of the other formats which doesn’t use = signs. But, with over 350 pages on the site and a fair few of my own custom frontmatter tags involved, I don’t fancy the regex wrestling that would entail.

Plus, my theory about the cause of the errors being down to the frontmatter might turn out not to be the case, anyway.

Hmmm… another theory bites the dust.

I dredged up from somewhere in the depths of my noggin that Hugo had a built-in function for converting frontmatter [although it ain’t documented in the docs!]. I managed to find the command by trial and error: hugo convert to<FORMAT> -o .

So I tried converting a selection of my asciidoc files’s frontmatter to all the various options in turn and then trying to build the site again:

hugo convert toYAML -o .
hugo convert JSON -o .
hugo convert toTOML -o .

No dice. I still got the same warnings/errors each time. But, now I was building on a small selection of files, rather than the entire site, I could see that the aciidoctor parser was actually generating the section title out of sequence WARNINGs for various lines in each file, not just the frontmatter.

Unfortunately, looking at the actual adoc files themselves isn’t much help as the lines reported as having WARNINGs by the asciidoc parser obviously don’t correspond to the lines in the original adoc files, due to includes / shortcodes / etc being thrown into the mix at compile time.

Answering myself again, just in case I ever need to look this up in future and remember what I did.

As per previous hugo server is building the site correctly but, unfortunately is refusing to run afterwards as it is mistakenly treating non-important WARNINGs from asciidoctor as if they were fatal ERRORs and bailing out.

Clunky temporary workaround:

  • Run hugo server as usual [site is built in spite of errors]
  • Use terminal one-liner python3 -m http.server 1313 --directory /path/to/your/site's/public to spin up a testing server on the appropriate port
1 Like

I’ve posted this as an issue on the Hugo github as --pending receipt of information to the contrary-- it seems like a serious bug in Hugo itself:

1 Like

WARNINGs by the asciidoc parser obviously don’t correspond to the lines in the original adoc files

yes

due to includes / shortcodes / etc

are you sure? last I bumped into this “minor” issue it was only the frontmatter that was not counted by asciidoc, afaict