Support inline HTML

[omus]

It would be great if you could embed HTML tags directly into the Markdown. For example I would like to do:

Use <kbd>Ctrl</kbd> + <kbd>D</kbd> to exit.

which would be rendered as

Use Ctrl + D to exit.

Unfortunately the only way to use HTML currently is using the @raw block which doesn't support an inline form:

```@raw html
Use <kbd>Ctrl</kbd> + <kbd>D</kbd> to exit.
```

[omus]

Possible solutions include adding support for an inline @raw form. Maybe something like:

```@raw html; <kbd>Ctrl</kbd> + <kbd>D</kbd>```

Alternatively, we could adopt the pandoc's syntax for inline code attributes:

`<kbd>Ctrl</kbd> + <kbd>D</kbd>`{@raw html}

[mortenpi]

CommonMark specifies that HTML should be detected when parsing Markdown. Hence I'd say the best option would be to add this to the parser in Base. All the other options would also rely on updates to the Base parser, so this is an upstream issue -- but it would be great to have support for this.

Edit: there's an upstream issue for this: JuliaLang/julia#17837

[juliohm]

What is the current status on this? I tried including some HTML today and found this issue. The linked issue doesn't seem very promising from the comments there. Conclusion is that we need to be happy with Markdown?

[friggog]

While this is fundamentally an upstream issue, is it possible to add a workaround to enable this anyway? Franklin uses ~~~...~~~ to wrap raw html for example: https://franklinjl.org/syntax/markdown/#raw_html

I guess the @raw trick above works for markdown pages, but it doesn't seem to work for me within docstrings.

[mortenpi]

I'm not a big fan of Franklin's syntax, but what we could do is to abuse the link syntax for inline at-raw blocks, e.g. [`<kbd>Ctrl</kbd>`](@raw html) (in line with the at-ref syntax). This wouldn't require us to implement any additional parsing.

[friggog]

Yeah, conceptually this link syntax idea is pretty gnarly but I feel like any syntax we come up with to do this (e.g. Franklin style) is going to be ugly in comparison to just having correct markdown behaviour (i.e. inline html parsing) which will need to be an upstream fix.

If the link syntax is much easier to implement then it seems like a good option - being able to support raw html would be great, even if it's ugly for now - hopefully in the future the hack can be removed when an upstream fix happens

[eranschweitzer]

I was running into this same issue and stumbled upon this thread. The @raw html solution in block form does not work for me in anything other than the main page text. That is it's not possible to use is in:

• lists
• footnotes
• ...

which seems rather restrictive.

[clarkevans]

How about using interpolation? It seems Markdown is already stripping $.

$(2+2) => 2 + 2

Instead... we could evaluate expressions, and if the result is showable("text/html"), let it render itself. If not, escape. Then you could write...

$(HTML("<br/>")) => <br/>

Moreover, one could embed any other sort of processing.

[mortenpi]

I don't remember off the top of my head how it works exactly, but it is possible to interpolate arbitrary Julia objects into the docstrings (DocStringExtensions uses it). So that could indeed be a workaround.