# Create \`@raw\` blocks programmatically from Documenter.jl

**URL:** <https://discourse.julialang.org/t/create-raw-blocks-programmatically-from-documenter-jl/101522>\
**Category:** General Usage\
**Tags:** documentation, documenter, plots\
**Created:** [July 12, 2023, 9:21am UTC](https://discourse.julialang.org/t/create-raw-blocks-programmatically-from-documenter-jl/101522 "2023-07-12T09:21:42Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![disberd](https://avatars.discourse-cdn.com/v4/letter/d/8edcca/32.png) [@disberd](https://discourse.julialang.org/u/disberd)\
**Post date:** [July 12, 2023, 9:21am UTC](https://discourse.julialang.org/t/create-raw-blocks-programmatically-from-documenter-jl/101522/1 "2023-07-12T09:21:42Z")

</div>

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](https://discourse.julialang.org/t/embed-interactive-html-plot-in-documentation-using-documenter-jl/68890/2) but I’d rather avoid using `iframe` for this as it’s more clunky.

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [July 12, 2023, 9:34am UTC](https://discourse.julialang.org/t/create-raw-blocks-programmatically-from-documenter-jl/101522/2 "2023-07-12T09:34:17Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![disberd](https://avatars.discourse-cdn.com/v4/letter/d/8edcca/32.png) [@disberd](https://discourse.julialang.org/u/disberd)\
**Post date:** [July 12, 2023, 9:40am UTC](https://discourse.julialang.org/t/create-raw-blocks-programmatically-from-documenter-jl/101522/3 "2023-07-12T09:40:35Z")

</div>

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 `somethig.md` 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.

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [July 12, 2023, 9:43am UTC](https://discourse.julialang.org/t/create-raw-blocks-programmatically-from-documenter-jl/101522/4 "2023-07-12T09:43:38Z")

</div>

It is a Documenter block type (like `@example`, `@docs`, …), see [Syntax · Documenter.jl](https://documenter.juliadocs.org/stable/man/syntax/#@eval-block)

---

<div class="post-metadata">

**Author:** ![disberd](https://avatars.discourse-cdn.com/v4/letter/d/8edcca/32.png) [@disberd](https://discourse.julialang.org/u/disberd)\
**Post date:** [July 12, 2023, 9:44am UTC](https://discourse.julialang.org/t/create-raw-blocks-programmatically-from-documenter-jl/101522/5 "2023-07-12T09:44:27Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![disberd](https://avatars.discourse-cdn.com/v4/letter/d/8edcca/32.png) [@disberd](https://discourse.julialang.org/u/disberd)\
**Post date:** [July 12, 2023, 10:10am UTC](https://discourse.julialang.org/t/create-raw-blocks-programmatically-from-documenter-jl/101522/6 "2023-07-12T10:10:36Z")

</div>

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):

````julia
```@raw html
<div>TEST1</div>
```

```@eval
Markdown.MD(Markdown.Code("@raw html",
"<div>TEST@</div>"))
```

````

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

 ![image](https://global.discourse-cdn.com/julialang/original/3X/f/1/f19a4d58d40d7f194d56a3a30953202ff60ef1f4.png)

---

<div class="post-metadata">

**Author:** ![disberd](https://avatars.discourse-cdn.com/v4/letter/d/8edcca/32.png) [@disberd](https://discourse.julialang.org/u/disberd)\
**Post date:** [July 12, 2023, 11:01am UTC](https://discourse.julialang.org/t/create-raw-blocks-programmatically-from-documenter-jl/101522/7 "2023-07-12T11:01:39Z")

</div>

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](https://github.com/JuliaDocs/Documenter.jl/pull/2182) to add a synthax block called `@evalraw` to provide this functionality.

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [July 12, 2023, 11:16am UTC](https://discourse.julialang.org/t/create-raw-blocks-programmatically-from-documenter-jl/101522/8 "2023-07-12T11:16:24Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![disberd](https://avatars.discourse-cdn.com/v4/letter/d/8edcca/32.png) [@disberd](https://discourse.julialang.org/u/disberd)\
**Post date:** [July 14, 2023, 12:09pm UTC](https://discourse.julialang.org/t/create-raw-blocks-programmatically-from-documenter-jl/101522/9 "2023-07-14T12:09:18Z")

</div>

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:

> **[GitHub - disberd/PlotlyDocumenter.jl: Show plotly plots in Documenter.jl as...](https://github.com/disberd/PlotlyDocumenter.jl)**
>
> Show plotly plots in Documenter.jl as static HTML. Contribute to disberd/PlotlyDocumenter.jl development by creating an account on GitHub.

which supports plot objects coming out of one of:

- PlotlyLight
- PlotlyBase
- PlotlyJS

If the [PR](https://github.com/JuliaDocs/Documenter.jl/pull/2182) ends up being merged succesfully it should also be possible to use this within `@eval` blocks to completely hide the generating code.