diff --git a/stdlib/Markdown/docs/src/index.md b/stdlib/Markdown/docs/src/index.md
index 47ec8cc793b4c..3c1f9ffb349c9 100644
--- a/stdlib/Markdown/docs/src/index.md
+++ b/stdlib/Markdown/docs/src/index.md
@@ -403,6 +403,10 @@ custom flavour of Markdown can be used, but this should generally be unnecessary
 
 Markdown strings can be constructed using the string literal syntax `md"..."`.
 
+## [API reference](@id stdlib-markdown-api)
+
 ```@docs
+Markdown.MD
 Markdown.@md_str
+Markdown.@doc_str
 ```
diff --git a/stdlib/Markdown/src/Markdown.jl b/stdlib/Markdown/src/Markdown.jl
index 01dedc44e28b4..913294ea5d73b 100644
--- a/stdlib/Markdown/src/Markdown.jl
+++ b/stdlib/Markdown/src/Markdown.jl
@@ -1,7 +1,11 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
 """
+    Markdown
+
 Tools for working with the Markdown file format. Mainly for documentation.
+The `Markdown` module provides the (internal) `MD` struct (type?) as well as the string 
+literals `md"..."` and `doc"..."`.
 """
 module Markdown
 
@@ -63,6 +67,12 @@ function doc_str(md, source::LineNumberNode, mod::Module)
 end
 doc_str(md::AbstractString, source::LineNumberNode, mod::Module) = doc_str(parse(md), source, mod)
 
+"""
+    macro doc_str(s)
+
+Parse the given string as Markdown text, add line and module information and return a 
+corresponding `Markdown.MD` object.
+"""
 macro doc_str(s::AbstractString, t...)
     docexpr(__source__, __module__, s, t...)
 end
diff --git a/stdlib/Markdown/src/parse/parse.jl b/stdlib/Markdown/src/parse/parse.jl
index 452d90d1176e1..82e7ba8d5a01f 100644
--- a/stdlib/Markdown/src/parse/parse.jl
+++ b/stdlib/Markdown/src/parse/parse.jl
@@ -1,5 +1,11 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
+"""
+    MD
+
+`MD` represents a Markdown document. However, `MD` objects should only be constructed using 
+the exported macros `@md_str` and `@doc_str`.
+"""
 mutable struct MD
     content::Vector{Any}
     meta::Dict{Symbol, Any}