bridgetown-core 2.0.0.beta1 → 2.0.0.beta3

data/lib/bridgetown-core/filters/grouping_filters.rb

@@ -3,14 +3,15 @@
 module Bridgetown
   module Filters
     module GroupingFilters
-      # Group an array of items by a property
+      # Group an array of items by a property, returning an array of hashes
       #
-      # input - the inputted Enumerable
-      # property - the property
+      # @example
+      #   {"name"  => "larry"
+      #    "items" => [...] } # all the items where `property` == "larry"
       #
-      # Returns an array of Hashes, each looking something like this:
-      #  {"name"  => "larry"
-      #   "items" => [...] } # all the items where `property` == "larry"
+      # @param input [Enumerable]
+      # @param property [String]
+      # @return [Array<Hash>]
       def group_by(input, property)
         if groupable?(input)
           groups = input.group_by { |item| item_property(item, property).to_s }
@@ -22,11 +23,10 @@ module Bridgetown
 
       # Group an array of items by an expression
       #
-      # input - the object array
-      # variable - the variable to assign each item to in the expression
-      # expression -a Liquid comparison expression passed in as a string
-      #
-      # Returns the filtered array of objects
+      # @param input [Enumerable]
+      # @param variable [String] variable to assign each item to in the expression
+      # @param expression [String] Liquid comparison expression
+      # @return [Array<Hash>]
       def group_by_exp(input, variable, expression)
         return input unless groupable?(input)
 

data/lib/bridgetown-core/filters.rb

@@ -11,33 +11,30 @@ module Bridgetown
     include TranslationFilters
     include ConditionHelpers
 
-    # Convert a Markdown string into HTML output.
+    # Convert a Markdown string into HTML output
     #
-    # input - The Markdown String to convert.
-    #
-    # Returns the HTML formatted String.
+    # @param input [String]
+    # @return [String] HTML formatted text
     def markdownify(input)
       @context.registers[:site].find_converter_instance(
         Bridgetown::Converters::Markdown
       ).convert(input.to_s)
     end
 
-    # Convert quotes into smart quotes.
-    #
-    # input - The String to convert.
+    # Convert quotes into smart quotes
     #
-    # Returns the smart-quotified String.
+    # @param input [String]
+    # @return [String] smart-quotified text
     def smartify(input)
       Utils::SmartyPantsConverter.new(@context.registers[:site].config).convert(input.to_s)
     end
 
-    # Slugify a filename or title.
-    #
-    # input - The filename or title to slugify.
-    # mode - how string is slugified
+    # Slugify a filename or title
     #
-    # Returns the given filename or title as a lowercase URL String.
-    # See Utils.slugify for more detail.
+    # @param input [String] the filename or title to slugify
+    # @param mode [String] how string is slugified
+    # @see Utils.slugify
+    # @return [String] lowercase URL
     def slugify(input, mode = nil)
       mode = @context.registers[:site].config.slugify_mode if mode.nil?
       Utils.slugify(input, mode:)
@@ -45,10 +42,9 @@ module Bridgetown
 
     # Titleize a slug or identifier string.
     #
-    # input - The string to titleize.
-    #
-    # Returns a transformed string with spaces and capitalized words.
-    # See Utils.titleize_slug for more detail.
+    # @param input [String]
+    # @see Utils.titleize_slug for more detail
+    # @return [String] transformed string with spaces and capitalized words
     def titleize(input)
       Utils.titleize_slug(input)
     end
@@ -56,13 +52,12 @@ module Bridgetown
     # XML escape a string for use. Replaces any special characters with
     # appropriate HTML entity replacements.
     #
-    # Examples
-    #
+    # @example
     #   xml_escape('foo "bar" <baz>')
     #   # => "foo &quot;bar&quot; &lt;baz&gt;"
     #
-    # @param input [String] The String to escape.
-    # @return [String] the escaped String.
+    # @param input [String]
+    # @return [String]
     def xml_escape(input)
       Utils.xml_escape(input)
     end
@@ -70,28 +65,24 @@ module Bridgetown
     # CGI escape a string for use in a URL. Replaces any special characters
     # with appropriate %XX replacements.
     #
-    # input - The String to escape.
-    #
-    # Examples
-    #
+    # @example
     #   cgi_escape('foo,bar;baz?')
     #   # => "foo%2Cbar%3Bbaz%3F"
     #
-    # Returns the escaped String.
+    # @param input [String]
+    # @return [String]
     def cgi_escape(input)
       CGI.escape(input.to_s)
     end
 
     # URI escape a string.
     #
