[WIP] Refactor and update to Documenter v1.0

Project.toml

@@ -1,6 +1,6 @@
 name = "DocumenterMarkdown"
 uuid = "997ab1e6-3595-5248-9280-8efb232c3433"
-version = "0.2.2"
+version = "0.3.0"
 
 [deps]
 ANSIColoredPrinters = "a4c015fc-c6ff-483c-b24f-f7ea428134e9"
@@ -10,11 +10,14 @@ Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
 
 [compat]
 ANSIColoredPrinters = "0.0.1"
-Documenter = "0.27.18"
+Documenter = "1.0"
 julia = "1"
 
 [extras]
+DocInventories = "43dc2714-ed3b-44b5-b226-857eda1aa7de"
+HTTP = "cd3eb016-35fb-5094-929b-558a96fad6f3"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+URIs = "5c2747f8-b7ea-4ff2-ba2e-563bfd36b1d4"
 
 [targets]
-test = ["Test"]
+test = ["Test", "DocInventories", "HTTP", "URIs"]

README.md

@@ -6,11 +6,6 @@
 
 This package provides a Markdown / MkDocs backend to [`Documenter.jl`][documenter].
 
-**Package status:** Currently, the package does not work with the 0.28 branch of Documenter, and
-therefore the latest versions of Documenter do not have a Markdown backend available.
-Older, released versions of this package can still be used together with older versions of Documenter (0.27
-and earlier) to enable the Markdown backend built in to those versions of Documenter.
-
 Right now, this package is not actively maintained. However, contributions are welcome by anyone
 who might be interested in using and developing this backend.
 

docs/make.jl

@@ -1,15 +1,21 @@
-using Documenter: makedocs, deploydocs, Deps
+using Documenter
 using DocumenterMarkdown
 
 makedocs(
     sitename = "DocumenterMarkdown",
-    format = Markdown(),
+    format = MkDocsMarkdown(),
+    pages = [
+        "Introduction" => "index.md",
+        "Markdown Flavors" => "flavors.md",
+        "API Reference" => "api.md",
+    ],
+    warnonly = true,
 )
 
-deploydocs(
-    repo = "github.com/JuliaDocs/DocumenterMarkdown.jl.git",
-    deps   = Deps.pip("mkdocs", "pygments", "python-markdown-math"),
-    make   = () -> run(`mkdocs build`),
-    target = "site",
-    push_preview = true,
-)
+# deploydocs(
+#     repo = "github.com/JuliaDocs/DocumenterMarkdown.jl.git",
+#     deps   = Deps.pip("mkdocs", "pygments", "python-markdown-math"),
+#     make   = () -> run(`mkdocs build`),
+#     target = "site",
+#     push_preview = true,
+# )

docs/src/api.md

@@ -0,0 +1,5 @@
+# API Reference
+
+```@autodocs
+Modules = [DocumenterMarkdown]
+```

docs/src/flavors.md

@@ -0,0 +1,14 @@
+# Flavors
+
+"Flavor"s are simply flavor implementations of markdown.  The default functions implement Julia flavored markdown, and any fallbacks also fall back to Julia flavored markdown.  
+
+In order to override the defaults for your format (`YourMarkdownFormat <: DocumenterMarkdown.MarkdownFormat`), you may override the following methods:
+
+- `render(doc)`
+- `render(fmt, io, ...)`
+- `renderdoc(fmt, io, ...)`
+- `render_mime(fmt, io, ...)`
+
+## Defining a simple override
+
+The way this works is that Documenter dispatches on the settings you send in to the `format` keyword in `makedocs` to find the appropriate `Format` type.

src/DocumenterMarkdown.jl

@@ -1,17 +1,21 @@
 module DocumenterMarkdown
-using Documenter: Documenter
-using Documenter.Utilities: Selectors
 
-const ASSETS = normpath(joinpath(@__DIR__, "..", "assets"))
+import Documenter: Documenter, Builder, Expanders, Selectors, MarkdownAST
+import Base64: base64decode, base64encode
+import Markdown
 
+import ANSIColoredPrinters
+
+include("types.jl")
+include("utils.jl")
+include("inventory.jl")
 include("writer.jl")
-export Markdown
+include("mime_rendering.jl")
+
+include("flavors/github.jl")
+include("flavors/mkdocs.jl")
 
 # Selectors interface in Documenter.Writers, for dispatching on different writers
