From afa05d03187e4bc53b868777d6e199c993dc21f1 Mon Sep 17 00:00:00 2001
From: Michael Tiemann <github@michaeltiemann.net>
Date: Fri, 22 Dec 2023 11:23:22 +0100
Subject: [PATCH 01/14] added doc string for @md_str string literal (#51168)

---
 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 30f530d1c6263..9a4f81ac5e54d 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 781fcbdafddc8..01dedc44e28b4 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> html(md"# Hello, world!")
+"<h1>Hello, world&#33;</h1>\\n"
+
+```
+"""
 macro md_str(s, t...)
     mdexpr(s, t...)
 end

From b0ffdd2ad089b6d196a9d1ea2932e25a12ad39e7 Mon Sep 17 00:00:00 2001
From: Michael Tiemann <github@michaeltiemann.net>
Date: Thu, 4 Jan 2024 10:38:06 +0100
Subject: [PATCH 02/14] add docstrings to doc_str, MD and include in
 documentation

---
 stdlib/Markdown/docs/src/index.md  |  4 ++++
 stdlib/Markdown/src/Markdown.jl    | 10 ++++++++++
 stdlib/Markdown/src/parse/parse.jl |  6 ++++++
 3 files changed, 20 insertions(+)

diff --git a/stdlib/Markdown/docs/src/index.md b/stdlib/Markdown/docs/src/index.md
index 9a4f81ac5e54d..eba91482e88de 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}

From d0e5bd6b48243b092fd52effecd8109d9041b474 Mon Sep 17 00:00:00 2001
From: Michael Tiemann <github@michaeltiemann.net>
Date: Fri, 22 Dec 2023 11:23:22 +0100
Subject: [PATCH 03/14] added doc string for @md_str string literal (#51168)

---
 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 30f530d1c6263..9a4f81ac5e54d 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 781fcbdafddc8..01dedc44e28b4 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> html(md"# Hello, world!")
+"<h1>Hello, world&#33;</h1>\\n"
+
+```
+"""
 macro md_str(s, t...)
     mdexpr(s, t...)
 end

From 0b21b52990544404e771aa22411f861220942e3a Mon Sep 17 00:00:00 2001
From: Michael Tiemann <github@michaeltiemann.net>
Date: Thu, 4 Jan 2024 10:38:06 +0100
Subject: [PATCH 04/14] add docstrings to doc_str, MD and include in
 documentation

---
 stdlib/Markdown/docs/src/index.md  |  4 ++++
 stdlib/Markdown/src/Markdown.jl    | 10 ++++++++++
 stdlib/Markdown/src/parse/parse.jl |  6 ++++++
 3 files changed, 20 insertions(+)

diff --git a/stdlib/Markdown/docs/src/index.md b/stdlib/Markdown/docs/src/index.md
index 9a4f81ac5e54d..eba91482e88de 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}

From 83fc423b9346e70e686d249a47f946b4c259dfce Mon Sep 17 00:00:00 2001
From: Michael Tiemann <github@michaeltiemann.net>
Date: Fri, 5 Jan 2024 00:22:50 +0100
Subject: [PATCH 05/14] fix reviewer concerns

---
 stdlib/Markdown/src/Markdown.jl | 23 +++++++++++++++--------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/stdlib/Markdown/src/Markdown.jl b/stdlib/Markdown/src/Markdown.jl
index 913294ea5d73b..f5a3cac175568 100644
--- a/stdlib/Markdown/src/Markdown.jl
+++ b/stdlib/Markdown/src/Markdown.jl
@@ -4,7 +4,7 @@
     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 
+The `Markdown` module provides the (internal) `MD`(@ref) type as well as the string 
 literals `md"..."` and `doc"..."`.
 """
 module Markdown
@@ -45,14 +45,18 @@ function docexpr(source::LineNumberNode, mod::Module, s, flavor = :julia)
 end
 
 """
-    macro md_str(s)
+    @md_str -> MD
 
-Parse the given string as Markdown text and return a corresponding `Markdown.MD` object.
+Parse the given string as Markdown text and return a corresponding [`MD`](@ref) object.
 
-# Example
+# Examples
 ```jldoctest
-julia> html(md"# Hello, world!")
-"<h1>Hello, world&#33;</h1>\\n"
+julia> s = md"# Hello, world!"
+  Hello, world!
+  ≡≡≡≡≡≡≡≡≡≡≡≡≡
+
+julia> typeof(s)
+Markdown.MD
 
 ```
 """
@@ -68,10 +72,13 @@ end
 doc_str(md::AbstractString, source::LineNumberNode, mod::Module) = doc_str(parse(md), source, mod)
 
 """
-    macro doc_str(s)
+    @doc_str -> MD
 
 Parse the given string as Markdown text, add line and module information and return a 
-corresponding `Markdown.MD` object.
+corresponding [`MD`](@ref) object.
+
+`@doc_str`` can be used in conjunction with the [`Base.Docs`](@ref) module. Please also refer to
+the manual section on [documentation](@ref man-documentation) for more information.
 """
 macro doc_str(s::AbstractString, t...)
     docexpr(__source__, __module__, s, t...)

From 4c30e3c6b2fd6c516952fe1318c60cd46d4ac458 Mon Sep 17 00:00:00 2001
From: Michael Tiemann <github@michaeltiemann.net>
Date: Fri, 5 Jan 2024 00:25:08 +0100
Subject: [PATCH 06/14] fix superfluous backtick

---
 stdlib/Markdown/src/Markdown.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/stdlib/Markdown/src/Markdown.jl b/stdlib/Markdown/src/Markdown.jl
index 4472d63364d86..65c67c482f70b 100644
--- a/stdlib/Markdown/src/Markdown.jl
+++ b/stdlib/Markdown/src/Markdown.jl
@@ -77,7 +77,7 @@ doc_str(md::AbstractString, source::LineNumberNode, mod::Module) = doc_str(parse
 Parse the given string as Markdown text, add line and module information and return a 
 corresponding [`MD`](@ref) object.
 
-`@doc_str`` can be used in conjunction with the [`Base.Docs`](@ref) module. Please also refer to
+`@doc_str` can be used in conjunction with the [`Base.Docs`](@ref) module. Please also refer to
 the manual section on [documentation](@ref man-documentation) for more information.
 """
 macro doc_str(s::AbstractString, t...)

From d44f5ce593f2b86ad907cb53602bd83a4719aa2c Mon Sep 17 00:00:00 2001
From: Michael Tiemann <github@michaeltiemann.net>
Date: Fri, 5 Jan 2024 00:27:27 +0100
Subject: [PATCH 07/14] fix missing refs and entries

---
 stdlib/Markdown/docs/src/index.md  | 2 ++
 stdlib/Markdown/src/parse/parse.jl | 2 +-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/stdlib/Markdown/docs/src/index.md b/stdlib/Markdown/docs/src/index.md
index eba91482e88de..1913909278b54 100644
--- a/stdlib/Markdown/docs/src/index.md
+++ b/stdlib/Markdown/docs/src/index.md
@@ -409,4 +409,6 @@ Markdown strings can be constructed using the string literal syntax `md"..."`.
 Markdown.MD
 Markdown.@md_str
 Markdown.@doc_str
+Markdown.html
+Markdown.latex
 ```
diff --git a/stdlib/Markdown/src/parse/parse.jl b/stdlib/Markdown/src/parse/parse.jl
index 82e7ba8d5a01f..fe2e9ef372ac5 100644
--- a/stdlib/Markdown/src/parse/parse.jl
+++ b/stdlib/Markdown/src/parse/parse.jl
@@ -4,7 +4,7 @@
     MD
 
 `MD` represents a Markdown document. However, `MD` objects should only be constructed using 
-the exported macros `@md_str` and `@doc_str`.
+the exported macros [`@md_str`](@ref) and [`@doc_str`](@ref).
 """
 mutable struct MD
     content::Vector{Any}

From 6166cdde5501546efa5d7ad624d9e936f2aedbd8 Mon Sep 17 00:00:00 2001
From: Michael Tiemann <github@michaeltiemann.net>
Date: Fri, 5 Jan 2024 00:48:25 +0100
Subject: [PATCH 08/14] add jldoctest to @doc_str

---
 stdlib/Markdown/src/Markdown.jl | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/stdlib/Markdown/src/Markdown.jl b/stdlib/Markdown/src/Markdown.jl
index 65c67c482f70b..cba4c4f1489ee 100644
--- a/stdlib/Markdown/src/Markdown.jl
+++ b/stdlib/Markdown/src/Markdown.jl
@@ -79,6 +79,16 @@ corresponding [`MD`](@ref) object.
 
 `@doc_str` can be used in conjunction with the [`Base.Docs`](@ref) module. Please also refer to
 the manual section on [documentation](@ref man-documentation) for more information.
+
+# Examples
+```
+julia> s = doc"f(x) = 2*x"
+  f(x) = 2*x
+
+julia> typeof(s)
+Markdown.MD
+
+```
 """
 macro doc_str(s::AbstractString, t...)
     docexpr(__source__, __module__, s, t...)

From d9bb72360c3213bf60d7cab48c45a6400e77742f Mon Sep 17 00:00:00 2001
From: Michael Tiemann <github@michaeltiemann.net>
Date: Fri, 5 Jan 2024 00:53:05 +0100
Subject: [PATCH 09/14] fix trailing whitespace

---
 stdlib/Markdown/src/Markdown.jl    | 4 ++--
 stdlib/Markdown/src/parse/parse.jl | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/stdlib/Markdown/src/Markdown.jl b/stdlib/Markdown/src/Markdown.jl
index cba4c4f1489ee..f4fb7f3b7c23c 100644
--- a/stdlib/Markdown/src/Markdown.jl
+++ b/stdlib/Markdown/src/Markdown.jl
@@ -4,7 +4,7 @@
     Markdown
 
 Tools for working with the Markdown file format. Mainly for documentation.
-The `Markdown` module provides the (internal) [`MD`](@ref) type as well as the string 
+The `Markdown` module provides the (internal) [`MD`](@ref) type as well as the string
 literals `md"..."` and `doc"..."`.
 """
 module Markdown
@@ -74,7 +74,7 @@ doc_str(md::AbstractString, source::LineNumberNode, mod::Module) = doc_str(parse
 """
     @doc_str -> MD
 
-Parse the given string as Markdown text, add line and module information and return a 
+Parse the given string as Markdown text, add line and module information and return a
 corresponding [`MD`](@ref) object.
 
 `@doc_str` can be used in conjunction with the [`Base.Docs`](@ref) module. Please also refer to
diff --git a/stdlib/Markdown/src/parse/parse.jl b/stdlib/Markdown/src/parse/parse.jl
index fe2e9ef372ac5..d9f59be97fcf5 100644
--- a/stdlib/Markdown/src/parse/parse.jl
+++ b/stdlib/Markdown/src/parse/parse.jl
@@ -3,7 +3,7 @@
 """
     MD
 
-`MD` represents a Markdown document. However, `MD` objects should only be constructed using 
+`MD` represents a Markdown document. However, `MD` objects should only be constructed using
 the exported macros [`@md_str`](@ref) and [`@doc_str`](@ref).
 """
 mutable struct MD

From 209f47ad9c08e3ffed45d619d0f2bbb7362a1f49 Mon Sep 17 00:00:00 2001
From: Michael Tiemann <github@michaeltiemann.net>
Date: Fri, 5 Jan 2024 00:59:43 +0100
Subject: [PATCH 10/14] add public MD

---
 stdlib/Markdown/src/parse/parse.jl | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/stdlib/Markdown/src/parse/parse.jl b/stdlib/Markdown/src/parse/parse.jl
index d9f59be97fcf5..4ea222b6b9164 100644
--- a/stdlib/Markdown/src/parse/parse.jl
+++ b/stdlib/Markdown/src/parse/parse.jl
@@ -14,6 +14,8 @@ mutable struct MD
         new(content, meta)
 end
 
+public MD
+
 MD(xs...) = MD(vcat(xs...))
 
 function MD(cfg::Config, xs...)

From adfef160c5cfa9adbc1f2b460fb8388c110aa3df Mon Sep 17 00:00:00 2001
From: Michael Tiemann <github@michaeltiemann.net>
Date: Fri, 5 Jan 2024 01:04:30 +0100
Subject: [PATCH 11/14] add reviewer suggestion

---
 stdlib/Markdown/src/parse/parse.jl | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/stdlib/Markdown/src/parse/parse.jl b/stdlib/Markdown/src/parse/parse.jl
index 4ea222b6b9164..cf7de92da73bc 100644
--- a/stdlib/Markdown/src/parse/parse.jl
+++ b/stdlib/Markdown/src/parse/parse.jl
@@ -3,8 +3,9 @@
 """
     MD
 
-`MD` represents a Markdown document. However, `MD` objects should only be constructed using
-the exported macros [`@md_str`](@ref) and [`@doc_str`](@ref).
+`MD` represents a Markdown document. Note that the `MD` constructor should not generally be
+used directly, since it constructs the internal data structures.   Instead, you can
+construct `MD` objects using the exported macros [`@md_str`](@ref) and [`@doc_str`](@ref).
 """
 mutable struct MD
     content::Vector{Any}

From 534953abb2a4edcc14bbccffb009edea0e57cccf Mon Sep 17 00:00:00 2001
From: Michael Tiemann <126827163+mitiemann@users.noreply.github.com>
Date: Fri, 5 Jan 2024 01:05:33 +0100
Subject: [PATCH 12/14] add reviewer suggestion

Co-authored-by: Steven G. Johnson <stevenj@mit.edu>
---
 stdlib/Markdown/src/Markdown.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/stdlib/Markdown/src/Markdown.jl b/stdlib/Markdown/src/Markdown.jl
index f4fb7f3b7c23c..93d8dbc39fc59 100644
--- a/stdlib/Markdown/src/Markdown.jl
+++ b/stdlib/Markdown/src/Markdown.jl
@@ -3,7 +3,7 @@
 """
     Markdown
 
-Tools for working with the Markdown file format. Mainly for documentation.
+Tools for working with the Markdown markup language for formatted text, used within Julia for documentation.
 The `Markdown` module provides the (internal) [`MD`](@ref) type as well as the string
 literals `md"..."` and `doc"..."`.
 """

From b4f216a26f2167420843dd73377b4f669d4a07b7 Mon Sep 17 00:00:00 2001
From: Michael Tiemann <github@michaeltiemann.net>
Date: Fri, 5 Jan 2024 23:29:14 +0100
Subject: [PATCH 13/14] fix whitespace

---
 stdlib/Markdown/src/parse/parse.jl | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/stdlib/Markdown/src/parse/parse.jl b/stdlib/Markdown/src/parse/parse.jl
index cf7de92da73bc..47a52656b14ab 100644
--- a/stdlib/Markdown/src/parse/parse.jl
+++ b/stdlib/Markdown/src/parse/parse.jl
@@ -4,8 +4,8 @@
     MD
 
 `MD` represents a Markdown document. Note that the `MD` constructor should not generally be
-used directly, since it constructs the internal data structures.   Instead, you can
-construct `MD` objects using the exported macros [`@md_str`](@ref) and [`@doc_str`](@ref).
+used directly, since it constructs the internal data structures. Instead, you can construct 
+`MD` objects using the exported macros [`@md_str`](@ref) and [`@doc_str`](@ref).
 """
 mutable struct MD
     content::Vector{Any}

From 63174d0af62c11fa03570639a7af5557af0b0f94 Mon Sep 17 00:00:00 2001
From: Michael Tiemann <github@michaeltiemann.net>
Date: Fri, 5 Jan 2024 23:52:39 +0100
Subject: [PATCH 14/14] fix trailing whitespace

---
 stdlib/Markdown/src/parse/parse.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/stdlib/Markdown/src/parse/parse.jl b/stdlib/Markdown/src/parse/parse.jl
index 47a52656b14ab..0f3cbe857c2f9 100644
--- a/stdlib/Markdown/src/parse/parse.jl
+++ b/stdlib/Markdown/src/parse/parse.jl
@@ -4,7 +4,7 @@
     MD
 
 `MD` represents a Markdown document. Note that the `MD` constructor should not generally be
-used directly, since it constructs the internal data structures. Instead, you can construct 
+used directly, since it constructs the internal data structures. Instead, you can construct
 `MD` objects using the exported macros [`@md_str`](@ref) and [`@doc_str`](@ref).
 """
 mutable struct MD