Documenter.jl icon indicating copy to clipboard operation
Documenter.jl copied to clipboard

Allow Documenter.RawNode through `@eval`

Open asinghvi17 opened this issue 6 months ago • 5 comments

Markdown backends may sanitize text to avoid HTML detection in Markdown objects, permitting raw nodes may prevent that.

If this makes sense, I can add a test etc.

asinghvi17 avatar May 31 '25 12:05 asinghvi17

Can you explain the use case here a bit? You have an at-eval block that tries to interpolate a Documenter.RawNode?

In general, I'd like the at-eval blocks to be a bit more powerful in this respect (being able to eval raw HTML into a document can often be handy). But I am not 100% sure exposing RawNode is the right approach.

mortenpi avatar Jun 01 '25 07:06 mortenpi

Specifically I want to interpolate a video tag but only if the page is not in draft mode (otherwise it breaks the Vitepress build)

asinghvi17 avatar Jun 01 '25 11:06 asinghvi17

Should we maybe use the standard Docs.HTML for that? I.e. if the block returns that, we'll just convert it to an @raw html node?

mortenpi avatar Jun 02 '25 06:06 mortenpi

That loses the ability to return other forms of raw content, like Markdown, though (Docs doesn't seem to have a markdown thing). Specifically the thing of interest there is to avoid automated markdown sanitization, for example...

Plus, RawNode is sufficiently simple that I don't think it will change much...

asinghvi17 avatar Jun 04 '25 02:06 asinghvi17

Could you perhaps show an example of how you'd use this?

Even better, could we perhaps add a test case demonstrating (and testing) this?

fingolfin avatar Oct 30 '25 21:10 fingolfin