diff --git a/.yardopts b/.yardopts
index d68057917..8adb9fd6b 100644
--- a/.yardopts
+++ b/.yardopts
@@ -1,4 +1,7 @@
 bridgetown-core/lib/**/*.rb
 bridgetown-builder/lib/**/*.rb
+bridgetown-foundation/lib/**/*.rb
 bridgetown-paginate/lib/**/*.rb
+bridgetown-routes/lib/**/*.rb
 -m markdown
+-p yard/templates
\ No newline at end of file
diff --git a/bridgetown-builder/lib/bridgetown-builder/dsl/generators.rb b/bridgetown-builder/lib/bridgetown-builder/dsl/generators.rb
index 28c4d7a3d..56570b427 100644
--- a/bridgetown-builder/lib/bridgetown-builder/dsl/generators.rb
+++ b/bridgetown-builder/lib/bridgetown-builder/dsl/generators.rb
@@ -4,6 +4,10 @@ module Bridgetown
   module Builders
     module DSL
       module Generators
+        # Set up a new generator based on the block or method provided which will run alongside
+        # other generators during the build process
+        #
+        # @param method_name [Symbol] use a Builder method rather than a block to run
         def generator(method_name = nil, &block)
           block = method(method_name) if method_name.is_a?(Symbol)
           local_name = name # pull the name method into a local variable
diff --git a/bridgetown-builder/lib/bridgetown-builder/dsl/helpers.rb b/bridgetown-builder/lib/bridgetown-builder/dsl/helpers.rb
index ca4f8974c..c213a705a 100644
--- a/bridgetown-builder/lib/bridgetown-builder/dsl/helpers.rb
+++ b/bridgetown-builder/lib/bridgetown-builder/dsl/helpers.rb
@@ -5,9 +5,15 @@ module Builders
     module DSL
       module Helpers
         def helpers
-          @helpers # could be nil
+          @helpers # could be nil. gets set once a helper method is actually called
         end
 
+        # Define a helper for use in view templates, alongside built-in helpers, using either a
+        # builder method or a block
+        #
+        # @param helper_name [Symbol] name of the helper
+        # @param method_name [Symbol] name of a Builder method to use, if block isn't provided
+        #   and the method is named different from the helper
         def helper(helper_name, method_name = nil, &block)
           m = Module.new
 
diff --git a/bridgetown-builder/lib/bridgetown-builder/dsl/hooks.rb b/bridgetown-builder/lib/bridgetown-builder/dsl/hooks.rb
index f21a2cb10..e1567f6bd 100644
--- a/bridgetown-builder/lib/bridgetown-builder/dsl/hooks.rb
+++ b/bridgetown-builder/lib/bridgetown-builder/dsl/hooks.rb
@@ -4,6 +4,13 @@ module Bridgetown
   module Builders
     module DSL
       module Hooks
