diff --git a/doc/default/markdown.md b/doc/default/markdown.md
index 7801e590f7..c4866c8206 100644
--- a/doc/default/markdown.md
+++ b/doc/default/markdown.md
@@ -9,7 +9,7 @@ Generates markdown formatting with Lorem Ipsum text
 Faker::Markdown.headers #=> "##### Autem"
 
 # Emphasis - generates random emphasis formatting on a random word in two sentences
-Faker::Markdown.emphasis #=> "Incidunt atque quis repellat id impedit.  Quas numquam quod incidunt dicta non. Blanditiis delectus laudantium atque reiciendis qui."
+Faker::Markdown.emphasis #=> "_Incidunt atque quis repellat id impedit.  Quas numquam quod incidunt dicta non. Blanditiis delectus laudantium atque reiciendis qui._"
 
 # Ordered List - generates an ordered list of items between 1 and 10 randomly
 Faker::Markdown.ordered_list #=> "1. Qui reiciendis non consequatur atque.\n2. Quo doloremque veritatis tempora aut.\n3. Aspernatur.\n4. Ea ab.\n5. Qui.\n6. Sit pariatur nemo eveniet.\n7. Molestiae aut.\n8. Nihil molestias iure placeat.\n9. Dolore autem quisquam."
diff --git a/lib/faker/default/markdown.rb b/lib/faker/default/markdown.rb
index 2ed35dcd9f..40bd15ddf4 100644
--- a/lib/faker/default/markdown.rb
+++ b/lib/faker/default/markdown.rb
@@ -3,10 +3,28 @@
 module Faker
   class Markdown < Base
     class << self
+      ##
+      # Produces a random header format.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.headers #=> "##### Autem"
+      #
+      # @faker.version 1.8.0
       def headers
         "#{fetch('markdown.headers')} #{Lorem.word.capitalize}"
       end
 
+      ##
+      # Produces a random emphasis formatting on a random word in two sentences.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.emphasis #=> "_Incidunt atque quis repellat id impedit.  Quas numquam quod incidunt dicta non. Blanditiis delectus laudantium atque reiciendis qui._"
+      #
+      # @faker.version 1.8.0
       def emphasis
         paragraph = Faker::Lorem.paragraph(sentence_count: 3)
         words = paragraph.split(' ')
@@ -16,6 +34,15 @@ def emphasis
         words.join(' ')
       end
 
+      ##
+      # Produces a random ordered list of items between 1 and 10 randomly.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.ordered_list #=> "1. Qui reiciendis non consequatur atque.\n2. Quo doloremque veritatis tempora aut.\n3. Aspernatur.\n4. Ea ab.\n5. Qui.\n6. Sit pariatur nemo eveniet.\n7. Molestiae aut.\n8. Nihil molestias iure placeat.\n9. Dolore autem quisquam."
+      #
+      # @faker.version 1.8.0
       def ordered_list
         number = rand(1..10)
 
@@ -26,6 +53,15 @@ def ordered_list
         result.join('')
       end
 
+      ##
+      # Produces a random unordered list of items between 1 and 10 randomly.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.unordered_list #=> "* Voluptatum aliquid tempora molestiae facilis non sed.\n* Nostrum omnis iste impedit voluptatum dolor.\n* Esse quidem et facere."
+      #
+      # @faker.version 1.8.0
       def unordered_list
         number = rand(1..10)
 
@@ -36,14 +72,41 @@ def unordered_list
         result.join('')
       end
 
+      ##
+      # Produces a random inline code snippet between two sentences.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.inline_code #=> "Aut eos quis suscipit. `Dignissimos voluptatem expedita qui.` Quo doloremque veritatis tempora aut."
+      #
+      # @faker.version 1.8.0
       def inline_code
         "`#{Faker::Lorem.sentence(word_count: 1)}`"
       end
 
+      ##
+      # Produces a random code block formatted in Ruby.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.block_code #=> "```ruby\nEos quasi qui.\n```"
+      #
+      # @faker.version 1.8.0
       def block_code
         "```ruby\n#{Lorem.sentence(word_count: 1)}\n```"
       end
 
+      ##
+      # Produces a random 3x4 table with a row of headings, a row of hyphens and two rows of data
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.table #=> "ad | similique | voluptatem\n---- | ---- | ----\ncorrupti | est | rerum\nmolestiae | quidem | et"
+      #
+      # @faker.version 1.8.0
       def table
         table = []
         3.times do
@@ -53,12 +116,38 @@ def table
         table.join("\n")
       end
 
+      ##
+      # Produces a random method from the methods above or the methods listed in the arguments.
+      #
+      # @param methods [Symbol] Specify which methods to use.
+      # @return [String, Array<String>]
+      #
+      # @example
+      #   Faker::Markdown.random #=> returns output from a single method outlined above
+      #   Faker::Markdown.random("table") #=> returns output from any single method outlined above except for "table"
+      #   Faker::Markdown.random("ordered_list", "unordered_list") #=> returns output from any single method outlined above except for either ordered_list and unordered_list
+      #
+      # @faker.version 1.8.0
       def random(*args)
         method_list = available_methods
         args&.each { |ex| method_list.delete_if { |meth| meth == ex.to_sym } }
         send(method_list[rand(0..method_list.length - 1)])
       end
 
+      ##
+      # Produces a simulated blog-esque text-heavy block in markdown
+      #
+      # Keyword arguments: sentences, repeat
+      # @param sentences [Integer] Specifies how many sentences make a text block.
+      # @param repeat [Integer] Specifies how many times the text block repeats.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.sandwich #=> returns newline separated content of 1 header, 1 default lorem paragraph, and 1 random markdown element
+      #   Faker::Markdown.sandwich(sentences: 5) #=> returns newline separated content of 1 header, 1 5-sentence lorem paragraph, and 1 random markdown element
+      #   Faker::Markdown.sandwich(sentences: 6, repeat: 3) #=> returns newline separated content of 1 header, and then 3 sections consisting of, here, 1 6-sentence lorem paragraph and 1 random markdown element. The random markdown element is chosen at random in each iteration of the paragraph-markdown pairing.
+      #
+      # @faker.version 1.8.0
       def sandwich(legacy_sentences = NOT_GIVEN, legacy_repeat = NOT_GIVEN, sentences: 3, repeat: 1)
         warn_for_deprecated_arguments do |keywords|
           keywords << :sentences if legacy_sentences != NOT_GIVEN