Add Github link support to beta and experimental macros

README.asciidoc

@@ -1479,7 +1479,14 @@ Text about old functionality...
 == Experimental and Beta
 
 APIs or parameters that are experimental or in beta can be marked as such, using
-markup similar to that used in <<changes>>.  For instance:
+markup similar to that used in <<changes>>.
+
+In the block format, you have the option of adding a related GitHub issue link.
+If both custom text and a GitHub link are provided, the GitHub link **must** be
+provided second. If it's supported in your repo, you can use the `{issue}`
+attribute in place of the GitHub issue link.
+
+For instance:
 
 [source,asciidoc]
 ----------------------------------
@@ -1488,8 +1495,16 @@ markup similar to that used in <<changes>>.  For instance:
 
 experimental::[]
 
+experimental::[https://github.com/elastic/docs/issues/505]
+
+experimental::[{issue}505]
+
 experimental::[Custom text goes here]
 
+experimental::[Custom text goes here,https://github.com/elastic/docs/issues/505]
+
+experimental::[Custom text goes here,{issue}505]
+
 Text about new feature...
 
 [[old-feature]]
@@ -1510,10 +1525,17 @@ a new experimental parameter:
 
 experimental::[]
 
+experimental::[https://github.com/elastic/docs/issues/505]
+
+experimental::[{issue}505]
+
 experimental::[Custom text goes here]
 
-Text about new feature...
+experimental::[Custom text goes here,https://github.com/elastic/docs/issues/505]
 
+experimental::[Custom text goes here,{issue}505]
+
+Text about new feature...
 [[old-feature]]
 === Established feature
 
@@ -1532,8 +1554,16 @@ a new experimental parameter:
 
 beta::[]
 
+beta::[https://github.com/elastic/docs/issues/505]
+
+beta::[{issue}505]
+
 beta::[Custom text goes here]
 
+beta::[Custom text goes here,https://github.com/elastic/docs/issues/505]
+
+beta::[Custom text goes here,{issue}505]
+
 Text about new feature...
 
 [[old-beta-feature]]
@@ -1554,8 +1584,16 @@ a new beta parameter:
 
 beta::[]
 
+beta::[https://github.com/elastic/docs/issues/505]
+
+beta::[{issue}505]
+
 beta::[Custom text goes here]
 
+beta::[Custom text goes here,https://github.com/elastic/docs/issues/505]
+
+beta::[Custom text goes here,{issue}505]
+
 Text about new feature...
 
 [[old-beta-feature]]

resources/asciidoctor/lib/care_admonition/extension.rb

@@ -34,19 +34,44 @@ def activate(registry)
   # Block care admonition.
   class ChangeAdmonitionBlock < Asciidoctor::Extensions::BlockMacroProcessor
     use_dsl
-    name_positional_attributes :passtext
+    name_positional_attributes :passtext, :issue_url
 
     def initialize(role, default_text)
       super(nil)
       @role = role
       @default_text = default_text
     end
 
+    def generate_text(text, issue_url)
+      if text&.start_with?('http', '{issue}')
+        issue_url = text
+        text = @default_text
+      else
+        issue_url = issue_url
+        text ||= @default_text
+      end
+      text = add_issue_text(text, issue_url) if issue_url
+      text
+    end
+
+    def add_issue_text(text, issue_url)
+      issue_num = get_issue_num(issue_url)
+      issue_text = <<~TEXT
+        For feature status, see #{issue_url}[\##{issue_num}].
+      TEXT
+      text + ' ' + issue_text
+    end
+
+    def get_issue_num(url)
+      return url.split('/').last.chomp('/') if url.start_with?('http')
+
+      url.sub('{issue}', '')
+    end
+
     def process(parent, _target, attrs)
+      text = generate_text(attrs[:passtext], attrs[:issue_url])
       Asciidoctor::Block.new(
-        parent, :admonition,
-        source: attrs[:passtext] || @default_text,
-        attributes: {
+        parent, :admonition, source: text, attributes: {
           'role' => @role,
           'name' => 'warning',
           'style' => 'warning',

resources/asciidoctor/spec/care_admonition_spec.rb

@@ -71,6 +71,56 @@ def expect_block_admonition(body)
           expect(converted).to include "<p>#{key}[]</p>"
         end
       end
+      context 'when only a Github issue link is provided' do
+        let(:input) do
+          <<~ASCIIDOC
+            #{key}::[https://github.com/elastic/docs/issues/505]
+          ASCIIDOC
+        end
+        it 'has default text and github text' do
+          expect_block_admonition <<~HTML.strip
+            <p>#{default_text} For feature status, see <a href="https://github.com/elastic/docs/issues/505" class="ulink" target="_top">#505</a>.</p>
+          HTML
+        end
+      end
+      context 'when only an {issue} link is provided' do
+        let(:input) do
+          <<~ASCIIDOC
+            :issue: https://github.com/elastic/docs/issues/
+            #{key}::[{issue}505]
+          ASCIIDOC
+        end
+        it 'has default text and github text' do
+          expect_block_admonition <<~HTML.strip
+            <p>#{default_text} For feature status, see <a href="https://github.com/elastic/docs/issues/505" class="ulink" target="_top">#505</a>.</p>
+          HTML
+        end
+      end
+      context 'when custom text and a Github issue link are provided' do
+        let(:input) do
+          <<~ASCIIDOC
+            #{key}::["Custom text." https://github.com/elastic/docs/issues/505]
+          ASCIIDOC
+        end
+        it 'has custom text and github text' do
+          expect_block_admonition <<~HTML.strip
+            <p>Custom text. For feature status, see <a href="https://github.com/elastic/docs/issues/505" class="ulink" target="_top">#505</a>.</p>
+          HTML
+        end
+      end
+      context 'when custom text and an {issue} link are provided' do
+        let(:input) do
+          <<~ASCIIDOC
+            :issue: https://github.com/elastic/docs/issues/
+            #{key}::["Custom text." {issue}505]
+          ASCIIDOC
+        end
+        it 'has custom text and github text' do
+          expect_block_admonition <<~HTML.strip
+            <p>Custom text. For feature status, see <a href="https://github.com/elastic/docs/issues/505" class="ulink" target="_top">#505</a>.</p>
+          HTML
+        end
+      end
     end
     context 'inline form' do
       def expect_inline_admonition(text)