asciidoctor-rhrev 1.0.1

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+
+This project includes code from Asciidoctor PDF by OpenDevise Inc. and the Asciidoctor Project,
+licensed under the MIT License:
+
+Copyright (c) 2025 白一百 baiyibai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.adoc

@@ -0,0 +1,138 @@
+= rhrev - Asciidoctor PDF Revision History Extension
+
+rhrev is a comprehensive revision history tracking system for the AsciiDoc and Antora ecosystems which automatically creates a grouped, formatted table of document changes.
+
+https://baiyibai-antora.gitlab.io
+
+It supports several converters/backends:
+
+* asciidoctor-pdf
++
+image::resources/ruby-pdf-output.png[width=50%]
++
+xref:./tests/block/test-block-ordering-comprehensive.pdf[Comprehensive Block Ordering Test]
+* asciidoctor
++
+image::resources/ruby-html5-output.png[width=50%]
++
+* Antora
++
+image::resources/nodejs-html5-output.png[width=50%]
++
+* 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:
+
+. Install the required Gems:
++
+[source,bash]
+----
+gem install asciidoctor
+gem install asciidoctor-pdf
+gem install asciidoctor-pdf-rhrev
+----
++
+. Render your document:
++
+[source,bash]
+----
+asciidoctor-pdf -r asciidoctor-pdf-rhrev document.adoc
+----
+
+=== Basic Usage
+
+[source,asciidoc]
+----
+= 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 link:USAGE.adoc[] for complete documentation including:
+
+* Configuration options
+* Advanced features
+* Localization
+* Export functionality
+* xrefstyle support
+* Examples and use cases
+
+== Testing
+
+Run the test suite:
+
+[source,bash]
+----
+./run-tests.sh
+----
+
+This will generate PDFs for all test cases in the `tests/` directory.
+
+=== Ruby GEM Build Instructions (for 白一百 baiyibai)
+
+[source,bash]
+----
+gem build asciidoctor-pdf-rhrev.gemspec 
+gem install ./asciidoctor-pdf-rhrev-1.0.0.gem
+----
+
+== License
+
+MIT License. See the link:LICENSE[] file for details.
+
+== Contributing
+
+Contributions welcome! Please ensure all tests pass before submitting changes.
+
+== Copyright
+
+Copyright (C) 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 link:LICENSE[] file.

package/antora-extension/antora-rhrev-asciidoc.js

