optional tools

Optional Tools

Table of Contents

• Antora xref validator
• Installing the xref Validator

Antora xref validator

https://gitlab.com/opendevise/oss/antora-xref-validator

A custom Antora site generator that performs rudimentary validation of xrefs (specifically page references). Scans converted pages and navigation files for unresolved xrefs. If any unresolved xrefs are detected, it prints a report and exits with a failure code.

The generator will output a report of unresolved xrefs by component version to stderr, if any are found, then terminate with a non-zero exit status. If no unresolved xrefs are found, it will exit normally without emitting any messages.

Installing the xref Validator

1. If you have followed our NVM installation guide for antora simply run:

   npm install -g gitlab:antora/xref-validator

2. The above command installs the xref-validator locally. To run validation:

   make validate-suma

   Example Output

   make validate-suma
   NODE_PATH="" antora --generator @antora/xref-validator suma-site.yml
   Unresolved xrefs (grouped by origin):
   
   repo: https://github.com/SUSE/doc-susemanager.git | branch: master | component: suse-manager | version: master
     path: modules/architecture/pages/salt-contact-method-overview.adoc | xref: salt/salt-pull.adoc
     path: modules/architecture/pages/salt-contact-method-overview.adoc | xref: salt/salt-ssh-push.adoc
     path: modules/architecture/pages/salt-contact-method-overview.adoc | xref: salt/salt-ssh-push-tunnel.adoc
     path: modules/client-configuration/pages/clients-and-activation-keys.adoc | xref: reference:system-details/activation-keys.adoc
     path: modules/client-configuration/pages/virt-xenkvm.adoc | xref: client-configuration:manual-registration-overview.adoc
     path: modules/client-configuration/pages/virt-xenkvm.adoc | xref: client-configurastion:kickstart.adoc
     path: modules/installation/pages/server-setup.adoc | xref: client-configuration:manual-registration-overview.adoc
     path: modules/reference/pages/systems/activation-keys.adoc | xref: client-configuration:creating-activation-keys.adoc
     path: modules/reference/pages/systems/activation-keys.adoc | xref: client-configuration:client-and-activation-keys.adoc
     path: modules/reference/pages/systems/autoinst-profile-details.adoc | xref: administration:virtualization.adoc
     path: modules/reference/pages/systems/system-details.adoc | xref: reference:systems/sd-software-channels.adoc
     path: modules/reference/pages/systems/virtual-host-managers.adoc | xref: administration:virtual-hosts.adoc
     path: modules/retail/pages/retail-components.adoc | xref: installation/install-proxy-unified.adoc
     path: modules/retail/pages/retail-components.adoc | xref: client-configuration/client-config-overview.adoc
     path: modules/retail/pages/retail-components.adoc | xref: retail:retail-formulas.adoc
     path: modules/retail/pages/retail-deploy-terminals.adoc | xref: retail:retail-formulas.adoc
     path: modules/retail/pages/retail-install-packages.adoc | xref: retail:retail-formulas.adoc
     path: modules/retail/pages/retail-install-setup.adoc | xref: client-configuration:manual-registration-overview.adoc
     path: modules/retail/pages/retail-install-setup.adoc | xref: retail:retail-formulas.adoc
     path: modules/retail/pages/retail-migration-slepostosuma.adoc | xref: retail_chap_install.adoc
     path: modules/retail/pages/retail-terminal-names.adoc | xref: retail:retail-formulas.adoc
     path: modules/salt/pages/large-scale.adoc | xref: salt:large-scale_tuning.adoc
   
   antora: xref validation failed! See previous report for details.
   make: *** [Makefile:87: validate-suma] Error 1