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

1

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.

2

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.

3

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
4

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
5

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

6

I’m super happy with the asciidoctor progress in hugo. Awesome work!

I’m up against this issue as well… Hugo is reporting as an error what asciioctor is only reporting as INFO. Not even WARNING. And this is an asciidoctor reference doc.

ERROR 2020/11/27 11:08:35 post/asciidoc-syntax-quick-reference.adoc: asciidoctor: INFO: possible invalid reference: paragraphs

I tried putting an entry for failure-level: fatal or FATAL in my config.yaml as below but that didn’t work. But according to asciidoctor --help fatal should be the default.

(btw the includedir also doesn’t seem to work in the config file, but at least does in the asciidoc header attributes.

 markup:    
   asciidocext:    
      backend: html5    
      workingfoldercurrent: true  
      failure-level: FATAL  
      includedir: ../include/
1 Like
7

I did a write up on the trials and tribulations of using AsciiDoc and hugo and how I eventually got it running fairly smoothly. Mind you, it’s still very slow to build --especially the first run-- compared to Markdown. It’s here, of anyone wants to follow me down the rabbit hole:

8

ok I got it now. in hugo its failurelevel (no hyphen) Also my includdir should be an attribute.

1 Like
9

Thanks for the info… What do you mean by “my includdir should be an attribute”? And could you post the working config snippet please?

10

for the includedir, I didn’t put it correctly under attributes section below. But here is my working config

markup:
  asciidocext:
    safeMode: unsafe
    failureLevel: fatal
    backend: html5
    workingFolderCurrent: true
    trace: true
    verbose: true
    attributes:
      icons: font
      experimental: true
      sectlinks: true
      sectanchors: true
      source-highlighter: rouge
      rouge-css: style
      rouge-style: github
      imagesdir: /images/
      includedir: ../_include/

There are still two things I find difficult.

  1. with asciidoctor (or Antora) if you include a file in content/en/posts/file.adoc with:

    include::somefile.csv[]

then normally asciidcotor looks for the included file in the same directory as the main document. Unless you specify a path like so

include::/content/fr/_includes/somefile.csv[]

But hugo wants to find the included files with no path way down at the root of the website (as I recall at the same level as content.)

So as a workaround if I have an included flle I specify it as:

include::{includedir}somefile.csv[]

with the {includedire} set in the config file. (…/…/_include) which gives it a relative path. But…

  1. If you put that in the config file as I have above, then you can also no longer control that on a per document basis. With Antora for example the config file is a general setting and then each document can override this. (which IMO makes much more sense). Anyway I am managing with the above configuration.
11

Very useful, much appreciated.