-abstract type MarkdownFormat <: Documenter.Writers.FormatSelector end
-Selectors.order(::Type{MarkdownFormat}) = 1.0
-Selectors.matcher(::Type{MarkdownFormat}, fmt, _) = isa(fmt, Markdown)
-Selectors.runner(::Type{MarkdownFormat}, fmt, doc) = render(doc, fmt)
 
 # This is from the old Deps module:
 

src/flavors/github.jl

@@ -0,0 +1,20 @@
+# # Github-flavored markdown
+
+# In Github-flavored markdown, the syntax for admonitions is 
+# slightly different.  They are implemented using quotes and 
+# an indicator string at the top, and the category is always
+# uppercase.
+
+# So, we need to convert the admonition AST nodes to the
+# appropriate syntax.
+
+function render(fmt::GithubMarkdown, io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Node, admonition::Documenter.MarkdownAST.Admonition, page, doc; kwargs...)
+    category = admonition.category
+    if category == "note"
+        category = "Note"
+    end
+    println(io, "\n> [!$(uppercase(category))]")
+    iob = IOBuffer()
+    render(fmt, iob, mime, node, node.children, page, doc; kwargs...)
+    println(io, replace(String(take!(iob)), "\n" => "\n> "))
+end

src/flavors/mkdocs.jl

@@ -0,0 +1,31 @@
+# # MkDocs flavored markdown
+
+# For MkDocs, we copy over the files in `assets/mkdocs`, which are a CSS file and a MathJax helper file.
+# For this, we override the main entry point to `render` to copy these assets to the `build/assets` folder,
+# if they do not currently exist.
+
+
+function render(settings::MkDocsMarkdown, doc::Documenter.Document)
+    @info "DocumenterMarkdown: rendering Markdown pages in MkDocs markdown."
+    mime = MIME"text/plain"()
+    builddir = isabspath(doc.user.build) ? doc.user.build : joinpath(doc.user.root, doc.user.build)
+    mkpath(builddir)
+    # Copy over assets
+    ASSET_PATH = joinpath(@__DIR__, "assets", "mkdocs")
+    mkpath(joinpath(builddir, "assets"))
+    for file in readdir(ASSET_PATH)
+        cp(file, joinpath(builddir, "assets", file); force = false)
+    end
+    # Now, render the pages
+    for (src, page) in doc.blueprint.pages
+        # This is where you can operate on a per-page level.
+        open(docpath(builddir, page.build), "w") do io
+            for node in page.mdast.children
+                render(settings, io, mime, node, page, doc)
+            end
+        end
+    end
+    Documenter.HTMLWriter.write_inventory(doc, ___MarkdownContext(doc))
+end
+
+# Aside from the asset copying, the rendering process is the same as the default Markdown renderer.

src/flavors/vitepress.jl

@@ -0,0 +1,21 @@
+struct VitepressMarkdown <: Documenter.Flavor end
+
+function render(fmt::VitepressMarkdown, io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Node, admonition::MarkdownAST.Admonition, page, doc; kwargs...)
+    # Main.@infiltrate
+    category = admonition.category
+    if category == "note" # Julia markdown says note, but Vitepress says tip
+        category = "tip"
+    end
+    println(io, "\n::: $(category) $(admonition.title)")
+    render(fmt, io, mime, node, node.children, page, doc; kwargs...)
+    println(io, "\n:::")
+end
+
+# Here, we are rendering images as HTML.  It is my hope that at some point we figure out how to render them in Markdown, but for now, this is also perfectly sufficient.
+function render(::VitepressMarkdown, io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Node, image::MarkdownAST.Image, page, doc; kwargs...)
+    println()
+    url = replace(image.destination, "\\" => "/")
+    print(io, "<img src=\"", url, "\" alt=\"")
+    render(fmt, io, mime, node, node.children, page, doc; kwargs...)
+    println(io, "\">")
+end

src/inventory.jl

@@ -0,0 +1,29 @@
+#=
+# Inventory files
+
+This file provides overloads to the Documenter.jl inventory finding functions which allow us
+to write the Sphinx inventory file used by DocumenterInterLinks and Intersphinx.
+
+By providing a Markdown context, you can use the `Documenter.HTMLWriters.write_inventory(doc, ___MarkdownContext(doc))` function 
+and provide it a `___MarkdownContext` object to generate the inventory file.
+
+=#
+
+"""
+    ___MarkdownContext(doc)
+
+This is a struct which duplicates the Documenter.jl HTMLContext for the purposes of 
+rendering a Sphinx inventory file.
+"""
+struct ___MarkdownContext
+    settings::NamedTuple
+    doc
+end
+
+function ___MarkdownContext(doc; inventory_version = Documenter.DOCUMENTER_VERSION)
+    settings = (; prettyurls = false, inventory_version)
+    ___MarkdownContext(settings, doc)
+end
+
+Documenter.HTMLWriter.getpage(ctx::___MarkdownContext, path) = ctx.doc.blueprint.pages[path]
+Documenter.HTMLWriter.getpage(ctx::___MarkdownContext, navnode::Documenter.NavNode) = Documenter.HTMLWriter.getpage(ctx, navnode.page)

