by

Awesome Asciidoctor.js: Catch processing errors and warnings using an in-memory logger

The new logging system introduces in Asciidoctor.js, can be used to catch processing errors and warnings. It can be really useful in a CI build when you want to make sure that your documentation is perfect before publishing it.

The in-memory logger stores every warning and error messages generated by the Asciidoctor.js processor. Once the processing is done, you can retrieve all these messages using the getMessages function:

const asciidoctor = require('asciidoctor.js')()
const loggerManager = asciidoctor.LoggerManager
const memoryLogger = asciidoctor.MemoryLogger.$new()
loggerManager.setLogger(memoryLogger)

asciidoctor.convert('input')

memoryLogger.getMessages() // returns an array of Message

For every message, you can get the following information:

const message = memoryLogger.getMessages()[0]
console.log(message.getSeverity()) 1
console.log(message.getText()) 2
const sourceLocation = message.getSourceLocation() 3
if (sourceLocation) {
  console.log(sourceLocation.getLineNumber()) 4
  console.log(sourceLocation.getFile()) 5
  console.log(sourceLocation.getDirectory()) 6
  console.log(sourceLocation.getPath()) 7
}
1 returns the severity (ERROR or WARNING)
2 returns the error or warning text message
3 returns the context about the source location (can be undefined)
4 returns the source line number associated to the message
5 returns the file name associated to the message (or undefined when converting from a String)
6 returns the absolute path to the source file parent directory, or the execution path when converting from a String
7 returns the path associated to the message (or <stdin> when converting from a String)

You could then check if there’s any error and fail your CI build using process.exit() function:

const messages = memoryLogger.getMessages()
const errors = messages.filter(message => message.getSeverity() === 'ERROR')
if (errors && errors.length > 0) {
  console.log(`${errors.length} errors thrown during the documentation generation, exiting.`)
  process.exit(1)
} else {
  // all good, continuing...
}

Written with Asciidoctor.js 1.5.9.