We could investigate providing our own template for the asciidoctor documentation in order to control paragraph numbering and cross referencing. Not sure how much work it would be though. On the other side we can reuse the code for other projects. See also https://github.com/hibernate/hibernate-validator/pull/312#issuecomment-56293010