Relative links in IMG tags used for non-image purposes

[landmaj]

I wrote a plugin which registers a Treeprocessor to find image tags linking to D2 diagrams. You can write something like this:

![Diagram](diagram.d2)

And have it rendered as an SVG. The plugin relies on RelativeDirPlaceholder passed in on_config event. This worked fine until one of the users tried it with Material for MkDocs blog plugin. The blog plugin creates temporary files for archive, excerpts, etc and in those files RelativeDirPlaceholder no longer points to the original file, so relative links to D2 files are broken.

I tried rewriting relative links to absolute links and changing file.abs_src_path to a temporary file with the modified links. It fixes the issue but breaks git-revision-date-localized plugin, as the abs_src_path of the original file no longer points to a git directory. God knows how many other plugins it would break.

I tried modifying files created by the blog plugin but they are created with some placeholder content and I can't find the place where the proper content is injected.

I am out of ideas on how to solve the issue and I would be glad for some help.

[kamilkrzyskow]

Hello @landmaj,
I'm a bit busy right now, so I can't really investigate it properly 😞, but I'll try to push the discussion forward a least. Given your greater expertise with the plugin creation process and using the RelativeDirPlaceholder forgive my ignorant questions ✌️

1. Why are the normal image tags (pointing to images) properly resolved? Does the blog plugin fix the relative paths, or does MkDocs handle that internally using some internal path list? I would first look into that why does one thing work and the other doesn't.
2. The blog plugin does some Markdown processing on its own for the excerpts (also worth pointing out the self.file is a copy), so perhaps you'd have to register the RelativeDirPlaceholder there too?
3. Events can have set priorities to handle the order in which they run. In MkDocs 1.6.0 plugins are allowed to set multiple functions for each event, to increase the possibilities. So you could perhaps play around with it to allow git-revision-date-localized to properly resolve the abs_src_path for git revision and edit it for your own requirements later, and afterwards restore the abs_src_path to how it was. So set the priority of on_page_markdown to -100 to change the path and on_page_content to 100 in your own plugin to restore the path. But I agree with you this is sort of a last option to try, as it might break other stuff, but in general markdown_extensions aren't MkDocs-aware.

[landmaj]

1. I don't know why normal images work as they should but there is a major difference between them and my use case. They only need to work in rendered HTML so it does not matter where the file came from as long as it is in the correct place once the site is built. I need to access the source file during the build process.
2. RelativeDirPlaceholder is just a programmatic way to configure !relative and it points to the Markdown file currently being processed: https://www.mkdocs.org/user-guide/configuration/#paths-relative-to-the-current-file-or-site
3. Event priorities do not help due to how the blog plugin works. The blog plugin creates files for archive, etc in on_files event, however it does not copy the content at that stage. At some later stage my Treeprocessor gets called multiple times for the exact same Markdown, once for the original file, 2-3 times for files created by the blog plugin:

INFO    -  mkdocs-d2-plugin: Processing diagram: /Users/landmaj/GitHub/mkdocs-d2-plugin/docs/docs/blog/posts/diagram.d2
WARNING -  mkdocs-d2-plugin: File not found: /Users/landmaj/GitHub/mkdocs-d2-plugin/docs/docs/blog/diagram.d2
WARNING -  mkdocs-d2-plugin: File not found: /Users/landmaj/GitHub/mkdocs-d2-plugin/docs/docs/blog/archive/diagram.d2

[landmaj]

I thought about storing paths to diagrams in on_files for use later during Markdown processing but it would not work. This is a valid directory structure with two distinct posts:

.
├── posts
│   ├── post
│   │   ├── diagram.d2
│   │   └── post.md
│   ├── diagram.d2
│   └── post.md
└── index.md

The blog plugin flattens it so what I see during Markdown processing, using a relative path provided by MkDocs (the RelativeDirPlaceholder mentioned earlier), is this:

INFO    -  mkdocs-d2-plugin: Rendering diagram: /Users/landmaj/GitHub/mkdocs-d2-plugin/docs/docs/blog/posts/diagram.d2
INFO    -  mkdocs-d2-plugin: Rendering diagram: /Users/landmaj/GitHub/mkdocs-d2-plugin/docs/docs/blog/posts/post/diagram.d2
WARNING -  mkdocs-d2-plugin: File not found: /Users/landmaj/GitHub/mkdocs-d2-plugin/docs/docs/blog/diagram.d2
WARNING -  mkdocs-d2-plugin: File not found: /Users/landmaj/GitHub/mkdocs-d2-plugin/docs/docs/blog/diagram.d2
WARNING -  mkdocs-d2-plugin: File not found: /Users/landmaj/GitHub/mkdocs-d2-plugin/docs/docs/blog/archive/diagram.d2
WARNING -  mkdocs-d2-plugin: File not found: /Users/landmaj/GitHub/mkdocs-d2-plugin/docs/docs/blog/archive/diagram.d2

The two INFO logs are from processing the original Markdown files. The other four WARNINGs are from files created by the blog plugin. The paths for both diagrams look identical, there is no way to distinguish them.

[landmaj]

So to summarize:

1. I can't substitute my modified Markdown in on_files, before the blog plugin creates its files and restore it afterwards, also in on_files, because those new files contain placeholder Markdown at that stage, nothing is copied.
2. I can't alter the original file abs_src_path attribute and leave it there because it breaks other plugins (git-revision-date-localized).
3. Doing anything during Markdown processing is futile as I have no way of knowing where the Markdown came from when it's created by the blog plugin.

There must be another way but my brain is already fried from reading an alien (to me) code base.