Create `@raw` blocks programmatically from Documenter.jl

Is there a way to interpolate or more precisely create blocks of raw html programmaticaly from Julia during the building step of Documenter.jl

I have been trying to make interactive plots from Plotly.js work by inserting <script> blocks using the @raw html blocks in my source documenter files.

This does not require fiddling with using assets or going through the RequireJS submodule in Documenter but it is quite tedious to manually generate the javascript code for creating plotly.js plots.

Most of the functionality to create the scripts contents for plotlyjs is already available from the packages that use plotlyjs as backend, so it would be very convenient to be able to use the julia API to generate the html content.

I have seen the solution in Embed interactive .html plot in documentation using Documenter.jl - #2 by cyrieln but I’d rather avoid using iframe for this as it’s more clunky.

You can perhaps use an @eval block? It has to return Markdown (I think?), but you can then return markdown with @raw code blocks.

I have to fully understand how and where to use the @eval here.

Is your proposed approach to use an @eval inside of make.jl that actually modifies the source document where I want my plot, or is this something that can be from the markdown file like as part of an @example block or another kind of block?

I would be amazing if the generated script contents would not be hardcoded inside the source file but just used as part of the build step.

It is a Documenter block type (like @example, @docs, …), see Syntax · Documenter.jl

1 Like

Ah yes, I also just realized it is another kind of block.
Still rather new to Documenter.jl :slight_smile:

I just tried but it doesn’t seem to work.

I tried adding the two following blocks to my markdown source file (I am using single quotes ' inside the code below as I don’t know how to escape triple backticks inside formatted code here on discourse):

```@raw html

Markdown.MD(Markdown.Code("@raw html",

But only the first get renedered as HTML, the last one is simply rendered as markdown:

I briefly checked the source code of Documenter.jl and I don’t think this is currently possible without modifications.

I just submitted a PR to add a synthax block called @evalraw to provide this functionality.

Right, I misremembered and the returned markdown isn’t further processed.

After discussion on the PR I realized that this is mostly feasible by using @example blocks for the original purpose of creative interactive plotly plots within documenter.

I created a very small package to simplify the procedure here:

which supports plot objects coming out of one of:

  • PlotlyLight
  • PlotlyBase
  • PlotlyJS

If the PR ends up being merged succesfully it should also be possible to use this within @eval blocks to completely hide the generating code.