-    # input - The String to escape.
-    #
-    # Examples
-    #
+    # @example
     #   uri_escape('foo, bar \\baz?')
     #   # => "foo,%20bar%20%5Cbaz?"
     #
-    # Returns the escaped String.
+    # @param input [String]
+    # @return [String]
     def uri_escape(input)
       Addressable::URI.normalize_component(input)
     end
@@ -113,23 +104,22 @@ module Bridgetown
 
     # Replace any whitespace in the input string with a single space
     #
-    # input - The String on which to operate.
-    #
-    # Returns the formatted String
+    # @param input [String]
+    # @return [String]
     def normalize_whitespace(input)
       input.to_s.gsub(%r!\s+!, " ").strip
     end
 
     # Count the number of words in the input string.
     #
-    # input - The String on which to operate.
-    #
-    # Returns the Integer word count.
+    # @param input [String]
+    # @return [Integer] word count
     def number_of_words(input)
       input.split.length
     end
 
-    # Calculates the average reading time of the supplied content.
+    # Calculates the average reading time of the supplied content
+    #
     # @param input [String] the String of content to analyze.
     # @return [Float] the number of minutes required to read the content.
     def reading_time(input, round_to = 0)
@@ -138,17 +128,15 @@ module Bridgetown
     end
 
     # Join an array of things into a string by separating with commas and the
-    # word "and" for the last one.
-    #
-    # array - The Array of Strings to join.
-    # connector - Word used to connect the last 2 items in the array
-    #
-    # Examples
+    # word "and" for the last one
     #
+    # @example
     #   array_to_sentence_string(["apples", "oranges", "grapes"])
     #   # => "apples, oranges, and grapes"
     #
-    # Returns the formatted String.
+    # @param array [Array<String>]
+    # @param connector [String] word used to connect the last 2 items in the array
+    # @return [String]
     def array_to_sentence_string(array, connector = "and")
       case array.length
       when 0
@@ -162,24 +150,20 @@ module Bridgetown
       end
     end
 
-    # Convert the input into json string
-    #
-    # input - The Array or Hash to be converted
+    # Convert the input into JSON string
     #
-    # Returns the converted json string
+    # @param input [Array, Hash, String, Integer]
+    # @return [String] JSON string
     def jsonify(input)
       as_liquid(input).to_json
     end
 
-    # Filter an array of objects
+    # Filter an array of objects or a hash (will use values)
     #
-    # input    - the object array.
-    # property - the property within each object to filter by.
-    # value    - the desired value.
-    #            Cannot be an instance of Array nor Hash since calling #to_s on them returns
-    #            their `#inspect` string object.
-    #
-    # Returns the filtered array of objects
+    # @param input [Array, Hash]
+    # @param property [String] the property within each object to filter by
+    # @param value [String] value for the search
+    # @return [Array] filtered array of objects
     def where(input, property, value) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       return input if !property || value.is_a?(Array) || value.is_a?(Hash)
       return input unless input.respond_to?(:select)
@@ -201,15 +185,14 @@ module Bridgetown
 
     # Filters an array of objects against an expression
     #
-    # input - the object array
-    # variable - the variable to assign each item to in the expression
-    # expression - a Liquid comparison expression passed in as a string
-    #
-    # Returns the filtered array of objects
+    # @param input [Array, Hash]
+    # @param variable [String] the variable to assign each item to in the expression
+    # @param expression [String] a Liquid comparison expression passed in as a string
+    # @return [Array] filtered array of objects
     def where_exp(input, variable, expression)
       return input unless input.respond_to?(:select)
 
-      input = input.values if input.is_a?(Hash) # FIXME
+      input = input.values if input.is_a?(Hash)
 
       condition = parse_condition(expression)
       @context.stack do
@@ -222,9 +205,8 @@ module Bridgetown
 
     # Convert the input into integer
     #
-    # input - the object string
-    #
-    # Returns the integer value
+    # @param input [String, Boolean] if boolean, 1 for true and 0 for false
+    # @return [Integer]
     def to_integer(input)
       return 1 if input == true
       return 0 if input == false
@@ -234,11 +216,10 @@ module Bridgetown
 
     # Sort an array of objects
     #
-    # input - the object array
-    # property - property within each object to filter by
-    # nils ('first' | 'last') - nils appear before or after non-nil values
-    #
-    # Returns the filtered array of objects
+    # @param input [Array]
+    # @param property [String] the property within each object to filter by
+    # @param nils [String] `first` | `last` (nils appear before or after non-nil values)
+    # @return [Array] sorted array of objects
     def sort(input, property = nil, nils = "first")
       raise ArgumentError, "Cannot sort a null object." if input.nil?
 

