added doc string for @md_str string literal (#51168)

fixed tailing blank lines

added an example

added suggestion from reviewer stevengj

stdlib/Markdown/docs/src/index.md

@@ -398,3 +398,11 @@ complex features (such as references) without cluttering the basic syntax.
 
 In principle, the Markdown parser itself can also be arbitrarily extended by packages, or an entirely
 custom flavour of Markdown can be used, but this should generally be unnecessary.
+
+## [Markdown String Literals](@id stdlib-markdown-literals)
+
+Markdown strings can be constructed using the string literal syntax `md"..."`.
+
+```@docs
+Markdown.@md_str
+```

stdlib/Markdown/src/Markdown.jl

@@ -40,6 +40,18 @@ function docexpr(source::LineNumberNode, mod::Module, s, flavor = :julia)
     :($doc_str($(mdexpr(s, flavor)), $(QuoteNode(source)), $mod))
 end
 
+"""
+    macro md_str(s)
+
+Parse the given string as Markdown text and return a corresponding `Markdown.MD` object.
+
+# Example
+```jldoctest
+julia> Markdown.html(md"# Hello, world!")
+"<h1>Hello, world&#33;</h1>\\n"
+
+```
+"""
 macro md_str(s, t...)
     mdexpr(s, t...)
 end