getting generated md files when a block starts with ??? instead of !!!

[lazarusA]

Let's say I have a block in my files within the src folder, something like

index.md

!!! info
    This is import information 

then when I do

makedocs(..., format = Markdown(), build = "docs")

this outputs a new file into docs where the syntax is the same (good)

!!! info
    This is import information

but if I do

index.md

??? info
    This is import information 

then I get

??? info This is import information

which is not good. I'm trying to have collapsible blocks (like the ones here but collapsible).
And in order to get them, I would need to have as output in my docs folder:

??? info
    This is import information

any hints on how to solve this?

[mortenpi]

I think using a @raw html block might work here... I.e.:

```@raw html
??? info
    This is import information
```

We should probably support @raw markdown though.

[lazarusA]

this kinda works. However, it creates an exact copy after doing:

makedocs(..., format = Markdown(), build = "docs")

hence, we have a leftover showing up, we don't need it.

```@raw html
```

The thing inside works.

This is what I have in mind

"""
example()

!!! tip ""
    yes, this works as expected

# Extended help
??? tip "collapse"
    yeah!, no?
"""
function example()
end

this example function is in src in a .md file where docs are being called.

```@docs
example
```

could we not better extended the function that deals with !!! (where is that function?) to also work with ??? ?

[mortenpi]

Oh, this workaround would only work in Markdown pages, not in docstrings. The docstrings get parsed before they reach Documenter, and the Base Markdown parser doesn't understand the ??? syntax, and so it gets parsed as a single paragraph (also, the at-blocks are generally ignored in docstrings):

julia> using Markdown

julia> m = md"""
       !!! info
           123

       ??? info
           123
       """
  │ Info
  │
  │  123

  ??? info 123

julia> m.content
2-element Vector{Any}:
 Markdown.Admonition("info", "Info", Any[Markdown.Paragraph(Any["123"])])
 Markdown.Paragraph(Any["??? info     123"])

If you want a hack to make it work: you could use admonition syntax with a custom label (e.g. !!! info-collapsed), and then add the appropriate render method to DocumenterMarkdown. Normally, the standard library elements dispatch to standard library methods here:

DocumenterMarkdown.jl/src/writer.jl

Lines 197 to 201 in b331558

	function render(io::IO, ::MIME"text/plain", other, page, doc)
	println(io)
	MarkdownStdlib.plain(io, other)
	println(io)
	end

In the case of the admonition, I believe it's this method: https://github.com/JuliaLang/julia/blob/b600f51eab283333ede6e3120b104b3aa4d9043b/stdlib/Markdown/src/render/plain.jl#L73-L81

You could probably add a method that picks out the Adminition objects, something like:

render(io::IO, ::MIME"text/plain", node::Markdown.Admonition, page, doc) = ...

[MichaelHatherly]

@lazarusA I'm curious which markdown parsers (in other languages) currently support ??? syntax? I'd not encountered that one, but if it's got reasonably good support we can at least add it to CommonMark.jl as an extension (though of course doesn't help your immediate need here).

[lazarusA]

I'm basically using the syntax from here, almost everything works. The docs for Tidier.jl are being generated using this.

Another example is in YAXArrays.jl where in that case the warning tag is already incorporated into the doc string and properly render by Markdown(). So the goal is to have this generation also for Extended help, such that when we generate the docs this block is collapsed. As I said, this almost works (the collapse part is there), but the

```@raw html
```

is surrounding this block.

Edit: But maybe, it might be better to just simply define a custom admonition directly in the docs and use that one in my doc string.

[MichaelHatherly]

Ah, thanks, so that's coming from https://facelessuser.github.io/pymdown-extensions/extensions/details/ it appears. Sound like good additions to add at some point, and should be relatively simple ones to do.

[mortenpi]

But maybe, it might be better to just simply define a custom admonition directly in the docs and use that one in my doc string.

This seems like a good solution for your use case. Do note that the admonition types are only allowed to be single lowercase words in the Julia parser.

[lazarusA]

@MichaelHatherly nice to hear that it might be possible to have this by default.
In the mean time I will define a new one directly in the docs.