data/lib/bridgetown-core/front_matter/defaults.rb

@@ -33,7 +33,6 @@ module Bridgetown
       #
       # @param path [String] the relative path of the resource
       # @param collection_name [Symbol] :posts, :pages, etc.
-      #
       # @return [Hash] all default values (an empty hash if there are none)
       def all(path, collection_name)
         if @defaults_cache.key?([path, collection_name])
@@ -70,11 +69,10 @@ module Bridgetown
 
       # Checks if a given default setting scope matches the given path and collection
       #
-      # scope - the hash indicating the scope, as defined in bridgetown.config.yml
-      # path - the path to check for
-      # collection - the collection (:posts or :pages) to check for
-      #
-      # Returns true if the scope applies to the given collection and path
+      # @param scope [Hash] the scope as defined in site configuration
+      # @param path [String] the path to check for
+      # @param collection [Symbol] the collection (:posts, :pages, etc.) to check for
+      # @return [Boolean] true if the scope applies to the given collection and path
       def applies?(scope, path, collection)
         applies_collection?(scope, collection) && applies_path?(scope, path)
       end
@@ -129,7 +127,6 @@ module Bridgetown
       #
       # @param scope [Hash] the defaults set being asked about
       # @param collection [Symbol] the collection of the resource being processed
-      #
       # @return [Boolean] whether either of the above conditions are satisfied
       def applies_collection?(scope, collection)
         !scope.key?("collection") || scope["collection"].eql?(collection.to_s)
@@ -137,8 +134,7 @@ module Bridgetown
 
       # Checks if a given set of default values is valid
       #
-      # @param set [Hash] the default value hash as defined in bridgetown.config.yml
-      #
+      # @param set [Hash] the default value hash as defined in site configuration
       # @return [Boolean] if the set is valid and can be used
       def valid?(set)
         set.is_a?(Hash) && set["values"].is_a?(Hash)
@@ -146,10 +142,9 @@ module Bridgetown
 
       # Determines if a new scope has precedence over an old one
       #
-      # old_scope - the old scope hash, or nil if there's none
-      # new_scope - the new scope hash
-      #
-      # Returns true if the new scope has precedence over the older
+      # @param old_scope [Hash] old scope hash, or nil if there's none
+      # @param new_scope [Hash] new scope hash
+      # @return [Boolean] true if the new scope has precedence over the older
       # rubocop: disable Naming/PredicateName
       def has_precedence?(old_scope, new_scope)
         return true if old_scope.nil?

data/lib/bridgetown-core/generated_page.rb

@@ -25,13 +25,13 @@ module Bridgetown
       .htm
     ).freeze
 
-    # Initialize a new GeneratedPage.
+    # Initialize a new GeneratedPage
     #
-    # site - The Site object.
-    # base - The String path to the source.
-    # dir  - The String path between the source and the file.
-    # name - The String filename of the file.
-    # from_plugin - true if the Page file is located in a Gem-based plugin folder
+    # @param site [Bridgetown::Site]
+    # @param base [String] path to the source
+    # @param dir [String] path between the source and the file
+    # @param name [String] filename of the file.
+    # @param from_plugin [Boolean] true if the Page file is located in a Gem-based plugin folder
     # rubocop:disable Metrics/ParameterLists
     def initialize(site, base, dir, name, from_plugin: false)
       @site = site

data/lib/bridgetown-core/generators/prototype_generator.rb

@@ -76,7 +76,6 @@ module Bridgetown
     # Check incoming prototype configuration and normalize options.
     #
     # @param prototype_page [Bridgetown::GeneratedPage, Bridgetown::Resource::Base]
-    #
     # @return [String, nil]
     def validate_search_term(prototype_page)
       # @type [String]
@@ -108,7 +107,6 @@ module Bridgetown
     # Provide a list of all relevent indexed values for the given term.
     #
     # @param search_term [String]
-    #
     # @return [Array<String>]
     def terms_matching_pages(search_term)
       pages_list = site.collections[@configured_collection].resources

data/lib/bridgetown-core/hooks.rb

@@ -25,7 +25,6 @@ module Bridgetown
 
     @registry = {}
 
-    NotAvailable = Class.new(RuntimeError)
     Uncallable = Class.new(RuntimeError)
 
     def self.priority_value(priority)

data/lib/bridgetown-core/layout.rb

