def rearrange_docs!
      docs_table   = {}
      custom_order = {}

      # pre-sort to normalize default array across platforms and then proceed to create a Hash
      # from that sorted array.
      docs.sort.each do |doc|
        docs_table[doc.relative_path] = doc
      end

      metadata["order"].each do |entry|
        custom_order[File.join(relative_directory, entry)] = nil
      end

      result = Jekyll::Utils.deep_merge_hashes(custom_order, docs_table).values
      result.compact!
      self.docs = result
    end
def rearrange_docs!
      docs_table   = {}
      custom_order = {}

      # pre-sort to normalize default array across platforms and then proceed to create a Hash
      # from that sorted array.
      docs.sort.each do |doc|
        docs_table[doc.relative_path] = doc
      end

      metadata["order"].each do |entry|
        custom_order[File.join(relative_directory, entry)] = nil
      end

      result = Jekyll::Utils.deep_merge_hashes(custom_order, docs_table).values
      result.compact!
      self.docs = result
    end
Rearrange documents within the `docs` array as listed in the `metadata["order"]` array.

 Involves converting the two arrays into hashes based on relative_paths as keys first, then
 merging them to remove duplicates and finally retrieving the Document instances from the
 merged array.