meta-tags 2.22.3 → 2.24.0

data/SECURITY.md

@@ -0,0 +1,40 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are provided for the latest released version of `meta-tags`.
+
+Older releases may not receive security updates. If you are reporting a vulnerability, please confirm whether it affects the latest release.
+
+## Reporting a Vulnerability
+
+Please do not report security issues through public GitHub issues, discussions, or pull requests.
+
+Use GitHub's private vulnerability reporting feature in the repository's `Security` tab to report a vulnerability.
+
+If private reporting through GitHub is unavailable for any reason, send a report by email to `kpumuk@kpumuk.info` with `SECURITY` in the subject line.
+
+When possible, include:
+
+- a short description of the issue
+- the affected version, commit, or tag
+- any required environment or configuration details
+- step-by-step reproduction instructions
+- proof-of-concept code, logs, or screenshots
+- an explanation of the likely impact
+
+## Disclosure Policy
+
+Please allow a reasonable amount of time to investigate and prepare a fix before making the issue public.
+
+If the report is confirmed, the fix will be released as soon as practical. Public disclosure will generally happen through a GitHub security advisory and/or release notes after a fix is available.
+
+## Scope Notes
+
+`meta-tags` is a Ruby gem for Rails applications that renders HTML metadata such as titles, descriptions, canonical links, robots directives, and social tags.
+
+Some behavior may depend on the host Rails application, layouts, templates, framework version, gem version, or deployment/runtime configuration. If a report depends on a specific setup, include those details.
+
+## Response Expectations
+
+This is a single-maintainer project, so response times may vary. Good-faith reports are appreciated, and I will try to acknowledge valid reports as quickly as practical.

data/lib/generators/meta_tags/install_generator.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
 module MetaTags
+  # Rails generators for MetaTags.
   module Generators
+    # Installs the default MetaTags initializer into a Rails application.
     class InstallGenerator < Rails::Generators::Base
       desc "Copy MetaTags default files"
       source_root File.expand_path("templates", __dir__)
 
+      # Copies the default MetaTags initializer template.
+      #
+      # @return [void]
       def copy_config
         template "config/initializers/meta_tags.rb"
       end

data/lib/generators/meta_tags/templates/config/initializers/meta_tags.rb

@@ -18,25 +18,36 @@ MetaTags.configure do |config|
   # a Unicode space (/\p{Space}/).
   # config.truncate_on_natural_separator = " "
 
+  # When true, arrays passed to `title` and `keywords` stop at item
+  # boundaries instead of partially truncating the overflowing item.
+  # Single-item arrays are still truncated normally. Default is false.
+  # config.truncate_array_items_at_boundaries = false
+
   # Maximum length of the page description. Default is 300.
   # Set to nil or 0 to remove limits.
   # config.description_limit = 300
 
-  # Maximum length of the keywords meta tag. Default is 255.
+  # Legacy compatibility: maximum length of the keywords meta tag.
+  # Most search engines ignore this tag. Default is 255.
   # config.keywords_limit = 255
 
-  # Default separator for keywords meta tag (used when an Array passed with
-  # the list of keywords). Default is ", ".
+  # Legacy compatibility: default separator for the keywords meta tag
+  # when an Array is passed. Default is ", ".
   # config.keywords_separator = ', '
 
-  # When true, keywords will be converted to lowercase, otherwise they will
-  # appear on the page as is. Default is true.
+  # Legacy compatibility: when true, keywords will be converted to lowercase.
+  # Otherwise they will appear on the page as is. Default is true.
   # config.keywords_lowercase = true
 
   # When true, the output will not include new line characters between meta tags.
   # Default is false.
   # config.minify_output = false
 
+  # When true, Symbols inside nested meta tag arrays resolve as references to
+  # normalized top-level tags. Default is false until MetaTags 3.0, when this
+  # behavior will become the default.
+  # config.resolve_symbolic_references_in_arrays = false
+
   # When false, generated meta tags will be self-closing (<meta ... />) instead
   # of open (`<meta ...>`). Default is true.
   # config.open_meta_tags = true

data/lib/meta_tags/configuration.rb

@@ -15,6 +15,10 @@ module MetaTags
     # A string or regexp separator to truncate text at a natural break.
     attr_accessor :truncate_on_natural_separator
 
+    # When true, multi-item arrays stop at item boundaries instead of
+    # truncating the overflowing item.
+    attr_accessor :truncate_array_items_at_boundaries
+
     # How many characters to truncate description to.
     attr_accessor :description_limit
 
