rhrev is a comprehensive revision history tracking system for the AsciiDoc and Antora ecosystems which automatically creates a grouped, formatted table of document changes.

It supports several converters/backends:

• asciidoctor-pdf

  

  Comprehensive Block Ordering Test

• asciidoctor

  

• Antora

  

• Antora-Assembler to asciidoctor-pdf

Features

• Automatic revision tracking with version-based grouping

• Dynamic version labels using :version-label: attribute

• Localization support for multiple languages

• Export to AsciiDoc for inclusion in other documents

• Flexible placement (auto or manual via macro)

• Extensive customization options for styling and formatting

• [PDF] Clickable page references that link to actual document locations

• [PDF] Flexible xrefstyle support (full, short, basic) for all block types

• [PDF] Custom captions for Examples, Tables, Listings, and Figures

• FAST

Inspiration

This extension draws inspiration from:

• DITA-like automatic revision histories - Darwin Information Typing Architecture (DITA) provides automatic change tracking and revision metadata management in technical documentation systems

• LaTeX revision tracking tools - LaTeX packages like changes, trackchanges, and custom revision history macros that automate change documentation in academic and technical publications

• Document management systems - Enterprise documentation platforms that maintain automatic audit trails and change histories

The goal was to bring similar automated revision tracking capabilities to the Asciidoctor ecosystem, with the added benefit of clickable page references and flexible customization options tailored for PDF technical documentation.

Quick Start

Installation

The asciidoctor-pdf-rhrev extension is available as a Ruby Gem.

https://rubygems.org/gems/asciidoctor-pdf-rhrev

Complete these steps to use:

1. Install the required Gems:

   gem install asciidoctor
   gem install asciidoctor-pdf
   gem install asciidoctor-pdf-rhrev

2. Render your document:

   asciidoctor-pdf -r asciidoctor-pdf-rhrev document.adoc

Basic Usage

= My Document
:doctype: book
:revnumber: 1.1
:rhrev:
:version-label: Version
// 1.0 Metadata
:1-1-prevrev: 1.0
:1-1-prevrevdate: 2024-02-01
:rhrev1-1-all: Feature update

[rhrev1-1="Updated introduction"]
== Introduction

Content here...

Documentation

See USAGE.adoc for complete documentation including:

• Configuration options

• Advanced features

• Localization

• Export functionality

• xrefstyle support

• Examples and use cases

Testing

Run the test suite:

./run-tests.sh

This will generate PDFs for all test cases in the tests/ directory.

Ruby GEM Build Instructions (for 白一百 baiyibai)

gem build asciidoctor-pdf-rhrev.gemspec
gem install ./asciidoctor-pdf-rhrev-1.0.0.gem

License

MIT License. See the LICENSE file for details.

Contributing

Contributions welcome! Please ensure all tests pass before submitting changes.

Copyright

Copyright © 2025-present 白一百 baiyibai

• The image The «Public Domain Mark» icon from Creative Commons with transparent background. is in the public domain and taken from:
  https://commons.wikimedia.org/wiki/File:Cc-public_domain_mark.svg

For the full text of the license, see the LICENSE file.