Add gitref macro to reference a git hash

With this extension a git hash can be easily referenced.

The porters handbook versions chapter uses this extension
as an example in the FreeBSD 14.0 version table.

An example of use

gitref:hash[repository="src|doc|ports",length=hash-longitude]

The repository should be src, doc or ports.
And if no length it's specified the macro will use 12 characters
of the specified hash.

PR:             253050
Submitted by:   jhb@

5 files changed, 36 insertions, 6 deletions

diff --git a/documentation/config/_default/config.toml b/documentation/config/_default/config.toml
index d75e4f5433..316f8bacd8 100644
--- a/documentation/config/_default/config.toml
+++ b/documentation/config/_default/config.toml
@@ -19,7 +19,7 @@ enableRobotsTXT = true
 
 [markup.asciidocExt]
     preserveTOC = true
-    extensions = ["../shared/lib/man-macro.rb", "../shared/lib/inter-document-references-macro.rb", "../shared/lib/sectnumoffset-treeprocessor.rb", "../shared/lib/packages-macro.rb"]
+    extensions = ["../shared/lib/man-macro.rb", "../shared/lib/inter-document-references-macro.rb", "../shared/lib/sectnumoffset-treeprocessor.rb", "../shared/lib/packages-macro.rb", "../shared/lib/git-macro.rb"]
 
 [outputs]
 home = [ "HTML" ]
diff --git a/documentation/content/en/books/porters-handbook/versions/chapter.adoc b/documentation/content/en/books/porters-handbook/versions/chapter.adoc
index cc3ab873b3..e55201ea51 100644
--- a/documentation/content/en/books/porters-handbook/versions/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/versions/chapter.adoc
@@ -43,22 +43,22 @@ Here is a convenient list of `__FreeBSD_version` values as defined in https://cg
 | Release
 
 |1400000
-|link:https://cgit.freebsd.org/src/commit/?id=a53ce3fc4938e37d5ec89304846203d2083c61a2[a53ce3fc4938]
+|gitref:a53ce3fc4938e37d5ec89304846203d2083c61a2[repository="src",length=12]
 |January 22, 2021
 |14.0-CURRENT.
 
 |1400001
-|link:https://cgit.freebsd.org/src/commit/?id=739ecbcf1c4fd22b5f6ee0bb180a67644046a3e0[739ecbcf1c4f]
+|gitref:739ecbcf1c4fd22b5f6ee0bb180a67644046a3e0[repository="src",length=12]
 |January 23, 2021
 |14.0-CURRENT after adding symlink support to lockless lookup.
 
 |1400002
-|link:https://cgit.freebsd.org/src/commit/?id=2cf84258922f306a3f84866685d2f5346f67db58[2cf84258922f]
+|gitref:2cf84258922f306a3f84866685d2f5346f67db58[repository="src",length=12]
 |January 26, 2021
 |14.0-CURRENT after fixing a clang assertion when building the package:devel/onetbb[] port.
 
 |1400003
-|link:https://cgit.freebsd.org/src/commit/?id=d386f3a3c32f0396aa7995349dd65d6c59711393[d386f3a3c32f]
+|gitref:d386f3a3c32f0396aa7995349dd65d6c59711393[repository="src",length=12]
 |January 28, 2021
 |14.0-CURRENT after adding various LinuxKPI bits conflicting with drm-kmod.
 |===
diff --git a/shared/lib/GitReferencesMacro/extension.rb b/shared/lib/GitReferencesMacro/extension.rb
new file mode 100644
index 0000000000..40dcbed1fd
--- /dev/null
+++ b/shared/lib/GitReferencesMacro/extension.rb
@@ -0,0 +1,25 @@
+require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
+
+include ::Asciidoctor
+
+class GitReferencesMacro < Asciidoctor::Extensions::InlineMacroProcessor
+  use_dsl
+
+  named :gitref
+
+  def process parent, target, attrs
+    hash = target
+    repository = if (repository = attrs['repository'])
+      "#{repository}"
+    else
+      "src"
+    end
+    length = if (length = attrs['length'])
+      length.to_i
+    else
+      12
+    end
+    url = %(https://cgit.freebsd.org/#{repository}/commit/?id=#{hash})
+    %(<a href="#{url}">#{hash[0, length]}</a>)
+  end
+end
diff --git a/shared/lib/git-macro.rb b/shared/lib/git-macro.rb
new file mode 100644
index 0000000000..0ed1526b14
--- /dev/null
+++ b/shared/lib/git-macro.rb
@@ -0,0 +1,5 @@
+RUBY_ENGINE == 'opal' ? (require 'GitReferencesMacro/extension') : (require_relative 'GitReferencesMacro/extension')
+
+Asciidoctor::Extensions.register do
+    inline_macro GitReferencesMacro
+end 
diff --git a/website/config/_default/config.toml b/website/config/_default/config.toml
index 656b88787c..a7c4585ebe 100644
--- a/website/config/_default/config.toml
+++ b/website/config/_default/config.toml
@@ -17,7 +17,7 @@ preserveTOC = true
 
 [markup.asciidocExt]
     preserveTOC = true
-    extensions = ["../shared/lib/man-macro.rb", "../shared/lib/inter-document-references-macro.rb", "../shared/lib/sectnumoffset-treeprocessor.rb", "../shared/lib/packages-macro.rb"]
+    extensions = ["../shared/lib/man-macro.rb", "../shared/lib/inter-document-references-macro.rb", "../shared/lib/sectnumoffset-treeprocessor.rb", "../shared/lib/packages-macro.rb", "../shared/lib/git-macro.rb"]
 
 staticDir = ["static", "shared"]