bridgetown-core 0.15.0.beta3 → 0.16.0

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

@@ -3,17 +3,19 @@
 module Bridgetown
   module Site::Extensible
     # Load necessary libraries, plugins, converters, and generators.
-    #
-    # Returns nothing.
+    # @see Bridgetown::Converter
+    # @see Bridgetown::Generator
+    # @see PluginManager
+    # @return [void]
     def setup
       plugin_manager.require_plugin_files
       self.converters = instantiate_subclasses(Bridgetown::Converter)
       self.generators = instantiate_subclasses(Bridgetown::Generator)
     end
 
-    # Run each of the Generators.
-    #
-    # Returns nothing.
+    # Run all Generators.
+    # @see Bridgetown::Generator
+    # @return [void]
     def generate
       generators.each do |generator|
         start = Time.now
@@ -32,8 +34,9 @@ module Bridgetown
     end
 
     # Get the implementation class for the given Converter.
-    # Returns the Converter instance implementing the given Converter.
-    # klass - The Class of the Converter to fetch.
+    # @param klass [Object] The Class of the Converter to fetch.
+    # @return [Bridgetown::Converter] Returns the {Bridgetown::Converter}
+    #   instance implementing the given +Converter+.
     def find_converter_instance(klass)
       @find_converter_instance ||= {}
       @find_converter_instance[klass] ||= begin
@@ -42,11 +45,11 @@ module Bridgetown
       end
     end
 
-    # klass - class or module containing the subclasses.
-    # Returns array of instances of subclasses of parameter.
-    # Create array of instances of the subclasses of the class or module
-    # passed in as argument.
-
+    # Create an array of instances of the subclasses of the class or module
+    #   passed in as argument.
+    # @param klass [Class, Module] - class or module containing the subclasses.
+    # @return [Array<Object>] Returns an array of instances of subclasses of
+    #   +klass+.
     def instantiate_subclasses(klass)
       klass.descendants.sort.map do |c|
         c.new(config)

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

@@ -2,9 +2,14 @@
 
 module Bridgetown
   module Site::Processable
-    # Public: Read, process, and write this Site to output.
-    #
-    # Returns nothing.
+    # Reset, Read, Generate, Render, Cleanup, Process, and Write this Site to output.
+    # @return [void]
+    # @see #reset
+    # @see #read
+    # @see #generate
+    # @see #render
+    # @see #cleanup
+    # @see #write
     def process
       reset
       read
@@ -16,10 +21,9 @@ module Bridgetown
     end
 
     # rubocop:disable Metrics/AbcSize
-    #
+
     # Reset Site details.
-    #
-    # Returns nothing
+    # @return [void]
     def reset
       self.time = if config["time"]
                     Utils.parse_date(config["time"].to_s, "Invalid time in bridgetown.config.yml.")
@@ -43,11 +47,11 @@ module Bridgetown
       Bridgetown::Cache.clear_if_config_changed config
       Bridgetown::Hooks.trigger :site, :after_reset, self
     end
+
     # rubocop:enable Metrics/AbcSize
 
     # Read Site data from disk and load it into internal data structures.
-    #
-    # Returns nothing.
+    # @return [void]
     def read
       Bridgetown::Hooks.trigger :site, :pre_read, self
       reader.read
@@ -58,8 +62,6 @@ module Bridgetown
     private
 
     # Limits the current posts; removes the posts which exceed the limit_posts
-    #
-    # Returns nothing
     def limit_posts!
       if limit_posts.positive?
         limit = posts.docs.length < limit_posts ? posts.docs.length : limit_posts

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

@@ -3,8 +3,7 @@
 module Bridgetown
   module Site::Renderable
     # Render the site to the destination.
-    #
-    # Returns nothing.
+    # @return [void]
     def render
       payload = site_payload
 
@@ -18,6 +17,14 @@ module Bridgetown
       Bridgetown::Hooks.trigger :site, :post_render, self, payload
     end
 
+    # Executes inline Ruby frontmatter if
+    # +ENV+["BRIDGETOWN_RUBY_IN_FRONTMATTER"] equals "true"
+    #
+    # @example
+    #   calculation: !ruby/string:Rb |
+    #     [2 * 4, 5 + 2].min
+    # @return [void]
+    # @see https://www.bridgetownrb.com/docs/front-matter#ruby-front-matter
     def execute_inline_ruby_for_layouts!
       return unless config.should_execute_inline_ruby?
 
@@ -26,6 +33,10 @@ module Bridgetown
       end
     end
 
+    # Renders all documents
+    # @param payload [Hash] A hash of site data.
+    # @return [void]
+    # @see Bridgetown::Site::Content#site_payload
     def render_docs(payload)
       collections.each_value do |collection|
         collection.docs.each do |document|
@@ -34,12 +45,21 @@ module Bridgetown
       end
     end
 
