jekyll-link-decorator 1.7.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff4ff4aab91fea08f0f9d818a35287da8ad337181e028a2a2da62245866b3420
-  data.tar.gz: 81737c19fc41c5134c6741b0b6ebfb28746ca376f591c46a95a16631d56cfebf
+  metadata.gz: 4bce3e5f4ec8d1f6c44a4e75243379e739253c84658dd9b059aa158ef35db38e
+  data.tar.gz: 3f32795f52745553508b8e24355bb2a478f66e1ae1d09c9e84b6f0819f57885f
 SHA512:
-  metadata.gz: e912b0fbdc82c9640912f96b5a4f436d378e79fd4f9099eaba218759d7dc6ca688285b6785aa34163d89c749e153b9e5de37623277e66c16f892abe23fe3be02
-  data.tar.gz: 0ba21a73e60ad550d74415a22f06b2ada6bf83d8bef37521e778fcb546ca39bdb0695bdeefe1fb53c6fe65003608c2725f8446f3943f69664e105c4f0d704880
+  metadata.gz: 9b3487b5cc2e11eb15344e1ac14e90c1ef0c66b8087c0f056bfac275c645defcd6b8ebae83bc48d458652ffccefdfaaebfd9e4a2ddf2210c12596f70741ffcd1
+  data.tar.gz: a1728c3bea0a49441f358147c66c6e6fa2115f61783918b04e91e541d4ec5f3684ad4814af200af27d16a9a3ad012c7c9cfb06014097937773bed4c5eca12394

data/README.md