@@ -95,11 +95,10 @@ module Bridgetown
       content || ""
     end
 
-    # Accessor for data properties by Liquid.
+    # Accessor for data properties by Liquid
     #
-    # property - The String name of the property to retrieve.
-    #
-    # Returns the String value or nil if the property isn't included.
+    # @param property [String] name of the property to retrieve
+    # @return [String, nil] value or nil if the property isn't included
     def [](property)
       data[property]
     end

data/lib/bridgetown-core/liquid_extensions.rb

@@ -4,11 +4,9 @@ module Bridgetown
   module LiquidExtensions
     # Lookup a Liquid variable in the given context.
     #
-    # context  - the Liquid context in question.
-    # variable - the variable name, as a string.
-    #
-    # Returns the value of the variable in the context
-    #   or the variable name if not found.
+    # @param context [Liquid::Context]
+    # @param variable [String] the variable name
+    # @return [Object] value of the variable in the context or the variable name if not found
     def lookup_variable(context, variable)
       lookup = context
 

data/lib/bridgetown-core/log_adapter.rb

@@ -11,23 +11,19 @@ module Bridgetown
       error: ::Logger::ERROR,
     }.freeze
 
-    # Public: Create a new instance of a log writer
+    # Create a new instance of a log writer
     #
-    # writer - Logger compatible instance
-    # log_level - (optional, symbol) the log level
-    #
-    # Returns nothing
+    # @param writer [Logger] compatible instance
+    # @param log_level [Symbol] the log level (`debug` | `info` | `warn` | `error`)
     def initialize(writer, level = :info)
       @messages = []
       @writer = writer
       self.log_level = level
     end
 
-    # Public: Set the log level on the writer
-    #
-    # level - (symbol) the log level
+    # Set the log level on the writer
     #
-    # Returns nothing
+    # @param log_level [Symbol] the log level (`debug` | `info` | `warn` | `error`)
     def log_level=(level)
       writer.level = level if level.is_a?(Integer) && level.between?(0, 3)
       writer.level = LOG_LEVELS[level] ||
@@ -45,63 +41,52 @@ module Bridgetown
       debug "Logging at level:", LOG_LEVELS.key(writer.level).to_s
     end
 
-    # Public: Print a debug message
-    #
-    # topic - the topic of the message, e.g. "Configuration file", "Deprecation", etc.
-    # message - the message detail
+    # Print a debug message
     #
-    # Returns nothing
+    # @param topic [String] e.g. "Configuration file", "Deprecation", etc.
+    # @param message [String] the message detail
     def debug(topic, message = nil, &)
       write(:debug, topic, message, &)
     end
 
-    # Public: Print a message
+    # Print an informational message
     #
-    # topic - the topic of the message, e.g. "Configuration file", "Deprecation", etc.
-    # message - the message detail
-    #
-    # Returns nothing
+    # @param topic [String] e.g. "Configuration file", "Deprecation", etc.
+    # @param message [String] the message detail
     def info(topic, message = nil, &)
       write(:info, topic, message, &)
     end
 
-    # Public: Print a message
-    #
-    # topic - the topic of the message, e.g. "Configuration file", "Deprecation", etc.
-    # message - the message detail
+    # Print a warning message
     #
-    # Returns nothing
+    # @param topic [String] e.g. "Configuration file", "Deprecation", etc.
+    # @param message [String] the message detail
     def warn(topic, message = nil, &)
       write(:warn, topic, message, &)
     end
 
-    # Public: Print an error message
-    #
-    # topic - the topic of the message, e.g. "Configuration file", "Deprecation", etc.
-    # message - the message detail
+    # Print an error message
     #
-    # Returns nothing
+    # @param topic [String] e.g. "Configuration file", "Deprecation", etc.
+    # @param message [String] the message detail
     def error(topic, message = nil, &)
       write(:error, topic, message, &)
     end
 
-    # Public: Print an error message and immediately abort the process
+    # Print an error message and immediately abort the process
     #
-    # topic - the topic of the message, e.g. "Configuration file", "Deprecation", etc.
-    # message - the message detail (can be omitted)
-    #
-    # Returns nothing
+    # @param topic [String] e.g. "Configuration file", "Deprecation", etc.
+    # @param message [String] the message detail
     def abort_with(topic, message = nil, &)
       error(topic, message, &)
       abort
     end
 
-    # Internal: Build a topic method
-    #
-    # topic - the topic of the message, e.g. "Configuration file", "Deprecation", etc.
-    # message - the message detail
+    # Build a topic method
     #
