Revert "Remove custom example plugin. (#25784)"

This reverts commit d01b4eb.

This implementation has many limitations/issues.

site/_plugins/example.rb

@@ -0,0 +1,95 @@
+module Jekyll
+  module Tags
+    class ExampleBlock < Liquid::Block
+      include Liquid::StandardFilters
+
+      # The regular expression syntax checker. Start with the language specifier.
+      # Follow that by zero or more space separated options that take one of three
+      # forms: name, name=value, or name="<quoted list>"
+      #
+      # <quoted list> is a space-separated list of numbers
+      SYNTAX = /^([a-zA-Z0-9.+#-]+)((\s+\w+(=((\w|[0-9_-])+|"([0-9]+\s)*[0-9]+"))?)*)$/
+
+      def initialize(tag_name, markup, tokens)
+        super
+        if markup.strip =~ SYNTAX
+          @lang = $1.downcase
+          @options = {}
+          if defined?($2) && $2 != ''
+            # Split along 3 possible forms -- key="<quoted list>", key=value, or key
+            $2.scan(/(?:\w+(?:=(?:(?:\w|[0-9_-])+|"[^"]*")?)?)/) do |opt|
+              key, value = opt.split('=')
+              # If a quoted list, convert to array
+              if value && value.include?("\"")
+                  value.gsub!(/"/, "")
+                  value = value.split
+              end
+              @options[key.to_sym] = value || true
+            end
+          end
+          @options[:linenos] = false
+        else
+          raise SyntaxError.new <<-eos
+Syntax Error in tag 'example' while parsing the following markup:
+
+  #{markup}
+
+Valid syntax: example <lang> [id=foo]
+eos
+        end
+      end
+
+      def render(context)
+        prefix = context["highlighter_prefix"] || ""
+        suffix = context["highlighter_suffix"] || ""
+        code = super.to_s.strip
+
+        output = case context.registers[:site].highlighter
+
+        when 'rouge'
+          render_rouge(code)
+        end
+
+        rendered_output = example(code) + add_code_tag(output)
+        prefix + rendered_output + suffix
+      end
+
+      def example(output)
+        "<div class=\"bd-example\"" + (@options[:id] ? " data-example-id=\"#{@options[:id]}\"" : "") + ">\n#{output}\n</div>"
+      end
+
+      def remove_holderjs(code)
+        code = code.gsub(/data-src="holder.js.+?"/, 'src="..."')
+      end
+
+      def remove_example_classes(code)
+        # Find `bd-` classes and remove them from the highlighted code. Because of how this regex works, it will also
+        # remove classes that are after the `bd-` class. While this is a bug, I left it because it can be helpful too.
+        # To fix the bug, replace `(?=")` with `(?=("|\ ))`.
+        code = code.gsub(/(?!class=".)\ *?bd-.+?(?=")/, "")
+        # Find empty class attributes after the previous regex and remove those too.
+        code = code.gsub(/\ class=""/, "")
+      end
+
+      def render_rouge(code)
+        require 'rouge'
+        formatter = Rouge::Formatters::HTML.new(line_numbers: @options[:linenos], wrap: false)
+        lexer = Rouge::Lexer.find_fancy(@lang, code) || Rouge::Lexers::PlainText
+        code = remove_holderjs(code)
+        code = remove_example_classes(code)
+        code = formatter.format(lexer.lex(code))
+        "<div class=\"highlight\"><pre>#{code}</pre></div>"
+      end
+
+      def add_code_tag(code)
+        # Add nested <code> tags to code blocks
+        code = code.sub(/<pre>\n*/,'<pre><code class="language-' + @lang.to_s.gsub("+", "-") + '" data-lang="' + @lang.to_s + '">')
+        code = code.sub(/\n*<\/pre>/,"</code></pre>")
+        code.strip
+      end
+
+    end
+  end
+end
+
+Liquid::Template.register_tag('example', Jekyll::Tags::ExampleBlock)

site/docs/4.1/components/alerts.md

@@ -10,41 +10,38 @@ toc: true
 
 Alerts are available for any length of text, as well as an optional dismiss button. For proper styling, use one of the eight **required** contextual classes (e.g., `.alert-success`). For inline dismissal, use the [alerts jQuery plugin](#dismissing).
 
-{% capture example %}
+{% example html %}
 {% for color in site.data.theme-colors %}
 <div class="alert alert-{{ color.name }}" role="alert">
   A simple {{ color.name }} alert—check it out!
 </div>{% endfor %}
-{% endcapture %}
-{% include example.html content=example %}
+{% endexample %}
 
 {% include callout-warning-color-assistive-technologies.md %}
 
 ### Link color
 
 Use the `.alert-link` utility class to quickly provide matching colored links within any alert.
 
-{% capture example %}
+{% example html %}
 {% for color in site.data.theme-colors %}
 <div class="alert alert-{{ color.name }}" role="alert">
   A simple {{ color.name }} alert with <a href="#" class="alert-link">an example link</a>. Give it a click if you like.
 </div>{% endfor %}
-{% endcapture %}
-{% include example.html content=example %}
+{% endexample %}
 
 ### Additional content
 
 Alerts can also contain additional HTML elements like headings, paragraphs and dividers.
 
-{% capture example %}
+{% example html %}
 <div class="alert alert-success" role="alert">
   <h4 class="alert-heading">Well done!</h4>
   <p>Aww yeah, you successfully read this important alert message. This example text is going to run a bit longer so that you can see how spacing within an alert works with this kind of content.</p>
   <hr>
   <p class="mb-0">Whenever you need to, be sure to use margin utilities to keep things nice and tidy.</p>
 </div>
-{% endcapture %}
-{% include example.html content=example %}
+{% endexample %}
 
 
 ### Dismissing
@@ -59,15 +56,14 @@ Using the alert JavaScript plugin, it's possible to dismiss any alert inline. He
 
 You can see this in action with a live demo:
 
-{% capture example %}
+{% example html %}
 <div class="alert alert-warning alert-dismissible fade show" role="alert">
   <strong>Holy guacamole!</strong> You should check in on some of those fields below.
   <button type="button" class="close" data-dismiss="alert" aria-label="Close">
     <span aria-hidden="true">&times;</span>
   </button>
 </div>
-{% endcapture %}
-{% include example.html content=example %}
+{% endexample %}
 
 ## JavaScript behavior
 

site/docs/4.1/components/badge.md

@@ -30,53 +30,48 @@ Badges scale to match the size of the immediate parent element by using relative
 
 Badges can be used as part of links or buttons to provide a counter.
 
-{% capture example %}
+{% example html %}
 <button type="button" class="btn btn-primary">
   Notifications <span class="badge badge-light">4</span>
 </button>
-{% endcapture %}
-{% include example.html content=example %}
+{% endexample %}
 
 Note that depending on how they are used, badges may be confusing for users of screen readers and similar assistive technologies. While the styling of badges provides a visual cue as to their purpose, these users will simply be presented with the content of the badge. Depending on the specific situation, these badges may seem like random additional words or numbers at the end of a sentence, link, or button.
 
 Unless the context is clear (as with the "Notifications" example, where it is understood that the "4" is the number of notifications), consider including additional context with a visually hidden piece of additional text.
 
-{% capture example %}
+{% example html %}
 <button type="button" class="btn btn-primary">
   Profile <span class="badge badge-light">9</span>
   <span class="sr-only">unread messages</span>
 </button>
-{% endcapture %}
-{% include example.html content=example %}
+{% endexample %}
 
 ## Contextual variations
 
 Add any of the below mentioned modifier classes to change the appearance of a badge.
 
-{% capture example %}
+{% example html %}
 {% for color in site.data.theme-colors %}
 <span class="badge badge-{{ color.name }}">{{ color.name | capitalize }}</span>{% endfor %}
-{% endcapture %}
-{% include example.html content=example %}
+{% endexample %}
 
 {% include callout-warning-color-assistive-technologies.md %}
 
 ## Pill badges
 
 Use the `.badge-pill` modifier class to make badges more rounded (with a larger `border-radius` and additional horizontal `padding`). Useful if you miss the badges from v3.
 
-{% capture example %}
+{% example html %}
 {% for color in site.data.theme-colors %}
 <span class="badge badge-pill badge-{{ color.name }}">{{ color.name | capitalize }}</span>{% endfor %}
-{% endcapture %}
-{% include example.html content=example %}
+{% endexample %}
 
 ## Links
 
 Using the contextual `.badge-*` classes on an `<a>` element quickly provide _actionable_ badges with hover and focus states.
 
-{% capture example %}
+{% example html %}
 {% for color in site.data.theme-colors %}
 <a href="#" class="badge badge-{{ color.name }}">{{ color.name | capitalize }}</a>{% endfor %}
-{% endcapture %}
-{% include example.html content=example %}
+{% endexample %}

site/docs/4.1/components/breadcrumb.md

@@ -7,7 +7,7 @@ group: components
 
 ## Example
 
-{% capture example %}
+{% example html %}
 <nav aria-label="breadcrumb">
   <ol class="breadcrumb">
     <li class="breadcrumb-item active" aria-current="page">Home</li>
@@ -28,8 +28,7 @@ group: components
     <li class="breadcrumb-item active" aria-current="page">Data</li>
   </ol>
 </nav>
-{% endcapture %}
-{% include example.html content=example %}
+{% endexample %}
 
 ## Changing the separator
 

site/docs/4.1/components/button-group.md

@@ -10,14 +10,13 @@ toc: true
 
 Wrap a series of buttons with `.btn` in `.btn-group`. Add on optional JavaScript radio and checkbox style behavior with [our buttons plugin]({{ site.baseurl }}/docs/{{ site.docs_version }}/components/buttons/#button-plugin).
 
-{% capture example %}
+{% example html %}
 <div class="btn-group" role="group" aria-label="Basic example">
   <button type="button" class="btn btn-secondary">Left</button>
   <button type="button" class="btn btn-secondary">Middle</button>
   <button type="button" class="btn btn-secondary">Right</button>
 </div>
-{% endcapture %}
-{% include example.html content=example %}
+{% endexample %}
 
 {% capture callout %}
 ##### Ensure correct `role` and provide a label
@@ -32,7 +31,7 @@ In addition, groups and toolbars should be given an explicit label, as most assi
 
 Combine sets of button groups into button toolbars for more complex components. Use utility classes as needed to space out groups, buttons, and more.
 
-{% capture example %}
+{% example html %}
 <div class="btn-toolbar" role="toolbar" aria-label="Toolbar with button groups">
   <div class="btn-group mr-2" role="group" aria-label="First group">
     <button type="button" class="btn btn-secondary">1</button>
@@ -49,12 +48,11 @@ Combine sets of button groups into button toolbars for more complex components.
     <button type="button" class="btn btn-secondary">8</button>
   </div>
 </div>
-{% endcapture %}
-{% include example.html content=example %}
+{% endexample %}
 
 Feel free to mix input groups with button groups in your toolbars. Similar to the example above, you'll likely need some utilities though to space things properly.
 
-{% capture example %}
+{% example html %}
 <div class="btn-toolbar mb-3" role="toolbar" aria-label="Toolbar with button groups">
   <div class="btn-group mr-2" role="group" aria-label="First group">
     <button type="button" class="btn btn-secondary">1</button>
@@ -84,8 +82,7 @@ Feel free to mix input groups with button groups in your toolbars. Similar to th
     <input type="text" class="form-control" placeholder="Input group example" aria-label="Input group example" aria-describedby="btnGroupAddon2">
   </div>
 </div>
-{% endcapture %}
-{% include example.html content=example %}
+{% endexample %}
 
 ## Sizing
 
@@ -121,7 +118,7 @@ Instead of applying button sizing classes to every button in a group, just add `
 
 Place a `.btn-group` within another `.btn-group` when you want dropdown menus mixed with a series of buttons.
 
-{% capture example %}
+{% example html %}
 <div class="btn-group" role="group" aria-label="Button group with nested dropdown">
   <button type="button" class="btn btn-secondary">1</button>
   <button type="button" class="btn btn-secondary">2</button>
@@ -136,8 +133,7 @@ Place a `.btn-group` within another `.btn-group` when you want dropdown menus mi
     </div>
   </div>
 </div>
-{% endcapture %}
-{% include example.html content=example %}
+{% endexample %}
 
 ## Vertical variation