@@ -0,0 +1,495 @@
+'use strict'
+
+/**
+ * Antora extension for revision history (rhrev) block macro.
+ * 
+ * Provides HTML5 backend support for revision history tables.
+ * Auto-injects revision history at document start unless :rhrev: macro or manual mode.
+ * 
+ * Usage in antora-playbook.yml:
+ *   antora:
+ *     extensions:
+ *       - require: ./antora-extension/antora-rhrev-asciidoc.js
+ */
+
+// Catalog for storing revision entries
+class RevisionCatalog {
+  constructor() {
+    this.entries = {}       // Block-level entries: { '1-1': [...], '1-2': [...] }
+    this.allEntries = {}    // Document-level -all entries: { '1-1': 'text', '1-2': 'text' }
+    this.sequence = 0
+  }
+
+  addEntry(revision, anchor, change, metadata = {}) {
+    if (!this.entries[revision]) {
+      this.entries[revision] = []
+    }
+    
+    this.entries[revision].push({
+      anchor,
+      change,
+      title: metadata.title || null,
+      sequence: this.sequence++,
+      ...metadata
+    })
+  }
+
+  addAllEntry(revision, change) {
+    this.allEntries[revision] = change
+  }
+
+  sortedRevisions() {
+    // Collect all unique revisions from entries and allEntries
+    const revisions = new Set([
+      ...Object.keys(this.entries),
+      ...Object.keys(this.allEntries)
+    ])
+    
+    return Array.from(revisions).sort((a, b) => {
+      const [aMajor, aMinor] = a.split('-').map(Number)
+      const [bMajor, bMinor] = b.split('-').map(Number)
+      
+      if (aMajor !== bMajor) return bMajor - aMajor
+      return bMinor - aMinor
+    })
+  }
+}
+
+// Helper functions
+function isInitialRelease(revnumber) {
+  return revnumber === '1.0' || revnumber === '1'
+}
+
+function formatPrevRev(prevTitle, prevDate, doc) {
+  const includeDateAttr = doc.getAttribute('rhrev-customization-prevrev-include-date')
+  const includeDate = includeDateAttr !== undefined
+  
+  if (includeDate && prevDate) {
+    const dateFormat = doc.getAttribute('rhrev-customization-date-format') || '%Y-%m-%d'
+    // Simple date formatting (Node.js doesn't have strftime, keep it simple)
+    return `${prevTitle} ${prevDate}`
+  }
+  
+  return prevTitle
+}
+
+function preprocessAttributeContent(text) {
+  // Handle line continuations (backslash at end of line)
+  return text.replace(/\\\s*\n\s*/g, ' ')
+}
+
+function formatChangeAsHtmlList(text) {
+  if (!text) return ''
+  
+  const processed = preprocessAttributeContent(text)
+  
+  // Split by asterisks to create list items
+  const tokens = processed.split(/\s(?=\*+\s)/)
+  const items = []
+  
+  if (tokens.length === 1 && !processed.includes('*')) {
+    // Single item without asterisk - wrap in list anyway
+    items.push({ level: 1, content: processed })
+  } else {
+    tokens.forEach(token => {
+      if (!token.trim()) return
+      
+      const match = token.trim().match(/^(\*+)\s+(.+)/)
+      if (match) {
+        items.push({ level: match[1].length, content: match[2] })
+      } else {
+        items.push({ level: 1, content: token.trim() })
+      }
+    })
+  }
+  
+  // Always generate HTML list
+  const html = ['<ul>']
+  items.forEach(item => {
+    html.push(`<li>${item.content}</li>`)
+  })
+  html.push('</ul>')
+  
+  return html.join('\n')
+}
+
+function collectAllEntries(doc) {
+  const catalog = new RevisionCatalog()
+  const prefix = doc.getAttribute('revhistoryprefix') || 'rhrev'
+  
+  // Collect document-level entries (-all)
+  for (let major = 0; major <= 9; major++) {
+    for (let minor = 0; minor <= 9; minor++) {
+      const revision = `${major}-${minor}`
+      const prevrevAttr = `${revision}-prevrev`
+      
+      if (doc.getAttribute(prevrevAttr)) {
+        const allAttrName = `${prefix}${revision}-all`
+        const allValue = doc.getAttribute(allAttrName)
+        
+        if (allValue) {
+          catalog.addAllEntry(revision, allValue)
+        }
+      }
+    }
+  }
+  
+  // Collect block-level entries by scanning document
+  const contexts = ['section', 'floating_title', 'example', 'listing', 'table', 'image']
+  
+  function scanBlocks(blocks) {
+    if (!blocks) return
+    
+    blocks.forEach(block => {
+      const blockId = block.getId()
+      const blockContext = block.getContext()
+      
+      if (contexts.includes(blockContext) && blockId) {
+        // Try both getAttributes() and direct attribute access
+        const attrs = block.getAttributes()
+        
+        // Also check if attributes are exposed differently
+        // Some Asciidoctor.js versions expose them via getAttribute(name) only
+        Object.keys(attrs).forEach(key => {
+          const value = attrs[key]
+          
+          if (key.startsWith(prefix) && !key.includes('-all') && !key.endsWith('-cover')) {
+            const revision = key.substring(prefix.length)
+            
+            catalog.addEntry(revision, blockId, String(value), {
+              title: block.getTitle(),
+              context: blockContext
+            })
+          }
+        })
+      }
+      
+      // Recurse into nested blocks
+      if (block.getBlocks) {
+        scanBlocks(block.getBlocks())
+      }
+    })
+  }
+  
+  scanBlocks(doc.getBlocks())
+  
+  return catalog
+}
+
+function generateInitialReleaseHtml(doc) {
+  const discrete = doc.hasAttribute('rhrev-discrete')
+  const html = []
+  
+  // Wrapper
+  if (discrete) {
+    html.push('<div class="rhrev-section">')
+  } else {
+    html.push('<section id="revision-history">')
+  }
+  
+  // Title
+  const customTitle = doc.getAttribute('rhrev-customization-title')
+  if (customTitle !== undefined && customTitle === '') {
+    // Empty title, suppress
+  } else if (customTitle) {
+    const versionLabel = String(doc.getAttribute('version-label') || 'Revision')
+    const resolvedTitle = String(customTitle).replace('{version-label}', versionLabel)
+    html.push(`<h2>${resolvedTitle}</h2>`)
+  } else {
+    const versionLabel = String(doc.getAttribute('version-label') || 'Revision')
+    html.push(`<h2>${versionLabel} History</h2>`)
+  }
+  
+  // Simple table
+  const initialText = doc.getAttribute('rhrev-customization-initial-release-text') ||
+                     doc.getAttribute('rhrev-localization-initial-release') ||
+                     'Initial release'
+  
+  const columnWidths = String(doc.getAttribute('rhrev-table-column-width') || '30,70').split(',').map(w => w.trim())
+  const sectionLabel = doc.getAttribute('rhrev-localization-location') || 'Section'
+  const majorChangesText = doc.getAttribute('rhrev-localization-major-changes') || 'Major changes since'
+  const versionLabel = doc.getAttribute('version-label') || 'Revision'
+  const revnumber = doc.getAttribute('revnumber') || '1.0'
+  
+  // Build table with frame/grid classes
+  const frame = doc.getAttribute('rhrev-table-frame') || 'all'
+  const grid = doc.getAttribute('rhrev-table-grid') || 'all'
+  html.push(`<table class="tableblock frame-${frame} grid-${grid} stretch">`)
+  
+  // Caption as title div
+  if (!doc.hasAttribute('rhrev-disable-caption')) {
+    const caption = doc.getAttribute('rhrev-table-caption')
+    if (caption) {
+      html.push(`<div class="title">${caption}</div>`)
+    }
+  }
+  
+  html.push('<colgroup>')
+  columnWidths.forEach(w => {
+    html.push(`<col style="width: ${w}%;">`)
+  })
+  html.push('</colgroup>')
+  html.push('<tbody>')
+  html.push('<tr class="rhrev-header">')
+  html.push(`<th class="tableblock halign-left valign-top">${sectionLabel}</th>`)
+  html.push(`<th class="tableblock halign-left valign-top"><strong>${majorChangesText} ${versionLabel} ${revnumber}</strong></th>`)
+  html.push('</tr>')
+  html.push('<tr>')
+  html.push('<td>&nbsp;</td>')
+  html.push(`<td>${initialText}</td>`)
+  html.push('</tr>')
+  html.push('</tbody>')
+  html.push('</table>')
+  
+  // Close wrapper
+  html.push(discrete ? '</div>' : '</section>')
+  
+  return html.join('\n')
+}
+
+function generateHtmlOutput(doc, catalog, currentPage = '') {
+  const discrete = doc.hasAttribute('rhrev-discrete')
+  const html = []
+  
+  // Wrapper
+  if (discrete) {
+    html.push('<div class="rhrev-section">')
+  } else {
+    html.push('<section id="revision-history">')
+  }
+  
+  // Title
+  const customTitle = doc.getAttribute('rhrev-customization-title')
+  if (customTitle !== undefined && customTitle === '') {
+    // Empty title, suppress
+  } else if (customTitle) {
+    const versionLabel = String(doc.getAttribute('version-label') || 'Revision')
+    const resolvedTitle = String(customTitle).replace('{version-label}', versionLabel)
+    html.push(`<h2>${resolvedTitle}</h2>`)
+  } else {
+    const versionLabel = String(doc.getAttribute('version-label') || 'Revision')
+    html.push(`<h2>${versionLabel} History</h2>`)
+  }
+  
+  // Table
+  html.push(generateHtmlTable(doc, catalog, currentPage))
+  
+  // Close wrapper
+  html.push(discrete ? '</div>' : '</section>')
+  
+  return html.join('\n')
+}
+
+function generateHtmlTable(doc, catalog, currentPage = '') {
+  const columnWidths = String(doc.getAttribute('rhrev-table-column-width') || '30,70').split(',').map(w => w.trim())
+  const html = []
+  
+  // Build table with frame/grid classes
+  const frame = doc.getAttribute('rhrev-table-frame') || 'all'
+  const grid = doc.getAttribute('rhrev-table-grid') || 'all'
+  html.push(`<table class="tableblock frame-${frame} grid-${grid} stretch">`)
+  
+  // Caption as title div
+  if (!doc.hasAttribute('rhrev-disable-caption')) {
+    const caption = doc.getAttribute('rhrev-table-caption')
+    if (caption) {
+      html.push(`<div class="title">${caption}</div>`)
+    }
+  }
+  
+  html.push('<colgroup>')
+  columnWidths.forEach(w => {
+    html.push(`<col style="width: ${w}%;">`)
+  })
+  html.push('</colgroup>')
+  html.push('<tbody>')
+  
+  // Custom first row
+  const firstRow = doc.getAttribute('rhrev-customization-first-row')
+  const firstRowLeft = doc.getAttribute('rhrev-customization-first-row-left')
+  const firstRowRight = doc.getAttribute('rhrev-customization-first-row-right')
+  
+  if (firstRow) {
+    html.push('<tr class="rhrev-custom-first-row">')
+    html.push(`<td colspan="2">${firstRow}</td>`)
+    html.push('</tr>')
+  } else if (firstRowLeft || firstRowRight) {
+    html.push('<tr class="rhrev-custom-first-row">')
+    html.push(`<td>${firstRowLeft || '&nbsp;'}</td>`)
+    html.push(`<td>${firstRowRight || '&nbsp;'}</td>`)
+    html.push('</tr>')
+  }
+  
+  const sectionLabel = doc.getAttribute('rhrev-localization-location') || 'Section'
+  const majorChangesText = doc.getAttribute('rhrev-localization-major-changes') || 'Major changes since'
+  const allText = doc.getAttribute('rhrev-localization-all') || 'All'
+  
+  catalog.sortedRevisions().forEach(revision => {
+    const prevrevAttr = `${revision}-prevrev`
+    const prevrevdateAttr = `${revision}-prevrevdate`
+    const revisionLabel = String(doc.getAttribute('version-label') || 'Revision')
+    const prevTitle = String(doc.getAttribute(prevrevAttr) || revision.replace('-', '.'))
+    const prevDate = String(doc.getAttribute(prevrevdateAttr) || '')
+    const prevRevText = formatPrevRev(prevTitle, prevDate, doc)
+    
+    // Build header text
+    let headerText
+    if (prevTitle.trim().toLowerCase().startsWith(revisionLabel.toLowerCase())) {
+      headerText = `${majorChangesText} ${prevRevText}`
+    } else {
+      headerText = `${majorChangesText} ${revisionLabel} ${prevRevText}`
+    }
+    
+    // Header row for this revision
+    html.push('<tr class="rhrev-header">')
+    html.push(`<th class="tableblock halign-left valign-top">${sectionLabel}</th>`)
+    html.push(`<th class="tableblock halign-left valign-top"><strong>${headerText}</strong></th>`)
+    html.push('</tr>')
+    
+    // All entry
+    const allChange = catalog.allEntries[revision]
+    if (allChange) {
+      html.push('<tr>')
+      html.push(`<td>${allText}</td>`)
+      html.push(`<td>${formatChangeAsHtmlList(allChange)}</td>`)
+      html.push('</tr>')
+    }
+    
+    // Block entries
+    const entries = catalog.entries[revision] || []
+    entries.sort((a, b) => (a.sequence || 0) - (b.sequence || 0))
+    
+    entries.forEach(entry => {
+      const anchor = entry.anchor
+      const title = entry.title || anchor.replace(/[_-]/g, ' ').split(' ').map(w => 
+        w.charAt(0).toUpperCase() + w.slice(1)
+      ).join(' ')
+      
+      html.push('<tr>')
+      
+      // Build link - if entry is from a different page, include page path
+      let linkHref = `#${anchor}`
+      if (entry.page && entry.page !== currentPage) {
+        // Cross-page link: convert "modules/ROOT/pages/chapter-1.adoc" to "chapter-1.html#anchor"
+        const pagePath = entry.page.replace('modules/ROOT/pages/', '').replace('.adoc', '.html')
+        linkHref = `${pagePath}#${anchor}`
+      }
+      
+      html.push(`<td><a href="${linkHref}">${title}</a></td>`)
+      html.push(`<td>${formatChangeAsHtmlList(entry.change)}</td>`)
+      html.push('</tr>')
+    })
+  })
+  
+  html.push('</tbody>')
+  html.push('</table>')
+  
+  return html.join('\n')
+}
+
+// Main registration function
+module.exports.register = function (registry, context = {}) {
+  // Register block macro for rhrev::[]
+  registry.blockMacro('rhrev', function () {
+    const self = this
+    
+    self.process(function (parent, target, attrs) {
+      const doc = parent.getDocument()
+      
+      // Check if manual mode
+      if (doc.getAttribute('rhrev') === 'manual') {
+        return self.createBlock(parent, 'paragraph', '')
+      }
+      
+      // Check initial release handling
+      const revnumber = doc.getAttribute('revnumber') || '1.0'
+      const initialHandling = doc.getAttribute('rhrev-initial-handling') || 'initial-release'
+      
+      if (isInitialRelease(revnumber)) {
+        if (initialHandling === 'skip') {
+          return self.createBlock(parent, 'paragraph', '')
+        }
+        
+        if (initialHandling === 'initial-release') {
+          const html = generateInitialReleaseHtml(doc)
+          return self.createBlock(parent, 'pass', html)
+        }
+      }
+      
+      // Try to use global catalog from Antora pipeline extension
+      // Otherwise fall back to collecting from current document only
+      let catalog = global.antoraRhrevCatalog
+      
+      if (!catalog || !catalog.entries) {
+        // Fallback: collect from current document only (standalone mode)
+        catalog = collectAllEntries(doc)
+      }
+      
+      if (catalog.sortedRevisions().length === 0) {
+        return self.createBlock(parent, 'paragraph', '')
+      }
+      
+      // Get current page path for cross-page link resolution
+      const currentPage = doc.getAttribute('page-component-src-relative') || 
+                         doc.getAttribute('docfile') || ''
+      
+      const html = generateHtmlOutput(doc, catalog, currentPage)
+      return self.createBlock(parent, 'pass', html)
+    })
+  })
+  
+  // Register treeprocessor for auto-injection
+  registry.treeProcessor(function () {
+    const self = this
+    
+    self.process(function (doc) {
+      if (!doc.hasAttribute('rhrev')) {
+        return doc
+      }
+      
+      const rhrevValue = doc.getAttribute('rhrev')
+      if (rhrevValue === 'macro' || rhrevValue === 'manual') {
+        return doc
+      }
+      
+      // Auto-inject revision history at document start
+      const blocks = doc.getBlocks()
+      
+      // Create rhrev block
+      const rhrevBlock = self.createBlock(doc, 'pass', '')
+      
+      // Check initial release handling
+      const revnumber = doc.getAttribute('revnumber') || '1.0'
+      const initialHandling = doc.getAttribute('rhrev-initial-handling') || 'initial-release'
+      
+      let html
+      if (isInitialRelease(revnumber)) {
+        if (initialHandling === 'skip') {
+          return doc
+        }
+        
+        if (initialHandling === 'initial-release') {
+          html = generateInitialReleaseHtml(doc)
+        } else {
+          const catalog = collectAllEntries(doc)
+          html = generateHtmlOutput(doc, catalog)
+        }
+      } else {
+        const catalog = collectAllEntries(doc)
+        
+        if (catalog.sortedRevisions().length === 0) {
+          return doc
+        }
+        
+        html = generateHtmlOutput(doc, catalog)
+      }
+      
+      rhrevBlock.setContent(html)
+      
+      // Insert at beginning
+      blocks.unshift(rhrevBlock)
+      
+      return doc
+    })
+  })
+}