@@ -24,7 +28,7 @@ module MetaTags
     # Keywords separator - a string to join keywords with.
     attr_accessor :keywords_separator
 
-    # Should keywords forced into lowercase?
+    # Should keywords be forced into lowercase?
     attr_accessor :keywords_lowercase
 
     # Switches between open (<meta ... >) and closed (<meta ... />) meta tags.
@@ -35,13 +39,18 @@ module MetaTags
     # Default is false.
     attr_accessor :minify_output
 
-    # Custom meta tags that should use `property` attribute instead of `name`
-    # - an array of strings or symbols representing their names or name-prefixes.
+    # When true, Symbols inside nested meta tag arrays resolve as references to
+    # normalized top-level tags. Default is false until MetaTags 3.0.
+    attr_accessor :resolve_symbolic_references_in_arrays
+
+    # Custom meta tags that should use the `property` attribute instead of `name`.
+    # An array of strings or symbols representing their names or name prefixes.
     attr_reader :property_tags
 
-    # Configure whenever Meta-Tags should skip canonicals on pages with noindex: true
-    # "shouldn't mix noindex & rel=canonical comes from: they're very contradictory pieces of information for us."
-    # - John Mueller (Webmaster Trends Analyst at Google)
+    # Configure whether MetaTags should skip canonical links on pages with
+    # `noindex: true`.
+    # John Mueller has noted that mixing `noindex` and `rel=canonical` sends
+    # contradictory signals.
     # https://www.reddit.com/r/TechSEO/comments/8yahdr/2_questions_about_the_canonical_tag/e2dey9i/
     attr_accessor :skip_canonical_links_on_noindex
 
@@ -50,16 +59,20 @@ module MetaTags
       reset_defaults!
     end
 
+    # Returns the default meta tag prefixes and names that use `property`.
+    #
+    # @return [Array<String>] default property tag names.
     def default_property_tags
       [
-        # App Link metadata https://developers.facebook.com/docs/applinks/metadata-reference
+        # App Links metadata https://developers.facebook.com/docs/applinks/metadata-reference
         "al",
         # Open Graph Markup https://developers.facebook.com/docs/sharing/webmasters#markup
         "fb",
         "og",
-        # Facebook OpenGraph Object Types https://developers.facebook.com/docs/reference/opengraph
-        # Note that these tags are used in a regex, so including e.g. 'restaurant' will affect
-        # 'restaurant:category', 'restaurant:price_rating', and anything else under that namespace.
+        # Facebook Open Graph object types https://developers.facebook.com/docs/reference/opengraph
+        # These tags are matched as exact property names or namespace prefixes, so e.g.
+        # 'restaurant' affects 'restaurant:category', 'restaurant:price_rating', and other
+        # properties under that namespace.
         "article",
         "book",
         "books",
@@ -75,14 +88,21 @@ module MetaTags
       ].freeze
     end
 
+    # Indicates whether meta tags should be rendered with open tag syntax.
+    #
+    # @return [Boolean] true when open meta tags are enabled.
     def open_meta_tags?
       !!open_meta_tags
     end
 
+    # Restores the default configuration values.
+    #
+    # @return [void]
     def reset_defaults!
       @title_limit = 70
       @truncate_site_title_first = false
       @truncate_on_natural_separator = " "
+      @truncate_array_items_at_boundaries = false
       @title_tag_attributes = {}
       @description_limit = 300
       @keywords_limit = 255
@@ -91,6 +111,7 @@ module MetaTags
       @property_tags = default_property_tags.dup
       @open_meta_tags = true
       @minify_output = false
+      @resolve_symbolic_references_in_arrays = false
       @skip_canonical_links_on_noindex = false
     end
   end

data/lib/meta_tags/content_tag.rb

@@ -4,13 +4,12 @@ module MetaTags
   # Represents an HTML meta tag with content (<tag></tag>).
   # Content should be passed as a `:content` attribute.
   class ContentTag < Tag
-    # Render tag into a Rails view.
+    # Renders the tag in a Rails view.
     #
-    # @param [ActionView::Base] view instance of a Rails view.
+    # @param view [ActionView::Base] instance of a Rails view.
     # @return [String] HTML string for the tag.
-    #
     def render(view)
-      view.content_tag(name, attributes[:content], prepare_attributes(attributes.except(:content)))
+      view.content_tag(name, attributes[:content], serialize_iso8601_attributes(attributes.except(:content)))
     end
   end
 end

data/lib/meta_tags/controller_helper.rb

@@ -2,18 +2,20 @@
 
 module MetaTags
   # Contains methods to use in controllers.