+    # Renders all pages
+    # @param payload [Hash] A hash of site data.
+    # @return [void]
+    # @see Bridgetown::Site::Content#site_payload
     def render_pages(payload)
       pages.each do |page|
         render_regenerated(page, payload)
       end
     end
 
+    # Regenerates a site using {Bridgetown::Renderer}
+    # @param document [Post] The document to regenerate.
+    # @param payload [Hash] A hash of site data.
+    # @return [void]
+    # @see Bridgetown::Renderer
     def render_regenerated(document, payload)
       return unless regenerator.regenerate?(document)
 

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

@@ -4,14 +4,14 @@ module Bridgetown
   module Site::Writable
     # Remove orphaned files and empty directories in destination.
     #
-    # Returns nothing.
+    # @return [void]
     def cleanup
       @cleaner.cleanup!
     end
 
     # Write static files, pages, and posts.
     #
-    # Returns nothing.
+    # @return [void]
     def write
       each_site_file do |item|
         item.write(dest) if regenerator.regenerate?(item)
@@ -20,6 +20,20 @@ module Bridgetown
       Bridgetown::Hooks.trigger :site, :post_write, self
     end
 
+    # Yields the pages from {#pages}, {#static_files}, and {#docs_to_write}.
+    #
+    # @yieldparam item [Document, Page, StaticFile] Yields a
+    # {#Bridgetown::Page}, {#Bridgetown::StaticFile}, or
+    # {#Bridgetown::Document} object.
+    #
+    # @return [void]
+    #
+    # @see #pages
+    # @see #static_files
+    # @see #docs_to_write
+    # @see Page
+    # @see StaticFile
+    # @see Document
     def each_site_file
       %w(pages static_files docs_to_write).each do |type|
         send(type).each do |item|

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Validatable
+    # FIXME: there should be ONE TRUE METHOD to read the YAML frontmatter
+    # in the entire project. Both this and the equivalent Document method
+    # should be extracted and generalized.
+    #
+    # Read the YAML frontmatter.
+    #
+    # base - The String path to the dir containing the file.
+    # name - The String filename of the file.
+    # opts - optional parameter to File.read, default at site configs
+    #
+    # Returns nothing.
+    # rubocop:disable Metrics/AbcSize
+    def read_yaml(base, name, opts = {})
+      filename = File.join(base, name)
+
+      begin
+        self.content = File.read(@path || site.in_source_dir(base, name),
+                                 **Utils.merged_file_read_opts(site, opts))
+        if content =~ Document::YAML_FRONT_MATTER_REGEXP
+          self.content = $POSTMATCH
+          self.data = SafeYAML.load(Regexp.last_match(1))&.with_indifferent_access
+        end
+      rescue Psych::SyntaxError => e
+        Bridgetown.logger.warn "YAML Exception reading #{filename}: #{e.message}"
+        raise e if site.config["strict_front_matter"]
+      rescue StandardError => e
+        Bridgetown.logger.warn "Error reading file #{filename}: #{e.message}"
+        raise e if site.config["strict_front_matter"]
+      end
+
+      self.data ||= ActiveSupport::HashWithIndifferentAccess.new
+
+      validate_data! filename
+      validate_permalink! filename
+
+      self.data
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    # FIXME: why doesn't Document validate data too?
+    def validate_data!(filename)
+      unless self.data.is_a?(Hash)
+        raise Errors::InvalidYAMLFrontMatterError,
+              "Invalid YAML front matter in #{filename}"
+      end
+    end
+
+    # FIXME: Layouts don't have permalinks...d'oh
+    def validate_permalink!(filename)
+      if self.data["permalink"]&.to_s&.empty?
+        raise Errors::InvalidPermalinkError, "Invalid permalink in #{filename}"
+      end
+    end
+  end
+end

data/lib/bridgetown-core/configuration.rb

@@ -19,6 +19,7 @@ module Bridgetown
       "data_dir"             => "_data",
       "components_dir"       => "_components",
       "includes_dir"         => "_includes",
+      "partials_dir"         => "_partials",
       "collections"          => {},
 
       # Handling Reading

data/lib/bridgetown-core/converter.rb

@@ -2,6 +2,20 @@
 
 module Bridgetown
   class Converter < Plugin
+    class << self
+      attr_accessor :extname_list
+
+      # Converters can provide one or more extensions they accept. Examples:
+      #
+      # * `input :erb`
+      # * `input %i(xls xlsx)`
+      def input(extnames)
+        extnames = Array(extnames)
+        self.extname_list ||= []
+        self.extname_list += extnames.map { |e| ".#{e.to_s.downcase}" }
+      end
+    end
+
     # Public: Get or set the highlighter prefix. When an argument is specified,
     # the prefix will be set. If no argument is specified, the current prefix
     # will be returned.
@@ -37,6 +51,26 @@ module Bridgetown
       @config = config
     end
 
