bridgetown-core 0.15.0 → 0.17.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97ae06ce8eba440f7fbf028094f48c4779b08245c7e2edd2641deed2ccb271b0
-  data.tar.gz: b0680214291a6721bb43230bca4627608414fea6a6fc741b2431672dfd04a39d
+  metadata.gz: 7878e020dc228c491934a986395227f17fa2ca93398ae0f3961a77c4df6e1761
+  data.tar.gz: 73dd2ad473c8525974708393f97f0ce464241fedcc78951186b726ea3435c444
 SHA512:
-  metadata.gz: b742ce6a54a89c48beb0f12e27cb0bb8a67630ca0e749b30919ffc8a4be2054a9de38374bde59ba2f2f2db1a436a6704dc070f6eb418e85f650bb2f66d8c3dd0
-  data.tar.gz: 99a4bfe0ab8fb3dcf94e92423089048d9149722044b79ac698c95eda96872cfa84a25e5cc2e190d4f77f2215c80199aae01d9d7aa63669f6e21790c4279e50dc
+  metadata.gz: 38624e9ea2b7e604b773f2224eec18fdce5e44fc9c9e388c7cefa1ebee6fcee62aa96406ff783a7458a5b3d7a24f45c486a2cc2e925867609a26cb8e30336bb1
+  data.tar.gz: eb46348e312153b95b46b1b5e7fbfca154c4d39c87af62e9b77ccdfacdd43cca640b8adf216c223aeb9f47f92977df48d3550dab1a7a173dac256c92cf89f77f

data/Rakefile

@@ -12,3 +12,17 @@ Rake::TestTask.new(:test) do |test|
   test.pattern = "test/**/test_*.rb"
   test.verbose = true
 end
+
+require 'yard'
+YARD::Rake::YardocTask.new(:yard) do |t|
+ t.files   = ['lib/**/*.rb']
+ t.options = ['--no-output']
+ t.stats_options = ['--list-undoc']
+end
+
+namespace :yard do
+  task :serve do
+    port = ENV['YARD_PORT'] || "8808"
+    sh("yard server --reload -p #{port}")
+  end
+end

data/bridgetown-core.gemspec

@@ -33,10 +33,12 @@ Gem::Specification.new do |s|
 
   s.add_runtime_dependency("activesupport",         "~> 6.0")
   s.add_runtime_dependency("addressable",           "~> 2.4")
-  s.add_runtime_dependency("awesome_print",         "~> 1.8")
+  s.add_runtime_dependency("amazing_print",         "~> 1.2")
   s.add_runtime_dependency("colorator",             "~> 1.0")
+  s.add_runtime_dependency("erubi",                 "~> 1.9")
   s.add_runtime_dependency("faraday",               "~> 1.0")
   s.add_runtime_dependency("faraday_middleware",    "~> 1.0")
+  s.add_runtime_dependency("hash_with_dot_access",  "~> 1.0")
   s.add_runtime_dependency("i18n",                  "~> 1.0")
   s.add_runtime_dependency("kramdown",              "~> 2.1")
   s.add_runtime_dependency("kramdown-parser-gfm",   "~> 1.0")
@@ -49,4 +51,5 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency("safe_yaml",             "~> 1.0")
   s.add_runtime_dependency("terminal-table",        "~> 1.8")
   s.add_runtime_dependency("thor",                  "~> 1.0")
+  s.add_runtime_dependency("tilt",                  "~> 2.0")
 end

data/lib/bridgetown-core.rb

@@ -29,8 +29,8 @@ require "csv"
 require "json"
 
 # 3rd party
-require "active_support/core_ext/hash/indifferent_access"
 require "active_support/core_ext/string/inflections"
+require "hash_with_dot_access"
 require "pathutil"
 require "addressable/uri"
 require "safe_yaml/load"