-  #
   # You can define several instance variables to set meta tags:
   #   @page_title = 'Member Login'
   #   @page_description = 'Member login page.'
-  #   @page_keywords = 'Site, Login, Members'
-  #
-  # Also you can use {#set_meta_tags} method, that have the same parameters
-  # as {ViewHelper#set_meta_tags}.
-  #
+  #   @page_keywords = 'Site, Login, Members' # legacy keywords tag
+  # You can also use the {#set_meta_tags} method, which has the same
+  # parameters as {ViewHelper#set_meta_tags}.
   module ControllerHelper
-    # Processes the <tt>@page_title</tt>, <tt>@page_keywords</tt>, and
-    # <tt>@page_description</tt> instance variables and calls +render+.
+    # Processes the <tt>@page_title</tt>, <tt>@page_description</tt>, and
+    # legacy <tt>@page_keywords</tt> instance variables and calls +render+.
+    #
+    # @param args [Array<Object>] positional arguments forwarded to +render+.
+    # @param block [Proc, nil] optional block forwarded to +render+.
+    # @yield optional block forwarded to +render+.
+    # @yieldreturn [Object] result of the render block.
     def render(*args, &block)
       meta_tags[:title] = @page_title if defined?(@page_title) && @page_title
       meta_tags[:keywords] = @page_keywords if defined?(@page_keywords) && @page_keywords
@@ -24,6 +26,7 @@ module MetaTags
 
     # Set meta tags for the page.
     #
+    # @param meta_tags [Hash] list of meta tags to merge into the page state.
     # See <tt>MetaTags::ViewHelper#set_meta_tags</tt> for details.
     def set_meta_tags(meta_tags)
       self.meta_tags.update(meta_tags)

data/lib/meta_tags/meta_tags_collection.rb

@@ -1,42 +1,38 @@
 # frozen_string_literal: true
 
 module MetaTags
-  # Class represents a collection of meta tags. Basically a wrapper around
+  # This class represents a collection of meta tags. Basically a wrapper around
   # HashWithIndifferentAccess, with some additional helper methods.
   class MetaTagsCollection
     attr_reader :meta_tags
 
     # Initializes a new instance of MetaTagsCollection.
-    #
     def initialize
       @meta_tags = ActiveSupport::HashWithIndifferentAccess.new
     end
 
     # Returns meta tag value by name.
     #
-    # @param [String, Symbol] name meta tag name.
+    # @param name [String, Symbol] meta tag name.
     # @return meta tag value.
-    #
     def [](name)
       @meta_tags[name]
     end
 
     # Sets meta tag value by name.
     #
-    # @param [String, Symbol] name meta tag name.
+    # @param name [String, Symbol] meta tag name.
     # @param value meta tag value.
     # @return meta tag value.
-    #
     def []=(name, value)
       @meta_tags[name] = value
     end
 
-    # Recursively merges a Hash of meta tag attributes into current list.
+    # Recursively merges a Hash of meta tag attributes into the current list.
     #
-    # @param [Hash, #to_meta_tags] object Hash of meta tags (or object responding
+    # @param object [Hash, #to_meta_tags] Hash of meta tags (or object responding
     #   to #to_meta_tags and returning a hash) to merge into the current list.
     # @return [Hash] result of the merge.
-    #
     def update(object = {})
       meta_tags = if object.respond_to?(:to_meta_tags)
         # @type var object: _MetaTagish & Object
@@ -48,11 +44,10 @@ module MetaTags
       @meta_tags.deep_merge! normalize_open_graph(meta_tags)
     end
 
-    # Temporary merges defaults with current meta tags list and yields the block.
+    # Temporarily merges defaults with the current meta tags list and yields the block.
     #
-    # @param [Hash] defaults list of default meta tag attributes.
+    # @param defaults [Hash] list of default meta tag attributes.
     # @return result of the block call.
-    #
     def with_defaults(defaults = {})
       old_meta_tags = @meta_tags
       @meta_tags = normalize_open_graph(defaults).deep_merge!(@meta_tags)
@@ -63,9 +58,8 @@ module MetaTags
 
     # Constructs the full title as if it would be rendered in title meta tag.
     #
-    # @param [Hash] defaults list of default meta tag attributes.
+    # @param defaults [Hash] list of default meta tag attributes.
     # @return [String] page title.
-    #
     def full_title(defaults = {})
       with_defaults(defaults) { extract_full_title }
     end
@@ -73,30 +67,26 @@ module MetaTags
     # Constructs the title without site title (for normalized parameters). When title is empty,
     # use the site title instead.
     #