package/antora-extension/antora-rhrev-assembler-pagerhref.js

@@ -0,0 +1,79 @@
+'use strict'
+
+/**
+ * Antora extension to rewrite pagerhref: macros in assembled documents to provide page numbers for asciidoctor-pdf
+ * 
+ * Converts pagerhref targets from xref format to Antora ID format:
+ *   pagerhref:chapter-1.adoc[] -> pagerhref:chapter-1[]
+ *   pagerhref:chapter-1.adoc#section-1-1[] -> pagerhref:chapter-1----section-1-1[]
+ * 
+ * This matches how Antora handles xrefs during assembly.
+ * 
+ * Usage in antora-playbook.yml:
+ *   antora:
+ *     extensions:
+ *       - require: ./{the-path-to-the-file}/antora-rhrev-assembler-pagerhref.js
+ *         quiet: true  # Set to false for debug output
+ */
+
+const PAGERHREF_RX = /pagerhref:([^\[]+)\[([^\]]*)\]/g
+
+module.exports.register = function ({ config: extensionConfig = {} }) {
+  const logger = this.getLogger('pagerhref-extension')
+  
+  // Config from playbook extension options (quiet: true is default)
+  const quiet = extensionConfig.quiet !== undefined ? extensionConfig.quiet : true
+  
+  if (!quiet) {
+    logger.debug('pagerhref-extension: REGISTERED')
+  }
+  
+  // Hook into contentClassified - after content is parsed but before conversion
+  this.on('contentClassified', ({ contentCatalog }) => {
+    if (!contentCatalog) return
+    
+    // Process all page files
+    const pageFiles = contentCatalog.findBy({ family: 'page' }) || []
+    
+    pageFiles.forEach(file => {
+      if (!file.contents) return
+      
+      const contents = file.contents.toString()
+      if (!contents.includes('pagerhref:')) return
+      
+      let modified = false
+      const newContents = contents.replace(PAGERHREF_RX, (match, target, attrs) => {
+        // Convert .adoc# to ---- (e.g., chapter-1.adoc#section -> chapter-1----section)
+        // Using ---- instead of ::: to avoid confusing Asciidoctor's HTML parser
+        if (target.includes('.adoc#')) {
+          const newTarget = target.replace('.adoc#', '----')
+          if (!quiet) {
+            logger.debug(`Rewriting pagerhref: ${target} -> ${newTarget}`)
+          }
+          modified = true
+          return `pagerhref:${newTarget}[${attrs}]`
+        }
+        
+        // Strip .adoc suffix (e.g., chapter-1.adoc -> chapter-1)
+        if (target.endsWith('.adoc')) {
+          const newTarget = target.slice(0, -5)
+          if (!quiet) {
+            logger.debug(`Rewriting pagerhref: ${target} -> ${newTarget}`)
+          }
+          modified = true
+          return `pagerhref:${newTarget}[${attrs}]`
+        }
+        
+        // Already in correct format
+        return match
+      })
+      
+      if (modified) {
+        file.contents = Buffer.from(newContents)
+        if (!quiet) {
+          logger.debug(`Updated pagerhref macros in ${file.src?.relative}`)
+        }
+      }
+    })
+  })
+}

