Confusing Location for Files Written from `@example Blocks

[MarkNahabedian]

In some of my documentation pages, I have examples that generate SVG images. I use XML.jl to generate the SVG and write it to a file. This is done in an @example block and then @raw htmlis used to add the image to the doc page.

This might relate somewhat to #2533. It's not clear in the example that resolves that issue how to do this in an md file rather than a jl file. In any case, I would prefer my SVG files be incorporated by reference, arther than in-lined.

My markdown files contain examples like

```@example sine-wave-example
using RoseEngine
rotor = Rotor(3, 1//2, 1//8, sine_wave)
render_rotors(joinpath(@__DIR__, "sine-wave-example.svg"),
              rotor,
              1//256; debug=true)
```

```@raw html
<img src="sine-wave-example.svg"
     width="50%"/>
```

These are in a file named docs/src/check_wave_amplitudes.md, which is inclused in the documentation via the pages block

    pages=[
    "Home" => "index.md",
    "Check Wave Amplitudes" => "check_wave_amplitudes.md"
],

When I build my documentation locally, the img.src links for my SVG files are broken. This is because the SVG files are written to docs/build while the generated HTML file that refers to them is written to docs/build/check_wave_amplitudes.

If Documenter is going to create a separate directory for each of the items in the pages clause, shouldn't that directory be the working directory when any example code for that page is run?

The current behavior is confusing and requires documentation authors to kludge the link references for their documentation to render properly.

I fear this might be a breaking change unless some possibly questionable and fragile cleverness is applied though.