Fix links/Markdown in headings (#151)

* Only print the ID if it differs from heading text

* perform ID check based on rendered string

* Use Documenter.mdflatten for sidebar links

* Fix link writing

* Remove exfiltrate

src/vitepress_config.jl

@@ -141,11 +141,11 @@ function pagelist2str(doc, page::String)
     # If no name is given, find the first header in the page,
     # and use that as the name.
     elements = doc.blueprint.pages[page].elements
-    idx = findfirst(x -> x isa Markdown.Header, elements)
+    idx = findfirst(x -> x isa MarkdownAST.Heading, elements)
     name = if isnothing(idx)
         splitext(page)[1]
     else
-        elements[idx].text[1]
+        Documenter.MDFlatten.mdflatten(elements[idx])
     end
     return "{ text: '$(replace(name, "'" => "\\'"))', link: '/$(splitext(page)[1])' }" # , $(sidebar_items(doc, page)) }"
 end
@@ -168,18 +168,18 @@ end
 function sidebar_items(doc, page::String)
     # We look at the page elements, and obtain all level 1 and 2 headers.
     elements = doc.blueprint.pages[page].elements
-    headers = elements[findall(x -> x isa Union{Markdown.Header{1}, Markdown.Header{2}}, elements)]
+    headers = filter(x -> x isa Union{MarkdownAST.Heading{1}, MarkdownAST.Heading{2}}, elements)
     # If nothing is found, move on in life
     if length(headers) ≤ 1
         return ""
     end
     # Otherwise, we return a collapsible tree of headers for each level 1 and 2 header.
-    items = _get_first_or_string.(getproperty.(headers, :text))
+    items = headers
     return "collapsed: true, items: [\n $(join(_item_link.((page,), items), ",\n"))\n]"
 end
 
 function _item_link(page, item)
-    return "{ text: '$(replace(item, "'" => "\\'"))', link: '/$(splitext(page)[1])#$(replace(item, " " => "-"))' }"
+    return "{ text: '$(replace(Documenter.MDFlatten.mdflatten(item), "'" => "\\'"))', link: '/$(splitext(page)[1])#$(replace(item, " " => "-"))' }"
 
 end
 

src/vitepress_interface.jl

@@ -1,5 +1,5 @@
 """
-    dev_docs(builddir::String)
+    dev_docs(builddir::String; md_output_path = ".documenter")
 
 Runs the vitepress dev server to serve the docs built from the Markdown
 files (generated by `makedocs`) in the given directory.
@@ -13,22 +13,21 @@ Work is in progress to let the user pass the config object to fix this.
     This does **NOT** run `makedocs` - you have to do that yourself!
     Think of it as the second stage of `LiveServer.jl` for DocumenterVitepress specifically.
 """
-dev_docs(builddir::String) = run_vitepress_command(builddir, "dev")
+dev_docs(builddir::String; md_output_path = ".documenter") = run_vitepress_command(builddir, "dev"; md_output_path)
 
 """
-    build_docs(builddir::String)
+    build_docs(builddir::String; md_output_path = ".documenter")
 
 Builds the Vitepress site in the given directory.
 
 If passing a String, pass the path to the `builddir`, i.e., `\$packagepath/docs/build`.
 """
-build_docs(builddir::String) = run_vitepress_command(builddir, "build")
+build_docs(builddir::String; md_output_path = ".documenter") = run_vitepress_command(builddir, "build"; md_output_path)
 
 
-function run_vitepress_command(builddir::String, command::String)
+function run_vitepress_command(builddir::String, command::String; md_output_path = ".documenter")
     @assert ispath(builddir)
     builddir = abspath(builddir)
-    md_output_path = ".documenter"
     @info "DocumenterVitepress: running `vitepress $command`."
     should_remove_package_json = false
     try

src/writer.jl

@@ -98,7 +98,6 @@ render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Node, elemen
 where `Eltype` is the type of the `element` field of the `node` object which you care about.
 """
 function render(doc::Documenter.Document, settings::MarkdownVitepress=MarkdownVitepress())
-    # Main.@exfiltrate
     @info "DocumenterVitepress: rendering MarkdownVitepress pages."
     # copy_assets(doc, settings.md_output_path)
     # Handle the case where the site name has to be set...
@@ -685,12 +684,16 @@ end
 function render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Node, header::Documenter.AnchoredHeader, page, doc; kwargs...)
     anchor = header.anchor
     id = string(Documenter.anchor_label(anchor))
-    # @infiltrate
     heading = first(node.children)
     println(io)
     print(io, "#"^(heading.element.level), " ")
-    render(io, mime, node, heading.children, page, doc; kwargs...)
-    print(io, " {#$(replace(id, " " => "-"))}") # potentially use MarkdownAST.mdflatten here?
+    heading_iob = IOBuffer()
+    render(heading_iob, mime, node, heading.children, page, doc; kwargs...)
+    heading_text = rstrip(String(take!(heading_iob)))
+    print(io, heading_text)
+    if id != heading_text # if a custom ID is set, then use it.
+        print(io, " {#$(replace(id, " " => "-"))}") # potentially use MarkdownAST.mdflatten here?
+    end
     println(io)
 end
 # Thematic breaks