Documenter.jl: Displaying images via raw html is broken for hosted but not local docs

[timholy]

In older versions of Documenter one could display an image like this:

```@raw html
<img src="images/stepin2.png" width="660px"/>
```

This still works when I build the docs locally, but for the hosted docs I get broken links: https://timholy.github.io/Rebugger.jl/dev/usage/.

I'm not sure I'd report this as a bug, except that it worked on older versions of Documenter (see https://timholy.github.io/Rebugger.jl/v0.1.5/usage.html and https://github.com/timholy/Rebugger.jl/pull/53/files).

[Evizero]

quick fix:

```

````

(the ../ prefix)

[timholy]

At least when I test locally, that doesn't work. In this case images is a subdirectory of src. Nothing besides the original works for me locally.

However, if you're confident this will fix it, I should just try it anyway by pushing this to master. Thoughts?

[mortenpi]

The crux of the problem is that in the hosted builds the HTML files technically live one directory down. (e.g. the dev/usage/ page is dev/usage/index.html, instead of just dev/usage.html, as it is for local builds). So the links need to have an additional "go up one directory" part -- @Evizero suggestion should fix the hosted docs, but will break the local prettyurls = false builds.

There is no good way to support this difference in file structure with at-raw blocks since they just copy everything verbatim by definition. One option is to drop the prettyurls argument in make.jl and just build "hosted" builds locally too. The downside is that you then need to run something like python3 -m http.server to create a webserver locally (see also the second note here).

[timholy]

Thanks, indeed it works.

Could one fix it by adding an option, e.g., @raw prependpath=".." html?

[mortenpi]

You would still have to update the value of prependpath when changing the build mode, no? It would also open up a whole can of worms where we'd have to decide which parts of the user-provided HTML we need to update and which parts we don't.

Myself, I was thinking maybe one could have a simple HTML templating engine / variable interpolation. So e.g. we could have a variable that would always expand to the relative path to root of the build, and so you could have something like this:

markdown ```@raw html; template=true <img src="$(DOCUMENTER_DOCROOT)/images/stepin2.png" width="660px"/> ```

[MrUrq]

I don't know if this would be an easy feature to implement, but would it be possible to create the same directory structure for the local builds as for the hosted? And then use some optional argument

local_dir_structure_fix = get(ENV, "CI", nothing) != "true"