Images don't appear in final site

[dominic-chang]

I’m struggling to include images in markdown files with DocumenterVitepress.jl The final site renders with a Documenter.LocalImage("image.png") instead of the actual image.

Here is my config.mts

import { defineConfig } from 'vitepress'
import { tabsMarkdownPlugin } from 'vitepress-plugin-tabs'
import mathjax3 from "markdown-it-mathjax3";
import footnote from "markdown-it-footnote";

// https://vitepress.dev/reference/site-config
export default defineConfig({
  base: 'REPLACE_ME_DOCUMENTER_VITEPRESS',// TODO: replace this in makedocs!
  title: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
  description: "A VitePress Site",
  lastUpdated: true,
  cleanUrls: true,
  outDir: 'REPLACE_ME_DOCUMENTER_VITEPRESS', // This is required for MarkdownVitepress to work correctly...
  head: [['link', { rel: 'icon', href: '/public/favicon.ico' }]],

  markdown: {
    math: true,
    config(md) {
      md.use(tabsMarkdownPlugin),
      md.use(mathjax3),
      md.use(footnote)
    },
    theme: {
      light: "github-light",
      dark: "github-dark"}
  },
  themeConfig: {
    outline: 'deep',
    // https://vitepress.dev/reference/default-theme-config
    logo: { src: '/logo_dark.png', width: 24, height: 24 },
    search: {
      provider: 'local',
      options: {
        detailedView: true
      }
    },
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Getting Started', link: '/getting_started' },
      { text: 'Examples', link: '/examples/coordinate_example' },
      { text: 'API', link: '/api' }
    ],

    sidebar: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
    editLink: {
      pattern: 'https://github.com/LuxDL/DocumenterVitepress.jl/edit/master/docs/src/:path' // TODO: replace this in makedocs!
    },
    socialLinks: [
      { icon: 'github', link: 'https://github.com/LuxDL/DocumenterVitepress.jl' }
    ],
    footer: {
      message: 'Made with <a href="https://documenter.juliadocs.org/stable/" target="_blank"><strong>Documenter.jl</strong></a> & <a href="https://vitepress.dev" target="_blank"><strong>VitePress</strong></a> <br>',
      copyright: \`© Copyright ${new Date().getUTCFullYear()}. Released under the MIT License.\`
    }
  }
})

and my make.jl

using Krang
using Documenter
using DocumenterVitepress
using Glob
using Literate

# Make the examples using Literate
GENERATED = joinpath(@__DIR__, "..", "examples")
OUTDIR = joinpath(@__DIR__, "src", "examples")

SOURCE_FILES = Glob.glob("*.jl", GENERATED)
foreach(fn -> Literate.markdown(fn, OUTDIR, documenter=true), filter(x-> !occursin("gpu", x) && !occursin("JuKeBOX", x) , SOURCE_FILES))
MD_FILES = filter(x-> !occursin("gpu", x) && !occursin("JuKeBOX", x) , [joinpath("examples", file) for file in readdir(OUTDIR)])

Documenter.DocMeta.setdocmeta!(Krang, :DocTestSetup, :(using Krang); recursive=true)

format=DocumenterVitepress.MarkdownVitepress(
    repo = "https://dchang10.github.io/Krang.jl", # this must be the full URL!
   devbranch = "main",
    devurl = "dev",
    #clean_md_output = true
    ;
)

makedocs(;
    sitename="Krang.jl",
    authors="Dominic <dchang3419@hotmail.com> and contributors",
    modules=[Krang],
    repo="https://github.com/dchang10/Krang.jl/blob/{commit}{path}#{line}",
    format=format,
    pages=[
        "Home" => "index.md",
        "Getting Started" => "getting_started.md",
        "Examples" => MD_FILES,
        "Theory" => [
            "Raytracing" => [
                "kerr_geodesic_summary.md",
                "time_regularization.md",
            ],
            "Polarization" => [
                "newmann_penrose.md",
                "polarization.md",
            ]
        ],
        "api.md",
    ],
)

deploydocs(;
    repo="github.com/dchang10/Krang.jl",
    devbranch="main",
)

[lazarusA]

your format should look like this:

format=DocumenterVitepress.MarkdownVitepress(
        repo = "github.com/LuxDL/DocumenterVitepress.jl", # this must be the full URL!
        devbranch = "master",
        devurl = "dev";

could you try with that? please.

[dominic-chang]

Sorry, I copied and pasted the incorrect make.jl file. My formatter is actually this

format=DocumenterVitepress.MarkdownVitepress(
    repo = "https://dchang10.github.io/Krang.jl", # this must be the full URL!
   devbranch = "main",
    devurl = "dev",
    #clean_md_output = true
    ;
)

I've edited the original post to reflect this.

[dominic-chang]

Here's an example of a markdown file. I generate these with Literate.jl

\`\`\`@meta
EditURL = "../../../examples/test_example.jl"
\`\`\`

\`\`\`\`@example test_example
using Krang
using CairoMakie

curr_theme = Theme(
    Axis = (
        xticksvisible = false,
        xticklabelsvisible = false,
        yticksvisible = false,
        yticklabelsvisible = false,
        ),
)
set_theme!(merge!(curr_theme, theme_latexfonts()))

fig = Figure(resolution=(700, 700));
CairoMakie.heatmap!(Axis(fig[1,1]), rand(100,100))

save("test.png", fig)
\`\`\`\`

![image](test.png)

---

*This page was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).*

This results in a page that looks like this

while the equivalent page with the default Documenter.HTML formatter looks like this:

[avik-pal]

As a temporary workaround you can split the codeblocks with the last line in the first block being fig and then saving in a separate block. See https://lux.csail.mit.edu/dev/tutorials/intermediate/5_BayesianNN#prediction-visualization

[dominic-chang]

Thanks, that works for the example case I gave, but I also use these images in other places in my docs. This method also doesn't seem to work for animations. I typically get around this by generating gifs to render.

recording = CairoMakie.record(fig, "radius.gif", range(0.0, π, length=180), framerate=12) do θs
    draw!(axes, camera, observation, rmin, rmax, θs, flag)
end

# ![image](radius.gif)

Anyway of getting the other markdown pages to be able to render those images?

[dominic-chang]

I think I understand the source of the error. The images are not rendering because Documenter.jl replaces the ![](image.png) markdown with its own Documenter.LocalImage("image.png") which vite does not recognize when building.

[lazarusA]

I believe this might be fix on the next release, could you please try master ?

[dominic-chang]

Thanks. That worked!