+    # @param defaults [Hash] list of default meta tag attributes.
     # @return [String] page title.
-    #
     def page_title(defaults = {})
-      old_site = @meta_tags[:site]
-      @meta_tags[:site] = nil
-      full_title = with_defaults(defaults) { extract_full_title }
-      full_title.presence || old_site || ""
-    ensure
-      @meta_tags[:site] = old_site
+      with_defaults(defaults) do
+        site = extract(:site)
+        extract_full_title.presence || site || ""
+      end
     end
 
     # Deletes and returns a meta tag value by name.
     #
-    # @param [String, Symbol] name meta tag name.
+    # @param name [String, Symbol] meta tag name.
     # @return [Object] meta tag value.
-    #
     def extract(name)
       @meta_tags.delete(name)
     end
 
     # Deletes specified meta tags.
     #
-    # @param [Array<String, Symbol>] names a list of meta tags to delete.
-    #
+    # @param names [Array<String, Symbol>] list of meta tags to delete.
     def delete(*names)
       names.each { |name| @meta_tags.delete(name) }
     end
@@ -104,7 +94,6 @@ module MetaTags
     # Extracts full page title and deletes all related meta tags.
     #
     # @return [String] page title.
-    #
     def extract_full_title
       site_title = extract(:site) || ""
       title = extract_title
@@ -117,14 +106,20 @@ module MetaTags
     # Extracts page title as an array of segments without site title and separators.
     #
     # @return [Array<String>] segments of page title.
-    #
     def extract_title
+      lowercase = extract(:lowercase) == true
       title = extract(:title).presence
       return [] unless title
 
-      # @type var title: Array[String]
       title = Array(title)
-      return title.map(&:downcase) if extract(:lowercase) == true
+      if lowercase
+        return title.map do |segment|
+          string = String.try_convert(segment)
+          raise ArgumentError, "Expected a string or an object that implements #to_str" unless string
+
+          string.downcase
+        end
+      end
 
       title
     end
@@ -132,7 +127,6 @@ module MetaTags
     # Extracts title separator as a string.
     #
     # @return [String] page title separator.
-    #
     def extract_separator
       if meta_tags[:separator] == false
         # Special case: if separator is hidden, do not display suffix/prefix
@@ -147,11 +141,44 @@ module MetaTags
       TextNormalizer.safe_join([prefix, separator, suffix], "")
     end
 
-    # Extracts noindex settings as a Hash mapping noindex tag name to value.
-    #
-    # @return [Hash<String,String>] noindex attributes.
+    # Extracts robots settings as a Hash mapping tag names to rendered values.
     #
+    # @return [Hash{String => String}] robots attributes.
     def extract_robots