+    # Does the given extension match this converter's list of acceptable extensions?
+    #
+    # @param [String] ext
+    #   The file's extension (including the dot)
+    #
+    # @return [Boolean] Whether the extension matches one in the list
+    def matches(ext)
+      (self.class.extname_list || []).include?(ext.downcase)
+    end
+
+    # You can override this in Converter subclasses as needed. Default is ".html"
+    #
+    # @param [String] ext
+    #   The extension of the original file
+    #
+    # @return [String] The output file extension (including the dot)
+    def output_ext(_ext)
+      ".html"
+    end
+
     # Get the highlighter prefix.
     #
     # Returns the String prefix.

data/lib/bridgetown-core/converters/erb_templates.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "tilt/erubi"
+require "erubi/capture_end"
+
+module Bridgetown
+  class ERBView < RubyTemplateView
+    def h(input)
+      Erubi.h(input)
+    end
+
+    def partial(partial_name, options = {})
+      options.merge!(options[:locals]) if options[:locals]
+
+      partial_segments = partial_name.split("/")
+      partial_segments.last.sub!(%r!^!, "_")
+      partial_name = partial_segments.join("/")
+
+      Tilt::ErubiTemplate.new(
+        site.in_source_dir(site.config[:partials_dir], "#{partial_name}.erb"),
+        outvar: "@_erbout",
+        engine_class: Erubi::CaptureEndEngine
+      ).render(self, options)
+    end
+
+    def markdownify
+      previous_buffer_state = @_erbout
+      @_erbout = +""
+      result = yield
+      @_erbout = previous_buffer_state
+
+      content = Bridgetown::Utils.reindent_for_markdown(result)
+      converter = site.find_converter_instance(Bridgetown::Converters::Markdown)
+      md_output = converter.convert(content).strip
+      @_erbout << md_output
+    end
+
+    def capture
+      previous_buffer_state = @_erbout
+      @_erbout = +""
+      result = yield
+      @_erbout = previous_buffer_state
+
+      result
+    end
+  end
+
+  module Converters
+    class ERBTemplates < Converter
+      input :erb
+
+      # Logic to do the ERB content conversion.
+      #
+      # @param content [String] Content of the file (without front matter).
+      # @params convertible [Bridgetown::Page, Bridgetown::Document, Bridgetown::Layout]
+      #   The instantiated object which is processing the file.
+      #
+      # @return [String] The converted content.
+      def convert(content, convertible)
+        erb_view = Bridgetown::ERBView.new(convertible)
+
+        erb_renderer = Tilt::ErubiTemplate.new(
+          convertible.relative_path,
+          outvar: "@_erbout",
+          engine_class: Erubi::CaptureEndEngine
+        ) { content }
+
+        if convertible.is_a?(Bridgetown::Layout)
+          erb_renderer.render(erb_view) do
+            convertible.current_document_output
+          end
+        else
+          erb_renderer.render(erb_view)
+        end
+      end
+    end
+  end
+end

data/lib/bridgetown-core/converters/markdown.rb

@@ -8,6 +8,12 @@ module Bridgetown
       highlighter_prefix "\n"
       highlighter_suffix "\n"
 
+      def initialize(config = {})
+        super
+
+        self.class.input @config["markdown_ext"].split(",")
+      end
+
       def setup
         return if @setup ||= false
 
@@ -51,25 +57,6 @@ module Bridgetown
         self.class.constants - [:KramdownParser, :PRIORITIES]
       end
 
-      # Does the given extension match this converter's list of acceptable extensions?
-      # Takes one argument: the file's extension (including the dot).
-      #
-      # ext - The String extension to check.
-      #
-      # Returns true if it matches, false otherwise.
-      def matches(ext)
-        extname_list.include?(ext.downcase)
-      end
-
-      # Public: The extension to be given to the output file (including the dot).
-      #
-      # ext - The String extension or original file.
-      #
-      # Returns The String output file extension.
-      def output_ext(_ext)
-        ".html"
-      end
-
       # Logic to do the content conversion.
       #
       # content - String content of file (without front matter).
@@ -82,10 +69,6 @@ module Bridgetown
         end
       end
 
-      def extname_list
-        @extname_list ||= @config["markdown_ext"].split(",").map! { |e| ".#{e.downcase}" }
-      end
-
       private
 
       def custom_processor

data/lib/bridgetown-core/converters/smartypants.rb

@@ -30,16 +30,6 @@ module Bridgetown
         @config[:input] = :SmartyPants
       end
 
-      # Does the given extension match this converter's list of acceptable extensions?
-      # Takes one argument: the file's extension (including the dot).
-      #
-      # ext - The String extension to check.
-      #
-      # Returns true if it matches, false otherwise.
-      def matches(_ext)
-        false
-      end
-
       # Public: The extension to be given to the output file (including the dot).
       #
       # ext - The String extension or original file.