-    # Returns the formatted message
+    # @param topic [String] e.g. "Configuration file", "Deprecation", etc.
+    # @param message [String] the message detail
+    # @return [String] the formatted message
     def message(topic, message = nil)
       raise ArgumentError, "block or message, not both" if block_given? && message
 
@@ -113,34 +98,30 @@ module Bridgetown
       out
     end
 
-    # Internal: Format the topic
-    #
-    # topic - the topic of the message, e.g. "Configuration file", "Deprecation", etc.
-    # colon -
+    # Format the topic
     #
-    # Returns the formatted topic statement
+    # @param topic [String] e.g. "Configuration file", "Deprecation", etc.
+    # @param colon [Boolean]
+    # @return [String] formatted topic statement
     def formatted_topic(topic, colon = false) # rubocop:disable Style/OptionalBooleanParameter
       "#{topic}#{colon ? ": " : " "}".rjust(20)
     end
 
-    # Internal: Check if the message should be written given the log level.
+    # Check if the message should be written given the log level
     #
-    # level_of_message - the Symbol level of message, one of :debug, :info, :warn, :error
-    #
-    # Returns whether the message should be written.
+    # @param level_of_message [Symbol] the message level (`debug` | `info` | `warn` | `error`)
+    # @return [Boolean] whether the message should be written to the log
     def write_message?(level_of_message)
       LOG_LEVELS.fetch(level) <= LOG_LEVELS.fetch(level_of_message)
     end
 
-    # Internal: Log a message.
-    #
-    # level_of_message - the Symbol level of message, one of :debug, :info, :warn, :error
-    # topic - the String topic or full message
-    # message - the String message (optional)
-    # block - a block containing the message (optional)
+    # Log a message. If a block is provided containing the message, use that instead.
     #
-    # Returns false if the message was not written, otherwise returns the value of calling
-    # the appropriate writer method, e.g. writer.info.
+    # @param level_of_message [Symbol] the message level (`debug` | `info` | `warn` | `error`)
+    # @param topic [String] e.g. "Configuration file", "Deprecation", etc.
+    # @param message [String] the message detail
+    # @return [BasicObject] false if the message was not written, otherwise returns the value of
+    #   calling the appropriate writer method, e.g. writer.info.
     def write(level_of_message, topic, message = nil, &)
       return false unless write_message?(level_of_message)
 

data/lib/bridgetown-core/plugin_manager.rb

@@ -27,6 +27,7 @@ module Bridgetown
 
         require_relative "utils/initializers"
         load_determined_bundler_environment
+        require_plugin_features
 
         ENV["BRIDGETOWN_NO_BUNDLER_REQUIRE"] = "true"
         true
@@ -52,6 +53,16 @@ module Bridgetown
       end
     end
 
+    def self.require_plugin_features
+      bundler_specs.select do |loaded_gem|
+        loaded_gem.to_spec.metadata["bridgetown_features"] == "true"
+      end.each do |plugin_gem|
+        Bridgetown::Utils::RequireGems.require_with_graceful_fail(
+          "bridgetown/features/#{plugin_gem.name}"
+        )
+      end
+    end
+
     def self.require_gem(name)
       Bridgetown::Utils::RequireGems.require_with_graceful_fail(name)
       plugins = Bridgetown::PluginManager.install_npm_dependencies(name:)
@@ -70,12 +81,12 @@ module Bridgetown
     end
 
     def self.package_manager
-      @package_manager ||= if File.exist?("package-lock.json")
-                             "npm"
-                           elsif File.exist?("yarn.lock")
+      @package_manager ||= if File.exist?("yarn.lock")
                              "yarn"
                            elsif File.exist?("pnpm-lock.yaml")
                              "pnpm"
+                           elsif File.exist?("package.json")
+                             "npm"
                            else
                              ""
                            end
@@ -85,6 +96,10 @@ module Bridgetown
       package_manager == "npm" ? "install" : "add"
     end
 
+    def self.package_manager_uninstall_command
+      package_manager == "npm" ? "uninstall" : "remove"
+    end
+
     # rubocop:disable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
 
     # Iterates through loaded gems and finds npm-add gemspec metadata.

data/lib/bridgetown-core/rack/logger.rb

@@ -7,8 +7,6 @@ module Bridgetown
   module Rack
     class Logger < Bridgetown::LogWriter
       def self.message_with_prefix(msg)
-        #        return if msg.include?("/_bridgetown/live_reload")
-
         "\e[35m[Server]\e[0m #{msg}"
       end