+        # Define a hook to run at some point during the build process
+        #
+        # @param owner [Symbol] name of the owner (`:site`, `:resource`, etc.)
+        # @param event [Symbol] name of the event (`:pre_read`, `:post_render`, etc.)
+        # @param method_name [Symbol] name of a Builder method to use, if block isn't provided
+        # @param priority [Integer, Symbol] either `:low`, `:normal`, or `:high`, or an integer.
+        #   Default is normal (20)
         def hook(
           owner,
           event,
@@ -17,9 +24,13 @@ def hook(
           functions << { name:, hook: [owner, event, priority, hook_block] }
         end
 
+        # Define a site post_read hook and add data returned by the block to the site data/signals
         def add_data(data_key)
           hook(:site, :post_read) do
-            site.data[data_key] = yield
+            yield.tap do |value|
+              site.data[data_key] = value
+              site.signals[data_key] = value
+            end
           end
         end
       end
diff --git a/bridgetown-core/lib/bridgetown-core/cache.rb b/bridgetown-core/lib/bridgetown-core/cache.rb
index ab26f2676..028d3dc1f 100644
--- a/bridgetown-core/lib/bridgetown-core/cache.rb
+++ b/bridgetown-core/lib/bridgetown-core/cache.rb
@@ -33,8 +33,6 @@ def clear
 
       # Compare the current config to the cached config
       # If they are different, clear all caches
-      #
-      # Returns nothing.
       def clear_if_config_changed(config)
         config = config.inspect
         cache = Bridgetown::Cache.new "Bridgetown::Cache"
@@ -49,8 +47,6 @@ def clear_if_config_changed(config)
       private
 
       # Delete all cached items from all caches
-      #
-      # Returns nothing.
       def delete_cache_files
         FileUtils.rm_rf(@cache_dir) if disk_cache_enabled
       end
@@ -60,9 +56,7 @@ def delete_cache_files
 
     # Get an existing named cache, or create a new one if none exists
     #
-    # name - name of the cache
-    #
-    # Returns nothing.
+    # @param name [String] name of the cache
     def initialize(name)
       @cache = Bridgetown::Cache.base_cache[name] ||= {}
       @name = name.gsub(%r![^\w\s-]!, "-")
@@ -77,7 +71,7 @@ def clear
     # Retrieve a cached item
     # Raises if key does not exist in cache
     #
-    # Returns cached value
+    # @return [Object] cached value
     def [](key)
       return @cache[key] if @cache.key?(key)
 
@@ -88,8 +82,6 @@ def [](key)
     end
 
     # Add an item to cache
-    #
-    # Returns nothing.
     def []=(key, value)
       @cache[key] = value
       return unless disk_cache_enabled?
@@ -112,8 +104,6 @@ def getset(key)
     end
 
     # Remove one particular item from the cache
-    #
-    # Returns nothing.
     def delete(key)
       @cache.delete(key)
       File.delete(path_to(hash(key))) if disk_cache_enabled?
@@ -121,7 +111,7 @@ def delete(key)
 
     # Check if `key` already exists in this cache
     #
-    # Returns true if key exists in the cache, false otherwise
+    # @return [Boolean] true if key exists in the cache, false otherwise
     def key?(key)
       # First, check if item is already cached in memory
       return true if @cache.key?(key)
@@ -153,14 +143,11 @@ def hash(key)
     end
 
     # Remove all this caches items from disk
-    #
-    # Returns nothing.
     def delete_cache_files
       FileUtils.rm_rf(path_to) if disk_cache_enabled?
     end
 
     # Load `path` from disk and return the result.
-    # This MUST NEVER be called in Safe Mode
     # rubocop:disable Security/MarshalLoad
     def load(path)
       raise unless disk_cache_enabled?
@@ -173,9 +160,6 @@ def load(path)
     # rubocop:enable Security/MarshalLoad
 
     # Given a path and a value, save value to disk at path.
-    # This should NEVER be called in Safe Mode
-    #
-    # Returns nothing.
     def dump(path, value)
       return unless disk_cache_enabled?
 
diff --git a/bridgetown-core/lib/bridgetown-core/cleaner.rb b/bridgetown-core/lib/bridgetown-core/cleaner.rb
index c0933965e..7c3a2552a 100644
--- a/bridgetown-core/lib/bridgetown-core/cleaner.rb
+++ b/bridgetown-core/lib/bridgetown-core/cleaner.rb
@@ -17,9 +17,9 @@ def cleanup!
 
     private
 
-    # Private: The list of files and directories to be deleted during cleanup process
+    # The list of files and directories to be deleted during cleanup process
     #
-    # Returns an Array of the file and directory paths
+    # @return [Array<String>] file and directory paths
     def obsolete_files
       out = (existing_files - new_files - new_dirs + replaced_files).to_a
       Bridgetown::Hooks.trigger :clean, :on_obsolete, out
@@ -27,10 +27,9 @@ def obsolete_files
       out
     end
 
-    # Private: The list of existing files, apart from those included in
-    # keep_files and hidden files.
+    # The list of existing files, apart from those included in keep_files and hidden files
     #
-    # Returns a Set with the file paths
+    # @return [Set<String>] file paths
     def existing_files
       files = Set.new
       regex = keep_file_regex
@@ -45,9 +44,9 @@ def existing_files
       files
     end
 
-    # Private: The list of files to be created when site is built.
+    # The list of files to be created when site is built.
     #
-    # Returns a Set with the file paths
+    # @return [Set<String>] file paths
     def new_files
       @new_files ||= Set.new.tap do |files|
         site.each_site_file do |item|
@@ -60,17 +59,17 @@ def new_files
       end
     end
 
-    # Private: The list of directories to be created when site is built.
+    # The list of directories to be created when site is built.
     # These are the parent directories of the files in #new_files.
     #
-    # Returns a Set with the directory paths
+    # @return [Set<String>] directory paths
     def new_dirs
       @new_dirs ||= new_files.flat_map { |file| parent_dirs(file) }.to_set
     end
 
-    # Private: The list of parent directories of a given file
+    # The list of parent directories of a given file
     #
-    # Returns an Array with the directory paths
+    # @return [Array<String>] directory paths
     def parent_dirs(file)
       parent_dir = File.dirname(file)
       if parent_dir == site.dest
@@ -80,29 +79,28 @@ def parent_dirs(file)
       end
     end
 
-    # Private: The list of existing files that will be replaced by a directory
-    # during build
+    # The list of existing files that will be replaced by a directory during build
     #
-    # Returns a Set with the file paths
+    # @return [Set<String>] file paths
     def replaced_files
       new_dirs.select { |dir| File.file?(dir) }.to_set
     end
 
-    # Private: The list of directories that need to be kept because they are
+    # The list of directories that need to be kept because they are
     # parent directories of files specified in keep_files
     #
-    # Returns a Set with the directory paths
+    # @return [Set<String>] directory paths
     def keep_dirs
       site.config.keep_files.flat_map { |file| parent_dirs(site.in_dest_dir(file)) }.to_set
     end
 
-    # Private: Creates a regular expression from the config's keep_files array
+    # Creates a regular expression from the config's keep_files array
     #
-    # Examples
+    # @example
     #   ['.git','.svn'] with site.dest "/myblog/_site" creates
     #   the following regex: /\A\/myblog\/_site\/(\.git|\/.svn)/
     #
-    # Returns the regular expression
+    # @return [Regexp]
     def keep_file_regex
       %r!\A#{Regexp.quote(site.dest)}/(#{Regexp.union(site.config.keep_files).source})!
     end
diff --git a/bridgetown-core/lib/bridgetown-core/commands/build.rb b/bridgetown-core/lib/bridgetown-core/commands/build.rb
index ae4d2047a..bf1ca2b27 100644
--- a/bridgetown-core/lib/bridgetown-core/commands/build.rb
+++ b/bridgetown-core/lib/bridgetown-core/commands/build.rb
@@ -79,11 +79,9 @@ def build
 
       protected
 
-      # Build your Bridgetown site.
+      # Build your Bridgetown site
       #
-      # options - A Hash of options passed to the command or loaded from config
-      #
-      # Returns nothing.
+      # @param options [Bridgetown::Configuration] options loaded from config and/or CLI
       def build_site(config_options)
         t = Time.now
         display_folder_paths(config_options)
@@ -97,20 +95,16 @@ def build_site(config_options)
                                           "#{(Time.now - t).ceil(2)} seconds."
       end
 
-      # Watch for file changes and rebuild the site.
-      #
-      # options - A Hash of options passed to the command or loaded from config
+      # Watch for file changes and rebuild the site
       #
-      # Returns nothing.
+      # @param options [Bridgetown::Configuration] options loaded from config and/or CLI
       def watch_site(config_options)
         Bridgetown::Watcher.watch(@site, config_options)
       end
 
       # Display the source and destination folder paths
       #
-      # options - A Hash of options passed to the command
-      #
-      # Returns nothing.
+      # @param options [Bridgetown::Configuration] options loaded from config and/or CLI
       def display_folder_paths(config_options)
         source = File.expand_path(config_options["source"])
         destination = File.expand_path(config_options["destination"])
diff --git a/bridgetown-core/lib/bridgetown-core/component.rb b/bridgetown-core/lib/bridgetown-core/component.rb
index a7ef15365..2b7b5b942 100644
--- a/bridgetown-core/lib/bridgetown-core/component.rb
+++ b/bridgetown-core/lib/bridgetown-core/component.rb
@@ -94,7 +94,7 @@ def supported_template_extensions
 
       def path_for_errors
         File.basename(component_template_path)
-      rescue RuntimeError
+      rescue RuntimeError, TypeError
         source_location
       end
     end
diff --git a/bridgetown-core/lib/bridgetown-core/concerns/layout_placeable.rb b/bridgetown-core/lib/bridgetown-core/concerns/layout_placeable.rb
index f6db771d1..dc6b91834 100644
--- a/bridgetown-core/lib/bridgetown-core/concerns/layout_placeable.rb
+++ b/bridgetown-core/lib/bridgetown-core/concerns/layout_placeable.rb
@@ -4,7 +4,7 @@ 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
+    # @return [Boolean] false if the document is an asset file or if the front matter
     #   specifies `layout: none`
     def place_in_layout?
       no_layout?.!
diff --git a/bridgetown-core/lib/bridgetown-core/concerns/publishable.rb b/bridgetown-core/lib/bridgetown-core/concerns/publishable.rb
index 36ab1f1bb..64cfe03a1 100644
--- a/bridgetown-core/lib/bridgetown-core/concerns/publishable.rb
+++ b/bridgetown-core/lib/bridgetown-core/concerns/publishable.rb
@@ -3,6 +3,8 @@
 module Bridgetown
   module Publishable
     # Whether the resource is published or not, as indicated in YAML front-matter
+    #
+    # @return [Boolean]
     def published?
       !(data.key?("published") && data["published"] == false)
     end
diff --git a/bridgetown-core/lib/bridgetown-core/concerns/site/content.rb b/bridgetown-core/lib/bridgetown-core/concerns/site/content.rb
index 480c861dd..e9ffa144c 100644
--- a/bridgetown-core/lib/bridgetown-core/concerns/site/content.rb
+++ b/bridgetown-core/lib/bridgetown-core/concerns/site/content.rb
@@ -27,6 +27,7 @@ def categories
     end
 
     # Returns the contents of the site metadata file or a blank hash
+    #
     # @return [HashWithDotAccess::Hash] Returns a hash of site metadata
     def metadata
       signals["site_metadata"] ||= HashWithDotAccess::Hash.new
@@ -49,7 +50,6 @@ def site_payload
     #
     # @return [HashWithDotAccess::Hash{String, Symbol => Collection}] A Hash
     #   containing a collection name-to-instance pairs.
-    #
     # @return [HashWithDotAccess::Hash] Returns a blank hash if no items found
     def collections
       @collections ||= collection_names.each_with_object(
@@ -60,6 +60,7 @@ def collections
     end
 
     # An array of collection names.
+    #
     # @return [Array<String>] an array of collection names from the configuration,
     #   or an empty array if the `config["collections"]` key is not set.
     def collection_names
@@ -84,6 +85,7 @@ def taxonomy_types
     end
 
     # Get all loaded resources.
+    #
     # @return [Array<Bridgetown::Resource::Base>] an array of resources
     def resources
       collections.each_with_object(Set.new) do |(_, collection), set|
@@ -112,6 +114,7 @@ def add_generated_page(generated_page)
     end
 
     # Loads and memoizes the parsed frontend bundler manifest file (if available)
+    #
     # @return [Hash]
     def frontend_manifest
       @frontend_manifest ||= begin
diff --git a/bridgetown-core/lib/bridgetown-core/concerns/site/extensible.rb b/bridgetown-core/lib/bridgetown-core/concerns/site/extensible.rb
index 6516eb0d7..cf639353f 100644
--- a/bridgetown-core/lib/bridgetown-core/concerns/site/extensible.rb
+++ b/bridgetown-core/lib/bridgetown-core/concerns/site/extensible.rb
@@ -4,6 +4,7 @@ class Bridgetown::Site
   module Extensible
     # Load necessary libraries, plugins, converters, and generators.
     # This is only ever run once for the lifecycle of the site object.
+    #
     # @see Converter
     # @see Generator
     # @see PluginManager
@@ -16,6 +17,7 @@ def setup
     end
 
     # Run all Generators.
+    #
     # @see Generator
     # @return [void]
     def generate
@@ -34,6 +36,7 @@ def generate
     end
 
     # Get the implementation for the given Converter class.
+    #
     # @param klass [Class] The Class of the Converter to fetch.
     # @return [Converter] Returns the {Converter}
     #   instance implementing the given `Converter` class.
@@ -46,7 +49,8 @@ def find_converter_instance(klass)
 
     # Create an array of instances of the subclasses of the class
     #   passed in as argument.
-    # @param klass [Class] - class which is the parent of the subclasses.
+    #
+    # @param klass [Class] class which is the parent of the subclasses.
     # @return [Array<Converter, Generator>] Returns an array of instances of
     #   subclasses of `klass`.
     def instantiate_subclasses(klass)
@@ -56,6 +60,7 @@ def instantiate_subclasses(klass)
     end
 
     # Shorthand for registering a site hook via {Bridgetown::Hooks}
+    #
     # @param event [Symbol] name of the event (`:pre_read`, `:post_render`, etc.)
     # @yield the block will be called when the event is triggered
     # @yieldparam site the site which triggered the event hook
diff --git a/bridgetown-core/lib/bridgetown-core/concerns/site/localizable.rb b/bridgetown-core/lib/bridgetown-core/concerns/site/localizable.rb
index f42cd24a8..e95a62b5c 100644
--- a/bridgetown-core/lib/bridgetown-core/concerns/site/localizable.rb
+++ b/bridgetown-core/lib/bridgetown-core/concerns/site/localizable.rb
@@ -3,6 +3,7 @@
 class Bridgetown::Site
   module Localizable
     # Returns the current and/or default configured locale
+    #
     # @return String
     def locale
       @locale ||= begin
@@ -16,6 +17,7 @@ def locale
     end
 
     # Sets the current locale for the site
+    #
     # @param new_locale [String] for example: "en" for English, "es" for Spanish
     def locale=(new_locale)
       I18n.locale = @locale = new_locale.to_sym
diff --git a/bridgetown-core/lib/bridgetown-core/concerns/site/processable.rb b/bridgetown-core/lib/bridgetown-core/concerns/site/processable.rb
index 14a120476..0119d9980 100644
--- a/bridgetown-core/lib/bridgetown-core/concerns/site/processable.rb
+++ b/bridgetown-core/lib/bridgetown-core/concerns/site/processable.rb
@@ -3,6 +3,7 @@
 class Bridgetown::Site
   module Processable
     # Reset, Read, Generate, Render, Cleanup, Process, and Write this Site to output.
+    #
     # @return [void]
     # @see #reset
     # @see #read
@@ -67,6 +68,7 @@ def refresh_layouts_and_data
     end
 
     # Read data from disk and load it into internal memory.
+    #
     # @return [void]
     def read
       Bridgetown::Hooks.trigger :site, :pre_read, self
diff --git a/bridgetown-core/lib/bridgetown-core/concerns/site/renderable.rb b/bridgetown-core/lib/bridgetown-core/concerns/site/renderable.rb
index d6b67e61c..4bf4c8f2e 100644
--- a/bridgetown-core/lib/bridgetown-core/concerns/site/renderable.rb
+++ b/bridgetown-core/lib/bridgetown-core/concerns/site/renderable.rb
@@ -3,6 +3,7 @@
 class Bridgetown::Site
   module Renderable
     # Render all pages & documents so they're ready to be written out to disk.
+    #
     # @return [void]
     # @see Page
     # @see Document
@@ -97,6 +98,7 @@ def warn_on_missing_layout(convertible, layout, layout_name)
     end
 
     # Renders all resources
+    #
     # @return [void]
     def render_resources
       collections.each_value do |collection|
@@ -109,6 +111,7 @@ def render_resources
     end
 
     # Renders a content item while ensuring site locale is set if the data is available.
+    #
     # @param item [Bridgetown::Resource::Base] The item to render
     # @yield Runs the block in between locale setting and resetting
     # @return [void]
diff --git a/bridgetown-core/lib/bridgetown-core/configuration.rb b/bridgetown-core/lib/bridgetown-core/configuration.rb
index 9f25d96e9..26533dd7f 100644
--- a/bridgetown-core/lib/bridgetown-core/configuration.rb
+++ b/bridgetown-core/lib/bridgetown-core/configuration.rb
@@ -111,12 +111,11 @@ def initialize(*)
     attr_writer :source_manifests, :roda_initializers
 
     class << self
-      # Static: Produce a Configuration ready for use in a Site.
+      # Produce a Configuration ready for use in a Site.
       # It takes the input, fills in the defaults where values do not exist.
       #
-      # user_config - a Hash or Configuration of overrides.
-      #
-      # Returns a Configuration filled with defaults.
+      # @param user_config [Hash, Configuration]
+      # @return [Configuration] filled with defaults
       def from(user_config, starting_defaults = DEFAULTS)
         Utils.deep_merge_hashes(starting_defaults.deep_dup, Configuration.new(user_config))
           .merge_environment_specific_options!
@@ -177,16 +176,14 @@ def get_config_value_with_override(config_key, override)
     # Directory of the top-level root where config files are located
     #
     # @param override [Hash] options hash which will override value if key is present
-    #
     # @return [String] path to the Bridgetown root directory
     def root_dir(override = {})
       get_config_value_with_override("root_dir", override)
     end
 
-    # Public: Directory of the Bridgetown source folder
+    # Directory of the Bridgetown source folder
     #
     # @param override [Hash] options hash which will override value if key is present
-    #
     # @return [String]  path to the Bridgetown source directory
     def source(override = {})
       get_config_value_with_override("source", override)
@@ -208,11 +205,10 @@ def safe_load_file(filename)
       raise "Unable to parse `#{File.basename(filename)}'. #{e.message}"
     end
 
-    # Public: Generate list of configuration files from the override
+    # Generate list of configuration files from the override
     #
-    # override - the command-line options hash
-    #
-    # Returns an Array of config files
+    # @param override [Hash] the command-line options hash
+    # @return [Array<string>] config files
     def config_files(override)
       # Adjust verbosity quickly
       Bridgetown.logger.adjust_verbosity(
@@ -232,9 +228,8 @@ def config_files(override)
     # Read in a list of configuration files and merge with this hash
     #
     # @param files [Array<String>]
-    #
     # @return [Hash] configuration with the defaults overridden by the values in the
-    # configuration files
+    #   configuration files
     def read_config_files(files)
       config = self
 
@@ -257,7 +252,6 @@ def read_config_files(files)
     # Read configuration and return merged Hash
     #
     # @param file [String] the path to the YAML file to be read in
-    #
     # @return [Hash]
     def read_config_file(file)
       default_config_file = file == "bridgetown.config.yml"
diff --git a/bridgetown-core/lib/bridgetown-core/converter.rb b/bridgetown-core/lib/bridgetown-core/converter.rb
index d5c07b44f..055f72fb7 100644
--- a/bridgetown-core/lib/bridgetown-core/converter.rb
+++ b/bridgetown-core/lib/bridgetown-core/converter.rb
@@ -40,7 +40,6 @@ def initialize(config = {})
     #
     # @param content [String] content of file (without front matter).
     # @param convertible [Bridgetown::Layout, Bridgetown::Resource::Base]
-    #
     # @return [String] the converted content.
     def convert(content, convertible = nil) # rubocop:disable Lint/UnusedMethodArgument
       content
@@ -48,10 +47,8 @@ def convert(content, convertible = nil) # rubocop:disable Lint/UnusedMethodArgum
 
     # Does the given extension match this converter's list of acceptable extensions?
     #
-    # @param [String] ext
-    #   The file's extension (including the dot)
+    # @param ext [String] the file's extension (including the dot)
     # @param convertible [Bridgetown::Layout, Bridgetown::Resource::Base]
-    #
     # @return [Boolean] Whether the extension matches one in the list
     def matches(ext, _convertible = nil)
       (self.class.extname_list || []).include?(ext.downcase)
@@ -67,9 +64,7 @@ def determine_template_engine(convertible)
     # You can override this in Converter subclasses as needed. Default is ".html", unless the
     # converter is a template engine and the input file doesn't match the normal template extension
     #
-    # @param [String] ext
-    #   The extension of the original file
-    #
+    # @param ext [String] the extension of the original file
     # @return [String] The output file extension (including the dot)
     def output_ext(ext)
       if self.class.template_engine
diff --git a/bridgetown-core/lib/bridgetown-core/converters/identity.rb b/bridgetown-core/lib/bridgetown-core/converters/identity.rb
index 261edba01..b737eaeb4 100644
--- a/bridgetown-core/lib/bridgetown-core/converters/identity.rb
+++ b/bridgetown-core/lib/bridgetown-core/converters/identity.rb
@@ -9,21 +9,13 @@ class Identity < Converter
 
       support_slots
 
-      # Public: 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 (not relevant here)
-      #
-      # Returns true since it always matches.
+      # @return [Boolean] true since it always matches.
       def matches(*)
         true
       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.
+      # @param ext [String] the extension of the original file
+      # @return [String] The output file extension (including the dot)
       def output_ext(ext)
         ext
       end
diff --git a/bridgetown-core/lib/bridgetown-core/converters/liquid_templates.rb b/bridgetown-core/lib/bridgetown-core/converters/liquid_templates.rb
index b073821ff..edb5f10c6 100644
--- a/bridgetown-core/lib/bridgetown-core/converters/liquid_templates.rb
+++ b/bridgetown-core/lib/bridgetown-core/converters/liquid_templates.rb
@@ -22,7 +22,6 @@ class << self
       # @param convertible [
       #   Bridgetown::GeneratedPage, Bridgetown::Resource::Base, Bridgetown::Layout]
       #   The instantiated object which is processing the file.
-      #
       # @return [String] The converted content.
       def convert(content, convertible)
         self.class.cached_partials ||= {}
@@ -55,17 +54,16 @@ def convert(content, convertible)
       # rubocop: enable Metrics/MethodLength
       # rubocop: enable Metrics/AbcSize
 
-      # Fetches the payload used in Liquid rendering.
-      # Falls back to site.site_payload if no payload is set.
+      # Fetches the payload used in Liquid rendering, aka `site.site_payload`
       #
-      # Returns a Bridgetown::Drops::UnifiedPayloadDrop
+      # @return [Bridgetown::Drops::UnifiedPayloadDrop]
       def payload
         @payload ||= site.site_payload
       end
 
       # Set page content to payload and assign paginator if document has one.
       #
-      # Returns nothing
+      # @return [void]
       def configure_payload(content = nil)
         payload["page"] = document.to_liquid
         payload["paginator"] = document.respond_to?(:paginator) ? document.paginator.to_liquid : nil
diff --git a/bridgetown-core/lib/bridgetown-core/converters/markdown.rb b/bridgetown-core/lib/bridgetown-core/converters/markdown.rb
index 6a64f3520..ea906d093 100644
--- a/bridgetown-core/lib/bridgetown-core/converters/markdown.rb
+++ b/bridgetown-core/lib/bridgetown-core/converters/markdown.rb
@@ -43,26 +43,25 @@ def get_processor
       end
       # rubocop:enable Naming/AccessorMethodName
 
-      # Public: Provides you with a list of processors comprised of the ones we support internally
+      # Provides you with a list of processors comprised of the ones we support internally
       # and the ones that you have provided to us
       #
-      # Returns an array of symbols.
+      # @return [Array<Symbol>]
       def valid_processors
         [:kramdown] + third_party_processors
       end
 
-      # Public: A list of processors that you provide via plugins.
+      # A list of processors that you provide via plugins
       #
-      # Returns an array of symbols
+      # @return [Array<Symbol>]
       def third_party_processors
         self.class.constants - [:KramdownParser, :PRIORITIES]
       end
 
-      # Logic to do the content conversion.
+      # Logic to do the content conversion
       #
-      # content - String content of file (without front matter).
-      #
-      # Returns a String of the converted content.
+      # @param content [String] content of file (without front matter)
+      # @return [String] converted content
       def convert(content, convertible = nil)
         setup
         if @cache
@@ -85,13 +84,11 @@ def custom_processor
         self.class.const_get(converter_name).new(@config) if custom_class_allowed?(converter_name)
       end
 
-      # Private: Determine whether a class name is an allowed custom
-      #   markdown class name.
-      #
-      # parser_name - the name of the parser class
+      # Determine whether a class name is an allowed custom markdown class name.
       #
-      # Returns true if the parser name contains only alphanumeric characters and is defined
-      # within Bridgetown::Converters::Markdown
+      # @param parser_name [Symbol] name of the parser class
+      # @return [Boolean] true if the parser name contains only alphanumeric characters and is
+      #   defined within `Bridgetown::Converters::Markdown`
       def custom_class_allowed?(parser_name)
         parser_name !~ %r![^A-Za-z0-9_]! && self.class.constants.include?(parser_name.to_sym)
       end
diff --git a/bridgetown-core/lib/bridgetown-core/converters/markdown/kramdown_parser.rb b/bridgetown-core/lib/bridgetown-core/converters/markdown/kramdown_parser.rb
index 8335df272..e14bee99c 100644
--- a/bridgetown-core/lib/bridgetown-core/converters/markdown/kramdown_parser.rb
+++ b/bridgetown-core/lib/bridgetown-core/converters/markdown/kramdown_parser.rb
@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Kramdown
-  # A Kramdown::Document subclass meant to optimize memory usage from initializing
+  # A `Kramdown::Document`` subclass meant to optimize memory usage from initializing
   # a kramdown document for parsing.
   #
   # The optimization is by using the same options Hash (and its derivatives) for
diff --git a/bridgetown-core/lib/bridgetown-core/converters/serbea_templates.rb b/bridgetown-core/lib/bridgetown-core/converters/serbea_templates.rb
index c3ca3736a..ec72f5e60 100644
--- a/bridgetown-core/lib/bridgetown-core/converters/serbea_templates.rb
+++ b/bridgetown-core/lib/bridgetown-core/converters/serbea_templates.rb
@@ -25,14 +25,13 @@ class SerbeaTemplates < Converter
       template_engine :serbea
       input :serb
 
-      # Logic to do the Serbea content conversion.
+      # Logic to do the Serbea content conversion
       #
-      # @param content [String] Content of the file (without front matter).
+      # @param content [String] Content of the file (without front matter)
       # @param convertible [
       #   Bridgetown::GeneratedPage, Bridgetown::Resource::Base, Bridgetown::Layout]
       #   The instantiated object which is processing the file.
-      #
-      # @return [String] The converted content.
+      # @return [String] The converted content
       def convert(content, convertible)
         serb_view = Bridgetown::SerbeaView.new(convertible)
         serb_renderer = Tilt::SerbeaTemplate.new(
diff --git a/bridgetown-core/lib/bridgetown-core/drops/drop.rb b/bridgetown-core/lib/bridgetown-core/drops/drop.rb
index 5c1d73adb..0993a4e73 100644
--- a/bridgetown-core/lib/bridgetown-core/drops/drop.rb
+++ b/bridgetown-core/lib/bridgetown-core/drops/drop.rb
@@ -11,23 +11,22 @@ class Drop < Liquid::Drop
       # Mutability determines whether or not pre-defined fields may be
       # overwritten.
       #
-      # is_mutable - Boolean set mutability of the class (default: nil)
+      # @param is_mutable [Boolean] set mutability of the class
       #
-      # Returns the mutability of the class
+      # @return [Boolean] the mutability of the class
       def self.mutable(is_mutable = nil)
         @is_mutable = is_mutable || false
       end
 
+      # @return [Boolean] the mutability of the class
       def self.mutable?
         @is_mutable
       end
 
       # Create a new Drop
       #
-      # obj - the Bridgetown Site, Collection, or Resource required by the
+      # @param obj [Object] the Bridgetown Site, Collection, or Resource required by the
       # drop.
-      #
-      # Returns nothing
       def initialize(obj) # rubocop:disable Lint/MissingSuper
         @obj = obj
       end
@@ -37,9 +36,8 @@ def initialize(obj) # rubocop:disable Lint/MissingSuper
       # and finally check the underlying hash (e.g. document front matter)
       # if all the previous places didn't match.
       #
-      # key - the string key whose value to fetch
-      #
-      # Returns the value for the given key, or nil if none exists
+      # @param key [String] key whose value to fetch
+      # @return [Object, nil] returns the value for the given key if present
       def [](key)
         if self.class.mutable? && mutations.key?(key)
           mutations[key]
@@ -58,12 +56,11 @@ def [](key)
       # key to the value in the underlying hash (e.g. document front
       # matter)
       #
-      # key - the String key whose value to set
-      # val - the Object to set the key's value to
-      #
-      # Returns the value the key was set to unless the Drop is not mutable
-      # and the key matches a method in which case it raises a
-      # DropMutationException.
+      # @param key [String] key whose value to set
+      # @param val [Object] what to set the key's value to
+      # @return [Object] the value the key was set to unless the Drop is not mutable
+      #   and the key matches a method in which case it raises a
+      #   DropMutationException.
       def []=(key, val)
         setter = "#{key}="
         if respond_to?(setter)
@@ -82,7 +79,7 @@ def []=(key, val)
       # Generates a list of strings which correspond to content getter
       # methods.
       #
-      # Returns an Array of strings which represent method-specific keys.
+      # @return [Array<String>] method-specific keys
       def content_methods
         @content_methods ||= (
           self.class.instance_methods \
@@ -95,9 +92,8 @@ def content_methods
 
       # Check if key exists in Drop
       #
-      # key - the string key whose value to fetch
-      #
-      # Returns true if the given key is present
+      # @param key [String] key whose value to set
+      # @return [Boolean] true if the given key is present
       def key?(key)
         return false if key.nil?
         return true if self.class.mutable? && mutations.key?(key)
@@ -121,7 +117,7 @@ def keys
       # value. It includes Drop methods, mutations, and the underlying object's
       # data. See the documentation for Drop#keys for more.
       #
-      # Returns a Hash with all the keys and values resolved.
+      # @return [Hash<String, Object>] all the keys and values resolved
       def to_h
         keys.each_with_object({}) do |(key, _), result|
           result[key] = self[key]
@@ -132,33 +128,27 @@ def to_h
       # Inspect the drop's keys and values through a JSON representation
       # of its keys and values.
       #
-      # Returns a pretty generation of the hash representation of the Drop.
+      # @return [String]
       def inspect
         JSON.pretty_generate to_h
       end
 
-      # Generate a Hash for use in generating JSON.
-      # This is useful if fields need to be cleared before the JSON can generate.
+      # Generate a Hash for use in generating JSON. Essentially an alias for `to_h`
       #
-      # Returns a Hash ready for JSON generation.
+      # @return [Hash<String, Object>] all the keys and values resolved
       def hash_for_json(*)
         to_h
       end
 
-      # Generate a JSON representation of the Drop.
+      # Generate a JSON representation of the Drop
       #
-      # state - the JSON::State object which determines the state of current processing.
-      #
-      # Returns a JSON representation of the Drop in a String.
+      # @param state [JSON::State] object which determines the state of current processing
+      # @return [String] JSON representation of the Drop
       def to_json(state = nil)
         JSON.generate(hash_for_json(state), state)
       end
 
-      # Collects all the keys and passes each to the block in turn.
-      #
-      # block - a block which accepts one argument, the key
-      #
-      # Returns nothing.
+      # Collects all the keys and passes each to the block in turn
       def each_key(&)
         keys.each(&)
       end
@@ -194,10 +184,10 @@ def merge!(other)
         end
       end
 
-      # Imitate Hash.fetch method in Drop
+      # Imitate `Hash.fetch` method in Drop
       #
-      # Returns value if key is present in Drop, otherwise returns default value
-      # KeyError is raised if key is not present and no default value given
+      # @return [Object] value if key is present in Drop, otherwise returns default value.
+      #   KeyError is raised if key is not present and no default value given
       def fetch(key, default = nil, &block)
         return self[key] if key?(key)
         raise KeyError, %(key not found: "#{key}") if default.nil? && block.nil?
diff --git a/bridgetown-core/lib/bridgetown-core/drops/resource_drop.rb b/bridgetown-core/lib/bridgetown-core/drops/resource_drop.rb
index 7de7e9c0c..645c41fad 100644
--- a/bridgetown-core/lib/bridgetown-core/drops/resource_drop.rb
+++ b/bridgetown-core/lib/bridgetown-core/drops/resource_drop.rb
@@ -58,9 +58,8 @@ def previous_resource
       # Generate a Hash for use in generating JSON.
       # This is useful if fields need to be cleared before the JSON can generate.
       #
-      # state - the JSON::State object which determines the state of current processing.
-      #
-      # Returns a Hash ready for JSON generation.
+      # @param state [JSON::State] object which determines the state of current processing
+      # @return [Hash<String, Object>] all the keys and values resolved
       def hash_for_json(state = nil)
         to_h.tap do |hash|
           # use collection label in the hash
@@ -76,19 +75,13 @@ def hash_for_json(state = nil)
       # Generate a Hash which breaks the recursive chain.
       # Certain fields which are normally available are omitted.
       #
-      # Returns a Hash with only non-recursive fields present.
+      # @return [Hash<String, Object>] only non-recursive fields present
       def collapse_document(doc)
         doc.keys.each_with_object({}) do |(key, _), result|
           result[key] = doc[key] unless NESTED_OBJECT_FIELD_BLACKLIST.include?(key)
         end
       end
 
-      # Generates a list of keys with user content as their values.
-      # This gathers up the Drop methods and keys of the mutations and
-      # underlying data hashes and performs a set union to ensure a list
-      # of unique keys for the Drop.
-      #
-      # @return [Array<String>]
       def keys
         keys_to_remove = %w[next_resource previous_resource]
         (content_methods |
@@ -98,8 +91,6 @@ def keys
         end
       end
 
-      # Inspect the drop's keys and values through a JSON representation
-      # of its keys and values.
       def inspect
         JSON.pretty_generate hash_for_json
       end
diff --git a/bridgetown-core/lib/bridgetown-core/filters.rb b/bridgetown-core/lib/bridgetown-core/filters.rb
index b5b983fa1..1c03388be 100644
--- a/bridgetown-core/lib/bridgetown-core/filters.rb
+++ b/bridgetown-core/lib/bridgetown-core/filters.rb
@@ -11,33 +11,30 @@ module Filters
     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 @@ def slugify(input, mode = nil)
 
     # 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 @@ def titleize(input)
     # 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 @@ def xml_escape(input)
     # 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 @@ def obfuscate_link(input, prefix = "mailto")
 
     # 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 @@ def reading_time(input, round_to = 0)
     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 @@ def array_to_sentence_string(array, connector = "and")
       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,11 +185,10 @@ def where(input, property, value) # rubocop:disable Metrics/CyclomaticComplexity
 
     # 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)
 
@@ -222,9 +205,8 @@ def where_exp(input, variable, expression)
 
     # 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 @@ def to_integer(input)
 
     # 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?
 
diff --git a/bridgetown-core/lib/bridgetown-core/filters/condition_helpers.rb b/bridgetown-core/lib/bridgetown-core/filters/condition_helpers.rb
index fa4cb2481..a901f54de 100644
--- a/bridgetown-core/lib/bridgetown-core/filters/condition_helpers.rb
+++ b/bridgetown-core/lib/bridgetown-core/filters/condition_helpers.rb
@@ -2,10 +2,9 @@
 
 module Bridgetown
   module Filters
+    # The following set of code was *adapted* from `Liquid::If`
+    # ref: https://git.io/vp6K6
     module ConditionHelpers
-      # -----------   The following set of code was *adapted* from Liquid::If
-      # -----------   ref: https://git.io/vp6K6
-
       # Parse a string to a Liquid Condition
       def parse_condition(exp)
         parser    = Liquid::Parser.new(exp)
@@ -19,9 +18,8 @@ def parse_condition(exp)
       # the parsed expression based on whether the expression consists of binary operations with
       # Liquid operators `and` or `or`
       #
-      #  - parser: an instance of Liquid::Parser
-      #
-      # Returns an instance of Liquid::Condition
+      # @param parser [Liquid::Parser]
+      # @return [Liquid::Condition]
       def parse_binary_comparison(parser)
         condition = parse_comparison(parser)
         first_condition = condition
@@ -37,9 +35,8 @@ def parse_binary_comparison(parser)
       # on whether the parsed expression involves a "comparison" operator
       # (e.g. <, ==, >, !=, etc)
       #
-      #  - parser: an instance of Liquid::Parser
-      #
-      # Returns an instance of Liquid::Condition
+      # @param parser [Liquid::Parser]
+      # @return [Liquid::Condition]
       def parse_comparison(parser)
         left_operand = Liquid::Expression.parse(parser.expression)
         operator     = parser.consume?(:comparison)
diff --git a/bridgetown-core/lib/bridgetown-core/filters/date_filters.rb b/bridgetown-core/lib/bridgetown-core/filters/date_filters.rb
index 50104b3b4..1735915b4 100644
--- a/bridgetown-core/lib/bridgetown-core/filters/date_filters.rb
+++ b/bridgetown-core/lib/bridgetown-core/filters/date_filters.rb
@@ -8,12 +8,11 @@ module DateFilters
       # (e.g. "27th Jan 2011") and US ("e.g. Jan 27th, 2011") formats.
       # UK format is the default.
       #
-      # date - the Time to format.
-      # type - if "ordinal" the returned String will be in ordinal format
-      # style - if "US" the returned String will be in US format.
-      #         Otherwise it will be in UK format.
-      #
-      # Returns the formatting String.
+      # @param date [Time]
+      # @param type [String] if "ordinal" the returned String will be in ordinal format
+      # @param style [String] if "US" the returned String will be in US format.
+      #   Otherwise it will be in UK format.
+      # @return [String]
       def date_to_string(date, type = nil, style = nil)
         stringify_date(date, "%b", type, style)
       end
@@ -23,42 +22,29 @@ def date_to_string(date, type = nil, style = nil)
       # (e.g. "27th January 2011") and US ("e.g. January 27th, 2011") formats.
       # UK format is the default.
       #
-      # date - the Time to format.
-      # type - if "ordinal" the returned String will be in ordinal format
-      # style - if "US" the returned String will be in US format.
-      #         Otherwise it will be in UK format.
-      #
-      # Returns the formatted String.
+      # @param date [Time]
+      # @param type [String] if "ordinal" the returned String will be in ordinal format
+      # @param style [String] if "US" the returned String will be in US format.
+      #   Otherwise it will be in UK format.
+      # @return [String]
       def date_to_long_string(date, type = nil, style = nil)
         stringify_date(date, "%B", type, style)
       end
 
-      # Format a date for use in XML.
-      #
-      # date - The Time to format.
-      #
-      # Examples
-      #
-      #   date_to_xmlschema(Time.now)
-      #   # => "2011-04-24T20:34:46+08:00"
+      # Format a date for use in XML, e.g. "2011-04-24T20:34:46+08:00"
       #
-      # Returns the formatted String.
+      # @param date [Time]
+      # @return [String]
       def date_to_xmlschema(date)
         return date if date.to_s.empty?
 
         time(date).xmlschema
       end
 
-      # Format a date according to RFC-822
+      # Format a date according to RFC-822, e.g. "Sun, 24 Apr 2011 12:34:46 +0000"
       #
-      # date - The Time to format.
-      #
-      # Examples
-      #
-      #   date_to_rfc822(Time.now)
-      #   # => "Sun, 24 Apr 2011 12:34:46 +0000"
-      #
-      # Returns the formatted String.
+      # @param date [Time]
+      # @return [String]
       def date_to_rfc822(date)
         return date if date.to_s.empty?
 
@@ -67,11 +53,12 @@ def date_to_rfc822(date)
 
       private
 
-      # month_type: Notations that evaluate to 'Month' via `Time#strftime` ("%b", "%B")
-      # type: nil (default) or "ordinal"
-      # style: nil (default) or "US"
-      #
-      # Returns a stringified date or the empty input.
+      # @param date [Time]
+      # @param month_type [String] notations that evaluate to 'Month' via `Time#strftime`
+      #   ("%b", "%B")
+      # @param type [String]
+      # @param style [String]
+      # @return [String]
       def stringify_date(date, month_type, type = nil, style = nil)
         return date if date.to_s.empty?
 
diff --git a/bridgetown-core/lib/bridgetown-core/filters/grouping_filters.rb b/bridgetown-core/lib/bridgetown-core/filters/grouping_filters.rb
index d1119992e..59ac4329f 100644
--- a/bridgetown-core/lib/bridgetown-core/filters/grouping_filters.rb
+++ b/bridgetown-core/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 @@ def group_by(input, property)
 
       # 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)
 
diff --git a/bridgetown-core/lib/bridgetown-core/front_matter/defaults.rb b/bridgetown-core/lib/bridgetown-core/front_matter/defaults.rb
index d9041ba99..ced13ceea 100644
--- a/bridgetown-core/lib/bridgetown-core/front_matter/defaults.rb
+++ b/bridgetown-core/lib/bridgetown-core/front_matter/defaults.rb
@@ -33,7 +33,6 @@ def ensure_time!(set)
       #
       # @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 @@ def merge_data_cascade_for_path(path, merged_data)
 
       # 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 @@ def strip_collections_dir(path)
       #
       # @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 @@ def applies_collection?(scope, collection)
 
       # 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 @@ def valid?(set)
 
       # 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?
diff --git a/bridgetown-core/lib/bridgetown-core/generated_page.rb b/bridgetown-core/lib/bridgetown-core/generated_page.rb
index b783a6c8b..bdd15e7cd 100644
--- a/bridgetown-core/lib/bridgetown-core/generated_page.rb
+++ b/bridgetown-core/lib/bridgetown-core/generated_page.rb
@@ -25,13 +25,13 @@ class GeneratedPage
       .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
diff --git a/bridgetown-core/lib/bridgetown-core/generators/prototype_generator.rb b/bridgetown-core/lib/bridgetown-core/generators/prototype_generator.rb
index f453c8791..99d632661 100644
--- a/bridgetown-core/lib/bridgetown-core/generators/prototype_generator.rb
+++ b/bridgetown-core/lib/bridgetown-core/generators/prototype_generator.rb
@@ -76,7 +76,6 @@ def ensure_pagination_enabled
     # 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 @@ def generate_new_page_from_prototype(prototype_page, search_term, term)
     # 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
diff --git a/bridgetown-core/lib/bridgetown-core/layout.rb b/bridgetown-core/lib/bridgetown-core/layout.rb
index a7da530b9..41ed99376 100644
--- a/bridgetown-core/lib/bridgetown-core/layout.rb
+++ b/bridgetown-core/lib/bridgetown-core/layout.rb
@@ -95,11 +95,10 @@ def to_s
       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
diff --git a/bridgetown-core/lib/bridgetown-core/liquid_extensions.rb b/bridgetown-core/lib/bridgetown-core/liquid_extensions.rb
index 9be87dd0f..f01cf248e 100644
--- a/bridgetown-core/lib/bridgetown-core/liquid_extensions.rb
+++ b/bridgetown-core/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
 
diff --git a/bridgetown-core/lib/bridgetown-core/log_adapter.rb b/bridgetown-core/lib/bridgetown-core/log_adapter.rb
index fae6094a0..c7b9154cb 100644
--- a/bridgetown-core/lib/bridgetown-core/log_adapter.rb
+++ b/bridgetown-core/lib/bridgetown-core/log_adapter.rb
@@ -11,23 +11,19 @@ class LogAdapter
       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 @@ def adjust_verbosity(options = {})
       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 @@ def message(topic, message = nil)
       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)
 
diff --git a/bridgetown-core/lib/bridgetown-core/rack/logger.rb b/bridgetown-core/lib/bridgetown-core/rack/logger.rb
index d5f7e2395..bde7f13cb 100644
--- a/bridgetown-core/lib/bridgetown-core/rack/logger.rb
+++ b/bridgetown-core/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
 
diff --git a/bridgetown-core/lib/bridgetown-core/static_file.rb b/bridgetown-core/lib/bridgetown-core/static_file.rb
index 0adc222c8..bc06dd0b3 100644
--- a/bridgetown-core/lib/bridgetown-core/static_file.rb
+++ b/bridgetown-core/lib/bridgetown-core/static_file.rb
@@ -48,11 +48,10 @@ def path
       @path ||= File.join(*[@base, @dir, @name].compact)
     end
 
-    # Obtain destination path.
+    # Obtain destination path
     #
-    # dest - The String path to the destination dir.
-    #
-    # Returns destination file path.
+    # @param dest [String] path to the destination dir
+    # @return [String]
     def destination(dest)
       dest = site.in_dest_dir(dest)
       dest_url = url
@@ -76,22 +75,21 @@ def modified_time
 
     alias_method :date, :modified_time
 
-    # Returns last modification time for this file.
+    # @return [Integer] last modification time for this file
     def mtime
       modified_time.to_i
     end
 
     # Is source path modified?
     #
-    # Returns true if modified since last write.
+    # @return [Boolean] true if modified since last write
     def modified?
       self.class.mtimes[path] != mtime
     end
 
     # Whether to write the file to the filesystem
     #
-    # Returns true unless the defaults for the destination path from
-    # bridgetown.config.yml contain `published: false`.
+    # @return [Boolean] true unless the defaults for the destination path contain `published: false`
     def write?
       publishable = defaults.fetch("published", true)
       return publishable unless @collection
@@ -99,11 +97,10 @@ def write?
       publishable && @collection.write?
     end
 
-    # Write the static file to the destination directory (if modified).
-    #
-    # dest - The String path to the destination dir.
+    # Write the static file to the destination directory (if modified)
     #
-    # Returns false if the file was not modified since last time (no-op).
+    # @param dest [String] path to the destination dir
+    # @return [Boolean] false if the file was not modified since last time (no-op)
     def write(dest)
       dest_path = destination(dest)
       return false if File.exist?(dest_path) && !modified?
@@ -152,12 +149,12 @@ def placeholders
     #
     # NOTE: `String#gsub!` removes all trailing periods (in comparison to `String#chomp!`)
     #
-    # Examples:
+    # @example
     #   When `relative_path` is "_methods/site/my-cool-avatar...png":
     #     cleaned_relative_path
     #     # => "/site/my-cool-avatar"
     #
-    # Returns the cleaned relative path of the static file.
+    # @return [String] cleaned relative path of the static file
     def cleaned_relative_path
       @cleaned_relative_path ||= begin
         cleaned = relative_path[0..-extname.length - 1]
@@ -169,7 +166,7 @@ def cleaned_relative_path
 
     # Applies a similar URL-building technique as resources that takes
     # the collection's URL template into account. The default URL template can
-    # be overriden in the collection's configuration in bridgetown.config.yml.
+    # be overriden in the collection's configuration
     def url
       @url ||= begin
         newly_processed = false
@@ -183,19 +180,17 @@ def url
       end
     end
 
-    # Returns the type of the collection if present, nil otherwise.
+    # @return [Symbol, nil] type of the collection if present
     def type
       @type ||= @collection&.label&.to_sym
     end
 
-    # Returns the front matter defaults defined for the file's URL and/or type
-    # as defined in bridgetown.config.yml.
+    # @return [Hash] front matter defaults defined for the file's URL and/or type
     def defaults
       @defaults ||= site.frontmatter_defaults.all url, type
     end
 
-    # Returns a debug string on inspecting the static file.
-    # Includes only the relative path of the object.
+    # @return [String] includes only the relative path of the object
     def inspect
       "#<#{self.class} @relative_path=#{relative_path.inspect}>"
     end
diff --git a/bridgetown-core/lib/bridgetown-core/tags/post_url.rb b/bridgetown-core/lib/bridgetown-core/tags/post_url.rb
index 65d4ff27c..e6ab658a9 100644
--- a/bridgetown-core/lib/bridgetown-core/tags/post_url.rb
+++ b/bridgetown-core/lib/bridgetown-core/tags/post_url.rb
@@ -31,24 +31,6 @@ def post_date
       def ==(other)
         other.relative_path.to_s.match(@name_regex)
       end
-
-      def deprecated_equality(other)
-        slug == post_slug(other) &&
-          post_date.year  == other.date.year &&
-          post_date.month == other.date.month &&
-          post_date.day   == other.date.day
-      end
-
-      private
-
-      # Construct the directory-aware post slug for a Bridgetown::Post
-      #
-      # other - the Bridgetown::Post
-      #
-      # Returns the post slug with the subdirectory (relative to _posts)
-      def post_slug(other)
-        other.data.slug
-      end
     end
 
     class PostUrl < Liquid::Tag
@@ -75,19 +57,7 @@ def render(context)
         site.collections.posts.resources.each do |document|
           return relative_url(document) if @post == document
 
-          # New matching method did not match, fall back to old method
-          # with deprecation warning if this matches
-          next unless @post.deprecated_equality document
-
-          Bridgetown::Deprecator.deprecation_message(
-            "A call to " \
-            "'{% post_url #{@post.name} %}' did not match " \
-            "a post using the new matching method of checking name " \
-            "(path-date-slug) equality. Please make sure that you " \
-            "change this tag to match the post's name exactly."
-          )
-
-          return relative_url(document)
+          next
         end
 
         raise Bridgetown::Errors::PostURLError, <<~MSG
diff --git a/bridgetown-core/lib/bridgetown-core/utils.rb b/bridgetown-core/lib/bridgetown-core/utils.rb
index d198379e8..b53d4438c 100644
--- a/bridgetown-core/lib/bridgetown-core/utils.rb
+++ b/bridgetown-core/lib/bridgetown-core/utils.rb
@@ -49,15 +49,12 @@ def deep_merge_hashes(master_hash, other_hash)
       deep_merge_hashes!(master_hash.dup, other_hash)
     end
 
-    # Merges a master hash with another hash, recursively.
+    # Merges a master hash with another hash, recursively. This code was lovingly stolen from
+    # some random gem: https://rubygems.org/gems/tartan Thanks to whoever made it.
     #
-    # master_hash - the "parent" hash whose values will be overridden
-    # other_hash  - the other hash whose values will be persisted after the merge
-    #
-    # This code was lovingly stolen from some random gem:
-    # http://gemjack.com/gems/tartan-0.1.1/classes/Hash.html
-    #
-    # Thanks to whoever made it.
+    # @param target [Hash] the "parent" hash whose values will be overridden
+    # @param overwrite [Hash] the other hash whose values will be persisted after the merge
+    # @return [Hash]
     def deep_merge_hashes!(target, overwrite)
       merge_values(target, overwrite)
       merge_default_proc(target, overwrite)
@@ -110,11 +107,9 @@ def value_from_plural_key(hsh, key)
 
     # Parse a date/time and throw an error if invalid
     #
-    # input - the date/time to parse
-    # msg - (optional) the error message to show the user
-    #
-    # Returns the parsed date if successful, throws a FatalException
-    # if not
+    # @param input [String] the date/time to parse
+    # @param msg [String] the error message to show the user
+    # @return [Time] the parsed date if successful, throws a FatalException if not
     def parse_date(input, msg = "Input could not be parsed.")
       Time.parse(input).localtime
     rescue ArgumentError
@@ -140,35 +135,30 @@ def has_rbfm_header?(file) # rubocop: disable Naming/PredicateName
       FrontMatter::Loaders::Ruby.header?(file)
     end
 
-    # Slugify a filename or title.
+    # Slugify a filename or title
     #
-    # string - the filename or title to slugify
-    # mode - how string is slugified
-    # cased - whether to replace all uppercase letters with their
-    # lowercase counterparts
+    # When mode is `none`, return the given string.
     #
-    # When mode is "none", return the given string.
-    #
-    # When mode is "raw", return the given string,
+    # When mode is `raw`, return the given string,
     # with every sequence of spaces characters replaced with a hyphen.
     #
-    # When mode is "default", "simple", or nil, non-alphabetic characters are
+    # When mode is `default`, `simple`, or `nil`, non-alphabetic characters are
     # replaced with a hyphen too.
     #
-    # When mode is "pretty", some non-alphabetic characters (._~!$&'()+,;=@)
+    # When mode is `pretty`, some non-alphabetic characters (`._~!$&'()+,;=@`)
     # are not replaced with hyphen.
     #
-    # When mode is "ascii", some everything else except ASCII characters
-    # a-z (lowercase), A-Z (uppercase) and 0-9 (numbers) are not replaced with hyphen.
+    # When mode is `ascii`, some everything else except ASCII characters
+    # `a-z` (lowercase), `A-Z` (uppercase) and `0-9` (numbers) are not replaced with hyphen.
     #
-    # When mode is "latin", the input string is first preprocessed so that
+    # When mode is `latin`, the input string is first preprocessed so that
     # any letters with accents are replaced with the plain letter. Afterwards,
-    # it follows the "default" mode of operation.
+    # it follows the `default` mode of operation.
     #
-    # If cased is true, all uppercase letters in the result string are
+    # If `cased` is `true`, all uppercase letters in the result string are
     # replaced with their lowercase counterparts.
     #
-    # Examples:
+    # @example
     #   slugify("The _config.yml file")
     #   # => "the-config-yml-file"
     #
@@ -184,7 +174,11 @@ def has_rbfm_header?(file) # rubocop: disable Naming/PredicateName
     #   slugify("The _config.yml file", "latin")
     #   # => "the-config-yml-file"
     #
-    # Returns the slugified string.
+    # @param string [String] filename or title to slugify
+    # @param mode [String] how string is slugified
+    # @param cased [Boolean] whether to replace all uppercase letters with their
+    #   lowercase counterparts
+    # @return [String] the slugified string.
     def slugify(string, mode: nil, cased: false)
       mode ||= "default"
       return nil if string.nil?
@@ -210,13 +204,13 @@ def slugify(string, mode: nil, cased: false)
     end
 
     # Work the same way as Dir.glob but seperating the input into two parts
-    # ('dir' + '/' + 'pattern') to make sure the first part('dir') does not act
+    # (`'dir' + '/' + 'pattern'`) to make sure the first part(`'dir'`) does not act
     # as a pattern.
     #
-    # For example, Dir.glob("path[/*") always returns an empty array,
-    # because the method fails to find the closing pattern to '[' which is ']'
+    # For example, `Dir.glob("path[/*")` always returns an empty array,
+    # because the method fails to find the closing pattern to `[` which is `]`
     #
-    # Examples:
+    # @example
     #   safe_glob("path[", "*")
     #   # => ["path[/file1", "path[/file2"]
     #
@@ -226,12 +220,13 @@ def slugify(string, mode: nil, cased: false)
     #   safe_glob("path", ["**", "*"])
     #   # => ["path[/file1", "path[/folder/file2"]
     #
-    # dir      - the dir where glob will be executed under
-    #           (the dir will be included to each result)
-    # patterns - the patterns (or the pattern) which will be applied under the dir
-    # flags    - the flags which will be applied to the pattern
-    #
-    # Returns matched pathes
+    # @param dir [String] the dir where glob will be executed under
+    #   (the dir will be included to each result)
+    # @param patterns [String, Array<String>] the patterns (or the pattern) which will be applied
+    #   under the dir
+    # @param flags [Integer] the flags which will be applied to the pattern,
+    #   a bitwise OR of the `File::FNM_XXX` constants
+    # @return [Array<String>] matched pathes
     def safe_glob(dir, patterns, flags = 0)
       return [] unless Dir.exist?(dir)
 
@@ -243,8 +238,8 @@ def safe_glob(dir, patterns, flags = 0)
       end
     end
 
-    # Returns merged option hash for File.read of self.site (if exists)
-    # and a given param
+    # @return [Hash] merged option hash for `File.read` of `site` (if exists)
+    #   and a given param
     def merged_file_read_opts(site, opts)
       merged = (site ? site.file_read_opts : {}).merge(opts)
       if merged[:encoding] && !merged[:encoding].start_with?("bom|")
@@ -256,8 +251,10 @@ def merged_file_read_opts(site, opts)
       merged
     end
 
-    # Returns a string that's been reindented so that Markdown's four+ spaces =
-    # code doesn't get triggered for nested Liquid components
+    # Provides a string that's been reindented so that Markdown's four+ spaces =
+    #   code doesn't get triggered for nested components
+    # @param input [String]
+    # @return [String]
     # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/PerceivedComplexity
     def reindent_for_markdown(input)
       lines = input.lines
diff --git a/bridgetown-core/lib/bridgetown-core/utils/require_gems.rb b/bridgetown-core/lib/bridgetown-core/utils/require_gems.rb
index 6f5905027..aaed27b04 100644
--- a/bridgetown-core/lib/bridgetown-core/utils/require_gems.rb
+++ b/bridgetown-core/lib/bridgetown-core/utils/require_gems.rb
@@ -4,13 +4,11 @@ module Bridgetown
   module Utils
     module RequireGems
       class << self
-        #
         # Require a gem or gems. If it's not present, show a very nice error
         # message that explains everything and is much more helpful than the
         # normal LoadError.
         #
-        # names - a string gem name or array of gem names
-        #
+        # @param names [String, Array<String>] gem name or array of gem names
         def require_with_graceful_fail(names)
           Array(names).each do |name|
             Bridgetown.logger.debug "Requiring:", name.to_s
diff --git a/bridgetown-core/lib/bridgetown-core/watcher.rb b/bridgetown-core/lib/bridgetown-core/watcher.rb
index 4f9438c1d..cabd28907 100644
--- a/bridgetown-core/lib/bridgetown-core/watcher.rb
+++ b/bridgetown-core/lib/bridgetown-core/watcher.rb
@@ -159,9 +159,8 @@ def to_exclude(options)
 
     # Paths to ignore for the watch option
     #
-    # options - A Hash of options passed to the command
-    #
-    # Returns a list of relative paths from source that should be ignored
+    # @param options [Bridgetown::Configuration] options loaded from config and/or CLI
+    # @return [Array<String>] list of relative paths from source that should be ignored
     def listen_ignore_paths(options)
       source = Pathname.new(options["source"]).expand_path
       paths  = to_exclude(options)
diff --git a/bridgetown-core/test/test_tags.rb b/bridgetown-core/test/test_tags.rb
index 8f8d169b8..fcf8e24bd 100644
--- a/bridgetown-core/test/test_tags.rb
+++ b/bridgetown-core/test/test_tags.rb
@@ -427,49 +427,15 @@ def highlight_block_with_opts(options_string)
   end
 
   context "simple page with nested post linking and path not used in `post_url`" do
-    setup do
-      content = <<~CONTENT
-        ---
-        title: Deprecated Post linking
-        ---
-
-        - 1 {% post_url 2008-11-21-nested %}
-      CONTENT
-      create_post(content,
-                  "permalink"   => "pretty",
-                  "source"      => source_dir,
-                  "destination" => dest_dir,
-                  "read_posts"  => true)
-    end
-
-    should "not cause an error" do
-      refute_match(%r!markdown-html-error!, @result)
-    end
-
-    should "have the url to the 'nested' post from 2008-11-21" do
-      assert_match %r!1\s/2008/11/21/nested/!, @result
-    end
-
-    should "throw a deprecation warning" do
-      deprecation_warning = "       Deprecation: A call to " \
-                            "'{% post_url 2008-11-21-nested %}' did not match a post using the new matching " \
-                            "method of checking name (path-date-slug) equality. Please make sure that you " \
-                            "change this tag to match the post's name exactly."
-      assert_includes Bridgetown.logger.messages, deprecation_warning
-    end
-  end
-
-  context "simple page with invalid post name linking" do
     should "cause an error" do
-      content = <<~CONTENT
-        ---
-        title: Invalid post name linking
-        ---
-
-        {% post_url abc2008-11-21-complex %}
-      CONTENT
-
       assert_raises Bridgetown::Errors::PostURLError do
+        content = <<~CONTENT
+          ---
+          title: Deprecated Post linking
+          ---
+
+          - 1 {% post_url 2008-11-21-nested %}
+        CONTENT
         create_post(content,
                     "permalink"   => "pretty",
                     "source"      => source_dir,
@@ -477,17 +443,19 @@ def highlight_block_with_opts(options_string)
                     "read_posts"  => true)
       end
     end
+  end
 
-    should "cause an error with a bad date" do
+  context "simple page with invalid post name linking" do
+    should "cause an error" do
       content = <<~CONTENT
         ---
         title: Invalid post name linking
         ---
 
-        {% post_url 2008-42-21-complex %}
+        {% post_url abc2008-11-21-complex %}
       CONTENT
 
-      assert_raises Bridgetown::Errors::InvalidDateError do
+      assert_raises Bridgetown::Errors::PostURLError do
         create_post(content,
                     "permalink"   => "pretty",
                     "source"      => source_dir,
diff --git a/yard/templates/default/fulldoc/html/css/common.css b/yard/templates/default/fulldoc/html/css/common.css
new file mode 100644
index 000000000..072fd0376
--- /dev/null
+++ b/yard/templates/default/fulldoc/html/css/common.css
@@ -0,0 +1,86 @@
+:root {
+  --color-darkest-green: #142e28;
+  --color-dark-green: #1d453c;
+  --color-medium-green: #335b56;
+  --color-light-green: #3a6d62;
+  --color-lighter-green: #c3d3cf;
+  --color-wintermint: #f1fffa;
+  --color-orange: #f47c3c;
+  --color-light-orange: #ffb088;
+  --color-lightest-orange: #f8f5f0;
+  --color-brick: #d64045;
+  --color-dark-brick: #923538;
+  --color-blackish: #131e1b;
+  --color-dark-gray: #2e2525;
+  --color-darkest-gray: #0b0b0b;
+  --color-medium-gray: #454545;
+  --color-light-gray: #b0b5b3;
+}
+
+body {
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
+}
+
+/* boy this sucks! */
+code, tt, pre.code, #filecontents pre.code, .docstring pre.code, .source_code pre, p.signature, h3.signature, p.signature tt, h3.signature tt, ul.summary, .tags ul .name {
+  font-family: ui-monospace,
+    SF Mono, Menlo, Monaco, 
+    "Cascadia Mono", "Segoe UI Mono", 
+    "Roboto Mono", 
+    "Oxygen Mono", 
+    "Ubuntu Mono", 
+    "Source Code Pro",
+    "Fira Mono", 
+    "Droid Sans Mono", 
+    "Consolas", "Courier New", monospace;
+}
+
+li.clicked > .item {
+  background-color: var(--color-medium-green);
+
+  #content & :is(a, a:visited) {
+    color: white;
+  }
+}
+
+a, a:visited, #content a, #content a:visited {
+  color: var(--color-brick);
+  font-weight: inherit;
+}
+
+#main #content a:hover {
+  background-color: color-mix(in srgb, var(--color-light-orange), 70% lightyellow);
+}
+
+#full_list_nav a:hover, #menu a:hover {
+  background-color: color-mix(in srgb, var(--color-light-orange), 70% lightyellow);
+  color: var(--color-brick);
+}
+
+p.signature, h3.signature, .summary_signature {
+  background-color: var(--color-lightest-orange);
+}
+
+#content .summary_signature:hover {
+  background-color: var(--color-orange);
+  color: white;
+
+  & :is(a, a:visited) {
+    color: inherit;
+
+    &:hover {
+      background-color: transparent !important;
+    }
+  }
+}
+
+#content .note.title {
+  background: var(--color-light-green);
+  border-color: var(--color-lighter-green);
+}
+
+.docstring p > code, .docstring p > tt, .tags p > code, .tags p > tt, *:not(pre) > code, 
+#filecontents pre.code, .docstring pre.code, .tags pre.example {
+  background-color: var(--color-lightest-orange);
+  color: var(--color-dark-brick);
+}