From c06aebda619bf82548a908b58cc2d3af1f741f0c Mon Sep 17 00:00:00 2001
From: Michael Tiemann <github@michaeltiemann.net>
Date: Fri, 22 Dec 2023 11:23:22 +0100
Subject: [PATCH] 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 |  8 ++++++++
 stdlib/Markdown/src/Markdown.jl   | 12 ++++++++++++
 2 files changed, 20 insertions(+)

diff --git a/stdlib/Markdown/docs/src/index.md b/stdlib/Markdown/docs/src/index.md
index 44f2f2dbfd6881..47ec8cc793b4c3 100644
--- a/stdlib/Markdown/docs/src/index.md
+++ b/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
+```
diff --git a/stdlib/Markdown/src/Markdown.jl b/stdlib/Markdown/src/Markdown.jl
index 781fcbdafddc84..50dcec199031df 100644
--- a/stdlib/Markdown/src/Markdown.jl
+++ b/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