src/mime_rendering.jl

@@ -0,0 +1,152 @@
+#=
+# MIME rendering
+
+This file contains utilities to render various objects as different MIME types within Markdown.
+
+## MIME priority
+
+The `mime_priority` function is used to determine the priority of a given MIME type.  This is used to select the best MIME type for rendering a given element.  Priority is in ascending order, i.e., 1 has more priority than 0.
+
+What happens is that the output dictionary that Documenter returns is sorted by the output of `mime_priority` on its keys.
+
+As a general rule, the closer the MIME type is to plain text (meaning it can encode less information), the lower the priority.  
+
+For example, showing a video is strictly more preferable to showing an image, which is itself more preferable to showing the unmodified Julia REPL show output.
+
+=#
+
+"""
+    mime_priority(mime::MIME)::Float64
+
+This function returns a priority for a given MIME type, which
+is used to select the best MIME type for rendering a given
+element.  Priority is in ascending order, i.e., 1 has more priority than 0.
+"""
+function mime_priority end
+mime_priority(::MIME"text/plain") = 0.0
+mime_priority(::MIME"text/markdown") = 1.0
+mime_priority(::MIME"text/html") = 2.0
+mime_priority(::MIME"text/latex") = 2.5
+mime_priority(::MIME"image/svg+xml") = 3.0
+mime_priority(::MIME"image/png") = 4.0
+mime_priority(::MIME"image/webp") = 5.0
+mime_priority(::MIME"image/jpeg") = 6.0
+mime_priority(::MIME"image/png+lightdark") = 7.0
+mime_priority(::MIME"image/jpeg+lightdark") = 8.0
+mime_priority(::MIME"image/svg+xml+lightdark") = 9.0
+mime_priority(::MIME"image/gif") = 10.0
+mime_priority(::MIME"video/mp4") = 11.0
+mime_priority(::MIME) = Inf
+
+#=
+## MIME rendering
+
+Now, we define functions to render mime types.
+=#
+
+
+function render_mime(flavor::AbstractMarkdown, io::IO, mime::MIME, node, element, page, doc; kwargs...)
+    @warn("DocumenterMarkdown: Unknown MIME type $mime provided and no alternatives given.  Ignoring render!")
+end
+
+function render_mime(flavor::AbstractMarkdown, io::IO, mime::MIME"text/markdown", node, element, page, doc; kwargs...)
+    println(io, element)
+end
+
+function render_mime(flavor::AbstractMarkdown, io::IO, mime::MIME"text/html", node, element, page, doc; kwargs...)
+    println(io, element)
+end
+
+function render_mime(flavor::AbstractMarkdown, io::IO, mime::MIME"image/svg+xml", node, element, page, doc; kwargs...)
+    # NOTE: It seems that we can't simply save the SVG images as a file and include them
+    # as browsers seem to need to have the xmlns attribute set in the <svg> tag if you
+    # want to include it with <img>. However, setting that attribute is up to the code
+    # creating the SVG image.
+    image_text = element
+    # Additionally, Vitepress complains about the XML version and encoding string below,
+    # so we just remove this bad hombre!
+    bad_hombre_string = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>" |> lowercase
+    location = findfirst(bad_hombre_string, lowercase(image_text))    
+    if !isnothing(location) # couldn't figure out how to do this in one line - maybe regex?  A question for later though.
+        image_text = replace(image_text, image_text[location] => "")
+    end
+    println(io, "<img src=\"data:image/svg+xml;base64," * base64encode(image_text) * "\"/>")
+end
+
+function render_mime(flavor::AbstractMarkdown, io::IO, mime::MIME"image/png", node, element, page, doc; md_output_path, kwargs...)
+    filename = String(rand('a':'z', 7))
+    write(joinpath(doc.user.build, md_output_path, dirname(relpath(page.build, doc.user.build)), "$(filename).png"),
+        base64decode(element))
+    println(io, "![]($(filename).png)")
+end
+
+function render_mime(flavor::AbstractMarkdown, io::IO, mime::MIME"image/webp", node, element, page, doc; md_output_path, kwargs...)
+    filename = String(rand('a':'z', 7))
+    write(joinpath(doc.user.build, md_output_path, dirname(relpath(page.build, doc.user.build)), "$(filename).webp"),
+        base64decode(element))
+    println(io, "![]($(filename).webp)")
+end
+
+function render_mime(flavor::AbstractMarkdown, io::IO, mime::MIME"image/jpeg", node, element, page, doc; md_output_path, kwargs...)
+    filename = String(rand('a':'z', 7))
+    write(joinpath(doc.user.build, md_output_path, dirname(relpath(page.build, doc.user.build)), "$(filename).jpeg"),
+        base64decode(element))
+    println(io, "![]($(filename).jpeg)")
+end
+
+# function render_mime(flavor::AbstractMarkdown, io::IO, mime::MIME"image/png+lightdark", node, element, page, doc; md_output_path, kwargs...)
+#     fig_light, fig_dark, backend = element
+#     filename = String(rand('a':'z', 7))
+#     write(joinpath(doc.user.build, md_output_path, dirname(relpath(page.build, doc.user.build)), "$(filename)_light.png"), fig_light)
+#     write(joinpath(doc.user.build, md_output_path, dirname(relpath(page.build, doc.user.build)), "$(filename)_dark.png"), fig_dark)
+#     println(io,
+#         """
+#         ![]($(filename)_light.png){.light-only}
+#         ![]($(filename)_dark.png){.dark-only}
+#         """
+#     )
+# end
+
+# function render_mime(flavor::AbstractMarkdown, io::IO, mime::MIME"image/jpeg+lightdark", node, element, page, doc; md_output_path, kwargs...)
+#     fig_light, fig_dark, backend = element
+#     filename = String(rand('a':'z', 7))
+#     Main.Makie.save(joinpath(doc.user.build, md_output_path, dirname(relpath(page.build, doc.user.build)), "$(filename)_light.jpeg"), fig_light)
+#     Main.Makie.save(joinpath(doc.user.build, md_output_path, dirname(relpath(page.build, doc.user.build)), "$(filename)_dark.jpeg"), fig_dark)
+#     println(io,
+#         """
+#         ![]($(filename)_light.jpeg){.light-only}
+#         ![]($(filename)_dark.jpeg){.dark-only}
+#         """
+#     )
+# end
+
+# function render_mime(flavor::AbstractMarkdown, io::IO, mime::MIME"image/svg+xml+lightdark", node, element, page, doc; md_output_path, kwargs...)
+#     fig_light, fig_dark, backend = element
+#     filename = String(rand('a':'z', 7))
+#     Main.Makie.save(joinpath(doc.user.build, md_output_path, dirname(relpath(page.build, doc.user.build)), "$(filename)_light.svg"), fig_light)
+#     Main.Makie.save(joinpath(doc.user.build, md_output_path, dirname(relpath(page.build, doc.user.build)), "$(filename)_dark.svg"), fig_dark)
+#     println(io,
+#         """
+#         <img src = "$(filename)_light.svg" style=".light-only"></img>
+#         <img src = "$(filename)_dark.svg" style=".dark-only"></img>
+#         """
+#     )
+# end
+
+function render_mime(flavor::AbstractMarkdown, io::IO, mime::MIME"image/gif", node, element, page, doc; md_output_path, kwargs...)
+    filename = String(rand('a':'z', 7))
+    write(joinpath(doc.user.build, md_output_path, dirname(relpath(page.build, doc.user.build)), "$(filename).gif"),
+        base64decode(element))
+    println(io, "![]($(filename).gif)")
+end
+
+function render_mime(flavor::AbstractMarkdown, io::IO, mime::MIME"video/mp4", node, element, page, doc; md_output_path, kwargs...)
+    filename = String(rand('a':'z', 7))
+    write(joinpath(doc.user.build, md_output_path, dirname(relpath(page.build, doc.user.build)), "$(filename).mp4"),
+        base64decode(element))
+    println(io, "<video src='$filename.mp4' controls='controls' autoplay='autoplay'></video>")
+end
+
+function render_mime(flavor::AbstractMarkdown, io::IO, mime::MIME"text/plain", node, element, page, doc; kwargs...)
+    return render(io, mime, node, Markdown.Code(element), page, doc; kwargs...)
+end