Improvement Proposal: Quadruple Backticks for @example Codefences in (Documenter-)Markdown

[manuelbb-upb]

I am testing Literate for writing a module where some functions have docstrings attached.
I noticed that if I am including code-examples or math in the docstrings, then the resulting Code-Blocks in markdown output get split.

Example: The Julia Code

"""
Doc String with math:
```math
    π = 3
```
"""
function funny_fun(x) nothing end

will result in Markdown that looks something like

```@example
"""
Doc String with math:
```

and

math
    π = 3
```@example
```
"""
function funny_fun(x) nothing end

This of course can break the whole document.
A simple fix is to provide the codefence keyword argument to Literate.markown, specifying to use 4 consecutive backticks instead of 3, i.e.,

codefence = "````@example SomeName" => "````"

I am thinking that maybe this should be the default behavior, at least for documenter output?
Anyways, thanks for the great work!

[fredrikekre]

Makes sense, are there any downside at all of using four backticks? @mortenpi?

[mortenpi]

I don't think so, the parser should handle it fine.

Will break again if someone decides to use 4-backticks in their docstring though. That should be much more rare, but might be worth mentioning in the docs?

[manuelbb-upb]

I am glad, that the switch would be possible :)
I agree, that 4 backticks in a docstring will probably occur rather seldomly.
Whether or not the default behavior is changed, a note in the docs would be great, as I was caught quite of guard by the broken output.

If the behavior is changed, it could be documented be in the section about output formats
Right after the rendered markdown is shown, there could be a note like this:
Note that we use 4 consecutive backticks to fence the code blocks so as to allow for docstrings containing triple backticks.
If your Julia code itself contains 4 consecutive backticks, you can use the keyword argument codefence to tell Literate.jl to use 5 backticks for code blocks.

[fredrikekre]

Do you want to make a PR to change this and add that documentation?

[manuelbb-upb]

Yes, I'd love to :) I will make the PR and reference this issue.

[manuelbb-upb]

I have just noticed something else:
Julia comments have to start with "## " to not be parsed as markdown.
But "##" is also the code cell delimiter in VSCode (which is not user configurable atm).
Thus, I unwillingly introduce new code cells when commenting.

To overcome this, I have written a preprocessing function allowing for comments with an alternative prefix ("#~" in my case).
Allowing something similar in Literate.jl would only require a slight modification to this line, e.g.,
the additional rule r"^(\h*)#~(.*)$" => s"\1#\2".
I don't know whether this warrants its own issue/pull request.