Catch xref errors and report them along with source file information

Currently, if an xref macro target cannot be resolved, no error is emitted and the HTML contains inappropriate markup. For example, with this markup:

xref:reference:crud.adoc[CRUD]

and the target doesn't exist in the specified module, the HTML contains:

<a href="#">reference:crud.adoc</a>

This should, IMHO, always be flagged as an error, and cause Antora to exit with a non-zero exit code.

Btw, you can find an xref validator to use in the interim here: https://gitlab.com/antora/xref-validator. You'd run this before you run antora to generate the site.

Here's an example in action: https://github.com/mulesoft/docs-site-antora/blob/master/Jenkinsfile#L58-L59

changed title from Catch {-xref: errors.-} to Catch xref errors and report them along with source file information

The message should include enough information to be able to figure out where the broken xref is located. It's not enough just to report the basename of the source file.

mentioned in issue #512 (closed)

I've directed #512 (closed) here. From that report came this request:

ultimately knowing which component, file, version and line number this came from would be preferred

We also want to address the case when the syntax of the target is invalid. We could still consider throwing an exception, but a corresponding log message should be issued that contains the details.

IMO this should be handled with logging and log levels. Stopping the build for this kind of error is overkill.

Indeed, logging and log level configuration would help manage the level of output required.

However, I didn't say "stop the build". I said "cause Antora to exit with a non-zero exit code." That's so that make, or other build coordination tooling, can determine whether there were errors during the run. Currently, Antora provides an exit code of 0 whether there are errors or not.

I apologize if my phrasing made it seem like I was asking for an immediate termination of the Antora process.

Indeed you didn't mention the case of invalid xref syntax, but Dan did and invalid syntax currently stops the build. I think invalid xref syntax should be reported, but not stop the build by default. Some varieties of xrefs are somewhat counterintuitive, and if you've put a lot in your e.g. converted documents you'd want a report rather than having to run the build once for each mistake.

Logging seems like a big part of the solution here in any case.

Would it be appropriate to tie the exit code to logging, e.g. logging an error will eventually result in a non-zero exit code?

I agree: all errors encountered during Antora processing should result in a non-zero exit code, whether processing stops immediately or runs to completion.

It would certainly be pleasant to be able to manage logging thresholds via playbook configuration so that stop+complain or log+defer exit were reasonable choices.

marked this issue as related to #145 (closed)

added [Domain] Architecture [Type] Discussion labels

removed the relation with #145 (closed)

marked this issue as related to #145 (closed)

changed milestone to %v3.0.x

added [Domain] Backend [Type] Feature labels and removed [Domain] Architecture [Type] Discussion labels

assigned to @mojavelinux

mentioned in issue #776 (closed)

Error message:

[17:04:38.796] ERROR (asciidoctor): target of xref not found: xref:no-such-page.adoc[link text]
    file: /home/comp/docs/modules/ROOT/pages/index.adoc:14
    source: /home/comp/docs (refname: v6.7.8 <worktree>, start path: woohoo)

Also, remove TODO log "Unresolved page ID" if undefined or "Invalid page ID syntax" if false on line 39 of https://gitlab.com/antora/antora/-/blob/master/packages/asciidoc-loader/lib/xref/convert-page-ref.js. A helper shouldn't do this operation.

Let's also look at updating the message for includes. Currently, it's ERROR (asciidoctor): include target not found: not-found.js, but we could adjust it to target of include (directive?) not found: include::example$not-found.js[]. And no error is logged at all for image targets (we'll handle attachments when we update the target method). I can create separate issues for includes and images if your want @mojavelinux, or do we want to wait?

mentioned in merge request !663 (merged)

include (directive?)

I think it's best if we don't get too specific. Since we say "xref", then we can also just say "include".

One open question is whether the error message should show the whole xref macro or just the target (plus fragment). While it would be nice to show as much context as possible, there are problems with showing the whole xref:

• We have to recreate what the user entered from parsed data, and it may not be exactly the same
• We don't know if the user entered the xref macro or xref shorthand, so we could only show it as an xref macro
• The link text may be partially converted, so the user might see <strong>text</strong> instead of *text*
• We don't know exactly where the additional attributes were places, such as id and role

In the end, it wouldn't be possible to do a search and replace to find the full xref macro, so perhaps it is best just to stick with showing the target (which is the subject of the message anyway).

Note that when the sourcemap option is enabled on the processor (#776 (closed)), the message will include the correct file and line number where the paragraph containing the xref macro begins. This will even work if the paragraph is inside an include file, in which case the log message will contain the include stack.

Without the sourcemap option enabled, the log message will only show the top-level file (in other words, the published page) without a line number.

Here's an updated example of a prettified message:

[17:04:38.796] ERROR (asciidoctor): target of xref not found: no-such-page.adoc
    file: docs/modules/ROOT/pages/index.adoc:14
    source: https://git.example.org/repo.git (refname: v6.7.8, start path: docs)

The line number will only be available if the sourcemap option is enabled on the AsciiDoc processor. See #776 (closed).

We're considering adding component and version information to each log message (when appropriate). We'll address that enhancement in a separate issue.

mentioned in commit 341e56bf

closed with commit 10c2e26e

added [Version] 3.0.0 label

mentioned in issue #800 (closed)