Catch Asciidoctor.js errors.

If an include:: target cannot be found/resolved, Asciidoctor.js emits an error, such as:

asciidoctor: ERROR: crud.adoc: line 163: include target not found: ROOT:partial$examples/crud/iteration_3.adoc

Currently, Antora simply continues operating as if there was no error and exits with an exit code of 0, confounding build systems that depend on correct status codes.

Antora should catch such errors.

Is there a way to get this working locally? I have an inconsistent rendering between antora and asciidoctor that seems to have something to do with includes. Would love to investigate this option

Asciidoctor now provides a failure level option. As soon as we implement the logging bridge between Antora and Asciidoctor, we'll enable that option in Antora. Related: #145 (closed).

marked this issue as related to #145 (closed)

I'd like to chip in that this is crucial part of documentation generator, hope it gets prioritized accordingly.

Trust me, it's prioritized.

Thanks Dan :)

marked this issue as related to #522 (closed)

added [Domain] Backend [Type] Feature labels

removed the relation with #145 (closed)

marked this issue as related to #145 (closed)

Hello guys, this is problem for me too. Thanks this is Antora not useful on CI for generating documentation in production project.

How it's looking?

I thought that this is problem of my build stack, but probably not, I see: https://github.com/siouan/frontend-gradle-plugin/issues/143

And for me it's a bug not feature.

Thank you

Errors from asciidoctor are already output on the command line, although not with enough detail to make them easy to use to find the problem. However for CI I would expect you could run the output through grep and fail if you see “ERROR”.

@djencks sure, that's my planned workaround for now, but handling exit codes would be better.

Note that I switched to Sphinx because of this issue, since not catching errors on CI is quite a blocker to have trust in the tooling not deploy a broken documentation site.

I always use a package.json file to install Antora in my doc projects, and scripts in the package.json to run Antora with the options I need. After a couple of minutes of googling I came up with:

{
  "private": true,
  "scripts": {
    "build": "antora antora-playbook.yml --stacktrace --fetch",
    "build-error": "! antora antora-playbook.yml --stacktrace --fetch 2>&1| grep 'ERROR'"
  },
  "devDependencies": {
    "@antora/cli": "^2.3.3",
    "@antora/site-generator-default": "^2.3.3"
  }
}

npm run build-error fails if the asciidoc processing emits "ERROR". The extension to also fail on "WARNING" should be pretty obvious. (edited so it actually works on my mac, it might have worked previously on linux)

It would be nice if asciidoctor logging was connected to Antora, and my prototype for #145 (closed) fails on asciidoctor error, but there's no need to wait for that.

Even if we wire the Asciidoctor logger into Antora, I'm not convinced failing the build is the right thing to do. First, the errors and warnings in Asciidoctor are advisory, not necessarily appropriate for failing a build (a positive exit code). (It depends on what you consider to be a violation). Second, they are already going to stderr, which is actually the correct place to send them in a CI environment. If your CI is not handling errors on stderr, then the trust issue you have is with your CI server, not Antora.

Note that I switched to Sphinx because of this issue, since not catching errors on CI is quite a blocker to have trust in the tooling not deploy a broken documentation site.

This is just an inflammatory statement and I will pay no mind to it. Open source doesn't work using extortion. If you don't want to be part of the solution, then your comments aren't welcome here anyway.

but handling exit codes would be better.

Antora already does handle exit codes. Asciidoctor log messages are not setting the exit code. We do plan to integrate the logger into Antora so that we can have something like Asciidoctor's failure-level, which would give you that. But Asciidoctor has always considered log messages to be advisory by default (since stopping a build can be a major disruption to publishing and should be opt-in).

@landsman We will integrate the logger into Antora when we upgrade Asciidoctor. We have yet to determine if that will be in Antora 3 or 4. There are currently blockers we are trying to deal with. It will certainly be one of the two.

@mojavelinux Thank you so much. I am ready to help if there is some space for that. I really like Antora solution for building documentation across my all projects in any language.

Anyway I wish good luck and happy Christmas!

I'm struggling with this myself. Is there a way we can run normal asciidoctor on an individual page in the mean time? Some extravagant command line we can run to get these warnings without building the site? I'm struggling with docs that have errors that asciidoctor normally throws warnings about getting into our docs site. If there is a way to run it manually, then I can throw that into our developer build bash scripts and help these devs out.

And on the issue of should an error blow up the build in CI, I would say the best option is to give us an option. A CLI option that lets us switch back and forth. I can see legit arguments on both sides there. In my world, yes, that would be a build fail, build fails get automatically logged as a work item and automatically assigned to the developer that kicked the build. Those logs are then recorded by our intelligence system and statistics are generated that give us an idea if developers are testing things locally before deploy or habit the "push and pray" method which needlessly consumes CI agent time which costs money.

just my 2 cents