Support for Documenter 1.0?

[fingolfin]

Are there plans to update this package for Documenter 1.0?

[mortenpi]

Good question. And the answer is not by me. So this package is very much looking for a maintainer, preferably someone who is actually using the Markdown backend :slightly_smiling_face:

[fingolfin]

Makes sense. I am not using it myself, but I think @thofma is using it for Hecke.jl... though I am not sure he is interested in taking over DocumenterMarkdown for that, maybe he'll rather switch to plain Documenter.jl, dunno shrug

[thofma]

I am not the only one! I will have a look.

[lazarusA]

I had been trying to get it to work for a similar writer, but I just can see how to go beyond this line:

https://github.com/JuliaDocs/DocumenterMarkdown.jl/blob/5283d2fdce9d634c51936658345a2eee824ed784/src/writer.jl#L30

since now, mapping is gone. And where in the latest version, elem has the form

elem = Markdown.code("...", "")

with fields code and language. However, https://github.com/JuliaDocs/DocumenterMarkdown.jl/blob/5283d2fdce9d634c51936658345a2eee824ed784/src/writer.jl#L31 expects node to be some kinda of Node, i.e. RawNode, DocsNode etc. Any hints on how to convert that elem to a node?

[thofma]

Haha, we made it to the same point. Maybe I should push my progress somewhere.

[mortenpi]

I think you just need to loop over over the child nodes of the page (.children of the MarkdownAST.Node object)? The corresponding line the LaTeXWriter is here I think https://github.com/JuliaDocs/Documenter.jl/blob/dad1a4d3d4e07e0bb3eb464111f178d3da9dfa3a/src/latex/LaTeXWriter.jl#L126C37-L126C37

[lazarusA]

@mortenpi any luck?

[mortenpi]

@lazarusA I didn't actually try to port the code. I was just suggesting that you can take a look at LaTeXWriter to see how you might be able to make it work.

[sylvaticus]

I am another one that use it for my Julia/ML course to produce md that I then further process toward PDF using MarkdownPP.

Just realised that DocumenterMarkdown blocks newer Documenter version... any alternative you suggest to make a single PDF from a mix of .jl/ .md source files ? (I use the two together because for mostly theoretical pages I write them directly in .md format with Julia code chunks and then use Documenter, for more coding pages I use .jl and then Literate)

[thofma]

OK, I looked at this more closely, trying to follow the https://github.com/JuliaDocs/DocumenterMarkdown.jl/issues/11#issuecomment-1754154549. I am still a bit puzzled. I have a page p:

julia> typeof(p)
Documenter.Page

Now I look at the children of the p.mdast (as in the LaTeXWriter.jl).

julia> c = first(p.mdast.children)
@ast Documenter.AnchoredHeader([...]) do
  MarkdownAST.Heading(1) do
    MarkdownAST.Text("Testing")
  end
end

I poked at this some more, but could not find anything useful to pass to the render function. More precisely, we have a bunch of methods of the form

 function render(io::IO, mime::MIME"text/plain", node::Documenter.DocsNode, page, doc)

and

function render(io::IO, mime::MIME"text/plain", node::Documenter.EvalNode, page, doc)

But I have not found anything Node like in p.mdast.children.

I think there is a big understanding on my part. Where are those Node thingies hidden? Or do we have to adjust the render methods to accept the MarkdownAST.NodeChildren thingies? Do you have some more breadcrumbs left @mortenpi?

[mortenpi]

@thofma I'd say you should pass both the ::Node object, and also the corresponding node.element value . That is how the updated LaTeXWriter and HTMLWriter work. E.g. https://github.com/JuliaDocs/Documenter.jl/blob/deecbd7d3abc395fe31d7a393539bcda4c00d753/src/latex/LaTeXWriter.jl#L560-L563

The element object is really only there for dispatch since you can always access it via the ::Node object. But this seems like an okay way to dispatch to different implementations based on which element the node is. That said, there's also probably some other pattern that could be used to iterate over the tree.

[goerz]

So this package is very much looking for a maintainer

Based on https://github.com/JuliaDocs/DocumenterMarkdown.jl/pull/13 and his work on DocumenterVitepress, it seems like maybe @asinghvi17 would want to volunteer for that position?

[asinghvi17]

I probably don't have the bandwidth to be a full maintainer but can definitely review PRs and chip in here and there!