@@ -11,6 +11,10 @@ intervention.
 For complete documentation, configuration options, and examples, visit the
 [documentation site](https://centos.gitlab.io/artwork/centos-web/jekyll-link-decorator/).
 
+## Release notes
+
+See [GitLab Releases](https://gitlab.com/CentOS/artwork/centos-web/jekyll-link-decorator/-/releases).
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) file for details.

data/lib/jekyll-link-decorator/configuration/schema.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'did_you_mean'
+
+module Jekyll
+  module LinkDecorator
+    module Configuration
+      # The type of each setting under CONFIG_KEY, and how a value of the
+      # wrong type is converted or replaced by its default, with a warning.
+      # Configuration.resolve applies it after merging the site's settings.
+      module Schema
+        # The type of every leaf setting, by key path under CONFIG_KEY.
+        TYPES = {
+          %w[enabled] => :boolean,
+          %w[default_link_classes] => :class_list,
+          %w[alert_link_classes] => :class_list,
+          %w[external_link_icon] => :boolean,
+          %w[external_link_icon_excluded_tags] => :tag_list,
+          %w[heading_anchor enabled] => :boolean,
+          %w[heading_anchor icon] => :class_list,
+          %w[heading_anchor icon_size] => :class_list
+        }.freeze
+
+        # Per type: what the warning says to expect, which values pass as is,
+        # and how a near-miss converts (returns [converted], or nil when the
+        # value can't be converted and the default applies instead).
+        COERCERS = {
+          # "true"/"false" in any case, surrounding spaces ignored
+          boolean: {
+            expected: 'true or false',
+            accept: ->(value) { [true, false].include?(value) },
+            convert: lambda { |value|
+              word = value.strip.downcase if value.is_a?(String)
+              [word == 'true'] if %w[true false].include?(word)
+            }
+          },
+          # An empty string means no classes; nil means unset
+          class_list: {
+            expected: 'a space-separated string of classes',
+            accept: ->(value) { value.nil? || value.is_a?(String) },
+            convert: ->(value) { [value.join(' ')] if value.is_a?(Array) && value.all?(String) }
+          },
+          # A single string is not split on spaces: each entry is a CSS
+          # selector, so "a img" is one entry
+          tag_list: {
+            expected: 'a list of tag names',
+            accept: ->(value) { value.is_a?(Array) && value.all?(String) },
+            convert: ->(value) { [[value]] if value.is_a?(String) }
+          }
+        }.freeze
+
+        # Returns value if its type accepts it; otherwise its conversion,
+        # with a warning; otherwise the default, with a warning.
+        def self.coerce(value, path, type)
+          coercer = COERCERS.fetch(type)
+          return value if coercer[:accept].call(value)
+
+          key_path = [CONFIG_KEY, *path].join('.')
+          converted = coercer[:convert].call(value)
+          if converted
+            warn_invalid(key_path, value, coercer[:expected], "reading it as #{converted.first.inspect}")
+            return converted.first
+          end
+
+          warn_invalid(key_path, value, coercer[:expected])
+          DEFAULTS.dig(*path)
+        end
+
+        # Site-level keys removed in 2.0.0, mapped to where their settings
+        # live now.
+        LEGACY_KEYS = {
+          'with_link_decorator' => "#{CONFIG_KEY}.enabled",
+          'with_link_decorator_data' => "the keys directly under #{CONFIG_KEY}",
+          'with_heading_anchor' => "#{CONFIG_KEY}.heading_anchor.enabled",
+          'with_heading_anchor_data' => "the keys under #{CONFIG_KEY}.heading_anchor"
+        }.freeze
+
+        # Warns once per LEGACY_KEYS entry present in the site config, even
+        # with an empty value. The old keys stay ignored.
+        def self.warn_legacy_keys(site_config)
+          (LEGACY_KEYS.keys & site_config.keys).each do |old_key|
+            Jekyll.logger.warn 'LinkDecorator:',
+                               "#{old_key} was removed in 2.0.0 and is ignored; " \
+                               "use #{LEGACY_KEYS[old_key]} instead."
+          end
+        end
+
+        # Returns a copy of settings (the user's hash at `parents` under
+        # CONFIG_KEY) without the keys TYPES doesn't know, recursing into known
+        # nested mappings such as heading_anchor. Warns once per dropped key.
+        def self.without_unknown_keys(settings, parents = [])
+          known = known_keys(parents)
+          settings.each_with_object({}) do |(key, value), kept|
+            unless known.include?(key)
+              warn_unknown([CONFIG_KEY, *parents, key].join('.'), key, known)
+              next
+            end
+
+            nested = value.is_a?(Hash) && !known_keys([*parents, key]).empty?
+            kept[key] = nested ? without_unknown_keys(value, [*parents, key]) : value
+          end
+        end
+
+        # The keys allowed directly under `parents`, derived from TYPES' paths.
+        def self.known_keys(parents)
+          depth = parents.size
+          TYPES.keys.select { |path| path.size > depth && path.take(depth) == parents }
+               .map { |path| path[depth] }.uniq
+        end
+
+        def self.warn_unknown(key_path, key, known)
+          suggestion = DidYouMean::SpellChecker.new(dictionary: known).correct(key.to_s).first
+          hint = suggestion ? "; did you mean `#{suggestion}`?" : '.'
+          Jekyll.logger.warn 'LinkDecorator:', "#{key_path} is not a known setting and is ignored#{hint}"
+        end
+
+        # One warning per invalid value per build: resolve runs once per build
+        # (see Configuration.for), so this never repeats page by page.
+        def self.warn_invalid(key_path, value, expected, outcome = 'using the default')
+          Jekyll.logger.warn 'LinkDecorator:',
+                             "#{key_path} should be #{expected}, got #{value.inspect}; #{outcome}."
+        end
+        private_class_method :known_keys, :warn_unknown
+      end
+    end
+  end
+end

data/lib/jekyll-link-decorator/configuration.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module LinkDecorator
+    # Resolves the plugin's settings: the `jekyll_link_decorator` hash from
+    # _config.yml, deep-merged over DEFAULTS so every key has a value.
+    module Configuration
+      CONFIG_KEY = 'jekyll_link_decorator'
+      DISABLED_NOTICE = 'Disabled via configuration. Skipping custom link modification.'
+
+      DEFAULT_LINK_CLASSES = 'link link-offset-2 link-offset-2-hover link-underline ' \
+                             'link-underline-opacity-0 link-underline-opacity-100-hover focus-ring'
+      DEFAULT_ALERT_LINK_CLASSES = 'alert-link focus-ring'
+      DEFAULT_EXTERNAL_LINK_ICON = true
+      DEFAULT_EXTERNAL_LINK_ICON_EXCLUDED_TAGS = [].freeze
+      DEFAULT_HEADING_ANCHOR      = true
+      DEFAULT_HEADING_ANCHOR_ICON = 'heading-anchor-hash'
+
+      DEFAULTS = {
+        'enabled' => true,
+        'default_link_classes' => DEFAULT_LINK_CLASSES,
+        'alert_link_classes' => DEFAULT_ALERT_LINK_CLASSES,
+        'external_link_icon' => DEFAULT_EXTERNAL_LINK_ICON,
+        'external_link_icon_excluded_tags' => DEFAULT_EXTERNAL_LINK_ICON_EXCLUDED_TAGS,
+        'heading_anchor' => {
+          'enabled' => DEFAULT_HEADING_ANCHOR,
+          'icon' => DEFAULT_HEADING_ANCHOR_ICON
+        }.freeze
+      }.freeze
+
+      # Returns a deep-frozen copy of DEFAULTS with the site's own
+      # jekyll_link_decorator settings merged over it. Memoized per
+      # site_config object, so a build resolves its settings once rather
+      # than once per page.
+      def self.for(site_config)
+        cache[site_config] ||= resolve(site_config)
+      end
+
+      # Drops every memoized result. Registered on :site, :after_reset below,
+      # so each build (including each `jekyll serve --watch` rebuild) starts
+      # from the site config as it is then.
+      def self.reset!
+        @cache = nil
+      end
+
+      # Keyed on object identity, and holds its results strongly: a weak map
+      # would let GC drop them mid-build and repeat every warning. reset!
+      # clears it at the start of each build, so it never outgrows one build.
+      def self.cache
+        @cache ||= {}.compare_by_identity
+      end
+
+      def self.resolve(site_config)
+        Schema.warn_legacy_keys(site_config)
+        user = Schema.without_unknown_keys(with_heading_anchor_mapping(user_settings(site_config[CONFIG_KEY])))
+        merged = Jekyll::Utils.deep_merge_hashes(DEFAULTS, user)
+        Schema::TYPES.each { |path, type| rewrite(merged, path) { |value| Schema.coerce(value, path, type) } }
+        # Here rather than in the Decorator, so a disabled build says so once.
+        Jekyll.logger.info 'LinkDecorator:', DISABLED_NOTICE unless merged['enabled']
+        frozen_copy(merged)
+      end
+
+      # Runs before the merge, because deep_merge_hashes would otherwise
+      # replace the whole heading_anchor defaults hash with a scalar. Accepts
+      # a bare true/false as a supported shorthand for `enabled`, like the
+      # top-level key does; warns about and drops any other non-mapping so the
+      # defaults apply. Returns a new hash; `user` is left untouched.
+      def self.with_heading_anchor_mapping(user)
+        value = user['heading_anchor']
+        return user if value.nil? || value.is_a?(Hash)
+        return user.merge('heading_anchor' => { 'enabled' => value }) if [true, false].include?(value)
+
+        Schema.warn_invalid("#{CONFIG_KEY}.heading_anchor", value, 'a mapping of settings')
+        user.except('heading_anchor')
+      end
+
+      # Replaces the value at path with the block's result, unless the key is
+      # absent. `merged` is safe to mutate: deep_merge_hashes returns fresh
+      # hashes at every level it merges.
+      def self.rewrite(merged, path)
+        *parents, key = path
+        parent = parents.empty? ? merged : merged.dig(*parents)
+        return unless parent.is_a?(Hash) && parent.key?(key)
+
+        parent[key] = yield(parent[key])
+      end
+
+      # Accepts the top-level key as a mapping, or as a bare true/false
+      # shorthand for `enabled`. Null means unset; anything else is warned
+      # about and ignored.
+      def self.user_settings(value)
+        case value
+        when Hash        then value
+        when true, false then { 'enabled' => value }
+        when nil         then {}
+        else
+          Schema.warn_invalid(CONFIG_KEY, value, 'a mapping of settings, or true/false')
+          {}
+        end
+      end
+
+      # Freezes copies, never the originals, so values shared by reference
+      # with site.config are left mutable for Jekyll and other plugins.
+      def self.frozen_copy(value)
+        case value
+        when Hash   then value.to_h { |key, val| [key, frozen_copy(val)] }.freeze
+        when Array  then value.map { |val| frozen_copy(val) }.freeze
+        when String then -value
+        else value
+        end
+      end
+      private_class_method :cache, :resolve, :user_settings, :with_heading_anchor_mapping, :rewrite,
+                           :frozen_copy
+    end
+  end
+end
+
+# Schema's constants read CONFIG_KEY, defined above.
+require_relative 'configuration/schema'
+
+Jekyll::Hooks.register(:site, :after_reset) { Jekyll::LinkDecorator::Configuration.reset! }

data/lib/jekyll-link-decorator/decorator.rb

@@ -0,0 +1,348 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+require 'set'
+
+module Jekyll
+  module LinkDecorator
+    # Decorates already-converted HTML: applies Bootstrap classes to <a> tags
+    # based on context (e.g., inside an alert box) via Nokogiri CSS selectors,
+    # excluding buttons; adds target and an external-link icon to
+    # cross-domain links, and rel to every link that opens in a new tab; and
+    # injects heading anchors. Built from the site config; both the
+    # post_convert hook and the decorate_links filter use it.
+    class Decorator
+      # An absolute http(s) URL, or a protocol-relative one ("//host/path"),
+      # which names a host just the same. Schemes are case-insensitive, and
+      # matching starts at the beginning of the string, not of any line.
+      ABSOLUTE_URL = %r{\A(?:https?:)?//}i
+
+      # The links the plugin decorates. Buttons are left alone: their look
+      # and behavior belong to the author's own .btn styling.
+      DECORATED_LINKS = 'a:not(.btn)'
+
+      # The headings that get a permalink anchor.
+      HEADINGS = 'h1, h2, h3, h4, h5, h6'
+
+      EXISTING_ICON_SELECTORS = [
+        'i[class*="fa-external-link"]',
+        'i[class*="up-right-from-square"]',
+        'svg[data-icon="external-link"]',
+        'svg[data-icon="up-right-from-square"]',
+        'svg[data-icon="arrow-up-right-from-square"]'
+      ].freeze
+
+      # Bootstrap 5 link-utility "families" whose defaults must not silently
+      # override an author's own explicit class from the same family — see
+      # classes_to_add_for.
+      #
+      # Each entry carries a single `pattern:` regex, anchored \A...\z and
+      # matched per class token (not against the whole class string), so a
+      # compound name like "social-link-danger" or "sidebar-link-offset-2" is
+      # never mistaken for an override.
+      #
+      # Enumerated families (offset, both opacity families) lock to Bootstrap's
+      # fixed value set, so an out-of-range value like "link-opacity-42" isn't
+      # recognized as an override either. Color and focus-ring families
+      # (link-{color}, link-underline-{color}, focus-ring(-{color})?) stay
+      # generic (\S+) since Bootstrap themes can define arbitrary custom color names.
+      LINK_CLASS_FAMILIES = [
+        { # link-{color}, e.g. link-primary, link-body-emphasis (bare colored-link class;
+          # excludes link-underline-*, link-offset-*, and link-opacity-* families)
+          pattern: /\Alink-(?!underline\b|offset-|opacity-)\S+\z/
+        },
+        { # link-underline and link-underline-{color}, e.g. link-underline-success
+          # (excludes -opacity-*); the bare class takes the link's own text color
+          pattern: /\Alink-underline(?:-(?!opacity)\S+)?\z/
+        },
+        { # link-offset-{1,2,3}, each with an optional -hover variant
+          pattern: /\Alink-offset-[123](-hover)?\z/
+        },
+        { # link-underline-opacity-{0,10,25,50,75,100}, each with an optional -hover variant
+          pattern: /\Alink-underline-opacity-(?:0|10|25|50|75|100)(-hover)?\z/
+        },
+        { # link-opacity-{10,25,50,75,100}, each with an optional -hover variant
+          # (controls link-text opacity, distinct from link-underline-opacity-*)
+          pattern: /\Alink-opacity-(?:10|25|50|75|100)(-hover)?\z/
+        },
+        { # focus-ring and focus-ring-{color}, e.g. focus-ring-primary, focus-ring-success
+          # Bootstrap 5.3 focus-ring has no hover, offset, or opacity variants — only bare
+          # and color forms; color stays generic (\S+) for custom theme colors
+          pattern: /\Afocus-ring(-\S+)?\z/
+        }
+      ].freeze
+
+      # site_config is the whole site config (site.config); the plugin's own
+      # settings are resolved from it by plugin_config.
+      def initialize(site_config)
+        @config = site_config
+      end
+
+      # Entry point for the post_convert hook and the decorate_links filter.
+      # Never raises: on any error it logs and returns html unchanged.
+      def decorate_html(html)
+        render(html)
+      rescue StandardError => e
+        Jekyll.logger.error 'LinkDecorator Error:',
+                            "An error occurred during link decoration: #{e.message}"
+        Jekyll.logger.error 'Backtrace:', e.backtrace.join("\n")
+
+        html
+      end
+
+      # Resolves settings, parses html, and runs every phase. Raises on
+      # error; kept apart from decorate_html's rescue so a trace span around
+      # it records the failure.
+      def render(html)
+        config = plugin_config
+        return html unless config['enabled']
+
+        doc = Nokogiri::HTML::DocumentFragment.parse(html)
+
+        apply_link_styles(doc, config)
+        add_external_link_features(doc, config)
+        add_heading_anchors(doc, config)
+
+        doc.to_html
+      end
+      private :render
+
+      # The plugin's resolved settings: the `jekyll_link_decorator` hash from
+      # _config.yml merged over Configuration::DEFAULTS.
+      def plugin_config
+        Jekyll::LinkDecorator::Configuration.for(@config)
+      end
+
+      # Phase 1: link styling.
+
+      # Applies alert_classes to links inside a p.alert or blockquote.alert,
+      # and default_classes to every other link.
+      def apply_link_styles(doc, config)
+        default_classes = config['default_link_classes']
+        alert_classes   = config['alert_link_classes']
+
+        # One search finds every alert link. Checking each link's ancestors
+        # instead would search the whole document once per link.
+        alert_links = doc.css("p.alert #{DECORATED_LINKS}, blockquote.alert #{DECORATED_LINKS}")
+        alert_links.each { |link| add_classes(link, alert_classes) }
+        alert_link_ids = alert_links.to_set(&:pointer_id)
+
+        doc.css(DECORATED_LINKS).each do |link|
+          next if alert_link_ids.include?(link.pointer_id)
+
+          add_classes(link, classes_to_add_for(link, default_classes))
+        end
+      end
+
+      # Drops any default class belonging to a family the link already customizes,
+      # so the author's explicit class wins instead of losing silently to a
+      # same-specificity Bootstrap !important rule declared later in the sheet.
+      # See LINK_CLASS_FAMILIES for how each family's pattern is matched.
+      def classes_to_add_for(link, default_classes)
+        link_classes = link['class'].to_s.split
+        LINK_CLASS_FAMILIES.reduce(default_classes) do |classes, family|
+          next classes unless link_classes.any? { |token| token.match?(family[:pattern]) }
+
+          classes.split.grep_v(family[:pattern]).join(' ')
+        end
+      end
+
+      def add_classes(link, classes_string)
+        classes_string.split.each { |cls| link.add_class(cls) }
+      end
+
+      # Phase 2: external-link features.
+
+      # Adds target="_blank" and the external-link icon to cross-domain
+      # links, then rel security attributes to every non-button link that
+      # opens in a new tab. rel needs no site domain, so a target="_blank"
+      # the author set is protected even when the site has no url.
+      def add_external_link_features(doc, config)
+        site_domain = extract_site_domain
+        external_link_candidates(doc, site_domain).each do |link|
+          add_external_target_blank(link, site_domain)
+          add_external_icon(link, site_domain, config, doc)
+        end
+        doc.css(DECORATED_LINKS).each { |link| add_external_target_protection(link) }
+      end
+
+      # The links add_external_link_features checks for target and icon:
+      # every non-button link, or none when the site has no url to compare
+      # them against. The link.external_link_count attribute counts from
+      # the same set.
+      def external_link_candidates(doc, site_domain)
+        return [] if site_domain.empty?
+
+        doc.css(DECORATED_LINKS)
+      end
+
+      # The site's own domain, from site.url. baseurl is a path, so it never
+      # says which links are cross-domain.
+      def extract_site_domain
+        extract_domain(@config['url'].to_s)
+      end
+
+      # Returns a URL's domain, stripped of scheme and path.
+      # "https://example.com/path?query=1#anchor" -> "example.com"
+      # A URL with no host, such as a bare "https://", gives "". Surrounding
+      # whitespace is ignored, as browsers ignore it.
+      def extract_domain(url)
+        domain = url.to_s.strip.sub(ABSOLUTE_URL, '')
+        domain.split(%r{[/?#]}).first.to_s.downcase
+      end
+
+      # Sets target="_blank" on a cross-domain link, unless it already has a target.
+      def add_external_target_blank(link, site_domain)
+        return if link['target'].to_s.strip != ''
+        return unless cross_domain_external_link?(link, site_domain)
+
+        link['target'] = '_blank'
+      end
+
+      # Appends the external-link icon to a cross-domain link. Skips it when
+      # the icon is disabled, when the link contains a tag listed in
+      # external_link_icon_excluded_tags, or when the link already has an
+      # icon (EXISTING_ICON_SELECTORS).
+      def add_external_icon(link, site_domain, config, doc)
+        return unless config['external_link_icon']
+        return if config['external_link_icon_excluded_tags'].any? { |tag| link.css(tag).any? }
+
+        return unless is_external_different_domain_link?(link, site_domain)
+
+        icon = Nokogiri::XML::Node.new('i', doc)
+        icon['class'] = 'fa-solid fa-external-link ms-1'
+        icon['aria-hidden'] = 'true'
+        link.add_child(icon)
+      end
+
+      # True when the link opens in a new tab. HTML matches the _blank
+      # keyword case-insensitively, so target="_BLANK" counts too.
+      def new_tab_link?(link)
+        link['target'].to_s.casecmp?('_blank')
+      end
+
+      # Adds rel="noopener noreferrer" to a new_tab_link?, keeping any rel
+      # values the author already set.
+      def add_external_target_protection(link)
+        return unless new_tab_link?(link)
+
+        existing_rel = link['rel'].to_s.strip
+        rel_values = existing_rel.empty? ? [] : existing_rel.split(/\s+/)
+        rel_values << 'noopener' unless rel_values.include?('noopener')
+        rel_values << 'noreferrer' unless rel_values.include?('noreferrer')
+
+        link['rel'] = rel_values.join(' ')
+      end
+
+      # True when href is an absolute http(s) or protocol-relative URL (see
+      # ABSOLUTE_URL) on a domain other than site_domain; such a link gets
+      # target="_blank". Relative URLs are always internal.
+      def cross_domain_external_link?(link, site_domain)
+        href = link['href'].to_s.strip
+        return false unless ABSOLUTE_URL.match?(href)
+
+        link_domain = extract_domain(href)
+        !link_domain.empty? && link_domain != site_domain
+      end
+
+      # True when this link needs the external-link icon: cross-domain and
+      # without an icon already.
+      def is_external_different_domain_link?(link, site_domain)
+        return false unless cross_domain_external_link?(link, site_domain)
+
+        EXISTING_ICON_SELECTORS.none? { |sel| link.css(sel).any? }
+      end
+
+      # Phase 3: heading anchors.
+
+      # Injects a permalink anchor into each heading (h1-h6). The anchor's
+      # icon classes come from jekyll_link_decorator.heading_anchor.icon, plus
+      # icon_size when set. The default class draws a plain "#" through
+      # jekyll-theme-centos-base's CSS; swap it for a Font Awesome icon or
+      # any other class list.
+      def add_heading_anchors(doc, config)
+        ha_data = config['heading_anchor']
+        return unless ha_data['enabled']
+
+        icon_classes = [ha_data['icon'], ha_data['icon_size']].compact.join(' ')
+        taken_ids    = ids_in_use(doc)
+
+        doc.css(HEADINGS).each do |heading|
+          next if anchored_heading?(heading)
+
+          id = resolve_heading_id(heading, taken_ids)
+          heading.add_child(build_heading_anchor(doc, heading, id, icon_classes))
+        end
+      end
+      private :add_heading_anchors
+
+      # True when the heading already carries a permalink anchor, whether
+      # this phase or the author put it there.
+      def anchored_heading?(heading)
+        heading.css('.heading-anchor').any?
+      end
+
+      # Every id already on the page, so generated heading ids avoid them.
+      def ids_in_use(doc)
+        doc.css('[id]').to_set { |node| node['id'].strip }
+      end
+      private :ids_in_use
+
+      # Builds the heading's permalink: an <a> pointing at #id, labelled with
+      # the heading text for screen readers, wrapping the icon.
+      def build_heading_anchor(doc, heading, id, icon_classes)
+        anchor = Nokogiri::XML::Node.new('a', doc)
+        anchor['class']            = 'heading-anchor p-1 mx-1 focus-ring'
+        anchor['href']             = "##{id}"
+        anchor['data-copy-anchor'] = "##{id}"
+        anchor['aria-label']       = "Link to #{heading.text.strip}"
+        anchor.add_child(build_heading_anchor_icon(doc, icon_classes))
+        anchor
+      end
+      private :build_heading_anchor
+
+      # The anchor's decorative glyph, hidden from screen readers.
+      def build_heading_anchor_icon(doc, icon_classes)
+        icon = Nokogiri::XML::Node.new('i', doc)
+        icon['class']       = icon_classes
+        icon['aria-hidden'] = 'true'
+        icon
+      end
+      private :build_heading_anchor_icon
+
+      # Returns the heading's existing id, trimmed and written back so the
+      # anchor's href matches it, or generates one from its text, assigns
+      # it, and adds it to taken_ids. taken_ids starts with every id on the
+      # page, so a generated id gets the first free "-1", "-2", ... suffix
+      # instead of repeating one. Text with no slug falls back to "section",
+      # as kramdown's auto ids do.
+      def resolve_heading_id(heading, taken_ids)
+        existing = heading['id'].to_s.strip
+        return heading['id'] = existing unless existing.empty?
+
+        base = slugify(heading.text)
+        base = 'section' if base.empty?
+        id = base
+        n = 0
+        id = "#{base}-#{n += 1}" while taken_ids.include?(id)
+        taken_ids << id
+        heading['id'] = id
+      end
+      private :resolve_heading_id
+
+      # Converts heading text to a URL-safe slug, loosely mirroring the slug
+      # rules in jekyll-theme-centos-base's link.html.liquid (same characters
+      # stripped and replaced), plus collapsing repeated/edge hyphens so
+      # headings with unusual punctuation still get a clean id.
+      def slugify(text)
+        text.strip
+            .downcase
+            .tr(' ', '-')
+            .delete('"\'?&#/')
+            .gsub(/-{2,}/, '-')
+            .gsub(/\A-|-\z/, '')
+      end
+      private :slugify
+    end
+  end
+end