bridgetown-core 0.15.0.beta2 → 0.16.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34bf7d4a458a8c56d645d8243fc445948bbed43c65d32930437ec92a06c25620
-  data.tar.gz: be2065a0a7e49ba29d84e49a5eb33df6d43f2a543d2cd29540e2f712599af4aa
+  metadata.gz: d9c23ef7da53e1f746ee14540f1f370ad6edea81667e314e9ff9e4c032c8c40c
+  data.tar.gz: f8ef26737713ef23c95a5b61407b51e791c266a0eef766ab4ca07fd9ad9e39bc
 SHA512:
-  metadata.gz: bf8ef56bf7943a347c9fe092794551e2c6c620a068d7008eca1ee1c8c1c95ae9d71dd42448fd57011f77f4fc5025a32219345917d7e5aa72c2de196ddade77c0
-  data.tar.gz: ed4bee93af751055e526365d84b3c34c10665add8f2d5329da7cd7549a473ed2f0beb6b19d5e8b04e2f511926465d8cb892355cb25f8b22b4060dc33915dafc9
+  metadata.gz: 4fd1626a1708c19486e34a74deeea3c5f2659eb7c96dc7ff0444d464347e4b83e410e36b7b75da727d0120399e01e9f9b11915f6a7f601bb89159bf5bcc863e5
+  data.tar.gz: f087e6a3c5d2990f514f9ebfa33cf6a7654d0ab2f22ea09f0411dee72caaed12684642a43a5fa4b55790544814f6a599fe663ccc91390849d3acb51ec58d9b22

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,7 +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("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")
@@ -48,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,6 +64,7 @@ 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"
@@ -77,17 +78,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

@@ -8,6 +8,11 @@ require "active_support/core_ext/string/indent"
 module Bridgetown
   module Commands
     module Actions
+      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
         data ||= yield if block_given?
@@ -77,31 +82,48 @@ module Bridgetown
 
       private
 
+      def determine_remote_filename(arg)
+        if arg.end_with?(".rb")
+          arg.split("/").yield_self do |segments|
+            arg.sub!(%r!/#{segments.last}$!, "")
+            segments.last
+          end
+        else
+          "bridgetown.automation.rb"
+        end
+      end
+
       # TODO: option to download and confirm remote automation?
+      # rubocop:disable Metrics/MethodLength
       def transform_automation_url(arg)
         return arg unless arg.start_with?("http")
 
-        remote_file = if arg.end_with?(".rb")
-                        arg.split("/").yield_self do |segments|
-                          arg.sub!(%r!/#{segments.last}$!, "")
-                          segments.last
-                        end
-                      else
-                        "bridgetown.automation.rb"
-                      end
-
-        if arg.start_with?("https://gist.github.com")
-          return arg.sub(
-            "https://gist.github.com", "https://gist.githubusercontent.com"
-          ) + "/raw/#{remote_file}"
-        elsif arg.start_with?("https://github.com")
-          return arg.sub(
-            "https://github.com", "https://raw.githubusercontent.com"
-          ) + "/master/#{remote_file}"
-        end
+        remote_file = determine_remote_filename(arg)
+        github_match = GITHUB_REGEX.match(arg)
+
+        arg = if arg.start_with?("https://gist.github.com")
+                arg.sub(
+                  "https://gist.github.com", "https://gist.githubusercontent.com"
+                ) + "/raw"
+              elsif github_match
+                new_url = arg.sub(GITHUB_REGEX, "https://raw.githubusercontent.com")
+                github_tree_match = GITHUB_TREE_REGEX.match(arg)
+                github_blob_match = GITHUB_BLOB_REGEX.match(arg)
+
+                if github_tree_match
+                  new_url.sub("/tree/", "/")
+                elsif github_blob_match
+                  new_url.sub("/blob/", "/")
+                else
+                  "#{new_url}/#{Bridgetown::Utils.default_github_branch_name(arg)}"
+                end
+              else
+                arg
+              end
 
-        arg + "/#{remote_file}"
+        "#{arg}/#{remote_file}"
       end
+      # rubocop:enable Metrics/MethodLength
     end
   end
 end

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "irb"
-
 module Bridgetown
   module Commands
     class Console < Thor::Group
@@ -21,11 +19,17 @@ module Bridgetown
                    type: :array,
                    banner: "FILE1 FILE2",
                    desc: "Custom configuration file(s)"
+      class_option :"bypass-ap",
+                   type: :boolean,
+                   desc: "Don't load AwesomePrint 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"]
+
         Bridgetown.logger.info "Starting:", "Bridgetown v#{Bridgetown::VERSION.magenta}" \
                                     " (codename \"#{Bridgetown::CODE_NAME.yellow}\")" \
                                     " console…"
@@ -56,6 +60,12 @@ module Bridgetown
 
         begin
           catch(:IRB_EXIT) do
+            unless options[:"bypass-ap"]
+              AwesomePrint.defaults = {
+                indent: 2,
+              }
+              AwesomePrint.irb!
+            end
             irb.eval_input
           end
         end

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

@@ -29,6 +29,11 @@ module Bridgetown
       class_option :skip_initial_build,
                    type: :boolean,
                    desc: "Skips the initial site build which occurs before the server is started."
+      class_option :watch,
+                   type: :boolean,
+                   aliases: "-w",
+                   default: true,
+                   desc: "Watch for changes and rebuild"
 
       def self.banner
         "bridgetown serve [options]"

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,107 @@ module Bridgetown
       @config
     end
 
-    # Returns the FrontmatterDefaults or creates a new FrontmatterDefaults
-    # if it doesn't already exist.
+    # 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