git: 9f72b37570 - main - documentation: Modernize custom macros

The branch main has been updated by ziaee:

URL: https://cgit.FreeBSD.org/doc/commit/?id=9f72b37570796755e9f34689ca48be0dc1debf2b

commit 9f72b37570796755e9f34689ca48be0dc1debf2b
Author:     Alexander Ziaee <ziaee@FreeBSD.org>
AuthorDate: 2026-06-18 03:19:22 +0000
Commit:     Alexander Ziaee <ziaee@FreeBSD.org>
CommitDate: 2026-06-18 03:19:22 +0000

    documentation: Modernize custom macros
    
    Convert our custom macros to output asciidoctor instead of raw html,
    silencing 6500 warnings. This will enable us to turn verbose builds
    on, which will enable us to actually understand what is going on in
    the doc tree.
    
    Reviewed by:    dch, kevans
---
 shared/lib/CrossDocumentReferencesMacro/extension.rb | 6 +++---
 shared/lib/GitReferencesMacro/extension.rb           | 5 ++++-
 shared/lib/InterDocumentReferencesMacro/extension.rb | 8 ++++----
 shared/lib/ManPageMacro/extension.rb                 | 3 ++-
 shared/lib/PackagesMacro/extension.rb                | 3 ++-
 5 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/shared/lib/CrossDocumentReferencesMacro/extension.rb b/shared/lib/CrossDocumentReferencesMacro/extension.rb
index e85efe67f3..f1af69e522 100644
--- a/shared/lib/CrossDocumentReferencesMacro/extension.rb
+++ b/shared/lib/CrossDocumentReferencesMacro/extension.rb
@@ -21,12 +21,12 @@ class CrossDocumentReferencesMacro < Asciidoctor::Extensions::InlineMacroProcess
     doc = parent.document
 
     if doc.attributes['isonline'] == "1"
-      (create_anchor parent, text, type: :link, target: %(#{destination}#{anchor})).render
+      create_anchor parent, text, type: :link, target: %(#{destination}#{anchor})
     else
       if doc.attributes['doctype'] == "book"
-        (create_anchor parent, text, type: :link, target: %(../#{destination}/index.html#{anchor})).render
+        create_anchor parent, text, type: :link, target: %(../#{destination}/index.html#{anchor})
       else
-        (create_anchor parent, text, type: :link, target: %(#{destination}/index.html#{anchor})).render
+        create_anchor parent, text, type: :link, target: %(#{destination}/index.html#{anchor})
       end
     end
 
diff --git a/shared/lib/GitReferencesMacro/extension.rb b/shared/lib/GitReferencesMacro/extension.rb
index 40dcbed1fd..089bdced78 100644
--- a/shared/lib/GitReferencesMacro/extension.rb
+++ b/shared/lib/GitReferencesMacro/extension.rb
@@ -20,6 +20,9 @@ class GitReferencesMacro < Asciidoctor::Extensions::InlineMacroProcessor
       12
     end
     url = %(https://cgit.freebsd.org/#{repository}/commit/?id=#{hash})
-    %(<a href="#{url}">#{hash[0, length]}</a>)
+
+    short_sha = hash[0...length]
+    create_anchor parent, short_sha, type: :link, target: url
+
   end
 end
diff --git a/shared/lib/InterDocumentReferencesMacro/extension.rb b/shared/lib/InterDocumentReferencesMacro/extension.rb
index 7d74ede1bb..010c858bbe 100644
--- a/shared/lib/InterDocumentReferencesMacro/extension.rb
+++ b/shared/lib/InterDocumentReferencesMacro/extension.rb
@@ -21,15 +21,15 @@ class InterDocumentReferencesMacro < Asciidoctor::Extensions::InlineMacroProcess
     if doc.backend == 'html5'
       if doc.attributes['book'] == "true"
         if doc.attributes['isonline'] == "1"
-          (create_anchor parent, text, type: :link, target: %(./##{anchor})).render
+          create_anchor parent, text, type: :link, target: %(./##{anchor})
         else
-          (create_anchor parent, text, type: :link, target: %(./index.html##{anchor})).render
+          create_anchor parent, text, type: :link, target: %(./index.html##{anchor})
         end
       else
         if doc.attributes['isonline'] == "1"
-          (create_anchor parent, text, type: :link, target: %(../#{target}/##{anchor})).render
+          create_anchor parent, text, type: :link, target: %(../#{target}/##{anchor})
         else
-          (create_anchor parent, text, type: :link, target: %(../#{target}/index.html##{anchor})).render
+          create_anchor parent, text, type: :link, target: %(../#{target}/index.html##{anchor})
         end
       end
     else
diff --git a/shared/lib/ManPageMacro/extension.rb b/shared/lib/ManPageMacro/extension.rb
index 7f930bbd21..f544bff6c7 100644
--- a/shared/lib/ManPageMacro/extension.rb
+++ b/shared/lib/ManPageMacro/extension.rb
@@ -16,6 +16,7 @@ class ManPageMacro < Asciidoctor::Extensions::InlineMacroProcessor
       ""
     end
     url = %(https://man.freebsd.org/cgi/man.cgi?query=#{manname}&sektion=#{section}&format=html)
-    %(<a href="#{url}">#{manname}(#{section})</a>)
+    link_text = section.empty? ? manname : "#{manname}(#{section})"
+    create_anchor parent, link_text, type: :link, target: url
   end
 end
diff --git a/shared/lib/PackagesMacro/extension.rb b/shared/lib/PackagesMacro/extension.rb
index 5476995c49..7d84349101 100644
--- a/shared/lib/PackagesMacro/extension.rb
+++ b/shared/lib/PackagesMacro/extension.rb
@@ -23,6 +23,7 @@ class PackagesMacro < Asciidoctor::Extensions::InlineMacroProcessor
 
     url = %(https://cgit.freebsd.org/ports/tree/#{pkgorigin}/)
 
-    %(<a class="package" href="#{url}">#{pkgname}</a>)
+    create_anchor parent, target, type: :link, target: url
+
   end
 end