Raw HTML in docstring

General Usage
,
1

I’m using Documenter.jl to generate online docs for my package. I want to include raw HTML in a method docstring such as:

@doc raw"""
    my_method(x, y)

This is my method. Now some raw HTML:

```@raw html
<svg style="display: block; margin: 0 auto;" width="5em" heigth="5em">
    <circle cx="2.5em" cy="2.5em" r="2em" stroke="black" stroke-width=".1em" fill="red" />
</svg>
```
"""
function my_method(x, y)
    return x + y
end

After adding my_method to a @docs block in the index.md file, the raw HTML block shows up as code, HTML-escaped in a <pre> block, instead of being included verbatim in the HTML source.

The raw block renders correctly (a red circle) if used outside of a docstring.

2

The @raw html syntax is valid in markdown.

Supported syntax in the comments of functions:
https://docs.julialang.org/en/v1/manual/documentation/#Syntax-Guide

3

The problem is that it is only valid at top-level, not inside function docstrings.

4

That’s intentional, since docstrings should be plain Markdown. E.g. the REPL is not capable of rendering Documenter’s at-blocks.

1 Like