package/antora-extension/antora-rhrev-html.js

@@ -0,0 +1,364 @@
+'use strict'
+
+/**
+ * Antora pipeline extension for revision history (rhrev).
+ * 
+ * Hooks into contentClassified to scan ALL pages in the content catalog
+ * and build a global revision history that spans across pages.
+ * Then injects the revision history into pages that have rhrev::[] macro.
+ */
+
+const RHREV_MACRO_RX = /^rhrev::(\[.*?\])?$/gm
+
+module.exports.register = function ({ config: extensionConfig = {} }) {
+  const logger = this.getLogger('rhrev-extension')
+  const quiet = extensionConfig.quiet !== undefined ? extensionConfig.quiet : true
+  
+  if (!quiet) {
+    logger.debug('rhrev-extension: REGISTERED')
+  }
+  
+  // Hook into contentClassified - we can still modify raw content
+  this.on('contentClassified', ({ contentCatalog, siteAsciiDocConfig }) => {
+    if (!contentCatalog) return
+    
+    if (!quiet) {
+      logger.debug('rhrev-extension: contentClassified event fired')
+    }
+    
+    // Find all pages in the catalog
+    const pageFiles = contentCatalog.findBy({ family: 'page' }) || []
+    
+    if (!quiet) {
+      logger.debug(`rhrev-extension: Found ${pageFiles.length} page files`)
+    }
+    
+    // Build global catalog by scanning all pages
+    const globalCatalog = buildGlobalCatalog(pageFiles, logger, quiet)
+    
+    if (!quiet) {
+      logger.debug(`rhrev-extension: Global catalog has ${Object.keys(globalCatalog.entries).length} revisions`)
+      logger.debug(`rhrev-extension: Total block entries: ${Object.values(globalCatalog.entries).reduce((sum, arr) => sum + arr.length, 0)}`)
+    }
+    
+    // Store the catalog globally so the Asciidoctor extension can access it
+    // This allows proper backend-specific rendering (HTML vs PDF)
+    global.antoraRhrevCatalog = globalCatalog
+    
+    if (!quiet) {
+      logger.debug('rhrev-extension: Global catalog stored for Asciidoctor extension')
+    }
+  })
+}
+
+function buildGlobalCatalog(pageFiles, logger, quiet) {
+  const catalog = {
+    entries: {},      // { '1-1': [...], '1-2': [...] }
+    allEntries: {},   // { '1-1': 'text', '1-2': 'text' }
+    sequence: 0,
+    
+    // Add sortedRevisions method for compatibility with Asciidoctor extension
+    sortedRevisions() {
+      const allRevisions = [
+        ...Object.keys(this.entries),
+        ...Object.keys(this.allEntries)
+      ]
+      const uniqueRevisions = [...new Set(allRevisions)]
+      
+      return uniqueRevisions.sort((a, b) => {
+        const [aMajor, aMinor] = a.split('-').map(Number)
+        const [bMajor, bMinor] = b.split('-').map(Number)
+        
+        if (aMajor !== bMajor) return bMajor - aMajor
+        return bMinor - aMinor
+      })
+    }
+  }
+  
+  // Get component attributes from first file's src.origin (antora.yml)
+  const firstFile = pageFiles[0]
+  if (!firstFile) return catalog
+  
+  // Component attributes are in src.origin.descriptor.asciidoc.attributes
+  const componentAttrs = firstFile.src?.origin?.descriptor?.asciidoc?.attributes || {}
+  const prefix = componentAttrs.revhistoryprefix || 'rhrev'
+  
+  if (!quiet) {
+    logger.debug(`rhrev-extension: Using prefix '${prefix}'`)
+  }
+  
+  // Collect document-level entries (-all)
+  for (let major = 0; major <= 9; major++) {
+    for (let minor = 0; minor <= 9; minor++) {
+      const revision = `${major}-${minor}`
+      const prevrevAttr = `${revision}-prevrev`
+      
+      if (componentAttrs[prevrevAttr]) {
+        const allAttrName = `${prefix}${revision}-all`
+        const allValue = componentAttrs[allAttrName]
+        
+        if (allValue) {
+          catalog.allEntries[revision] = allValue
+          
+          if (!quiet) {
+            logger.debug(`rhrev-extension: Found -all entry for ${revision}`)
+          }
+        }
+      }
+    }
+  }
+  
+  // Collect block-level entries from ALL pages
+  pageFiles.forEach(file => {
+    if (!file.contents) return
+    
+    const content = file.contents.toString()
+    
+    if (!quiet && content.includes(prefix)) {
+      logger.debug(`rhrev-extension: Scanning ${file.src?.relative} for block attributes`)
+    }
+    
+    // Match block attribute lines: [rhrev1-1="text"]
+    const blockAttrRx = new RegExp(`\\[${prefix}([0-9]+-[0-9]+)="([^"]+)"\\]`, 'g')
+    let match
+    
+    while ((match = blockAttrRx.exec(content)) !== null) {
+      const revision = match[1]
+      const changeText = match[2]
+      
+      // Look for anchor/title IMMEDIATELY after the attribute (within next 200 chars)
+      const matchEnd = match.index + match[0].length
+      const nextChunk = content.substring(matchEnd, matchEnd + 200)
+      
+      // Look for [#anchor], .Title, or === Section in that order
+      const anchorMatch = nextChunk.match(/^\s*\[#([^\]]+)\]/)
+      const titleMatch = nextChunk.match(/^\s*\.([^\n]+)/)
+      const sectionMatch = nextChunk.match(/^\s*(==+)\s+([^\n]+)/)
+      
+      let anchor = null
+      let title = null
+      
+      if (anchorMatch) {
+        anchor = anchorMatch[1]
+        // Still need to find title after anchor
+        const afterAnchor = nextChunk.substring(anchorMatch[0].length)
+        const titleAfterAnchor = afterAnchor.match(/^\s*\.([^\n]+)/)
+        const sectionAfterAnchor = afterAnchor.match(/^\s*(==+)\s+([^\n]+)/)
+        title = titleAfterAnchor ? titleAfterAnchor[1] : (sectionAfterAnchor ? sectionAfterAnchor[2] : anchor)
+      } else if (sectionMatch) {
+        title = sectionMatch[2]
+        // Generate anchor from section title (Asciidoctor's default behavior)
+        anchor = '_' + title.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '')
+      } else if (titleMatch) {
+        title = titleMatch[1]
+        // No explicit anchor, will use title as fallback
+      }
+      
+      if (!quiet) {
+        logger.debug(`rhrev-extension: Found ${revision} -> anchor=${anchor}, title=${title} in ${file.src?.relative}`)
+      }
+          
+          if (anchor) {
+            if (!catalog.entries[revision]) {
+              catalog.entries[revision] = []
+            }
+            
+            catalog.entries[revision].push({
+              anchor,
+              change: changeText,
+              title,
+              sequence: catalog.sequence++,
+              page: file.src?.relative || file.path
+            })
+            
+        if (!quiet) {
+          logger.debug(`rhrev-extension: Found block entry ${revision} -> ${anchor} in ${file.src?.relative}`)
+        }
+      } else if (!quiet) {
+        logger.debug(`rhrev-extension: Could not determine anchor for ${revision} in ${file.src?.relative}`)
+      }
+    }
+  })
+  
+  return catalog
+}
+
+function generateRevisionHistoryHtml(file, catalog, logger, quiet) {
+  // Get attributes from component descriptor (antora.yml)
+  const attrs = file.src?.origin?.descriptor?.asciidoc?.attributes || {}
+  
+  const columnWidths = String(attrs['rhrev-table-column-width'] || '30,70').split(',').map(w => w.trim())
+  const frame = attrs['rhrev-table-frame'] || 'all'
+  const grid = attrs['rhrev-table-grid'] || 'all'
+  const sectionLabel = attrs['rhrev-localization-location'] || 'Section'
+  const majorChangesText = attrs['rhrev-localization-major-changes'] || 'Major changes since'
+  const allText = attrs['rhrev-localization-all'] || 'All'
+  const versionLabel = attrs['version-label'] || 'Revision'
+  const discrete = attrs['rhrev-discrete'] !== undefined
+  
+  const html = []
+  
+  // Wrapper
+  if (discrete) {
+    html.push('<div class="rhrev-section">')
+  } else {
+    html.push('<section id="revision-history">')
+  }
+  
+  // Title
+  const customTitle = attrs['rhrev-customization-title']
+  if (customTitle !== undefined && customTitle === '') {
+    // Empty title, suppress
+  } else if (customTitle) {
+    const resolvedTitle = String(customTitle).replace('{version-label}', versionLabel)
+    html.push(`<h2>${resolvedTitle}</h2>`)
+  } else {
+    html.push(`<h2>${versionLabel} History</h2>`)
+  }
+  
+  // Table
+  html.push(`<table class="tableblock frame-${frame} grid-${grid} stretch">`)
+  
+  // Caption
+  if (!attrs['rhrev-disable-caption']) {
+    const caption = attrs['rhrev-table-caption']
+    if (caption) {
+      html.push(`<div class="title">${caption}</div>`)
+    }
+  }
+  
+  html.push('<colgroup>')
+  columnWidths.forEach(w => {
+    html.push(`<col style="width: ${w}%;">`)
+  })
+  html.push('</colgroup>')
+  html.push('<tbody>')
+  
+  // Custom first row
+  const firstRow = attrs['rhrev-customization-first-row']
+  const firstRowLeft = attrs['rhrev-customization-first-row-left']
+  const firstRowRight = attrs['rhrev-customization-first-row-right']
+  
+  if (firstRow) {
+    html.push('<tr class="rhrev-custom-first-row">')
+    html.push(`<td colspan="2">${firstRow}</td>`)
+    html.push('</tr>')
+  } else if (firstRowLeft || firstRowRight) {
+    html.push('<tr class="rhrev-custom-first-row">')
+    html.push(`<td>${firstRowLeft || '&nbsp;'}</td>`)
+    html.push(`<td>${firstRowRight || '&nbsp;'}</td>`)
+    html.push('</tr>')
+  }
+  
+  // Get sorted revisions
+  const allRevisions = [
+    ...Object.keys(catalog.entries),
+    ...Object.keys(catalog.allEntries)
+  ]
+  const uniqueRevisions = [...new Set(allRevisions)]
+  
+  const sortedRevisions = uniqueRevisions.sort((a, b) => {
+    const [aMajor, aMinor] = a.split('-').map(Number)
+    const [bMajor, bMinor] = b.split('-').map(Number)
+    
+    if (aMajor !== bMajor) return bMajor - aMajor
+    return bMinor - aMinor
+  })
+  
+  // Generate revision rows
+  sortedRevisions.forEach(revision => {
+    const prevrevAttr = `${revision}-prevrev`
+    const prevTitle = String(attrs[prevrevAttr] || revision.replace('-', '.'))
+    const prevrevdateAttr = `${revision}-prevrevdate`
+    const prevDate = attrs[prevrevdateAttr] || ''
+    
+    // Build header text
+    let headerText
+    if (prevTitle.trim().toLowerCase().startsWith(versionLabel.toLowerCase())) {
+      headerText = `${majorChangesText} ${prevTitle}`
+    } else {
+      headerText = `${majorChangesText} ${versionLabel} ${prevTitle}`
+    }
+    
+    // Header row
+    html.push('<tr class="rhrev-header">')
+    html.push(`<th class="tableblock halign-left valign-top">${sectionLabel}</th>`)
+    html.push(`<th class="tableblock halign-left valign-top"><strong>${headerText}</strong></th>`)
+    html.push('</tr>')
+    
+    // All entry
+    const allChange = catalog.allEntries[revision]
+    if (allChange) {
+      html.push('<tr>')
+      html.push(`<td>${allText}</td>`)
+      html.push(`<td>${formatChangeAsHtmlList(allChange)}</td>`)
+      html.push('</tr>')
+    }
+    
+    // Block entries
+    const entries = catalog.entries[revision] || []
+    entries.sort((a, b) => (a.sequence || 0) - (b.sequence || 0))
+    
+    entries.forEach(entry => {
+      html.push('<tr>')
+      
+      // Build link - if entry is from a different page, include page path
+      let linkHref = `#${entry.anchor}`
+      if (entry.page && entry.page !== file.src?.relative) {
+        // Cross-page link: convert "modules/ROOT/pages/chapter-1.adoc" to "chapter-1.html#anchor"
+        const pagePath = entry.page.replace('modules/ROOT/pages/', '').replace('.adoc', '.html')
+        linkHref = `${pagePath}#${entry.anchor}`
+      }
+      
+      html.push(`<td><a href="${linkHref}">${entry.title || entry.anchor}</a></td>`)
+      html.push(`<td>${formatChangeAsHtmlList(entry.change)}</td>`)
+      html.push('</tr>')
+    })
+  })
+  
+  html.push('</tbody>')
+  html.push('</table>')
+  
+  // Close wrapper
+  html.push(discrete ? '</div>' : '</section>')
+  
+  if (!quiet) {
+    logger.debug(`rhrev-extension: Generated HTML with ${sortedRevisions.length} revisions`)
+  }
+  
+  return html.join('\n')
+}
+
+function formatChangeAsHtmlList(text) {
+  if (!text) return ''
+  
+  // Handle line continuations
+  const processed = String(text).replace(/\\\s*\n\s*/g, ' ')
+  
+  // Split by asterisks
+  const tokens = processed.split(/\s(?=\*+\s)/)
+  const items = []
+  
+  if (tokens.length === 1 && !processed.includes('*')) {
+    items.push({ level: 1, content: processed })
+  } else {
+    tokens.forEach(token => {
+      if (!token.trim()) return
+      
+      const match = token.trim().match(/^(\*+)\s+(.+)/)
+      if (match) {
+        items.push({ level: match[1].length, content: match[2] })
+      } else {
+        items.push({ level: 1, content: token.trim() })
+      }
+    })
+  }
+  
+  const html = ['<ul>']
+  items.forEach(item => {
+    html.push(`<li>${item.content}</li>`)
+  })
+  html.push('</ul>')
+  
+  return html.join('\n')
+}

package/antora-extension/antora-rhrev-placeholder.js

@@ -0,0 +1,12 @@
+// This simply adds a blank paragraph as a temporary fix to avoid an Antora/AsciiDoctor debug message from displaying.
+
+module.exports.register = function (registry) {
+  // rhrev 
+  registry.blockMacro('rhrev', function () {
+    const self = this;
+    self.process(function (parent, target, attrs) {
+      // Create a simple paragraph placeholder
+      return self.createBlock(parent, 'paragraph', '');
+    });
+  });
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "asciidoctor-rhrev",
+  "version": "1.0.1",
+  "description": "Revision history block macro extension for Asciidoctor.js and Antora (HTML5 backend)",
+  "main": "antora-extension/antora-rhrev-asciidoc.js",
+  "scripts": {
+    "build": "antora antora-playbook.yml"
+  },
+  "keywords": [
+    "asciidoctor",
+    "antora",
+    "revision-history",
+    "documentation",
+    "versioning"
+  ],
+  "author": "白一百 baiyibai",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/baiyibai-asciidoc/rhrev-asciidoctor-automatic-revision-history.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "antora-extension/antora-rhrev-asciidoc.js",
+    "antora-extension/antora-rhrev-assembler-pagerhref.js",
+    "antora-extension/antora-rhrev-html.js",
+    "antora-extension/antora-rhrev-placeholder.js",
+    "README.adoc",
+    "LICENSE"
+  ]
+}