@@ -54,7 +54,7 @@ module Bridgetown
   autoload :Cleaner,             "bridgetown-core/cleaner"
   autoload :Collection,          "bridgetown-core/collection"
   autoload :Configuration,       "bridgetown-core/configuration"
-  autoload :Convertible,         "bridgetown-core/concerns/convertible"
+  autoload :DataAccessible,      "bridgetown-core/concerns/data_accessible"
   autoload :Deprecator,          "bridgetown-core/deprecator"
   autoload :Document,            "bridgetown-core/document"
   autoload :EntryFilter,         "bridgetown-core/entry_filter"
@@ -64,9 +64,11 @@ module Bridgetown
   autoload :FrontmatterDefaults, "bridgetown-core/frontmatter_defaults"
   autoload :Hooks,               "bridgetown-core/hooks"
   autoload :Layout,              "bridgetown-core/layout"
+  autoload :LayoutPlaceable,     "bridgetown-core/concerns/layout_placeable"
   autoload :Cache,               "bridgetown-core/cache"
   autoload :CollectionReader,    "bridgetown-core/readers/collection_reader"
   autoload :DataReader,          "bridgetown-core/readers/data_reader"
+  autoload :DefaultsReader,      "bridgetown-core/readers/defaults_reader"
   autoload :LayoutReader,        "bridgetown-core/readers/layout_reader"
   autoload :PostReader,          "bridgetown-core/readers/post_reader"
   autoload :PageReader,          "bridgetown-core/readers/page_reader"
@@ -77,17 +79,21 @@ module Bridgetown
   autoload :PageWithoutAFile,    "bridgetown-core/page_without_a_file"
   autoload :PathManager,         "bridgetown-core/path_manager"
   autoload :PluginManager,       "bridgetown-core/plugin_manager"
+  autoload :Publishable,         "bridgetown-core/concerns/publishable"
   autoload :Publisher,           "bridgetown-core/publisher"
   autoload :Reader,              "bridgetown-core/reader"
   autoload :Regenerator,         "bridgetown-core/regenerator"
   autoload :RelatedPosts,        "bridgetown-core/related_posts"
   autoload :Renderer,            "bridgetown-core/renderer"
+  autoload :LiquidRenderable,    "bridgetown-core/concerns/liquid_renderable"
   autoload :LiquidRenderer,      "bridgetown-core/liquid_renderer"
+  autoload :RubyTemplateView,    "bridgetown-core/ruby_template_view"
   autoload :LogWriter,           "bridgetown-core/log_writer"
   autoload :Site,                "bridgetown-core/site"
   autoload :StaticFile,          "bridgetown-core/static_file"
   autoload :URL,                 "bridgetown-core/url"
   autoload :Utils,               "bridgetown-core/utils"
+  autoload :Validatable,         "bridgetown-core/concerns/validatable"
   autoload :VERSION,             "bridgetown-core/version"
   autoload :Watcher,             "bridgetown-core/watcher"
 

data/lib/bridgetown-core/commands/concerns/actions.rb

@@ -11,6 +11,7 @@ module Bridgetown
       GITHUB_REGEX = %r!https://github\.com!.freeze
       GITHUB_TREE_REGEX = %r!#{GITHUB_REGEX}/.*/.*/tree/.*/?!.freeze
       GITHUB_BLOB_REGEX = %r!#{GITHUB_REGEX}/.*/.*/blob/!.freeze
+      GITHUB_REPO_REGEX = %r!github\.com/(.*?/[^/]*)!.freeze
 
       def create_builder(filename, data = nil)
         say_status :create_builder, filename
@@ -114,7 +115,7 @@ module Bridgetown
                 elsif github_blob_match
                   new_url.sub("/blob/", "/")
                 else
-                  "#{new_url}/master"
+                  "#{new_url}/#{Bridgetown::Utils.default_github_branch_name(arg)}"
                 end
               else
                 arg

data/lib/bridgetown-core/commands/console.rb