+      result = robots
+      delete(:noindex, :index, :follow, :nofollow, :noarchive)
+      [:robots, :googlebot, :bingbot].each do |bot|
+        extract(bot) if meta_tags[bot].is_a?(Hash)
+      end
+
+      result
+    end
+
+    # Returns whether robots settings produce a noindex directive.
+    #
+    # @return [Boolean] true when a noindex directive will be rendered.
+    def noindex?
+      contents = robots.values
+      property_tags = MetaTags.config.property_tags.map(&:to_s)
+      [:robots, :googlebot, :bingbot].each do |bot|
+        values = meta_tags[bot]
+        next if values.is_a?(Hash) || property_tags.include?(bot.to_s)
+
+        contents.concat(Array(values))
+      end
+
+      contents.any? do |content|
+        content.to_s.split(",").any? { |directive| directive.strip.casecmp?("noindex") }
+      end
+    end
+
+    protected
+
+    # Returns robots settings without modifying the collection.
+    #
+    # @return [Hash{String => String}] robots attributes.
+    def robots
+      # @type var result: Hash[String, Array[String]]
       result = Hash.new { |h, k| h[k] = [] }
 
       [
@@ -164,58 +191,104 @@ module MetaTags
         calculate_robots_attributes(result, attributes)
       end
 
+      [:robots, :googlebot, :bingbot].each do |bot|
+        values = meta_tags[bot]
+        if values.is_a?(Hash)
+          values.each do |key, value|
+            next if value == false
+
+            directive = (value.nil? || value == true) ? key.to_s : "#{key}:#{value}"
+            result[bot.to_s] << directive
+          end
+        end
+      end
+
       result.transform_values { |v| v.join(", ") }
     end
 
-    protected
-
     # Converts input hash to HashWithIndifferentAccess and renames :open_graph to :og.
+    # When both aliases contain hashes, they are deep-merged with :og taking precedence.
     #
-    # @param [Hash] meta_tags list of meta tags.
+    # @param meta_tags [Hash] list of meta tags.
     # @return [ActiveSupport::HashWithIndifferentAccess] normalized meta tags list.
-    #
     def normalize_open_graph(meta_tags)
       meta_tags = meta_tags.with_indifferent_access
-      meta_tags[:og] = meta_tags.delete(:open_graph) if meta_tags.key?(:open_graph)
+      if meta_tags.key?(:open_graph)
+        open_graph = meta_tags.delete(:open_graph)
+        if meta_tags.key?(:og)
+          meta_tags[:og] = open_graph.dup.deep_merge!(meta_tags[:og]) if open_graph.is_a?(Hash) && meta_tags[:og].is_a?(Hash)
+        else
+          meta_tags[:og] = open_graph
+        end
+      end
       meta_tags
     end
 
     # Extracts separator segment without deleting it from meta tags list.
-    # If the value is false, empty string will be returned.
+    # If the value is false, an empty string will be returned.
     #
-    # @param [Symbol, String] name separator segment name.
-    # @param [String] default default value.
+    # @param name [Symbol, String] separator segment name.
+    # @param default [String] default value.
     # @return [String] separator segment value.
-    #
     def extract_separator_section(name, default)
       (meta_tags[name] == false) ? "" : (meta_tags[name] || default)
     end
 
-    # Extracts robots attribute (noindex, nofollow, etc) name and value.
-    #
-    # @param [String, Symbol] name noindex attribute name.
-    # @return [Array<String>] pair of noindex attribute name and value.
+    # Extracts a robots attribute name/value pair (noindex, nofollow, etc.).
     #
+    # @param name [String, Symbol] noindex attribute name.
+    # @return [Array<Object>] normalized robots tag name(s) and directive value.
     def extract_robots_attribute(name)
-      noindex = extract(name)
-      noindex_name = (noindex.is_a?(String) || noindex.is_a?(Array)) ? noindex : "robots"
-      noindex_value = noindex ? name.to_s : nil
+      noindex = meta_tags[name]
+      # @type var noindex_name: String | Array[String]
+      noindex_name = if noindex.is_a?(Array)
+        noindex.reject { |target| target.is_a?(String) && target.blank? }.map(&:to_s)
+      elsif noindex.is_a?(String)
+        noindex.presence || []
+      else
+        "robots"
+      end
+      noindex_value = if robots_attribute_present?(noindex) && noindex_name.present?
+        name.to_s
+      end
 
       [noindex_name, noindex_value]
     end
 
+    # Returns whether a robots attribute resolves to at least one target.
+    #
+    # @param value [Object] robots attribute value.
+    # @return [Boolean] true when the attribute produces a directive.
+    def robots_attribute_present?(value)
+      !!value && (!value.is_a?(Array) || !value.empty?)
+    end
+
+    # Appends resolved robots directives while preserving first-write priority.
+    #
+    # @param result [Hash{String => Array<String>}] robots directives grouped by tag name.
+    # @param attributes [Symbol, Array<Symbol>] robots attributes to resolve.
+    # @return [void]
     def calculate_robots_attributes(result, attributes)
       processed = Set.new
       Array(attributes).each do |attribute|
+        # @type var attribute: String | Symbol
         names, value = extract_robots_attribute(attribute)
         next unless value
 
-        Array(names).each do |name|
+        robot_names = names.is_a?(String) ? [names] : names
+        robot_names.each do |name|
           apply_robots_value(result, name, value, processed)
         end
       end
     end
 
+    # Records a robots directive unless it has already been set for the same key.
+    #
+    # @param result [Hash{String => Array<String>}] robots directives grouped by tag name.
+    # @param name [String] robots tag name.
+    # @param value [String] robots directive value.
+    # @param processed [Set<String>] names already recorded in this pass.
+    # @return [void]
     def apply_robots_value(result, name, value, processed)
       name = name.to_s
       return if processed.include?(name)

data/lib/meta_tags/railtie.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
 module MetaTags
+  # Hooks MetaTags helpers into Rails controllers and views.
   class Railtie < Rails::Railtie
+    initializer "meta_tags.register_deprecator", before: :load_environment_config do |app|
+      app.deprecators[:meta_tags] = MetaTags.deprecator if app.respond_to?(:deprecators)
+    end
+
     initializer "meta_tags.setup_action_controller" do
       ActiveSupport.on_load :action_controller do
         include MetaTags::ControllerHelper