bridgetown-core 0.15.0.beta4 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71735e11ccbfa90136e92df69397f7c27555e846a509064e5ec44640e34a807f
-  data.tar.gz: 81f2e343ca9b675dbbc15877129d3c3a1d1e410f020d006fbbcf7ba3032a56a0
+  metadata.gz: bd231215591b9251d63525c740620bf4cd6da0beb5e48abd420ce745355ac0bb
+  data.tar.gz: 82dff2c41efbac2e9ea4f60cc441f8665044c3c8e6576695a50db376951c5866
 SHA512:
-  metadata.gz: 96f9dd7c20e611506bacc39b87bc74bef99281f98e08fb16f05a14b2f7d3e08da8929fe9036146cce3ebdc98cf5aad3466ab6c45f34853a5af7c8c0411827155
-  data.tar.gz: be4dbaa9575a318e31555f9a1d591090fa7c12d4a3a6e53d59d1b3f92783ed910bf62db97c36c6bb1dc3f4acdbf3a2b45991b37fea5be0fd395ae72b86ea62af
+  metadata.gz: 4606e45f6a843e7de6e9e81c873cb5082ca958277631d83dd260b0eef64289e8c93259d771fee5501dd5c7ec92747d278faffbaf3802ee72457e300aee96714e
+  data.tar.gz: 82cd06e0dd5a11061d2c37d3defb8d57e381f4129abed12bd47fa4af8c2bbaee3372c3aac09fcf3b9b6fd92a8152dd458b79da710fc575c8e91096946e5ced87

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,8 +33,9 @@ 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("i18n",                  "~> 1.0")
@@ -49,4 +50,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

@@ -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,41 +35,85 @@ 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
+    # +ActiveSupport::HashWithIndifferentAccess+
+    # @return [Hash] Returns a hash of site metadata
     def metadata
       data["site_metadata"] ||= ActiveSupport::HashWithIndifferentAccess.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
@@ -71,10 +122,11 @@ module Bridgetown
       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