@@ -21,14 +21,14 @@ module Bridgetown
                    desc: "Custom configuration file(s)"
       class_option :"bypass-ap",
                    type: :boolean,
-                   desc: "Don't load AwesomePrint when IRB opens"
+                   desc: "Don't load AmazingPrint when IRB opens"
       class_option :blank,
                    type: :boolean,
                    desc: "Skip reading content and running generators before opening console"
 
       def console
         require "irb"
-        require "awesome_print" unless options[:"bypass-ap"]
+        require "amazing_print" unless options[:"bypass-ap"]
 
         Bridgetown.logger.info "Starting:", "Bridgetown v#{Bridgetown::VERSION.magenta}" \
                                     " (codename \"#{Bridgetown::CODE_NAME.yellow}\")" \
@@ -61,10 +61,10 @@ module Bridgetown
         begin
           catch(:IRB_EXIT) do
             unless options[:"bypass-ap"]
-              AwesomePrint.defaults = {
+              AmazingPrint.defaults = {
                 indent: 2,
               }
-              AwesomePrint.irb!
+              AmazingPrint.irb!
             end
             irb.eval_input
           end

data/lib/bridgetown-core/concerns/data_accessible.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module DataAccessible
+    # Returns the contents as a String.
+    def to_s
+      output || content || ""
+    end
+
+    # 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.
+    def [](property)
+      data[property]
+    end
+  end
+end

data/lib/bridgetown-core/concerns/layout_placeable.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module LayoutPlaceable
+    # Determine whether the file should be placed into layouts.
+    #
+    # Returns false if the document is an asset file or if the front matter
+    #   specifies `layout: none`
+    def place_in_layout?
+      !(yaml_file? || no_layout?)
+    end
+
+    def no_layout?
+      data["layout"] == "none"
+    end
+  end
+end

data/lib/bridgetown-core/concerns/liquid_renderable.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module LiquidRenderable
+    # Determine whether the file should be rendered with Liquid.
+    #
+    # Returns false if the document is a yaml file or if the document doesn't
+    # contain any Liquid Tags or Variables, true otherwise.
+    def render_with_liquid?
+      return false if data["render_with_liquid"] == false
+
+      !(yaml_file? || !Utils.has_liquid_construct?(content))
+    end
+
+    # Override in individual classes
+    def yaml_file?
+      false
+    end
+  end
+end

data/lib/bridgetown-core/concerns/publishable.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Publishable
+    # Whether the file is published or not, as indicated in YAML front-matter
+    def published?
+      !(data.key?("published") && data["published"] == false)
+    end
+  end
+end

data/lib/bridgetown-core/concerns/site/configurable.rb

@@ -2,12 +2,17 @@
 
 module Bridgetown
   module Site::Configurable
-    # Public: Set the site's configuration. This handles side-effects caused by
+    # Set the site's configuration. This handles side-effects caused by
     # changing values in the configuration.
     #
-    # config - a Bridgetown::Configuration, containing the new configuration.
+    # @param config [Bridgetown::Configuration]
+    #   An instance of {Bridgetown::Configuration},
+    #   containing the new configuration.
     #
-    # Returns the new configuration.
+    # @return [Bridgetown::Configuration]
+    #   A new instance of {Bridgetown::Configuration}
+    #
+    # @see Bridgetown::Configuration
     def config=(config)
       @config = config.clone
 
@@ -32,81 +37,111 @@ module Bridgetown
       @config
     end
 
-    # Returns the FrontmatterDefaults or creates a new FrontmatterDefaults
-    # if it doesn't already exist.
+    def defaults_reader
+      @defaults_reader ||= DefaultsReader.new(self)
+    end
+
+    # Returns the current instance of {FrontmatterDefaults} or
+    # creates a new instance {FrontmatterDefaults} if it doesn't already exist.
     #
-    # Returns The FrontmatterDefaults
+    # @return [FrontmatterDefaults]
+    #   Returns an instance of {FrontmatterDefaults}
     def frontmatter_defaults
       @frontmatter_defaults ||= FrontmatterDefaults.new(self)
     end
 
-    # Whether to perform a full rebuild without incremental regeneration
+    # Whether to perform a full rebuild without incremental regeneration.
+    # If either +override+["incremental"] or +config+["incremental"] are true,
+    # fully rebuild the site. If not, incrementally build the site.
     #
-    # Returns a Boolean: true for a full rebuild, false for normal build
+    # @param [Hash] override
+    #   An override hash to override the current config value
+    # @option override [Boolean] "incremental" Whether to incrementally build
+    # @return [Boolean] true for full rebuild, false for normal build
     def incremental?(override = {})
       override["incremental"] || config["incremental"]
     end
 
-    # Returns the publisher or creates a new publisher if it doesn't
-    # already exist.
+    # Returns the current instance of {Publisher} or creates a new instance of
+    # {Publisher} if one doesn't exist.
     #
-    # Returns The Publisher
+    # @return [Publisher] Returns an instance of {Publisher}
     def publisher
       @publisher ||= Publisher.new(self)
     end
 
-    # Public: Prefix a given path with the root directory.
+    # Prefix a path or paths with the {#root_dir} directory.
     #
-    # paths - (optional) path elements to a file or directory within the
-    #         root directory
+    # @see Bridgetown.sanitized_path
+    # @param paths [Array<String>]
+    #   An array of paths to prefix with the root_dir directory using the
+    #   {Bridgetown.sanitized_path} method.
     #
-    # Returns a path which is prefixed with the root_dir directory.
+    # @return [Array<String>] Return an array of updated paths if multiple paths given.
     def in_root_dir(*paths)
       paths.reduce(root_dir) do |base, path|
         Bridgetown.sanitized_path(base, path)
       end
     end
 
-    # Public: Prefix a given path with the source directory.
-    #
-    # paths - (optional) path elements to a file or directory within the
-    #         source directory
+    # Prefix a path or paths with the {#source} directory.
     #
-    # Returns a path which is prefixed with the source directory.
+    # @see Bridgetown.sanitized_path
+    # @param paths [Array<String>]
+    #   An array of paths to prefix with the source directory using the
+    #   {Bridgetown.sanitized_path} method.
+    # @return [Array<String>] Return an array of updated paths if multiple paths given.
     def in_source_dir(*paths)
       paths.reduce(source) do |base, path|
         Bridgetown.sanitized_path(base, path)
       end
     end
 
-    # Public: Prefix a given path with the destination directory.
+    # Prefix a path or paths with the {#dest} directory.
     #
-    # paths - (optional) path elements to a file or directory within the
-    #         destination directory
+    # @see Bridgetown.sanitized_path
+    # @param paths [Array<String>]
+    #   An array of paths to prefix with the destination directory using the
+    #   {Bridgetown.sanitized_path} method.
     #
-    # Returns a path which is prefixed with the destination directory.
+    # @return [Array<String>] Return an array of updated paths if multiple paths given.
     def in_dest_dir(*paths)
       paths.reduce(dest) do |base, path|
         Bridgetown.sanitized_path(base, path)
       end
     end
 
-    # Public: Prefix a given path with the cache directory.
+    # Prefix a path or paths with the {#cache_dir} directory.
     #
-    # paths - (optional) path elements to a file or directory within the
-    #         cache directory
+    # @see Bridgetown.sanitized_path
+    # @param paths [Array<String>]
+    #   An array of paths to prefix with the {#cache_dir} directory using the
+    #   {Bridgetown.sanitized_path} method.
     #
-    # Returns a path which is prefixed with the cache directory.
+    # @return [Array<String>] Return an array of updated paths if multiple paths given.
     def in_cache_dir(*paths)
       paths.reduce(cache_dir) do |base, path|
         Bridgetown.sanitized_path(base, path)
       end
     end
 
-    # Public: The full path to the directory that houses all the collections registered
-    # with the current site.
+    # The full path to the directory that houses all the registered collections
+    # for the current site.
+    #
+    # If +@collections_path+ is specified use its value.
+    #
+    # If +@collections+ is not specified and +config+["collections_dir"] is
+    # specified, prepend it with {#source} and assign it to
+    # {#collections_path}.
+    #
+    # If +@collections+ is not specified and +config+["collections_dir"] is not
+    # specified, assign {#source} to +@collections_path+
     #
-    # Returns the source directory or the absolute path to the custom collections_dir
+    # @return [String] Returns the full path to the collections directory
+    # @see #config
+    # @see #source
+    # @see #collections_path
+    # @see #in_source_dir
     def collections_path
       dir_str = config["collections_dir"]
       @collections_path ||= dir_str.empty? ? source : in_source_dir(dir_str)

data/lib/bridgetown-core/concerns/site/content.rb

@@ -4,17 +4,24 @@ module Bridgetown
   module Site::Content
     # Construct a Hash of Posts indexed by the specified Post attribute.
     #
-    # post_attr - The String name of the Post attribute.
+    # @param post_attr [String] The String name of the Post attribute.
     #
-    # Examples
+    # @example
+    #   Returns a hash like so: { attr => posts } where
+    #
+    #   attr  - One of the values for the requested attribute.
+    #
+    #   posts - The Array of Posts with the given attr value.
+    #
+    # @example
     #
     #   post_attr_hash('categories')
     #   # => { 'tech' => [<Post A>, <Post B>],
     #   #      'ruby' => [<Post B>] }
     #
-    # Returns the Hash: { attr => posts } where
-    #   attr  - One of the values for the requested attribute.
-    #   posts - The Array of Posts with the given attr value.
+    # @return [Hash{String, Symbol => Array<Post>}]
+    #   Returns a hash of !{attr => posts}
+    #
     def post_attr_hash(post_attr)
       # Build a hash map based on the specified post attribute ( post attr =>
       # array of posts ) then sort each array in reverse order.
@@ -28,53 +35,98 @@ module Bridgetown
       end
     end
 
+    # Returns a hash of "tags" using {#post_attr_hash} where each tag is a key
+    # and each value is a post which contains the key.
+    # @example
+    #   tags
+    #   # => { 'tech': [<Post A>, <Post B>],
+    #   #      'ruby': [<Post C> }
+    # @return [Hash{String, Array<Post>}] Returns a hash of all tags and their corresponding posts
+    # @see post_attr_hash
     def tags
       post_attr_hash("tags")
     end
 
+    # Returns a hash of "categories" using {#post_attr_hash} where each tag is
+    # a key and each value is a post which contains the key.
+    # @example
+    #   categories
+    #   # => { 'tech': [<Post A>, <Post B>],
+    #   #      'ruby': [<Post C> }
+    # @return [Hash{String, Array<Post>}] Returns a hash of all categories and
+    #   their corresponding posts
+    # @see post_attr_hash
     def categories
       post_attr_hash("categories")
     end
 
+    # Returns the value of +data+["site_metadata"] or creates a new instance of
+    # +HashWithDotAccess::Hash+
+    # @return [Hash] Returns a hash of site metadata
     def metadata
-      data["site_metadata"] ||= ActiveSupport::HashWithIndifferentAccess.new
+      data["site_metadata"] ||= HashWithDotAccess::Hash.new
     end
 
     # The Hash payload containing site-wide data.
     #
-    # Returns the Hash: { "site" => data } where data is a Hash with keys:
-    #   "time"       - The Time as specified in the configuration or the
-    #                  current time if none was specified.
-    #   "posts"      - The Array of Posts, sorted chronologically by post date
-    #                  and then title.
-    #   "pages"      - The Array of all Pages.
-    #   "html_pages" - The Array of HTML Pages.
-    #   "categories" - The Hash of category values and Posts.
-    #                  See Site#post_attr_hash for type info.
-    #   "tags"       - The Hash of tag values and Posts.
-    #                  See Site#post_attr_hash for type info.
+    # @example
+    #   site_payload
+    #   # => { "site" => data } Where data is a Hash. See example below
+    #
+    #   site = site_payload["site"]
+    #   # => Returns a Hash with the following keys:
+    #   #
+    #   # site["time"]       - The Time as specified in the configuration or the
+    #   #                      current time if none was specified.
+    #   #
+    #   # site["posts"]      - The Array of Posts, sorted chronologically by post date
+    #   #                      and then title.
+    #   #
+    #   # site["pages"]      - The Array of all Pages.
+    #   #
+    #   # site["html_pages"] - The Array of HTML Pages.
+    #   #
+    #   # site["categories"] - The Hash of category values and Posts.
+    #   #                      See Site#post_attr_hash for type info.
+    #   #
+    #   # site["tags"]       - The Hash of tag values and Posts.
+    #   #                      See Site#post_attr_hash for type info.
+    #
+    # @return [Hash] Returns a hash in the structure of { "site" => data }
+    #
+    #   See above example for usage.
+    #
+    # @see #post_attr_hash
     def site_payload
       Drops::UnifiedPayloadDrop.new self
     end
     alias_method :to_liquid, :site_payload
 
-    # The list of collections and their corresponding Bridgetown::Collection instances.
-    # If config['collections'] is set, a new instance is created
-    # for each item in the collection, a new hash is returned otherwise.
+    # The list of {#collections} and their corresponding {Bridgetown::Collection} instances.
+    #
+    # If +config+['collections'] is set, a new instance of {Bridgetown::Collection} is created
+    # for each entry in the collections configuration.
+    #
+    # If +config+["collections"] is not specified, a blank hash is returned.
     #
-    # Returns a Hash containing collection name-to-instance pairs.
+    # @return [Hash{String, Symbol => Bridgetown::Collection}] A Hash
+    #   containing a collection name-to-instance pairs.
+    #
+    # @return [Hash] Returns a blank hash if no items found
+    # @see Collection
     def collections
       @collections ||= collection_names.each_with_object(
-        ActiveSupport::HashWithIndifferentAccess.new
+        HashWithDotAccess::Hash.new
       ) do |name, hsh|
         hsh[name] = Bridgetown::Collection.new(self, name)
       end
     end
 
-    # The list of collection names.
-    #
-    # Returns an array of collection names from the configuration,
-    #   or an empty array if the `collections` key is not set.
+    # An array of collection names.
+    # @return [Array<Collection>] an array of collection names from the configuration,
+    #   or an empty array if the +config+["collections"] key is not set.
+    # @raise ArgumentError Raise an error if +config+["collections"] is not
+    #   an Array or a Hash
     def collection_names
       case config["collections"]
       when Hash
@@ -88,22 +140,29 @@ module Bridgetown
       end
     end
 
-    # Get all the documents
-    #
-    # Returns an Array of all Documents
+    # Get all documents.
+    # @return [Array<String>] an array of documents from the configuration
     def documents
       collections.each_with_object(Set.new) do |(_, collection), set|
         set.merge(collection.docs).merge(collection.files)
       end.to_a
     end
 
-    # Get the to be written documents
+    # Get the documents to be written
     #
-    # Returns an Array of Documents which should be written
+    # @return [Array<String, File>] an Array of Documents which should be written and
+    #   that +respond_to :write?+
+    # @see #documents
+    # @see Collection
     def docs_to_write
       documents.select(&:write?)
     end
 
+    # Get all posts.
+    #
+    # @return [Collection] A #Collection of posts. Returns +#collections+["posts"]
+    # @return [Collection] Return a new #Collection if +#collections+["posts"] is nil
+    # @see Collection
     def posts
       collections["posts"] ||= Collection.new(self, "posts")
     end